Data dictionary
On this page you will find definitions and explanations for the data types used in the Gitcoin Passport stack. The Scorer, Stamp , Credential and Stamp-metadata objects require the most explanation so they are handled separately here. Other types found across the Passport stack are defined in "Other data".
The Scorer object
| Value | Type | Description | How to use |
|---|---|---|---|
address | string | The string of 20 bytes that uniquely identify an Ethereum account | Identifies a specific account to be scored |
score | string | The registry/score endpoint returns a string that should be parsed as a float. It represents the result of adding the weights of all a user's Stamps. | Returned from registry/score. Can be used to gate access to content. |
status | string | Shows whether a server request is PROCESSING or DONE. | Included in responses from registry/score |
last_score_timestamp | datetime string | The date and time of the previous request made to the Scorer instance. For example, "2023-04-28T09:35:49.159Z" | Returned by the registry/score and registry/submit-passport endpoint |
expiration_date | datetime string | The date and time that the next upcoming Stamp will expire, which will subsequently reduce the score. To see when each specific Stamp expires, please use the GET /stamps endpoint. | You might want to display this score expiration to the user to remind them to return to the Passport app to refresh their score before it expires |
evidence | struct | When the binary Scorer is selected, this field is used to explain why the return value was 0 or 1. Specifically, the returned data shows the threshold score required to return 1, and the actual score the Passport received. The current score threshold for a passing score is 20. | You can use this to check the reasoning behind a binary Passport score, and understand why a Passport was decided to be Sybil (0) or non-Sybil (1). |
error | string | Describes any error returned by the server. Refer to the API status and error codes page for more information. | Used to understand why a request failed. |
stamp_scores | struct | Contains key:value pairs with stamp names as keys and their weights for the scoring algoithm as values. |
The Stamp object
| Value | Type | Description | How to use |
|---|---|---|---|
credential | struct | Message displayed in the Passport Scorer app alongside a button to trigger verification of a specific Stamp See Credentials table below for more details. | This is what a Stamp actually comprises. It is associated with an Ethereum address. |
items | array<stamp> | An array containing data for each individual Stamp. | Each object in this array represents a specific Stamp. |
metadata | struct | Metadata is a struct containing id, icon, name, description, and connectMessage fields for each provider and then more granular data for each of the provider's Stamps | Returned from the registry/stamps endpoint if the qualifier include-metadata=true is also passed. Returned from registry/stamp-metadata for all Stamps |
next | string | A pointer to the next page of returned data, if the returned data has been paginated. | You can use this is a request to access a page and the subsequent page of results for a paginated response. If the value is null you are already seeing all the available information. |
prev | string | A pointer to the preceding page of returned data, if the returned data has been paginated. | You can use this is a request to access a page and the previous page of results for a paginated response. If the value is null you are already seeing all the available information. |
version | string | A version identifier for a Stamp | Returned for each Stamp from registry/stamps |
Credentials
A credential is a struct returned in the Stamp object. It has its own sub-fields as follows:
| Value | Type | Description | How to use |
|---|---|---|---|
type | string | A descriptor that shows what type of credential is present | Can be used to check that the returned data is of the expected structure for a given credential type. This is usually going to have the value VerifiableCredential. |
proof | struct | A struct containing several fields comprising the proof that a certain action was taken, for example a signed auth token proving that an account was unlocked. | Used to verify ownership of a specific Stamp |
issuer | hash | Each Stamp issuer has a specific identifying hash provided in this field. | Used to identify a Stamp issuer |
@context | url | Link to the credential definition documentation | Can be used to access reference documentation for the credential type |
issuanceDate | datetime string | The date and time that the Stamp was minted. For example, "2023-04-28T09:35:49.159Z" | Can be used to check the age of a Stamp |
expirationDate | datetime string | The date and time the Stamp should expire. For example, "2023-04-28T09:35:49.159Z" | Can be used to automatically expire a Stamp |
credentialSubject | struct | Contains anonymized information about the user that the Stamp is issued to. This includes a unique ID, a hash, link to the data schema and the Stamp provider name in plaintext. | Can be used to connect Stamps to a user in a privacy preserving way |
Stamp metadata
| Value | Type | Description | How to use |
|---|---|---|---|
connectMessage | string | Message displayed in the Passport scorer app alongside a button to trigger verification of a specific Stamp | Mainly used in the Passport app, but could be used to provide appropriate message for verification in other contexts |
description | string | Short description of what a specific Stamp demonstrates. For example, ownership of >0.5 ETH | Returned in Stamp metadata, can be used to understand a specific Stamp |
groups | string | Identifier for top-level groupings of Stamps for a given provider | Each provider may issue many Stamps which can be grouped together by theme, for example the Gitcoin Provider groups Stamps by Self GTC-staking and Community GTC-staking |
hash | string | A unique hash representing a specific instance of a credential | Used to prevent the same Stamp being used multiple times in a specific Scorer instance |
icon | string | A URL for an image to represent each Stamp provider | Returned in Stamp metadata, can be used to load an icon for a Stamp provider |
id | string | An identifier for a Stamp | Returned in Stamp metadata, can be used to scrape data for a specific Stamp |
name | string | Name of the provider issuing a given Stamp | Returned as part of the Stamp metadata, can be used to scrape information for specific providers |
stamps | array | Array containing Stamp structs for each individual Stamp. Each Stamp has name, description and hash fields | Included in Stamp metadata. Used to identify specific instances of individual Stamps |
GTC staking
| Value | Type | Description |
|---|---|---|
users | array | Contains the specified address's staking data, including a stakes object that contains data on how much and when a user staked GTC on themselves, and the xstakeAggregate, which contains data on how much a user has staked on other community members and when. |
stakes | array | Contains one or multiple stake objects, which includes data on how much GTC the specified user has staked on themselves. This array will include a different object for each round the user had staked any GTC on themselves. |
stake | string | Represents the number of GTC the user has staked on themselves in a specified round. |
round | object | Contains the ID of the round in which the associated stake amount was staked. |
id | number | Represents the round in which the associated stake amount was staked. |
xstakeAggregates | array | Contains one or multiple stake objects, which includes data on how much GTC the specified user has staked on themselves. This array will include a different object for each round the user had staked any GTC on themselves. |
total | string | Represents the total number of GTC the user staked on community members in a specified round. |
Other data
| Value | Type | Description | How to use |
|---|---|---|---|
API-Key | string | An authorization token generated by the Scorer app giving you access to a Scorer instance on the Gitcoin server. | Include this API key as part of your request headers. |
nonce | int | A transaction counter for an address that is used in signing to prevent certain types of attack | This is an optional field that can be provided to submit-passport for additional verification. Today access to Scorers is controlled using API keys only by default. |
scorer_id | string | Scorers are instantiated with unique IDs known as scorer_ids. | Create a Scorer in the Scorer app to receive a scorer_id. Then this value links your API requests to a specific Scorer instance matching your API key |
signature | string | Some workflows require a Scorer owner to demonstrate their ownership by signing a message with the Scorer owner's private key. | This is an optional field that can be provided to submit-passport for additional verification. Today access to Scorers is controlled using API keys only by default. |