Struct Credential 

pub struct Credential {
    pub id: u64,
    pub version: CredentialVersion,
    pub issuer_schema_id: u64,
    pub sub: FieldElement,
    pub genesis_issued_at: u64,
    pub expires_at: u64,
    pub claims: Vec<FieldElement>,
    pub associated_data_hash: FieldElement,
    pub signature: Option<EdDSASignature>,
    pub issuer: EdDSAPublicKey,
}

Base representation of a Credential in the World ID Protocol.

A credential is generally a verifiable digital statement about a subject. It is the canonical object: everything a verifier needs for proofs and authorization.

In the case of World ID these statements are about humans, with the most common credentials being Orb verification or document verification.

Associated Data

Credentials have a pre-defined strict structure, which is determined by their version. Extending this, issuers may opt to include additional arbitrary data with the Credential. This data is called Associated Data.

• Associated data is stored by Authenticators with the Credential.
• Including associated data is a decision by the issuer. Its structure and content is solely determined by the issuer and the data will not be exposed to RPs or others.
• An example of associated data use is supporting data to re-issue a credential (e.g. a sign up number).
• Associated data is never exposed to RPs or others. It only lives in the Authenticator.
• Associated data is authenticated in the Credential through the associated_data_hash field. The issuer can determine how this data is hashed. However providing the raw data to associated_data can ensure a consistent hashing into the field.

+------------------------------+
|          Credential          |
|                              |
|  - associated_data_hash <----+
|  - signature                 |
+------------------------------+
          ^
          |
    Hash(associated_data)
          |
Associated Data
+------------------------------+
| Optional arbitrary data      |
+------------------------------+

Design Principles:

• A credential clearly separates:
  • Assertion (the claim being made)
  • Issuer (who attests to it / vouches for it)
  • Subject (who it is about)
  • Presenter binding (who can present it)
• Credentials are usable across authenticators without leaking correlate-able identifiers to RPs.
• Revocation, expiry, and re-issuance are first-class lifecycle properties.
• Flexibility: credentials may take different formats but share common metadata (validity, issuer, trust, type).

All credentials have an issuer and schema, identified with the issuer_schema_id field. This identifier is registered in the CredentialSchemaIssuerRegistry contract. It represents a particular schema issued by a particular issuer. Some schemas are intended to be global (e.g. representing an ICAO-compliant passport) and some issuer-specific. Schemas should be registered in the CredentialSchemaIssuerRegistry contract and should be publicly accessible.

We want to encourage schemas to be widely distributed and adopted. If everyone uses the same passport schema, for example, the Protocol will have better interoperability across passport credential issuers, reducing the burden on holders (to make sense of which passport they have), and similarly, RPs.

Fields

id: u64

A reference identifier for the credential. This can be used by issuers to manage credential lifecycle.

• This ID is never exposed or used outside of issuer scope. It is never part of proofs or exposed to RPs.
• Generally, it is recommended to maintain the default of a random identifier.

Example Uses

• Track issued credentials to later support revocation after refreshing.

version: CredentialVersion

The version of the Credential determines its structure.

issuer_schema_id: u64

Unique issuer schema id represents the unique combination of the credential’s schema and the issuer.

The issuer_schema_id is registered in the CredentialSchemaIssuerRegistry. With this identifier, the RPs lookup the authorized keys that can sign the credential.

sub: FieldElement

The blinded subject (World ID) for which the credential is issued.

The underlying identifier comes from the WorldIDRegistry and is the leaf_index of the World ID on the Merkle tree. However, this is blinded for each issuer_schema_id with a blinding factor to prevent correlation of credentials by malicious issuers.

genesis_issued_at: u64

Timestamp of first issuance of this credential (unix seconds), i.e. this represents when the holder first obtained the credential. Even if the credential has been issued multiple times (e.g. because of a renewal), this timestamp should stay constant.

This timestamp can be queried (only as a minimum value) by RPs.

expires_at: u64

Expiration timestamp (unix seconds)

claims: Vec<FieldElement>

For Future Use. Concrete statements that the issuer attests about the receiver.

