Schemas

The did-auth library uses a set of robust schemas, built with Joi, to validate the structure and data types of configuration and request objects. This ensures that communication between your application and the user's wallet is reliable and predictable. This guide provides a comprehensive reference for the appInfo, chainInfo, and all supported claim type schemas.

appInfo Schema#

The appInfo object describes your application to the DID Wallet, which typically displays this information to the user for confirmation. It helps users understand which application is requesting their information.

Field	Type	Required	Description
name	string	Yes	The name of your application.
description	string	Yes	A brief description of your application.
icon	string (URI)	Yes	A URL to your application's icon. Must be an http or https URI.
link	string (URI)	No	A URL to your application's homepage.
path	string (URI)	No	The base URL for the wallet to display when linking back. Defaults to https://abtwallet.io/i/.
publisher	string (DID)	No	The DID of the application publisher.
updateSubEndpoint	boolean	No	Flag to indicate if the subscription endpoint should be updated.
subscriptionEndpoint	string	No	The endpoint for subscription updates.
nodeDid	string (DID)	No	The DID of the node associated with the application.
agentDid	string (DID)	No	The DID of the agent handling requests.

Example appInfo Object

chainInfo Schema#

The chainInfo object specifies the blockchain context for an authentication request. This is crucial for multi-chain applications, as it tells the wallet which network to target for operations like transaction signing or asset verification.

Field	Type	Default	Description
type	string	arcblock	The type of blockchain. Supported values: arcblock, ethereum, solona.
id	string	none	The chain ID. For ethereum and solona, this must be a string containing only numbers.
host	string	none	The endpoint of the chain's RPC/API. For arcblock, it must be a valid http or httpshttps URI or 'none'. For other chains, it can be any string.

Schema Logic

• If no chainInfo is provided, it defaults to { "type": "arcblock", "id": "none", "host": "none" }.
• For ethereum and solona types, the id field is required and must be a numeric string.

Example Configurations

claims Schemas#

Claims define the specific information or actions you are requesting from the user's wallet. You can request one or more claims in a single authentication request. Each claim object must include a type field that specifies the kind of claim.

Common Fields#

All claim types share a set of common fields that are added by the createStandardFields factory function.

Field	Description
type	The type of the claim (e.g., 'profile', 'signature').
description	A human-readable text displayed to the user in the wallet.
chainInfo	An optional chainInfo object to specify a different chain context for just this claim.
meta	An optional field to pass any extra metadata. Defaults to {}.

authPrincipal#

Requests the user to select an account (DID) from their wallet to authenticate and continue.

Field	Type	Default	Description
target	string (DID)	''	Suggest a specific DID for the user to select.
supervised	boolean	false	Indicates if the requested DID should be supervised (e.g., a child account).
targetType	object	{ key: 'ed25519', ... }	Specifies the cryptographic properties (key, hash, role, encoding) of the desired DID.

Example authPrincipal Claim

profile#

Requests specific pieces of profile information associated with the user's DID.

Field	Type	Default	Description
items	array of strings	['fullName']	An array specifying the profile items to request. The property was previously named fields.

Available items did, fullName, email, phone, signature, avatar, birthday, url

Example profile Claim

signature#

Requests the user to sign a piece of data, such as a message, transaction, or delegation.

Field	Type	Required	Description
typeUrl	string	Yes	Specifies the type of data being signed. Determines how the wallet interprets and displays the data. See valid values below.
display	string	No	A human-readable string representation of the data to be signed.
method	string	No	The hashing algorithm to use before signing. Defaults to sha3. Can be none.
digest	string	No	The pre-computed digest of the data to be signed.
origin	string	No	The origin URL of the request, for display and security purposes.
nonce	string	No	A nonce to prevent replay attacks.
requirement	object	No	Specifies token or asset requirements the user must meet to perform the signature.

Valid typeUrl Values

• fg:x:delegation
• fg:t:transaction
• mime:text/plain
• mime:text/html
• eth:transaction
• eth:standard-data
• eth:personal-data
• eth:typed-data
• eth:legacy-data

Example signature Claim

verifiableCredential#

Requests the user to present one or more Verifiable Credentials (VCs) that match specified criteria.

Field	Type	Default	Description
optional	boolean	false	If true, the user can skip this step.
filters	array of objects	[]	An array of filter objects. The user must provide a VC that matches at least one (OR) filter object in the array.

Filter Object Properties All properties within a single filter object are combined with an AND condition.

Field	Type	Description
type	array of strings	An array of acceptable VC type schemas.
target	string (DID)	A specific VC DID to request.
trustedIssuers	array	An array of trusted issuer DIDs. See format below.
tag	string	A tag to match against the VC's metadata.
ownerDid	array of DIDs	An array of acceptable owner DIDs.
claimUrl	string (URI)	A URL where the credential proof can be submitted or verified.
acquireUrl	string (URI)	A URL where the user can acquire the required credential if they don't have it.

trustedIssuers Format An item in the trustedIssuers array can be either a DID string or an object containing the issuer's DID and endpoint.

Example verifiableCredential Claim This example requests a Certificate VC issued by either of two trusted issuers.

asset#

Requests the user to present a non-fungible asset (NFT) that matches specific criteria. The structure is very similar to the verifiableCredential claim.

Field	Type	Default	Description
optional	boolean	false	If true, the user can skip this step.
filters	array of objects	[]	An array of filter objects. The user must provide an asset that matches at least one (OR) filter object.

Filter Object Properties All properties within a single filter object are combined with an AND condition.

Field	Type	Description
address	string (DID)	The contract address of the asset.
trustedIssuers	array	An array of trusted issuer DIDs.
trustedParents	array of DIDs	An array of trusted parent collection DIDs.
tag	string	A tag to match against the asset's metadata.
ownerDid	array of DIDs	An array of acceptable owner DIDs.
consumed	boolean	Whether to request a consumed or unconsumed asset.
acquireUrl	string (URI)	A URL where the user can acquire the required asset.

Example asset Claim

Other Claim Types#

Claim Type	Description
agreement	Requests the user to agree to a document (e.g., Terms of Service) by confirming a hash of the document's content.
prepareTx	Asks the wallet to prepare a transaction for signing, often used when the dApp needs the wallet to contribute some information to the transaction before the user signs it.
assetOrVC	A flexible claim that allows requesting either an asset or a verifiable credential that matches the given filter criteria.
keyPair	Requests the wallet to generate a new key pair (a new DID). Useful for account creation flows.
encryptionKey	Requests the wallet to derive an encryption key from the user's secret key and a provided salt. Used for establishing an encrypted communication channel.

For more specific examples and advanced use cases, you can review the library's source code and tests. A good next step is to see how these schemas are used in practice by reviewing the Testing guide.