Notify Developers of Score Changes Due to Deduplicated Stamps (API v2)

User Story:

As a developer integrating Passport XYZ's Unique Humanity Score through API v2, I want to be notified when a user's score is impacted by deduplication stamps, So that I can maintain the accuracy and integrity of user interactions in my application, while protecting user privacy.

Acceptance Criteria

GIVEN a developer is using the Passport XYZ API v2 to retrieve a user's Unique Humanity Score, WHEN the score is affected by the deduplication of stamps or addresses, THEN the "getScore" endpoint in API v2 should return additional information in the payload, indicating that a stamp/address has been deduplicated.

Product & Design Links:

N/A

Tech Details:

Introduce a new field in the "getScore" response payload for API v2 to notify about deduplication effects, e.g., deduplicationEffect: true.
This field should solely serve as an informational flag, without revealing any specific details about the linked addresses involved in the deduplication, ensuring privacy.

Open Questions:

[ ] What guidance should be provided regarding how developers should utilize this deduplication information within their applications?

Notes/Assumptions:

This feature is intended to ensure transparency wherein developers are informed of score changes due to deduplication, without compromising user privacy.
The upgrade applies to our new API v2, ensuring developers are using the latest and most secure integrations.
Documentation and developer support will be updated to reflect these enhancements and assure seamless adoption.

Thanks for putting this together Erich!

What guidance should be provided regarding how developers should utilize this deduplication information within their applications?

Developers can use this in a couple of different ways:

They can display a warning, such as the following:

"Your score may differ from your score within the Passport XYZ app since you've claimed the [stamp] with another account. Learn more about this deduplication [here](link to Passport support knowledge base article)."

If a user complains about a difference in score between the Passport XYZ app and their scorer, it will be much easier for them to support themselves. I'll put together an FAQ that describes how to troubleshoot score differences like this.

The below design might make #1 difficult for partners to be proactive about.

As far as a design, I wonder if we can do a couple of things...

First, I think we should add a single field within the credential object returned with GET /v2/stamps/{address}

            "credential": {
                "type": [   ...  ],
                "proof": {  ...  },
                "issuer": "did:ethr:0xd6f8d6ca86aa01e551a311d670a0d1bd8577e5fb",
                "@context": [ ... ],
                "issuanceDate": "2024-11-17T14:44:32.751Z",
                "expirationDate": "2025-02-15T14:44:32.751Z",
                **"deduplicated": true / false**
                "credentialSubject": { ... }
            }

Second, could we add a value to the GET /v2/stamps/{scorer_id}/scores/{address} endpoint's error field that suggests when a deduplication happens?

Reason being, the vast majority of developers will only use this endpoint, so the deduplicated field within the GET /v2/stamps/{address} endpoint will not be that valuable unless developers are notified via the endpoint they are actually using.

A potential value could be...

{ ... "error": "This user has one or more Stamps that have been deduplicated. This means the score that returns with this endpoint will differ from the score within the Passport XYZ app. Please refer to the deduplicated field that returns in the credentials object from the GET /v2/stamps/{address} endpoint to identify which Stamps have been deduplicated. You can learn more about Stamp deduplication here: https://docs.passport.xyz/building-with-passport/major-concepts/deduplicating-stamps", ... }

Thoughts?

passportxyz / passport