They can be just commitments to data (e.g. passport image) or the value directly (e.g. date of birth).

Currently these statements are not in use in the Proofs yet.

associated_data_hash: FieldElement

The commitment to the associated data issued with the Credential.

By default this uses the internal hash_bytes_to_field_element function, but each issuer may determine their own hashing algorithm.

This hash is generally only used by the issuer.

signature: Option<EdDSASignature>

The signature of the credential (signed by the issuer’s key)

issuer: EdDSAPublicKey

The public component of the issuer’s key which signed the Credential.

Implementations

impl Credential

pub const MAX_CLAIMS: usize = 16

The maximum number of claims that can be included in a credential.

pub fn new() -> Credential

Initializes a new credential.

Note default fields occupy a sentinel value of BaseField::zero()

pub const fn id(self, id: u64) -> Credential

Set the id of the credential.

pub const fn version(self, version: CredentialVersion) -> Credential

Set the version of the credential.

pub const fn issuer_schema_id(self, issuer_schema_id: u64) -> Credential

Set the issuerSchemaId of the credential.

pub const fn subject(self, sub: FieldElement) -> Credential

Set the sub for the credential.

pub const fn genesis_issued_at(self, genesis_issued_at: u64) -> Credential

Set the genesis issued at of the credential.

pub const fn expires_at(self, expires_at: u64) -> Credential

Set the expires at of the credential.

pub fn claim_hash( self, index: usize, claim: Uint<256, 4>, ) -> Result<Credential, PrimitiveError>

Set a claim hash for the credential at an index.

Errors

Will error if the index is out of bounds.

pub fn claim( self, index: usize, claim: &[u8], ) -> Result<Credential, PrimitiveError>

Set the claim hash at specific index by hashing arbitrary bytes using Poseidon2.

This method accepts arbitrary bytes, converts them to field elements, applies a Poseidon2 hash, and stores the result as claim at the provided index.

Arguments

• claim - Arbitrary bytes to hash (any length).

Errors

Will error if the data is empty and if the index is out of bounds.

pub fn associated_data_hash( self, associated_data_hash: Uint<256, 4>, ) -> Result<Credential, PrimitiveError>

Set the associated data hash of the credential from a pre-computed hash.

Errors

Will error if the provided hash cannot be lowered into the field.

pub fn associated_data(self, data: &[u8]) -> Result<Credential, PrimitiveError>

Set the associated data hash by hashing arbitrary bytes using Poseidon2.

This method accepts arbitrary bytes, converts them to field elements, applies a Poseidon2 hash, and stores the result as the associated data hash.

Arguments

• data - Arbitrary bytes to hash (any length).

Errors

Will error if the data is empty.

pub fn get_cred_ds(&self) -> FieldElement

Get the credential domain separator for the given version.

pub fn claims_hash(&self) -> Result<FieldElement, Report>

Get the claims hash of the credential.

Errors

Will error if there are more claims than the maximum allowed. Will error if the claims cannot be lowered into the field. Should not occur in practice.

pub fn hash(&self) -> Result<FieldElement, Report>

The hash is signed by the issuer to provide authenticity for the credential.

Errors

• Will error if there are more claims than the maximum allowed.
• Will error if the claims cannot be lowered into the field. Should not occur in practice.

pub fn sign(self, signer: &EdDSAPrivateKey) -> Result<Credential, Report>

Sign the credential.

Errors

Will error if the credential cannot be hashed.

pub fn verify_signature( &self, expected_issuer_pubkey: &EdDSAPublicKey, ) -> Result<bool, Report>

Verify the signature of the credential against the issuer public key and expected hash.

Errors

Will error if the credential is not signed. Will error if the credential cannot be hashed.

pub fn compute_sub( leaf_index: u64, blinding_factor: FieldElement, ) -> FieldElement

Compute the sub for a credential computed from leaf_index and a blinding_factor.

Trait Implementations

impl Clone for Credential

fn clone(&self) -> Credential

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Credential

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for Credential

fn default() -> Credential

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for Credential

fn deserialize<__D>( __deserializer: __D, ) -> Result<Credential, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for Credential

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.