Skip to content

feat: update document builder to data model 2.0 #104

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 5 commits into from
Aug 22, 2025
Merged

feat: update document builder to data model 2.0 #104

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
103d951
feat: update document builder to data model 2.0
moiz-sgtradex Aug 20, 2025
f375cba
feat: document builder readme update
moiz-sgtradex Aug 20, 2025
c39c3f3
feat: document builder update
moiz-sgtradex Aug 22, 2025
fd8337b
feat: document builder minor updates
moiz-sgtradex Aug 22, 2025
a5fa4cb
feat: mock OA document status verify
moiz-sgtradex Aug 22, 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
61 changes: 35 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -677,7 +677,7 @@ 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)

### 8. **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.
> 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 @@ -690,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'
});
```

Expand All @@ -699,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 @@ -736,7 +736,7 @@ builder.credentialStatus({
```

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

```ts
builder.expirationDate('2026-01-01T00:00:00Z');
Expand Down Expand Up @@ -764,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',
}
Comment on lines +767 to +777

@coderabbitai coderabbitai Bot Aug 22, 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

Clarify article usage and import path for key type

  • “The builder uses ECDSA key…” → should be “an ECDSA key” or “ECDSA keys.”
  • Double-check the import path of PrivateKeyPair. README says to import from @trustvc/trustvc, but tests import from @trustvc/w3c-issuer. Please align.

Run to confirm what your package actually exports:

🏁 Script executed:

#!/bin/bash
# Inspect re-exports of PrivateKeyPair from the library root.
rg -nC2 'export\s+.*PrivateKeyPair' -g '!**/dist/**'

Length of output: 218

Update README: correct ECDSA phrasing and import source

  • Change the sentence
    “The builder uses ECDSA key for signing by default.”
    to
    “The builder uses an ECDSA key for signing by default.”

  • Align the import path for PrivateKeyPair with the actual export: in your README replace

    import type { PrivateKeyPair } from '@trustvc/trustvc';

    with

    import type { PrivateKeyPair } from '@trustvc/w3c-issuer';

    to match the re-export in src/w3c/types.ts (see line 7).

🧰 Tools
🪛 LanguageTool

[grammar] ~767-~767: There might be a mistake here.
Context: ...rfrom@trustvc/trustvc`. The builder uses ECDSA key for signing by default. ```t...

(QB_NEW_EN)

🤖 Prompt for AI Agents 
In README.md around lines 767 to 777, update the phrasing and import source:
change the sentence "The builder uses ECDSA key for signing by default." to "The
builder uses an ECDSA key for signing by default." and change the import
statement to reference the actual export by replacing "import type {
PrivateKeyPair } from '@trustvc/trustvc';" with "import type { PrivateKeyPair }
from '@trustvc/w3c-issuer';" so the README matches src/w3c/types.ts re-exports.


const signedDocument = await builder.sign(privateKey);
console.log(signedDocument);
Expand All @@ -783,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"
],
Comment on lines +787 to 792

@coderabbitai coderabbitai Bot Aug 22, 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

Status list entry type inconsistent with code (V2 uses BitstringStatusListEntry)

Your code sets the credentialStatus.type to "BitstringStatusListEntry" but the README’s signed output shows "StatusList2021Entry". Align the docs with the implementation and add the status-list context if required in examples.

Apply:

   "credentialStatus": {
-    "id": "https://example.com/status-list#<placeholder>",
-    "type": "StatusList2021Entry",
+    "id": "https://example.com/status-list#<placeholder>",
+    "type": "BitstringStatusListEntry",
     "statusPurpose": "revocation",
     "statusListIndex": "<placeholder>",
     "statusListCredential": "https://example.com/status-list"
   },

If examples rely on status lists, also include the context in the example’s @context array:

   "@context": [
     "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/data-integrity/v2",
+    "https://w3id.org/vc/status-list/2021/v1"
   ],

Also applies to: 810-816

🤖 Prompt for AI Agents 
In README.md around lines 787-792 (and similarly 810-816), the example
credential output shows credentialStatus.type as "StatusList2021Entry" which is
inconsistent with the code that uses "BitstringStatusListEntry"; update the
examples to use "BitstringStatusListEntry" and add the appropriate status-list
context URL (e.g. the Status List 2021/2022 context) into the example @context
arrays so the status type is valid and the examples mirror the implementation.

"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 @@ -814,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
To derive the document, provide the attributes to be revealed 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
50 changes: 26 additions & 24 deletions package-lock.json
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

8 changes: 4 additions & 4 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -121,11 +121,11 @@
"@tradetrust-tt/tradetrust": "^6.10.2",
"@tradetrust-tt/tradetrust-utils": "^2.4.2",
"@tradetrust-tt/tt-verify": "^9.5.1",
"@trustvc/w3c": "^1.3.0-alpha.6",
"@trustvc/w3c-context": "^1.3.0-alpha.6",
"@trustvc/w3c-credential-status": "^1.3.0-alpha.6",
"@trustvc/w3c": "^1.3.0-alpha.7",
"@trustvc/w3c-context": "^1.3.0-alpha.7",
"@trustvc/w3c-credential-status": "^1.3.0-alpha.7",
"@trustvc/w3c-issuer": "^1.3.0-alpha.5",
"@trustvc/w3c-vc": "^1.3.0-alpha.6",
"@trustvc/w3c-vc": "^1.3.0-alpha.7",
"ethers": "^5.8.0",
Comment thread
Moiz47 marked this conversation as resolved.
"ethersV6": "npm:ethers@^6.14.4",
"js-sha3": "^0.9.3",
Expand Down
Loading