Skip to content

fix-js-sdk docs #244

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: develop
Choose a base branch
from
Open

fix-js-sdk docs #244

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
18bac02
fix-js-sdk docs
Nityam573 Jul 23, 2025
c37b88a
fix-wallet-docs
Nityam573 Jul 28, 2025
80a886a
fix typo
Nityam573 Aug 12, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
214 changes: 132 additions & 82 deletions docs/js-sdk/js-sdk-components/credential-wallet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: Credential Wallet
description: Credential Wallet components and capabilities.
keywords:
- docs
- polygon id
- privado id
- holder
- issuer
- verifier
Expand All @@ -14,156 +14,206 @@ keywords:
- credential
---

A Credential Wallet holds the credentials issued by the Issuer. The Credential Wallet is implemented with a Credential Interface that lets you interact with the credential storage.
A Credential Wallet manages credentials issued by issuers and provides secure storage and retrieval capabilities. The Credential Wallet is implemented through a Credential Interface that enables interaction with the underlying credential storage system.

The methods described below let you create and manage a credential wallet:
The methods described below enable you to create and manage credential wallets effectively:

## Get List of Credentials with list() method
## Credential Retrieval

This method retrieves a set of Verifiable Credentials in the W3C format:
### list()

Retrieves all stored Verifiable Credentials in W3C format from the wallet.

```typescript
list(): Promise<W3CCredential[]>;
```

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.list#credentialwalletlist-method" target="_blank">API Reference</a>.
**Returns:** An array of all W3C Verifiable Credentials stored in the wallet.

