Skip to content

feat: ecdsa and w3c data model 2.0 #105

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

Merged
rongquan1 merged 22 commits into from
Aug 25, 2025
Merged

feat: ecdsa and w3c data model 2.0 #105

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
22 commits
Select commit Hold shift + click to select a range
7cc1891
chore: back merge (#75)
nghaninn Jun 30, 2025
5690fcd
feat: token registry functions (#74)
RishabhS7 Jun 30, 2025
73847b7
chore(release): 1.6.0-alpha.1 [skip ci]
semantic-release-bot Jun 30, 2025
2ea52ce
feat: mint function (#78)
RishabhS7 Jul 4, 2025
81d0e36
feat: owner of function (#79)
RishabhS7 Jul 15, 2025
e0d1a77
chore(release): 1.6.0-alpha.2 [skip ci]
semantic-release-bot Jul 15, 2025
145e763
chore: e2e transfers tests (#82)
RishabhS7 Jul 17, 2025
58a8da2
chore: e2e tests reject transfer (#83)
RishabhS7 Jul 17, 2025
703be01
fix: e2e return token tests (#84)
RishabhS7 Jul 17, 2025
de2073b
chore(release): 1.6.0-alpha.3 [skip ci]
semantic-release-bot Jul 18, 2025
b81b422
chore: merge main into v1 (#85)
Moiz47 Jul 23, 2025
d2fb6fb
fix: trigger release (#86)
Moiz47 Jul 23, 2025
bc7405b
chore(release): 1.6.0-alpha.4 [skip ci]
semantic-release-bot Jul 23, 2025
b54b146
chore: rebase v1 with main (#95)
Moiz47 Jul 30, 2025
484e1ff
chore: ecdsa w3c verify (#100)
RishabhS7 Aug 15, 2025
3270cc6
fix: add w3c version detection function (#103)
RishabhS7 Aug 19, 2025
60ac708
chore(release): 1.6.0-alpha.5 [skip ci]
semantic-release-bot Aug 19, 2025
7b8a012
feat: update sign and derive method (#101)
Moiz47 Aug 20, 2025
30c0d67
chore(release): 1.6.0-alpha.6 [skip ci]
semantic-release-bot Aug 20, 2025
f04f153
feat: update document builder to data model 2.0 (#104)
Moiz47 Aug 22, 2025
51d0177
chore(release): 1.6.0-alpha.7 [skip ci]
semantic-release-bot Aug 22, 2025
04ca51b
breaking change: ecdsa and w3c data model 2.0
rongquan1 Aug 25, 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
192 changes: 144 additions & 48 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -16,15 +16,16 @@ TrustVC is a comprehensive wrapper library designed to simplify the signing and
- [2. **Signing**](#2-signing)
- [a) OpenAttestation Signing (signOA) v2 v3](#a-openattestation-signing-signoa-v2-v3)
- [b) TrustVC W3C Signing (signW3C)](#b-trustvc-w3c-signing-signw3c)
- [3. **Verifying**](#3-verifying)
- [4. **Encryption**](#4-encryption)
- [5. **Decryption**](#5-decryption)
- [6. **TradeTrust Token Registry**](#6-tradetrust-token-registry)
- [3. **Deriving (Selective Disclosure)**](#3-deriving-selective-disclosure)
- [4. **Verifying**](#4-verifying)
- [5. **Encryption**](#5-encryption)
- [6. **Decryption**](#6-decryption)
- [7. **TradeTrust Token Registry**](#7-tradetrust-token-registry)
- [Usage](#usage-2)
- [TradeTrustToken](#tradetrusttoken)
- [a) Token Registry v4](#a-token-registry-v4)
- [b) Token Registry V5](#b-token-registry-v5)
- [7. **Document Builder**](#7-document-builder)
- [8. **Document Builder**](#8-document-builder)

## Installation

Expand Down Expand Up @@ -154,15 +155,17 @@ const signedWrappedDocument = await signOA(wrappedDocument, {

#### b) TrustVC W3C Signing (signW3C)

The `signW3C` function signs W3C Verifiable Credentials using the provided cryptographic suite and key pair. By default, it uses the **ecdsa-sd-2023** crypto suite unless otherwise specified.

```ts
import { signW3C, VerificationType } from '@trustvc/trustvc';

const rawDocument = {
'@context': [
'https://www.w3.org/2018/credentials/v1',
'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v1.jsonld',
'https://w3id.org/security/bbs/v1',
'https://www.w3.org/ns/credentials/v2',
'https://w3id.org/security/data-integrity/v2',
'https://w3id.org/vc/status-list/2021/v1',
'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld',
],
credentialStatus: {
id: 'https://trustvc.github.io/did/credentials/statuslist/1#1',
Expand All @@ -172,29 +175,113 @@ const rawDocument = {
statusListCredential: 'https://trustvc.github.io/did/credentials/statuslist/1',
},
credentialSubject: {
name: 'TrustVC',
type: ['Person']
givenName: 'TrustVC',
birthDate: '2024-04-01T12:19:52Z',
type: ['PermanentResident', 'Person'],
},
Comment on lines +178 to 181

@coderabbitai coderabbitai Bot Aug 25, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

Fix syntax in rawDocument: missing comma after credentialSubject.type.

The sample as-is is invalid TS/JSON.

Apply:

-  credentialSubject: {
-    type: ['Person']
-    givenName: 'TrustVC',
+  credentialSubject: {
+    type: ['Person'],
+    givenName: 'TrustVC',
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
type: ['Person']
givenName: 'TrustVC',
birthDate: '2024-04-01T12:19:52Z',
type: ['PermanentResident', 'Person'],
},
credentialSubject: {
type: ['Person'],
givenName: 'TrustVC',
birthDate: '2024-04-01T12:19:52Z',
},
🤖 Prompt for AI Agents 
In README.md around lines 178 to 181, the sample rawDocument is invalid because
there's no comma after credentialSubject.type; add a trailing comma after the
line "type: ['Person']" (and verify surrounding punctuation/quotes) so the
object is valid TS/JSON, then run a quick linter/JSON parse to confirm the
snippet parses correctly.

expirationDate: '2029-12-03T12:19:52Z',
issuer: 'did:web:trustvc.github.io:did:1',
type: ['VerifiableCredential'],
issuanceDate: '2024-04-01T12:19:52Z',
validFrom: '2024-04-01T12:19:52Z',
validUntil: '2029-12-03T12:19:52Z'
};

// Using default ecdsa-sd-2023 crypto suite
const signingResult = await signW3C(rawDocument, {
id: 'did:web:trustvc.github.io:did:1#keys-1',
'@context': 'https://w3id.org/security/multikey/v1',
id: 'did:web:trustvc.github.io:did:1#multikey-1',
type: VerificationType.Multikey,
controller: 'did:web:trustvc.github.io:did:1',
type: VerificationType.Bls12381G2Key2020,
publicKeyBase58:
'oRfEeWFresvhRtXCkihZbxyoi2JER7gHTJ5psXhHsdCoU1MttRMi3Yp9b9fpjmKh7bMgfWKLESiK2YovRd8KGzJsGuamoAXfqDDVhckxuc9nmsJ84skCSTijKeU4pfAcxeJ',
privateKeyBase58: '<privateKeyBase58>',
publicKeyMultibase: 'zDnaemDNwi4G5eTzGfRooFFu5Kns3be6yfyVNtiaMhWkZbwtc',
secretKeyMultibase: '<secretKeyMultibase>'
});

// You can also specify mandatory pointers for selective disclosure with ecdsa-sd-2023
const signingResultWithPointers = await signW3C(
rawDocument,
{
'@context': 'https://w3id.org/security/multikey/v1',
id: 'did:web:trustvc.github.io:did:1#multikey-1',
type: VerificationType.Multikey,
controller: 'did:web:trustvc.github.io:did:1',
publicKeyMultibase: 'zDnaemDNwi4G5eTzGfRooFFu5Kns3be6yfyVNtiaMhWkZbwtc',
secretKeyMultibase: '<secretKeyMultibase>'
},
'ecdsa-sd-2023',
{
mandatoryPointers: ['/credentialStatus']
}
);

// Alternatively, specify a different crypto suite. Ensure the context is updated to include the crypto suite.
const signingResultWithBbs = await signW3C(
rawDocument,
{
id: 'did:web:trustvc.github.io:did:1#keys-1',
controller: 'did:web:trustvc.github.io:did:1',
type: VerificationType.Bls12381G2Key2020,
publicKeyBase58: 'oRfEeWFresvhRtXCkihZbxyoi2JER7gHTJ5psXhHsdCoU1MttRMi3Yp9b9fpjmKh7bMgfWKLESiK2YovRd8KGzJsGuamoAXfqDDVhckxuc9nmsJ84skCSTijKeU4pfAcxeJ',
privateKeyBase58: '<privateKeyBase58>',
},
'BbsBlsSignature2020'
);
Comment on lines +216 to +226

@coderabbitai coderabbitai Bot Aug 25, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue

BBS+ example lacks the required security context and still reuses the ECDSA-oriented rawDocument.

For BbsBlsSignature2020, include https://w3id.org/security/bbs/v1 and avoid passing multikey fields. Provide a BBS-specific raw document or override contexts in the call.

Apply:

-const signingResultWithBbs = await signW3C(
-  rawDocument,
+// Use a BBS-specific raw document with the BBS context
+const rawDocumentBbs = {
+  ...rawDocument,
+  '@context': [
+    'https://www.w3.org/ns/credentials/v2',
+    'https://w3id.org/security/bbs/v1',
+    'https://w3id.org/vc/status-list/2021/v1',
+    'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld',
+  ],
+};
+const signingResultWithBbs = await signW3C(
+  rawDocumentBbs,
   {
     id: 'did:web:trustvc.github.io:did:1#keys-1',
     controller: 'did:web:trustvc.github.io:did:1',
     type: VerificationType.Bls12381G2Key2020,
     publicKeyBase58: 'oRfEeWFresvhRtXCkihZbxyoi2JER7gHTJ5psXhHsdCoU1MttRMi3Yp9b9fpjmKh7bMgfWKLESiK2YovRd8KGzJsGuamoAXfqDDVhckxuc9nmsJ84skCSTijKeU4pfAcxeJ',
     privateKeyBase58: '<privateKeyBase58>',
   },
   'BbsBlsSignature2020'
 );
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
const signingResultWithBbs = await signW3C(
rawDocument,
{
id: 'did:web:trustvc.github.io:did:1#keys-1',
controller: 'did:web:trustvc.github.io:did:1',
type: VerificationType.Bls12381G2Key2020,
publicKeyBase58: 'oRfEeWFresvhRtXCkihZbxyoi2JER7gHTJ5psXhHsdCoU1MttRMi3Yp9b9fpjmKh7bMgfWKLESiK2YovRd8KGzJsGuamoAXfqDDVhckxuc9nmsJ84skCSTijKeU4pfAcxeJ',
privateKeyBase58: '<privateKeyBase58>',
},
'BbsBlsSignature2020'
);
// Use a BBS-specific raw document with the BBS context
const rawDocumentBbs = {
...rawDocument,
'@context': [
'https://www.w3.org/ns/credentials/v2',
'https://w3id.org/security/bbs/v1',
'https://w3id.org/vc/status-list/2021/v1',
'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld',
],
};
const signingResultWithBbs = await signW3C(
rawDocumentBbs,
{
id: 'did:web:trustvc.github.io:did:1#keys-1',
controller: 'did:web:trustvc.github.io:did:1',
type: VerificationType.Bls12381G2Key2020,
publicKeyBase58: 'oRfEeWFresvhRtXCkihZbxyoi2JER7gHTJ5psXhHsdCoU1MttRMi3Yp9b9fpjmKh7bMgfWKLESiK2YovRd8KGzJsGuamoAXfqDDVhckxuc9nmsJ84skCSTijKeU4pfAcxeJ',
privateKeyBase58: '<privateKeyBase58>',
},
'BbsBlsSignature2020'
);
🤖 Prompt for AI Agents 
In README.md around lines 216 to 226, the BBS+ example is incorrect: it reuses
an ECDSA-oriented rawDocument and omits the BBS security context. Replace the
rawDocument with a BBS-compatible document (remove multikey fields like
ECDSA-specific publicKey entries) or pass an explicit context override that
includes "https://w3id.org/security/bbs/v1" and any BBS proof-specific contexts,
and update the verification key metadata to the BLS key shape (no ECDSA fields)
before calling signW3C with proof type "BbsBlsSignature2020".


```

---

### 3. **Deriving (Selective Disclosure)**

> When using ECDSA-SD-2023 crypto suite, we can derive a new credential with selective disclosure. This means you can choose which parts of the credential to reveal while keeping others hidden.

```ts
import { deriveW3C } from '@trustvc/trustvc';

// This is a signed document using ecdsa-sd-2023
const signedDocument = {
'@context': [
'https://www.w3.org/ns/credentials/v2',
'https://w3id.org/security/data-integrity/v2',
'https://w3id.org/vc/status-list/2021/v1',
'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld'
],
credentialStatus: {
id: 'https://trustvc.github.io/did/credentials/statuslist/1#1',
type: 'StatusList2021Entry',
statusPurpose: 'revocation',
statusListIndex: '10',
statusListCredential: 'https://trustvc.github.io/did/credentials/statuslist/1'
},
credentialSubject: {
type: ['Person'],
givenName: 'TrustVC',
birthDate: '2024-04-01T12:19:52Z'
},
issuer: 'did:web:trustvc.github.io:did:1',
type: ['VerifiableCredential'],
validFrom: '2024-04-01T12:19:52Z',
validUntil: '2029-12-03T12:19:52Z',
id: 'urn:uuid:0198bd9e-6686-7ccd-9b2a-ce763ae710d7',
proof: {
type: 'DataIntegrityProof',
created: '2025-08-18T14:38:51Z',
verificationMethod: 'did:web:trustvc.github.io:did:1#multikey-1',
cryptosuite: 'ecdsa-sd-2023',
proofPurpose: 'assertionMethod',
proofValue: 'u2V0AhVhAxfLFkbv8J_O3zJAQrSWrEY3sgeMwN02b2eaHEgjnJYu1rnCBYORfZUVZwRoRuNIiY1NTGHmQpzlgqtQz7A0R3FgjgCQDzt3_aUvSMrlIZdsyVcB4KPHHjA4BbSv-PZ4Bbm4GpY5YIA1mQ8LYmpjJ7vNvN3DsfIengZrnziTLO9exbZjn1KqFilhA0lp1y6BZ-fhiUdWsojYesLDSzCy6Tq_AICaIvCjYSJMEaY7SomJnCkdpuhM0GQHDTy5kjzb7sSzowACqDDf9OVhAfOC7vg4WQGrI6M3dvLZW3KlBzp1SurRz1PPeHcqOGEDrqybzIlolwNXMhc2T8rcVLl-E04wNsiVjamvqWAQN-lhA4HmVqIxKuR0QvCMEVq3cjUU7G1pQbgMdp9HZDasOT9nh_k5l3JfcXB1_qtRblljXWN0FRKAr9T-DhxzDzGl3-lhA4nNDzd-6xl74rWqr_7U9XZE7LoE-mbgBsyOAOlfHGumMxwddnEZp2iD2uZ7lLXX8Q-nSDXJVvUqKLksy1l2vqVhAm3daNYjH1kVrTW7V-DElcj3K_QfbHEvjd1F2TGVGtBVhF8o01yCxXRX0vzk-AZLZnpDnAUBTSTF5Q8rF-t7L9lhAO7NeIXQtQsdncqtLm2qk1XzFYL2FM5Hx4GZOX39VyT4T0AlFRZQuY9WXYnvMZSvacRvJaSJk5S3cZ6uBminQgVhAExuTEvJQu42-SiaOJ_6M0EjuQfqIgJE-JHirmYs3AAoH_4EKUtPU3y_jRB8XFZxA-wtFDv3KJjqXtNo5aA_6f1hAaokZPSJghFufTaVR8LAwHpXOncGJblKpUZQjKWuA_o2s6tGmx-ja0wgpsqSxvAGMTtkhFTMOI2-tzUuGE05tk1hAzABtV2yEX-RAQFpxkuV0XydAsJDh2dPscrpPHqMfmORsC3xRNL73uDaqqlaL99CvOgq4kJWmChw7TUYO62yaSVhA5-F-snwj-OZtws7_qMwvBgeNK9wvkZTlFLjRV6GDYx6r5TaLkR05GVzyBMv0Qs2z-cXPRZByS7p7_hbeykoYSYJnL2lzc3VlcmovdmFsaWRGcm9t'
}
};

// Derive a new credential with only specific fields disclosed
const derivationResult = await deriveW3C(signedDocument, {
// Only reveal the credential type and givenName, hide birthDate
selectivePointers: ['/type', '/credentialSubject/givenName']
});

Comment on lines +232 to +279

@coderabbitai coderabbitai Bot Aug 25, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Verification agent

🧩 Analysis chain

Selective disclosure options name alignment (deriveW3C).

Double-check the parameter name “selectivePointers” matches the actual deriveW3C options type exported from src/w3c/derive.ts. If the library expects “revealedAttributes” or “revealPaths”, this example will confuse users.

Run:

If needed, I can patch the README to the correct option name. Do you want me to generate that diff?

🏁 Script executed:

#!/bin/bash
# Confirm deriveW3C options type and property names
rg -nP --type=ts -C2 '\bexport\s+async\s+function\s+deriveW3C\s*\('
rg -nP --type=ts -C3 'interface\s+.*(Derive|Selective).*Options|type\s+.*(Derive|Selective).*Options'

Length of output: 173

🏁 Script executed:

#!/bin/bash
# Search for deriveW3C function definition and its option type in TypeScript files
rg -n --type ts "deriveW3C" -C5
rg -n --type ts "interface.*Options" -C3
rg -n --type ts "type.*Options" -C3

Length of output: 7644

Update README to use the correct deriveW3C parameter

The deriveW3C function (in src/w3c/derive.ts) takes two positional arguments—credential and a revealedAttributes parameter of type ContextDocument | string[]. It does not accept an options object with a selectivePointers field. To selectively disclose ECDSA-SD-2023 fields, pass an array of JSON Pointers directly.

• Location: README.md (around lines 232–279)
• Change the deriveW3C example to pass the pointer array instead of { selectivePointers: […] }

Suggested diff:

- // Derive a new credential with only specific fields disclosed
- const derivationResult = await deriveW3C(signedDocument, {
-   // Only reveal the credential type and givenName, hide birthDate
-   selectivePointers: ['/type', '/credentialSubject/givenName']
- });
+ // Derive a new credential with only specific fields disclosed
+ const derivationResult = await deriveW3C(
+   signedDocument,
+   // Only reveal the credential type and givenName, hide birthDate
+   ['/type', '/credentialSubject/givenName']
+ );

This aligns the example with the actual signature:

export const deriveW3C = async (
  credential: SignedVerifiableCredential,
  revealedAttributes: ContextDocument | string[],
): Promise<DerivedResult> => { … }
🤖 Prompt for AI Agents 
README.md around lines 232 to 279: the example calls deriveW3C with an options
object { selectivePointers: [...] } but deriveW3C expects the second positional
argument to be a ContextDocument | string[] of JSON Pointers; update the README
example to call deriveW3C(signedDocument,
['/type','/credentialSubject/givenName']) (i.e. pass the pointer array directly
as the second argument) and remove the options object wrapper so the example
matches the function signature in src/w3c/derive.ts.

```

---

### 3. **Verifying**
### 4. **Verifying**

> TrustVC simplifies the verification process with a single function that supports both W3C Verifiable Credentials (VCs) and OpenAttestation Verifiable Documents (VDs). Whether you're working with W3C standards or OpenAttestation standards, TrustVC handles the verification seamlessly.

Expand Down Expand Up @@ -239,7 +326,7 @@ const resultFragments = await verifyDocument(signedDocument);

---

### 4. **Encryption**
### 5. **Encryption**

> The `encrypt` function encrypts plaintext messages using the **ChaCha20** encryption algorithm, ensuring the security and integrity of the input data. It supports custom keys and nonces, returning the encrypted message in hexadecimal format.

Expand Down Expand Up @@ -316,7 +403,7 @@ It also relies on the `ts-chacha20` library for encryption operations.

---

### 5. **Decryption**
### 6. **Decryption**

> The `decrypt` function decrypts messages encrypted with the **ChaCha20** algorithm. It converts the input from a hexadecimal format back into plaintext using the provided key and nonce.

Expand Down Expand Up @@ -399,7 +486,7 @@ It also relies on the `ts-chacha20` library for decryption operations.

---

### 6. **TradeTrust Token Registry**
### 7. **TradeTrust Token Registry**

> The Electronic Bill of Lading (eBL) is a digital document that can be used to prove the ownership of goods. It is a standardized document that is accepted by all major shipping lines and customs authorities. The [Token Registry](https://github.com/TradeTrust/token-registry) repository contains both the smart contract (v4 and v5) code for token registry (in `/contracts`) as well as the node package for using this library (in `/src`).
> The TrustVC library not only simplifies signing and verification but also imports and integrates existing TradeTrust libraries and smart contracts for token registry (V4 and V5), making it a versatile tool for decentralized identity and trust solutions.
Expand Down Expand Up @@ -589,8 +676,8 @@ function rejectTransferOwners(bytes calldata _remark) external;

For more information on Token Registry and Title Escrow contracts **version v5**, please visit the readme of [TradeTrust Token Registry V5](https://github.com/TradeTrust/token-registry/blob/master/README.md)

### 7. **Document Builder**
> The `DocumentBuilder` class helps build and manage W3C Verifiable Credentials (VCs) with credential status features. It supports creating documents with two types of credential statuses: `transferableRecords` and `verifiableDocument`. It can sign the document using a private key, verify its signature, and serialize the document to a JSON format. Additionally, it allows for configuration of document rendering methods and expiration dates.
### 8. **Document Builder**
> The `DocumentBuilder` class helps build and manage W3C Verifiable Credentials (VCs) with credential status features, implementing the **W3C VC Data Model 2.0** specification. It supports creating documents with two types of credential statuses: `transferableRecords` and `verifiableDocument`. It can sign the document using a private key, verify its signature, and serialize the document to a JSON format. Additionally, it allows for configuration of document rendering methods and expiration dates.

#### Usage

Expand All @@ -603,7 +690,7 @@ To learn more about defining custom contexts, check out the [Credential Subject
// Adds a custom vocabulary used to define terms in the `credentialSubject`.
// Users can define their own context if they have domain-specific fields or custom data structures.
const builder = new DocumentBuilder({
'@context': 'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v1.jsonld'
'@context': 'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld'
});
```
Comment on lines +693 to 695

@coderabbitai coderabbitai Bot Aug 25, 2025

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🛠️ Refactor suggestion

DocumentBuilder base @context likely needs VC v2 and Data Integrity contexts.

Using only the citizenship vocab context may yield an invalid VC unless the builder injects defaults. To be explicit and copy-paste friendly, include VC v2 and DI v2 here.

Apply:

-const builder = new DocumentBuilder({
-  '@context': 'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld'
-});
+const builder = new DocumentBuilder({
+  '@context': [
+    'https://www.w3.org/ns/credentials/v2',
+    'https://w3id.org/security/data-integrity/v2',
+    'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld',
+  ],
+});
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
'@context': 'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld'
});
```
const builder = new DocumentBuilder({
'@context': [
'https://www.w3.org/ns/credentials/v2',
'https://w3id.org/security/data-integrity/v2',
'https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld',
],
});
🤖 Prompt for AI Agents 
In README.md around lines 693 to 695, the DocumentBuilder example sets
'@context' to only the citizenship-v2 JSON-LD context which can produce an
invalid Verifiable Credential; update the example so the base '@context' is an
array that explicitly includes the W3C Verifiable Credentials v2 context and the
Data Integrity v2 context in addition to the citizenship-v2 context (preserve
order with VC v2 first, DI v2 next, then the citizenship vocab) so the snippet
is copy-paste friendly and produces a valid VC.


Expand All @@ -612,8 +699,8 @@ Set the subject of the Verifiable Credential, which typically contains informati

```ts
builder.credentialSubject({
id: 'did:example:123',
name: 'John Doe',
type: ['Person'],
givenName: 'TrustVC',
});
```

Expand Down Expand Up @@ -649,7 +736,7 @@ builder.credentialStatus({
```

##### Set Expiration Date
You can set an expiration date for the document.
You can set a valid until date (expiration) for the document.

```ts
builder.expirationDate('2026-01-01T00:00:00Z');
Expand Down Expand Up @@ -677,16 +764,17 @@ builder.qrCode({
```

##### Sign the Document
To sign the document, provide a `PrivateKeyPair` from `@trustvc/trustvc`.
To sign the document, provide a `PrivateKeyPair` from `@trustvc/trustvc`. The builder uses ECDSA key for signing by default.

```ts
const privateKey: PrivateKeyPair = {
id: 'did:example:456#key1',
controller: 'did:example:456',
type: VerificationType.Bls12381G2Key2020,
publicKeyBase58: 'your-public-key-base58',
privateKeyBase58: 'your-private-key-base58',
};
'@context': 'https://w3id.org/security/multikey/v1',
id: 'did:web:example.com#multikey-1',
type: VerificationType.Multikey,
controller: 'did:web:example.com',
publicKeyMultibase: 'your-public-key-multibase',
secretKeyMultibase: 'your-secret-key-multibase',
}

const signedDocument = await builder.sign(privateKey);
console.log(signedDocument);
Expand All @@ -696,19 +784,18 @@ Example Output After Signing
```json
{
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v1.jsonld",
"https://w3id.org/vc/status-list/2021/v1",
"https://trustvc.io/context/render-method-context.json",
"https://www.w3.org/ns/credentials/v2",
"https://w3c-ccg.github.io/citizenship-vocab/contexts/citizenship-v2.jsonld",
"https://trustvc.io/context/render-method-context-v2.json",
"https://trustvc.io/context/qrcode-context.json",
"https://w3id.org/security/bbs/v1"
"https://w3id.org/security/data-integrity/v2"
],
"type": ["VerifiableCredential"],
"credentialSubject": {
"id": "did:example:123",
"name": "John Doe"
"type": ["Person"],
"givenName": "TrustVC",
},
"expirationDate": "2026-01-01T00:00:00Z",
"validUntil": "2026-01-01T00:00:00Z",
"renderMethod": [
{
"id": "https://example.com/rendering-method",
Expand All @@ -727,21 +814,30 @@ Example Output After Signing
"statusListIndex": "<placeholder>",
"statusListCredential": "https://example.com/status-list"
},
"issuer": "did:example:456",
"issuanceDate": "2025-01-01T00:00:00Z",
"issuer": "did:web:example.com",
"validFrom": "2025-01-01T00:00:00Z",
"id": "urn:bnid:_:0195fec2-4ae1-7cca-9182-03fd7da5142b",
"proof": {
"type": "BbsBlsSignature2020",
"type": "DataIntegrityProof",
"created": "2025-01-01T00:00:01Z",
"verificationMethod": "did:web:example.com#multikey-1",
"cryptosuite": "ecdsa-sd-2023",
"proofPurpose": "assertionMethod",
"proofValue": "rV56L+QYozATRy3GOVLomzUo99sXtw2x0Cy9dEkHJ15wi4cS12cQJRIwzONVi3YscdhaSKoqD1jWmwb5A/khLZnDq5eo3QzDgTVClYuV86opL3HJyoS4+t2rRt3wl+chnATy2jqr5zMEvcVJ3gdXpQ==",
"verificationMethod": "did:example:456#key1"
"proofValue": "u2V0AhVhAh1oLoiuV2AwmSa2ZspbmrG2gCDbpZW.......",
}
}
```

##### Deriving the Document
Provide the attributes to reveal to the `derive` method.

```ts
const derivedDocument = await builder.derive(['/credentialSubject/givenName']);
console.log(derivedDocument);
```

##### Verify the Document
To verify the signature of the signed document:
To verify the signature of the signed document, ensure the document is derived first and then call the `verify` method.

```ts
const isVerified = await builder.verify();
Expand Down
Loading