Skip to content

docs: remove OA v3 references and add CLI comparison guide #13

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 4 commits into from
May 28, 2026
Merged

docs: remove OA v3 references and add CLI comparison guide #13

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
086bad7
fix: remove-oa-v3
RishabhS7 May 20, 2026
2e97d9e
docs: add CLI Comparison guide
rongquan1 May 20, 2026
e6b24b8
fix: remove OA v3 verification from documentation
RishabhS7 May 20, 2026
9904e94
Merge pull request #12 from TrustVC/fix/remove-oa-v3
rongquan1 May 21, 2026
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
6 changes: 3 additions & 3 deletions docs/getting-started.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ title: Getting Started

## Introduction

TrustVC (`@trustvc/trustvc`) is a comprehensive library for signing, verifying, and managing W3C Verifiable Credentials and OpenAttestation Verifiable Documents. It provides a unified API for credential issuance, selective disclosure, and multi-format verification.
TrustVC (`@trustvc/trustvc`) is a comprehensive library for signing, verifying, and managing W3C Verifiable Credentials and OpenAttestation v2 Verifiable Documents. It provides a unified API for credential issuance, selective disclosure, and multi-format verification.

## Prerequisites

Expand Down Expand Up @@ -145,9 +145,9 @@ The derived credential is independently verifiable -- the verifier does not need
| Function | Description |
|---|---|
| `signW3C` | Sign a W3C Verifiable Credential (`ecdsa-sd-2023` or `bbs-2023`) |
| `signOA` | Sign an OpenAttestation document (v2 or v3) |
| `signOA` | Sign an OpenAttestation document (v2) |
| `deriveW3C` | Derive a credential with selective disclosure from a signed W3C VC |
| `verifyDocument` | Verify any signed document (W3C VC, OA VD, or OpenCert) |
| `verifyDocument` | Verify any signed document (W3C VC or OA v2 VD) |
| `wrapOADocument` | Wrap a single OpenAttestation document |
| `encrypt` / `decrypt` | Encrypt and decrypt data using ChaCha20 |
| `DocumentBuilder` | Fluent API for building, signing, deriving, and verifying credentials |
Expand Down
64 changes: 8 additions & 56 deletions docs/how-tos/attachments.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,6 @@ TrustVC allows you to attach files directly to your verifiable documents and cre

Legacy formats (for reference only):
- OpenAttestation v2: Attachments are included in the document data before wrapping
- OpenAttestation v3: Attachments are added at the root level of the document

Attachments enable you to bundle supporting files with your verifiable documents, ensuring that all related information remains together and tamper-evident.

Expand All @@ -34,12 +33,12 @@ For broad compatibility with TrustVC, we recommend the following attachment stru
| Field | Type | Description | Required | Notes |
|-------|------|-------------|----------|-------|
| `data` | string | Base64-encoded file content | Yes | Must be plain base64 string without data URL prefixes (e.g., `JVBERi0xLjQKJ...`) |
| `filename` | string | Name of the file | Yes* | Example: "invoice.pdf" (also supports `fileName` in OA v3) |
| `filename` | string | Name of the file | Yes* | Example: "invoice.pdf" |
| `mimeType` | string | MIME type of the file | Yes* | Example: "application/pdf" (also supports `type` in OA v2) |

*Required for proper rendering in TrustVC Verification Website

This structure is preferred for new documents. However, the TrustVC platform, particularly its decentralized renderer, is designed to be flexible and can parse attachments from older OpenAttestation (OA) v2 and v3 formats as well.
This structure is preferred for new documents. However, the TrustVC platform, particularly its decentralized renderer, is designed to be flexible and can parse attachments from older OpenAttestation (OA) v2 formats as well.

### Important Considerations for Attachments

Expand All @@ -51,7 +50,7 @@ When working with attachments, keep these points in mind:

### Renderer Parsing and Legacy Support

The TrustVC decentralized renderer processes attachments to extract the necessary information for display. It primarily looks for the recommended fields (`data`, `filename`, `mimeType`) but also checks for common variations found in OA v2 and OA v3 documents.
The TrustVC decentralized renderer processes attachments to extract the necessary information for display. It primarily looks for the recommended fields (`data`, `filename`, `mimeType`) but also checks for common variations found in OA v2 documents.

The following code snippet from `decentralized-renderer-react-components/src/utils.ts` illustrates how the renderer extracts attachment details:

