This document describes how to create v1 verifiable presentations and how to verify them.

Table of Contents:

• Build Statement
  • Identity/account credential statements
• JSON representation
• Verifiable Presentation Request (proof request)
• Verifiable Presentation (proof)
• Verifiable Audit Record

The SDK contains a helper to create statements about identities, which can then be proven.

To do so, use the presentation request statement builder, to build a statement:

let builder = VerifiablePresentationRequestV1.statementBuilder();

// Add an identity credential statement. Alternatively, if the proof produced from the
// statement should be tied to an account, use `builder.addAccountStatement`.
// A third option `builder.addAccountOrIdentityStatement`exists where it's up to the
// application holding the credentials to decide which proof is produced.
builder = builder.addIdentityStatement(
    [0, 1].map((idpIndex) => new IdentityProviderDID('Testnet', idpIndex)),
    (b) => {
        b.addMinimumAge(18);
        b.addEUResidency();
        b.revealAttribute('firstName');
    }
);

// Get the complete statement to request a proof of.
const statement = builder.getStatements();

console.log('successfully constructed statement', statement);

To build a statement against an identity credential, the builder has two different entrypoints, which have an identical function signature, which consists of

1. A list of identity providers that the identity must be created from
2. A callback function which should be used to add statements for the credential

// used for proofs tied to an account created from the identity credential.
builder.addAccountStatement([0,2].map(idp => new IdentityProviderDID('Testnet', idp)), (build) => ...)
// used for proofs which are not tied to a specific account
builder.addIdentityStatement([0,2].map(idp => new IdentityProviderDID('Testnet', idp)), (build) => ...)
// alternatively let the application producing the proof decide
builder.addAccountOrIdentityStatement([0,2].map(idp => new IdentityProviderDID('Testnet', idp)), (build) => ...)

Below are a set of functions accessible for the build object passed in the callback

There is a helper function for specifying the prover must have some minimum age.

Example: add the statement that the prover must be at least 18 years old:

    build.addMinimumAge(18);

There is a helper function for specifying the prover must have some maximum age.

Example: add the statement that the prover must be at most 27 years old:

    build.addMaximumAge(27);

There are helpers for specifying the country of residency or nationality to be one of the EU member states.

    build.addEUNationality();
    build.addEUResidency();

State that a given attribute should be revealed as part of the proof.

    build.revealAttribute(AttributesKeys.nationality);

State that a given attribute should be between 2 given values.

Example: add the statement that the prover must be born between January 1, 1941 and Februar 2, 2005.

    build.addRange(AttributesKeys.dob, 19410101, 20050202);

Note that this type of statement is only allowed for the following attributes:

• dob (date of birth)
• idDocIssuedAt
• idDocExpiresAt

Example: add the statement that the prover's country of residency is France or Spain, specified in ISO3166-1 alpha-2 format:

    build.addMembership(AttributesKeys.CountryOfResidency, ['FR', 'ES']);

Note that this type of statement is only allowed for the following attributes:

• Nationality
• CountryOfResidency
• IdDocIssuer
• IdDocType

Example: add the statement that the prover's country of residency not Germany nor Portugal:

    build.addNonMembership(AttributesKeys.CountryOfResidency, ['DE', 'PT']);

Note that this type of statement is only allowed for the following attributes:

• Nationality
• CountryOfResidency
• IdDocIssuer
• IdDocType

The VerifiablePresentationRequestV1, VerifiablePresentationV1, and VerifiableAuditRecordV1 can be represented as JSON by calling the associated .toJSON method (will also be called implicitly with JSON.stringify). Correspondingly, parsing the JSON values can be done with the .fromJSON function exposed for each type.

bigints are used internally in the types described above and need to be handled with something like json-bigint

Example: service serializes presentation request in response to frontend; frontend deserializes and parses the JSON.

const json = JSON.stringify(presentationRequest); // service sends back presentation request to frontend
...
const presentationRequest = VerifiablePresentationRequestV1.fromJSON(JSON.parse(json)); // frontend parses the JSON.

To get a verifiable presentation of one or more verifiable credentials owned by a user, the entity requesting the information must first build a verifiable presentation request. In the V1 protocol, this is done in the following sequence:

1. Make the request context, consisting of a. a unique 32-byte "nonce" b. a "connection ID" which identifies the connection between prover and requester c. a "context string" which describes the context of the proof request, e.g. which store is being accessed d. a set of requested context values, identified by their labels. For now the defaults here are: the block hash of the anchor transaction and the resource ID (i.e. an identifier of the requester, e.g. a url of the website). The requested context is filled out by the application creating the proof.
2. Build the statement to be proven by the user

Once this is done, the request must be anchored on chain with a transaction. This can be achieved by calling

const nonce = Uint8Array.from(...) // randomly generated 32-byte value
const connectionID = ... // e.g. a wallet-connect ID
const contextString = 'My compliant web3 wine shop'
const context = VerifiablePresentationRequestV1.createSimpleContext(nonce, connectionID, contextString)

const statement = new VerifiablePresentationRequestV1.statementBuilder()...

// a GRPC client connected a node on the network the anchor should be registered on
const grpcClient: ConcordiumGRPCClient = ...;
// the sender of the anchor transaction
const sender: AccountAddress.Type = ...;
// the keys for the account to sign the anchor transaction
const signer: Signer = ...;

// create the presentation request with an on-chain anchor, which can be checked by the owner of the credentials.
const presentationRequest = await VerifiablePresentationRequestV1.createAndAchor(
    grpcClient,
    sender,
    signer,
    context,
    statement
);

Computing a verifiable presentation from a verifiable presentation request is a process of the following sequence for each credential statement in the request:

1. Identify valid credentials for the statement by looking at the ID qualifier of the VerfiablePresentationRequest.Statement.
2. Validate the attributes of the credential in the context of the statement.
3. Construct a VerifiablePresentationV1.Statement corresponding to the credential. This is is not the same as the VerfiablePresentationRequest.Statement we built for the VerfiablePresentationRequest previously; here we're working with a specific credential, e.g. from the users wallet. a. for VerfiablePresentationRequest.IdentityStatements, the source also needs to be taken into account. This specifies the type of credential requested by the dapp. This can either be set to ["Identity"] | ["Account"] | ["Identity", "Account"], where the latter means that the application constructing the proof can decide which proof to construct for the statement.

When this is done for all credential statements in the request, we construct the proof context corresponding to the request context of the request, specifying values for each requested context value in VerifiablePresentationRequestV1.Context.requested.

// specify the resource ID (e.g. website URL or fingerprint of TLS certificate that the wallet is connected to)
// from the connection to the requester of the proof. The block hash is _not_ specified here, as it is looked up
// later in `VerifiablePresentationV1.createFromAnchor` from the anchor transaction reference in the presentation
// request.
const contextValues: GivenContext[] = [{label: 'ResourceID', context: ...}];

// The application goes through each statement in the presentation request, and constructs a corresponding statement
// used as input to the presentation. The difference between the two statement types boil down to the presence of an ID
// qualifier vs. an ID (selected by the application based on the id qualifier).
const statements: VerifiablePresentationV1.Statement[] = presentationRequest.credentialStatements.map((entry) => {
    // prioritize creating identity based proofs, as these are more privacy-preserving
    if (entry.source.includes('identity'))
        return {id: createIdentityStatementDID(...), statement: entry.statement};
    return {id: createAccountDID(...), statement: entry.statement};
});

// the inputs for the credential owned by the user, i.e. credential attribute values. For each
// `SpecifiedCredentialStatement`, there should be a corresponding input
const inputs: CommitmentInput[] = [
    createIdentityCommitmentInputWithHdWallet(...),
    createAccountCommitmentInputWithHdWallet(...),
];

const presentation = await VerifiablePresentationV1.createFromAnchor(
    grpcClient,
    presentationRequest,
    statements,
    inputs,
    contextValues
);

// verify the presentation elsewhere
const result = VerifiablePresentationV1.verifyWithNode(presentation, presentationRequest, grpcClient, network);

Services can opt in to create a verification audit record from the verifiable presentation request and corresponding verifiable presentation. This exists as a record and a corresponding anchor. The record should be stored by the dapp backend (e.g. in a database), and the anchor should be registered on chain. The transacton hash of the anchor registration should be stored along the record.

const uuid: string = ...;
const record = VerificationAuditRecordV1.create(uuid, presentationRequest, presentation);
const anchorTransactionHash = await VerificationAuditRecordV1.registerAnchor(record, grpcClient, sender, signer);