Skip to content
This repository was archived by the owner on Oct 1, 2025. It is now read-only.

Commit 1bbe81f

Browse files
yehjxraymondyehjxraymond
authored
feat: v3 beta program (#63)
* feat: v3 beta program * fix: dup * feat: added OC & Verify Co-authored-by: Raymond Yeh <ray@geek.sg>
1 parent efb55fd commit 1bbe81f

File tree

5 files changed

+230
-1
lines changed

5 files changed

+230
-1
lines changed

‎website/docs/advanced/v3/different-files.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
id: different-files
3+
title: Different Types of Document
4+
sidebar_label: Different Types of Document
5+
---
6+
7+
OpenAttestation V3 is available for different types of document (Transferable Record & Verifiable Document) and different type of identity methods (`DNS-TXT`, `DNS-DID` & `DID`).
8+
9+
For a range of the different types of documents that are supported and tested, you may:
10+
11+
1. See how the documents are generated [here](https://github.com/Open-Attestation/oa-verify/blob/master/scripts/generate.v3.ts)
12+
1. See how the documents look like [here](https://github.com/Open-Attestation/oa-verify/tree/master/test/fixtures/v3)
13+
1. See how test output for different types of document looks like [here](https://github.com/Open-Attestation/oa-verify/blob/master/src/verify.v3.integration.test.ts)
14+
15+
For bug report and support, please [create an issue here](https://github.com/Open-Attestation/open-attestation/issues)

‎website/docs/advanced/v3/major-changes.md‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
---
2+
id: major-changes
3+
title: Major Change from V2
4+
sidebar_label: Major Changes
5+
---
6+
7+
Here are some of the major changes from OpenAttestation v2 Data Model
8+
9+
## `@context`
10+
11+
The `@context` property is now introduced as per [W3C VC Care Data Model](https://www.w3.org/TR/vc-data-model/#contexts) to allow the issuer to map such short-form aliases to the URIs required by specific verifiable credentials and verifiable presentations.
12+
13+
OpenAttestation has released our extension to W3C credentials context via `https://schemata.openattestation.com/com/openattestation/1.0/OpenAttestation.v3.json`.
14+
15+
## `credentialSubject`
16+
17+
Previously stored in the `data` key, the claims about the subject of the credential are now to be placed in the `credentialSubject` field.
18+
19+
## `openAttestationMetadata`
20+
21+
Previously mixed into the `data` object, additional metadata that are crucial in the role of verification of document integrity or provenance and display of document are now moved into the `openAttestationMetadata` field.
22+
23+
## `issuer`
24+
25+
Instead of allowing for multiple issuers as found in OA v2, version 3 restricts that there may only be one named `issuer` of verifiable credentials. For use cases where there is need for different entities to come together to co-issue the document, the entities will need to [choose a way to signal intent from multiple participants on the blockchain](https://geek.sg/blog/comparing-different-ways-to-signal-intent-from-multiple-participants-on-the-blockchain)
26+
27+
## Data access
28+
29+
In the previous version, every value in the document is made into a string with a random salt pre-pended as a mean to protect against rainbow table attack on obfuscated value. This results in the need for the `getData` method which strips the salt and change the type of the value back to the original type.
30+
31+
In the upgrade, the random salts has been moved to `proof.salts` to be pre-pended to the individual values only at the checksum verification stage. This allows the data of the VC to be directly accessible without the `getData` method.

‎website/docs/advanced/v3/overview.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,73 @@
1+
---
2+
id: overview
3+
title: OpenAttestation V3 (Beta)
4+
sidebar_label: Overview
5+
---
6+
7+
## Goal
8+
9+
OpenAttestation's latest version seeks to align the data model to [W3C Verifiable Credentials Data Model](https://www.w3.org/TR/vc-data-model/) for interoperability with other W3C VC wallets.
10+
11+
## Data Model Release Status
12+
13+
Version 3 Data Model is currently in `Beta` release.
14+
15+
This means that the OpenAttestation data model is feature complete but is likely to contain some known or unknown bugs. Refrain from using version 3 in production environment until the the release status is marked `General Availability`.
16+
17+
## Beta Program
18+
19+
If you are using OpenAttestation to issue or verify VC, you are encouraged to test out Version 3 as early beta tester. Feel free to get started with the tools and help report issues to our github repository at https://github.com/Open-Attestation/open-attestation.
20+
21+
## Major Changes from V2
22+
23+
Major changes from the version 2 can be found [here](/docs/advanced/v3/major-changes).
24+
25+
## Tool Compatibility
26+
27+
While the base data model is feature complete, we are in the work of upgrading the tools and documentations for support of v3. Below are the progress of update for different tools:
28+
29+
### oa-did-sign
30+
31+
https://www.npmjs.com/package/@govtechsg/oa-did-sign
32+
33+
Status: Pending
34+
35+
### oa-verify
36+
37+
https://www.npmjs.com/package/@govtechsg/oa-verify
38+
39+
Status: Supported
40+
41+
### oa-cli
42+
43+
https://www.npmjs.com/package/@govtechsg/open-attestation-cli
44+
45+
Status:
46+
47+
- `wrap`: Supported
48+
- `sign`: Pending
49+
- `verify`: Pending
50+
51+
### TradeTrust Website
52+
53+
https://tradetrust.io/
54+
55+
Status: Pending
56+
57+
### TradeTrust Creator
58+
59+
https://creator.tradetrust.io/
60+
61+
Status: Pending
62+
63+
### OpenCerts Website
64+
65+
https://opencerts.io
66+
67+
Status: Pending
68+
69+
### Verify Website
70+
71+
https://verify.gov.sg
72+
73+
Status: Pending

‎website/docs/advanced/v3/quick-start.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
---
2+
id: quick-start
3+
title: Quick Start (V3 Beta)
4+
sidebar_label: Quick Start
5+
---
6+
7+
In this guide, we will attempt to issue an driving license in the OpenAttestation Version 3 format. We will be using the document store to issue this document with `DNS-TXT` as the method to identify the issuer using DNS.
8+
9+
_The document will not be rendered yet as we have yet to create demo renderer_
10+
11+
> For a full range of documents (beside document store + DNS-TXT), you may look at the different types of document supported [here](/docs/advanced/v3/different-files)
12+
13+
## Document Store Setup
14+
15+
If you have not already deployed a document store, you may do so by following the guides listed below:
16+
17+
1. [Creating a wallet](/docs/verifiable-document/wallet)
18+
1. [Deploying Document Store](/docs/verifiable-document/document-store)
19+
1. [Configuring DNS](/docs/verifiable-document/dns-proof)
20+
21+
## Creating Raw Document
22+
23+
We will now create the data for the driving license. Create a file `licence.json` with the following data:
24+
25+
```json
26+
{
27+
"@context": [
28+
"https://www.w3.org/2018/credentials/v1",
29+
"https://schemata.openattestation.com/com/openattestation/1.0/DrivingLicenceCredential.json",
30+
"https://schemata.openattestation.com/com/openattestation/1.0/OpenAttestation.v3.json"
31+
],
32+
"issuer": {
33+
"id": "https://example.com",
34+
"name": "DEMO STORE"
35+
},
36+
"issuanceDate": "2010-01-01T19:23:24Z",
37+
"type": ["VerifiableCredential", "DrivingLicenceCredential"],
38+
"credentialSubject": {
39+
"id": "did:example:SERIAL_NUMBER_123",
40+
"class": [
41+
{
42+
"type": "3",
43+
"effectiveDate": "2010-01-01T19:23:24Z"
44+
},
45+
{
46+
"type": "3A",
47+
"effectiveDate": "2010-01-01T19:23:24Z"
48+
}
49+
]
50+
},
51+
"openAttestationMetadata": {
52+
"template": {
53+
"name": "CUSTOM_TEMPLATE",
54+
"type": "EMBEDDED_RENDERER",
55+
"url": "https://localhost:3000/renderer"
56+
},
57+
"proof": {
58+
"type": "OpenAttestationProofMethod",
59+
"method": "DOCUMENT_STORE",
60+
"value": "0x8bA63EAB43342AAc3AdBB4B827b68Cf4aAE5Caca"
61+
},
62+
"identityProof": {
63+
"type": "DNS-TXT",
64+
"identifier": "example.tradetrust.io"
65+
}
66+
}
67+
}
68+
```
69+
70+
You will need to replace the following values:
71+
72+
### `openAttestationMetadata.proof.value`
73+
74+
Replace this with the address of the document store deployed in the step [Deploying Document Store](/docs/verifiable-document/document-store)
75+
76+
### `openAttestationMetadata.identityProof.identifier`
77+
78+
Replace this with the domain where the TXT record has been inserted in the step [Configuring DNS](/docs/verifiable-document/dns-proof)
79+
80+
## Wrapping the Document
81+
82+
With `licence.json` saved, run the following command after the [CLI is installed](/docs/component/open-attestation-cli):
83+
84+
```sh
85+
open-attestation wrap licence.json --of wrapped.json --oav3
86+
```
87+
88+
The will wrap the original document and append additional data required by OpenAttestation to the `proof` key at the root of the document.
89+
90+
> Take note of the value `proof.merkleRoot`. This is the merkle root to be issued on the document store later.
91+
92+
## Issuing document
93+
94+
With the merkle root in `proof.merkleRoot`, you may following the [Issuing Document](/docs/verifiable-document/issuing-document) guide to issued the document on Ethereum.
95+
96+
## Verify document
97+
98+
TBD (after oa-cli is updated for `verify`)
99+
100+
If you are reading this now, you may programmatically verify the document with [`oa-verify`](http://localhost:3000/docs/component/oa-verify)

‎website/sidebars.json‎

Lines changed: 11 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,7 +69,17 @@
6969
"advanced/gsn/creating-a-custom-relay-provider"
7070
]
7171
},
72-
"advanced/configuring-dns"
72+
"advanced/configuring-dns",
73+
{
74+
"label": "Version 3 (Beta)",
75+
"type": "category",
76+
"items": [
77+
"advanced/v3/overview",
78+
"advanced/v3/major-changes",
79+
"advanced/v3/quick-start",
80+
"advanced/v3/different-files"
81+
]
82+
}
7383
],
7484
"Appendix": [
7585
"appendix/glossary",

0 commit comments

Comments
 (0)