Expand All @@ -63,16 +62,16 @@ const attachments = vc.isSignedDocument(document)
?.map((s) => s.attachments)
?.filter(Boolean)
?.flat()
: isV2Document(document) || isV3Document(document)
: isV2Document(document)
? document.attachments
: [];
const tabsRenderedFromAttachments = (attachments || ([] as Attachment[]))
.map((attachment: Attachment, index: number) => {
return {
id: `attachment-${index}`,
// For filename, it checks for 'fileName' (common in OA v3) then 'filename' (recommended, and OA v2)
// For filename, it checks for 'fileName' then 'filename' (recommended, and OA v2)
label: ((attachment as any).fileName ?? (attachment as any)?.filename) || "Unknown filename",
// For MIME type, it checks for 'type' (common in OA v2) then 'mimeType' (recommended, and OA v3)
// For MIME type, it checks for 'type' (common in OA v2) then 'mimeType' (recommended)
type: ((attachment as any).type ?? (attachment as any).mimeType) || "Unknown filetype",
// The 'data' property is used within attachmentToComponent to render the content
template: attachmentToComponent(attachment, document)!
Expand All @@ -83,8 +82,8 @@ const tabsRenderedFromAttachments = (attachments || ([] as Attachment[]))

As shown in the snippet:

- For the attachment's **name/label**, the renderer first looks for a `fileName` property (common in OA v3) and falls back to `filename` (recommended, and also used in OA v2).
- For the attachment's **type**, it first looks for a `type` property (common in OA v2) and falls back to `mimeType` (recommended, and also used in OA v3).
- For the attachment's **name/label**, the renderer first looks for a `fileName` property and falls back to `filename` (recommended, and also used in OA v2).
- For the attachment's **type**, it first looks for a `type` property (common in OA v2) and falls back to `mimeType` (recommended).

This ensures that documents created with older OpenAttestation schemas remain compatible. While this flexibility is provided, new implementations should adhere to the recommended structure (`data`, `filename`, `mimeType`) for clarity and future-proofing.

Expand Down Expand Up @@ -239,53 +238,6 @@ After wrapping, the attachments will be part of the document data with salted va
```
</details>

<details>
<summary><b>OpenAttestation v3</b></summary>

For OpenAttestation v3 documents, attachments are added at the root level:

```json
{
"version": "https://schema.openattestation.com/3.0/schema.json",
"network": {
"chain": "FREE",
"chainId": "101010"
},
"credentialSubject": {
// Document data goes here
},
"attachments": [
{
"data": "JVBERi0xLjQKJdPr6eEKMSAwIG9iago8PC9UaXRsZSAoRXhhbXBsZSBQREYpCi9Qcm9kdWNlciAoT3...",
"fileName": "certificate.pdf",
"mimeType": "application/pdf"
}
],
"openAttestationMetadata": {
"template": {
"type": "EMBEDDED_RENDERER",
"name": "CHAFTA_COO",
"url": "https://generic-templates.tradetrust.io"
},
"proof": {
"type": "OpenAttestationProofMethod",
"method": "DOCUMENT_STORE",
"value": "0xA594f6e10564e87888425c7CC3910FE1c800aB0B"
},
"identityProof": {
"type": "DNS-TXT",
"identifier": "example.tradetrust.io"
}
},
"issuer": {
"id": "https://example.com",
"name": "DEMO DOCUMENT STORE",
"type": "OpenAttestationIssuer"
}
}
```
</details>

## Handling Attachments in TrustVC Verification Website

TrustVC's Verification Website automatically detects and displays attachments in the document viewer. Attachments appear as tabs alongside the main document view, allowing users to switch between the main document and its attachments.
Expand Down
26 changes: 0 additions & 26 deletions docs/how-tos/implementing-qr-codes.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -60,32 +60,8 @@ For W3C Verifiable Credentials, you need to add a `qrCode` property to your cred

For OpenAttestation documents, QR codes are implemented in the document's links property:

- In OA v3: via `credentialSubject.links.self.href`
- In OA v2: via `data.links.self.href`

<details>
<summary>View OA v3 Example</summary>

```json
{
"version": "https://schema.openattestation.com/3.0/schema.json",
"@context": [
"https://www.w3.org/2018/credentials/v1",
"https://schemata.openattestation.com/com/openattestation/1.0/OpenAttestation.v3.json"
],
"credentialSubject": {
// Document data
"links": {
"self": {
"href": "https://actions.tradetrust.io?q=%7B%22type%22%3A%22DOCUMENT%22%2C%22payload%22%3A%7B%22uri%22%3A%22https%3A%2F%2Fexample.com%2Fdocuments%2F123%22%2C%22key%22%3A%22abcdef1234567890%22%2C%22permittedActions%22%3A%5B%22STORE%22%5D%2C%22redirect%22%3A%22https%3A%2F%2Ftradetrust.io%2F%22%2C%22chainId%22%3A%22101010%22%7D%7D"
}
}
},
// Other document properties
}
```
</details>

<details>
<summary>View OA v2 Example</summary>

Expand Down Expand Up @@ -186,14 +162,12 @@ When a TrustVC-compatible document with a QR code is loaded, the TrustVC website

2. Extracts the QR code URL using the `getQRCodeLink` function, which checks for:
- `qrCode.uri` in W3C VC documents
- `credentialSubject.links.self.href` in OA v3 documents
- `links.self.href` in OA v2 documents

3. TrustVC then downloads the document from the specified URI, decrypting it if necessary.

4. Renders the URL as a scannable QR code.


## Testing Your QR Code Implementation

To test if your QR code implementation is working correctly:
Expand Down
12 changes: 6 additions & 6 deletions docs/how-tos/verifydocument.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ sidebar_label: Verify Document

## Overview

The `verifyDocument` function is TrustVC's unified verification entry point. It accepts any signed document -- W3C Verifiable Credentials or OpenAttestation Verifiable Documents -- and returns an array of verification fragments describing the outcome.
The `verifyDocument` function is TrustVC's unified verification entry point. It accepts any signed document -- W3C Verifiable Credentials or OpenAttestation v2 Verifiable Documents -- and returns an array of verification fragments describing the outcome.

Verification answers three questions about a document:

Expand All @@ -27,15 +27,15 @@ console.log(fragments);
// Array of verification fragments, one per check
```

The function automatically detects the document format (W3C VC or OpenAttestation) and applies the correct set of verifiers.
The function automatically detects the document format (W3C VC or OpenAttestation v2) and applies the correct set of verifiers.

## Understanding Verification Fragments

`verifyDocument` returns an array of `VerificationFragment` objects. Each fragment corresponds to one of three verification checks:

### DOCUMENT_INTEGRITY

Validates that the document has not been modified after signing. For W3C VCs, this checks the `DataIntegrityProof` signature. For OpenAttestation documents, this verifies the Merkle root and document hash.
Validates that the document has not been modified after signing. For W3C VCs, this checks the `DataIntegrityProof` signature. For OpenAttestation v2 documents, this verifies the Merkle root and document hash.

```ts
const integrityFragment = fragments.find((f) => f.type === 'DOCUMENT_INTEGRITY');
Expand All @@ -44,7 +44,7 @@ console.log(integrityFragment.status); // "VALID" | "INVALID" | "SKIPPED" | "ERR

### DOCUMENT_STATUS

Checks whether the credential has been revoked or suspended. For W3C VCs using `BitstringStatusListEntry`, this resolves the status list credential and checks the bit at the specified index. For OpenAttestation documents, this checks the on-chain document store or token registry.
Checks whether the credential has been revoked or suspended. For W3C VCs using `BitstringStatusListEntry`, this resolves the status list credential and checks the bit at the specified index. For OpenAttestation v2 documents, this checks the on-chain document store or token registry.

```ts
const statusFragment = fragments.find((f) => f.type === 'DOCUMENT_STATUS');
Expand All @@ -53,7 +53,7 @@ console.log(statusFragment.status);

### ISSUER_IDENTITY

Verifies that the issuer's identity can be resolved and trusted. For W3C VCs, this resolves the issuer's DID document and confirms the signing key is listed. For OpenAttestation documents, this checks DNS-TXT records or DNS-DID identity proofs.
Verifies that the issuer's identity can be resolved and trusted. For W3C VCs, this resolves the issuer's DID document and confirms the signing key is listed. For OpenAttestation v2 documents, this checks DNS-TXT records or DNS-DID identity proofs.

```ts
const identityFragment = fragments.find((f) => f.type === 'ISSUER_IDENTITY');
Expand Down Expand Up @@ -107,7 +107,7 @@ for (const fragment of fragments) {

### rpcProviderUrl

For documents that require on-chain verification (e.g., OpenAttestation documents using document stores or token registries), pass an Ethereum-compatible JSON-RPC provider URL:
For documents that require on-chain verification (e.g., OpenAttestation v2 documents using document stores or token registries), pass an Ethereum-compatible JSON-RPC provider URL:

```ts
const fragments = await verifyDocument(signedDocument, {
Expand Down
Loading
Loading