[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.list#credentialwalletlist-method)

## Save Credentials with save() method
### findByQuery()

This method saves the W3C Credentials to the database using upsert.
Searches for credentials using the Iden3 protocol's query language, enabling precise credential filtering based on multiple criteria.

```typescript
save(credential: W3CCredential): Promise<void>;
findByQuery(query: ProofQuery): Promise<W3CCredential[]>;
```

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.save#credentialwalletsave-method" target="_blank">API Reference</a>.

## Save All Credentials with saveAll() method

This method saves a batch of W3C Credentials to the database using upsert.
**Parameters:**
- `query`: Query object containing search criteria

**ProofQuery Interface:**
```typescript
saveAll(credentials: W3CCredential[]): Promise<void>;
export interface ProofQuery {
allowedIssuers?: string[]; // Authorized credential issuers
credentialSubject?: { [key: string]: unknown }; // Subject attributes to match
schema?: string; // JSON schema URL for credential validation
claimId?: string; // Specific credential identifier
credentialSubjectId?: string; // Subject's unique identifier
context?: string; // Credential context information
type?: string; // Credential type specification
}
```

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.saveall#credentialwalletsaveall-method" target="_blank">API Reference</a>.
**Query Parameters:**
- `allowedIssuers`: Array of issuer DIDs authorized to issue matching credentials
- `claimId`: Unique identifier of the target credential
- `credentialSubjectId`: Identifier of the credential subject (recipient)
- `type`: Specific credential type to filter by
- `schema`: JSON schema URL used for credential creation and validation
- `credentialSubject`: Subject attributes and claims to match against

## Remove Credential with remove() method
**Returns:** Array of W3C Verifiable Credentials matching the query criteria.

This method removes a W3C credential from data storage.
The returned credentials can be used for proof generation in verification scenarios.

:::info Query Language

Learn more about the Iden3 query language capabilities in the [Query Language documentation](https://docs.iden3.io/protocol/querylanguage/).

:::

[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.findbyquery#credentialwalletfindbyquery-method)

## Credential Storage

### save()

Stores a single W3C Verifiable Credential in the database using upsert operation (insert or update if exists).

```typescript
remove(id: string): Promise<void>;
save(credential: W3CCredential): Promise<void>;
```

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.remove#credentialwalletremove-method" target="_blank">API Reference</a>.
**Parameters:**
- `credential`: W3C Verifiable Credential to be stored

## Find Credentials with Query with findByQuery() method
**Operation:** Uses upsert logic to either insert new credentials or update existing ones based on credential identifier.

This method lets you find credentials using the Iden3 protocol's query language.
[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.save#credentialwalletsave-method)

```typescript
findByQuery(query: ProofQuery): Promise<W3CCredential[]>;
### saveAll()

Performs batch storage of multiple W3C Verifiable Credentials using upsert operations for improved performance.

```typescript
saveAll(credentials: W3CCredential[]): Promise<void>;
```

where `ProofQuery` can contain parameters including:
**Parameters:**
- `credentials`: Array of W3C Verifiable Credentials to be stored

- `allowedIssuers`: issuers that are allowed to issue a credential,
- `claimId`: ID of the credential issued,
- `credentialSubjectId : ID of the subject of the credential to whom a credential is issued,
- `type`: type of credential issued,
- `schema`: JSON schema used to create a credential,
- `credentialSubject`: subject of the credential to whom a credential is issued.
**Benefits:** Optimized for bulk operations, reducing database transaction overhead compared to multiple individual save operations.

This credential is then used to create a proof.
[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.saveall#credentialwalletsaveall-method)

### remove()

Permanently removes a specific W3C Verifiable Credential from storage.

```typescript
export interface ProofQuery {
allowedIssuers?: string[];
credentialSubject?: { [key: string]: unknown };
schema?: string; // string url
claimId?: string;
credentialSubjectId?: string;
context?: string;
type?: string;
}
remove(id: string): Promise<void>;
```

Read more on Query Language [here](https://docs.iden3.io/protocol/querylanguage/).
**Parameters:**
- `id`: Unique identifier of the credential to be removed

**Warning:** This operation is irreversible. Ensure proper backup procedures before credential removal.

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.findbyquery#credentialwalletfindbyquery-method" target="_blank">API Reference</a>.
[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.remove#credentialwalletremove-method)

## Retrieve Auth BJJ Credential with getAuthBJJCredential() method
## Authentication Credentials

This method allows you to retrieve a credential of Auth BJJ type for a specific user so that it can be used for signing.
### getAuthBJJCredential()

Retrieves the Auth Baby Jubjub credential for a specific user, enabling cryptographic signing operations.

```typescript
getAuthBJJCredential(did: DID): Promise<W3CCredential>;
getAuthBJJCredential(did: DID): Promise<W3CCredential>;
```

where `did` is the DID of the issuer that has issued the credential.
**Parameters:**
- `did`: DID of the credential holder (not the issuer)

**Returns:** W3C Verifiable Credential of Auth BJJ type, containing the public key and signing capabilities.

This method returns a Verifiable Credential of the type Auth BJJ.
**Use Case:** Essential for identity authentication and message signing within the Iden3 ecosystem.

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.getauthbjjcredential#credentialwalletgetauthbjjcredential-method" target="_blank">API Reference</a>.
[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.getauthbjjcredential#credentialwalletgetauthbjjcredential-method)

## Get Revocation Status for a Credential with getRevocationStatusFromCredential() method
## Revocation Status Management

This method retrieves or builds revocation status for a given credential.
### getRevocationStatusFromCredential()

Retrieves or constructs the current revocation status for a given credential, determining whether it remains valid.

```typescript
getRevocationStatusFromCredential(cred: W3CCredential): Promise<RevocationStatus>;
```

where `cred` is the Credential for which the revocation status is to be retrieved.
**Parameters:**
- `cred`: W3C Verifiable Credential to check for revocation

**Returns:** `RevocationStatus` indicating whether the credential is currently valid or has been revoked.

The method returns a revocation status of the credential (whether a credential is revoked or not). The credential status could be either the **SparseMerkleTreeProof** or **Iden3ReverseSparseMerkleTreeProof** (if Reverse Hash Service is used) type.
**Supported Status Types:**
- **SparseMerkleTreeProof**: Standard on-chain revocation verification
- **Iden3ReverseSparseMerkleTreeProof**: Revocation verification using Reverse Hash Service

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.getrevocationstatusfromcredential#credentialwalletgetrevocationstatusfromcredential-method" target="_blank">API Reference</a>.
[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.getrevocationstatusfromcredential#credentialwalletgetrevocationstatusfromcredential-method)

## Get Revocation Status Depending on Type of Credential Status with getRevocationStatus() method
### getRevocationStatus()

This method retrieves the revocation status for a given credential depending on the type of its credential status.
Retrieves revocation status based on the specific credential status type and configuration.

```typescript
/**
*
*
* @param {(CredentialStatus )} credStatus - credentialStatus field of the Verifiable Credential.
* @param {CredentialStatusResolveOptions} credentialStatusResolveOptions - options to resolve credential status
* @returns `Promise<RevocationStatus>`
*/
getRevocationStatus(
credStatus: CredentialStatus,
credentialStatusResolveOptions?: CredentialStatusResolveOptions
): Promise<RevocationStatus>;
getRevocationStatus(
credStatus: CredentialStatus,
credentialStatusResolveOptions?: CredentialStatusResolveOptions
): Promise<RevocationStatus>;
```

where `credStatus` is the credential status type: with or without Reverse Hash Service / Agent / Onchain.
**Parameters:**
- `credStatus`: Credential status configuration specifying the revocation checking method
- `credentialStatusResolveOptions`: (Optional) Additional resolution parameters

`credentialStatusResolveOptions` are:
**CredentialStatusResolveOptions:**
- `issuerDID`: DID of the credential issuer
- `userDID`: DID of the user requesting status verification
- `issuerData`: Issuer metadata from either Signature Proof (BJJ) or Iden3SparseMerkleTreeProof

- `issuerDID` is the DID of the Issuer.
- `userDID` is the DID of the user who retrieves the status.
- `issuerData` is the metadata related to an Issuer. This metadata is contained in either the Signature Proof (BJJ Signature Proof) or Iden3SparseMerkleTreeProof (Merkle Tree Proof).
**Supported Status Types:**
- Standard revocation checking (on-chain verification)
- Reverse Hash Service integration
- Agent-based status resolution
- On-chain status verification

The method returns the revocation status of the credential (a credential is revoked or not).
**Returns:** Current revocation status indicating credential validity.

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.getrevocationstatus#credentialwalletgetrevocationstatus-method" target="_blank">API Reference</a>.
[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.getrevocationstatus#credentialwalletgetrevocationstatus-method)

## Create a Credential using createCredential() method
## Credential Creation

This method creates a Verifiable Credential in the W3C format.
### createCredential()

Creates a new W3C Verifiable Credential based on provided specifications and JSON schema validation.

```typescript
createCredential(issuer: DID, request: CredentialRequest, schema: JSONSchema): W3CCredential;
createCredential(issuer: DID, request: CredentialRequest, schema: JSONSchema): W3CCredential;
```

where `Issuer` is the DID of the Issuer.
`request` is the specification for the credential creation parameters.
`schema` is the JSON schema used for creating a credential.
**Parameters:**
- `issuer`: DID of the credential issuer
- `request`: Credential creation specification containing subject data and requirements
- `schema`: JSON schema for credential structure validation and type definition

**Process:**
1. Validates the credential request against the provided JSON schema
2. Creates credential claims based on the request specifications
3. Formats the credential according to W3C Verifiable Credential standards
4. Returns the properly structured credential ready for issuance

The method returns a Verifiable Credential in the W3C format.
**Returns:** W3C-compliant Verifiable Credential ready for signing and issuance.

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.createcredential#credentialwalletcreatecredential-property" target="_blank">API Reference</a>.
[API Reference](https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.credentialwallet.createcredential#credentialwalletcreatecredential-property)
39 changes: 26 additions & 13 deletions docs/js-sdk/js-sdk-components/iden3comm.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,7 @@ sidebar_label: Iden3comm
description: Iden3comm components and capabilities.
keywords:
- docs
- polygon id
- privado id
- holder
- issuer
- verifier
Expand All @@ -17,13 +17,16 @@ keywords:
- revocation
---

Iden3comm is the implementation of the messages that exist in the Iden3 protocol. It deals with different protocol message types; a few messages supported by the protocol are related to authentication, credentials, proof, and revocation.
Iden3comm is the reference implementation for message handling within the Iden3 protocol. It processes various protocol message types, including authentication requests, credential operations, proof generation, and revocation management.

## Packers

Iden3comm supports packers that receive some data as payload and create an envelope for different types of messages.
Iden3comm uses packers to encapsulate payload data into protocol-specific message envelopes. These components transform raw data into standardized message formats for secure transmission.

The Iden3 protocol supports packers for messages of 2 media types: plain messages and zero-knowledge proof (ZKP) messages. These packers let you generate tokens.
The Iden3 protocol supports packers for messages of 2 media types: - **Plain messages**: Standard unencrypted message format
- **Zero-knowledge proof (ZKP) messages**: Cryptographically secured messages with privacy-preserving properties

These packers let you generate tokens.

### ZKP Packer

Expand Down Expand Up @@ -51,7 +54,7 @@ For the messages of the type **ZKP**, the packer receives a payload (a serialize

## Handler

In Iden3, a handler manages the packers described above. There are two types of handlers that the protocol supports: Authentication and Fetch Handlers.
In Iden3, a handler manages the packers and orchestrate message processing workflows. There are two types of handlers that the protocol supports: Authentication Handler and Fetch Handler.

### Authentication Handler

Expand Down Expand Up @@ -83,7 +86,7 @@ It gets the payload and an identity (that can handle that request) as the input

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.authhandler.handleauthorizationrequest" target="_blank">API Reference</a>.

:::note
:::note **Privacy Consideration**

When a user logs into a Verifier, it does not have to share its identity. Instead, it can share with it the profile as the user does not receive a credential on his/her identifier but on his/her profile. Sharing one's profile instead of his/her identity prevents the possible identity tracking by a Verifier.

Expand All @@ -100,23 +103,33 @@ handleCredentialOffer(
): Promise<W3CCredential[]>
```

The offer should just be passed to the function. The DID that is supposed to fetch the credential will be determined from the offer message itself.

`offer` is the offer message that the Fetch handler receives.
**Parameters:**
- `offer` is the offer message that the Fetch handler receives.

The handler returns a Verifiable Credential in the W3C format.
**Process:**
- Automatically determines the target DID from the offer message content
- Processes the offer and retrieves the credential from the issuer
- Returns verifiable credentials in W3C standard format

Read more about iden3comm [here](https://github.com/iden3/iden3comm/tree/main/protocol).

Click here for the <a href="https://0xpolygonid.github.io/js-sdk-tutorials/docs/api/js-sdk.fetchhandler.handlecredentialoffer#fetchhandlerhandlecredentialoffer-method" target="_blank">API Reference</a>.

If you want to work with JWS instead of JWZ technology during the authorization or credential fetching you need to pass parameters to these functions.
## Alternative Message Formats

For applications requiring JSON Web Signature (JWS) instead of JSON Web Zero-knowledge (JWZ) technology, you can specify alternative packer parameters:

```typescript
let params = {
const params = {
mediaType: MediaType;
packerOptions?: JWSPackerParams;
}
```

where `mediaType` is the media type of iden3comm protocol and `packerOptions` are JWS required parameters.
**Configuration:**
- `mediaType`: Specifies the iden3comm protocol media type
- `packerOptions`: JWS-specific parameters for signature-based authentication

## Additional Resources

For comprehensive protocol specifications and implementation details, refer to the [Iden3comm Protocol Documentation](https://github.com/iden3/iden3comm/tree/main/protocol).
Loading