Understanding Claims
In the did-auth protocol, a claim is a specific piece of information or an action that your application requests from a user's DID Wallet. This could be anything from asking for their name and email, requesting a signature for a blockchain transaction, or presenting a Verifiable Credential to prove their identity. Claims are the building blocks of any authentication or interaction workflow.
Each claim is a JavaScript object that must conform to a specific schema. This ensures that the wallet can correctly interpret the request and present it to the user for approval.
Common Claim Properties#
All claim types share a set of standard fields that provide context for the request.
Property | Type | Description |
|---|---|---|
|
| The type of the claim (e.g., 'profile', 'signature'). This is automatically set based on the claim name. |
|
| A human-readable message displayed to the user in their wallet, explaining what is being requested and why. A clear description is crucial for user trust. |
|
| Specifies the blockchain context (e.g., which chain and endpoint) for on-chain operations like transactions or asset verification. For more details, see the Schemas Reference. |
|
| An array of numbers used for Multi-Factor Authentication (MFA). If the claim requires MFA, the wallet will prompt the user to select the correct code from this shuffled list. |
|
| An optional field to include any additional metadata your application might need to process the claim response. |
Claim Types#
The library supports a variety of claim types to handle different scenarios.
authPrincipal#
Requests the user to select an account (DID) to proceed with the application. This is typically the first step in an authentication flow.
Key Parameters
Property | Type | Description |
|---|---|---|
|
| An optional DID that you suggest the user select. |
|
| If |
|
| An optional object specifying the desired properties of the DID to be created (e.g., role, key type, hash). |
Example
const claims = {
authPrincipal: {
description: 'Please select an account to sign in.',
},
};profile#
Requests personal profile information from the user's wallet.
Key Parameters
Property | Type | Description |
|---|---|---|
|
| An array of profile fields to request. Defaults to |
Available items include: did, fullName, email, phone, signature, avatar, birthday, url.
Example
const claims = {
profile: {
description: 'Please provide your name and email to create an account.',
items: ['fullName', 'email', 'avatar'],
},
};signature#
Requests the user to sign a piece of data. This is one of the most powerful claims, used for signing messages, authorizing transactions, and more.
Key Parameters
Property | Type | Description |
|---|---|---|
|
| The type of data being signed. Determines how the wallet processes and displays the request. Common values include |
|
| The raw data to be signed, encoded as a Base58 string. |
|
| If the data is too large to send, you can send its pre-computed hash (digest) instead. The |
|
| The hashing algorithm the wallet should apply to |
|
| A JSON string that provides a rich display format in the wallet, such as rendering a URL. Example: |
|
| An optional object specifying assets or tokens the user must possess to complete the signature. |
Example: Signing a Simple Message
const { toBase58 } = require('@ocap/util');
const claims = {
signature: {
typeUrl: 'mime:text/plain',
description: 'Sign this message to prove ownership of your DID.',
origin: toBase58('Hello, DID!'),
},
};prepareTx#
Requests the user's wallet to complete a partially-formed transaction, sign it, and return it. This is useful for scenarios like payments, where the application defines the recipient and amount, but the user's wallet must provide the input funds.
Key Parameters
Property | Type | Description |
|---|---|---|
|
| The partially-encoded transaction, as a Base58 string. |
|
| A required object describing the tokens or assets the wallet needs to contribute. |
Example
const claims = {
prepareTx: {
description: 'Please complete this payment of 1 ABT.',
partialTx: 'z289k...encodedTx...oih1', // A partially-formed, base58-encoded transaction
requirement: {
tokens: [
{ address: 'z35nB2SA6xxBuoaiuUXUw6Gah2SNU3UzqdgEt', value: '1000000000000000000' }, // 1 ABT
],
},
},
};verifiableCredential#
Requests the user to present a Verifiable Credential (VC) that meets certain criteria.
Key Parameters
Property | Type | Description |
|---|---|---|
|
| If |
|
| An array of filter objects used to query the wallet for matching credentials. Multiple filters are treated as an |
|
| (Inside a filter) An array of DIDs of trusted issuers. The presented VC must be issued by one of these DIDs. A trusted issuer can also be an object: |
|
| (Inside a filter) An array of VC type names. The VC must match one of the specified types. |
Example: Requesting a Passport VC
const claims = {
verifiableCredential: {
description: 'Please present your Blocklet Server Passport to continue.',
filters: [
{
type: ['BlockletServerPassport'],
trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'],
},
],
},
};asset#
Similar to verifiableCredential, this claim requests the user to present a digital asset (like an NFT) that meets specific criteria.
Key Parameters
Property | Type | Description |
|---|---|---|
|
| An array of filter objects used to find matching assets in the wallet. The logic is the same as for VCs. |
|
| (Inside a filter) An array of DIDs of the asset's original minters. |
|
| (Inside a filter) An array of DIDs of parent assets, for factory-created assets. |
|
| (Inside a filter) The specific DID address of the asset being requested. |
Example: Requesting an NFT from a specific collection
const claims = {
asset: {
description: 'Please present your DevCon Ticket NFT to enter.',
filters: [
{
trustedIssuers: ['zNKjDm4Xsoaffb19UE6QxVeevuaTaLCS1n1S'], // The issuer of the NFT collection
},
],
},
};Other Claim Types#
agreement: Asks the user to agree to terms, typically by hashing a document at a given URI and signing it.assetOrVC: A flexible claim that allows the user to present either an asset or a VC that matches the provided filters.keyPair: Requests the wallet to generate a new key pair for a specific purpose (e.g., creating a new application account for the user).encryptionKey: Requests the wallet to derive an encryption key, enabling a secure, end-to-end encrypted communication channel between the application and the wallet.
Dynamic Claims#
Instead of a static object, you can define a claim as a function. This function receives context about the current session (e.g., userDid, userPk) and dynamically returns the claim object. This is useful when claim parameters depend on the user who is authenticating.
Example
const { fromPublicKey } = require('@ocap/wallet');
const client = new Client('https://beta.abtnetwork.io/api');
const claims = {
signature: async ({ userDid, userPk }) => {
// Dynamically create a transaction for the specific user
const { buffer } = await client.encodeTransferV2Tx({
tx: {
from: userDid,
pk: userPk,
itx: {
to: 'z123...recipient...abc',
value: '100',
},
},
wallet: fromPublicKey(userPk),
});
return {
typeUrl: 'fg:t:transaction',
description: 'Sign this transaction to confirm.',
origin: toBase58(buffer),
};
},
};Now that you understand the different types of claims available, you can build powerful and flexible authentication flows. For practical implementation examples, see our How-to Guides, such as Request a Signature. For a detailed breakdown of every field in each claim, refer to the Schemas API Reference.