feat: add obligation registry and related functions to the project

.github/workflows/tests.yml

@@ -32,7 +32,7 @@
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
       - run: npm ci
       - run: npm run test
         env:
           ANKR_API_KEY: ${{ secrets.ANKR_API_KEY }}
@@ -58,5 +58,7 @@
         with:
           node-version: ${{ matrix.node-version }}
           cache: 'npm'
       - run: npm ci
       - run: npm run build
+        env:
+          NODE_OPTIONS: --max-old-space-size=8192

package.json

@@ -73,6 +73,21 @@
       "import": "./dist/esm/token-registry-v5/contracts.js",
       "require": "./dist/cjs/token-registry-v5/contracts.js"
     },
+    "./obligation-registry": {
+      "types": "./dist/types/obligation-registry/index.d.ts",
+      "import": "./dist/esm/obligation-registry/index.js",
+      "require": "./dist/cjs/obligation-registry/index.js"
+    },
+    "./obligation-registry/contracts": {
+      "types": "./dist/types/obligation-registry/contracts.d.ts",
+      "import": "./dist/esm/obligation-registry/contracts.js",
+      "require": "./dist/cjs/obligation-registry/contracts.js"
+    },
+    "./obligation-registry-functions": {
+      "types": "./dist/types/obligation-registry-functions/index.d.ts",
+      "import": "./dist/esm/obligation-registry-functions/index.js",
+      "require": "./dist/cjs/obligation-registry-functions/index.js"
+    },
     "./utils": {
       "types": "./dist/types/utils/index.d.ts",
       "import": "./dist/esm/utils/index.js",
@@ -88,6 +103,16 @@
       "import": "./dist/esm/verify/fragments/index.js",
       "require": "./dist/cjs/verify/fragments/index.js"
     },
+    "./verify-obligation": {
+      "types": "./dist/types/verify-obligation/index.d.ts",
+      "import": "./dist/esm/verify-obligation/index.js",
+      "require": "./dist/cjs/verify-obligation/index.js"
+    },
+    "./verify-obligation/fragments": {
+      "types": "./dist/types/verify-obligation/fragments/index.d.ts",
+      "import": "./dist/esm/verify-obligation/fragments/index.js",
+      "require": "./dist/cjs/verify-obligation/fragments/index.js"
+    },
     "./w3c": {
       "types": "./dist/types/w3c/index.d.ts",
       "import": "./dist/esm/w3c/index.js",
@@ -118,15 +143,15 @@
     "@tradetrust-tt/dnsprove": "^2.18.0",
     "@tradetrust-tt/ethers-aws-kms-signer": "^2.1.4",
     "@tradetrust-tt/token-registry-v4": "npm:@tradetrust-tt/token-registry@^4.16.0",
-    "@tradetrust-tt/token-registry-v5": "npm:@tradetrust-tt/token-registry@^5.5.0",
+    "@tradetrust-tt/token-registry-v5": "npm:@tradetrust-tt/token-registry@^5.6.0-beta.1",
     "@tradetrust-tt/tradetrust": "^6.10.3",
     "@tradetrust-tt/tt-verify": "^9.7.5",
     "@trustvc/document-store": "^1.0.3",
-    "@trustvc/w3c": "^2.2.0",
-    "@trustvc/w3c-context": "^2.2.0",
-    "@trustvc/w3c-credential-status": "^2.2.0",
-    "@trustvc/w3c-issuer": "^2.2.0",
-    "@trustvc/w3c-vc": "^2.2.0",
+    "@trustvc/w3c": "^2.4.1",
+    "@trustvc/w3c-context": "^2.4.0",
+    "@trustvc/w3c-credential-status": "^2.4.0",
+    "@trustvc/w3c-issuer": "^2.3.0",
+    "@trustvc/w3c-vc": "^2.4.1",
     "ethers": "^5.8.0",
     "ethersV6": "npm:ethers@^6.14.4",
     "js-sha3": "^0.9.3",

src/__tests__/core/documentBuilder.obligation.test.ts

@@ -0,0 +1,24 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { TR_CONTEXT_URL } from '@trustvc/w3c-context';
+import { DocumentBuilder } from '../../core/documentBuilder';
+
+describe('DocumentBuilder (obligation records)', () => {
+  let documentBuilder: DocumentBuilder;
+
+  beforeEach(() => {
+    documentBuilder = new DocumentBuilder({
+      '@context': 'https://trustvc.io/context/bill-of-lading.json',
+    }).credentialSubject({ type: ['BillOfLading'] });
+  });
+
+  it('should configure obligationRecords correctly', () => {
+    documentBuilder.credentialStatus({
+      chain: 'amoy',
+      chainId: 80002,
+      obligationRegistry: '0x71D28767662cB233F887aD2Bb65d048d760bA694',
+      rpcProviderUrl: 'https://rpc-amoy.polygon.technology',
+    });
+    expect(documentBuilder).toBeDefined();
+    expect(documentBuilder.toString()).toContain(TR_CONTEXT_URL);
+  });
+});

src/__tests__/core/documentBuilder.test.ts

@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest';
 import { DocumentBuilder } from '../../core/documentBuilder';
 import {
   Bbs2023PrivateKeyPair,
@@ -148,7 +148,7 @@ describe('DocumentBuilder data model 2.0 using ECDSA', () => {
           index: 10,
         }),
       ).toThrow(
-        'Configuration Error: Do not mix transferable records and verifiable document properties.',
+        'Configuration Error: Do not mix transferable records, obligation records, and verifiable document properties.',
       );
     });
 
@@ -162,6 +162,16 @@ describe('DocumentBuilder data model 2.0 using ECDSA', () => {
   });
 
   describe('Sign, Derive and Verify', () => {
+    beforeEach(() => {
+      vi.spyOn(DocumentBuilder.prototype as never, 'verifyTokenRegistry').mockResolvedValue(
+        undefined,
+      );
+    });
+
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
     it('should sign, derive and verify the document successfully for transferableRecords using ECDSA', async () => {
       documentBuilder.credentialStatus({
         chain: 'amoy',
@@ -235,13 +245,20 @@ describe('DocumentBuilder data model 2.0 using ECDSA', () => {
   });
 
   describe('Error Handling', () => {
+    afterEach(() => {
+      vi.restoreAllMocks();
+    });
+
     it('Should throw error if document builder initialized with data model v1.1 context', () => {
       expect(
         () => new DocumentBuilder({ '@context': ['https://www.w3.org/2018/credentials/v1'] }),
       ).toThrow('Document builder does not support data model v1.1.');
     });
 
     it('Should throw an error when trying to verify without deriving using ECDSA', async () => {
+      vi.spyOn(DocumentBuilder.prototype as never, 'verifyTokenRegistry').mockResolvedValue(
+        undefined,
+      );
       documentBuilder.credentialStatus({
         chain: 'amoy',
         chainId: 80002,
@@ -256,6 +273,9 @@ describe('DocumentBuilder data model 2.0 using ECDSA', () => {
     });
 
     it('Should throw an error when trying to verify without deriving using BBS2023', async () => {
+      vi.spyOn(DocumentBuilder.prototype as never, 'verifyTokenRegistry').mockResolvedValue(
+        undefined,
+      );
       documentBuilder.credentialStatus({
         chain: 'amoy',
         chainId: 80002,
@@ -282,6 +302,7 @@ describe('DocumentBuilder data model 2.0 using ECDSA', () => {
     });
 
     it('should throw an error when unable to verify token registry', async () => {
+      vi.restoreAllMocks();
       documentBuilder.credentialStatus({
         chain: 'amoy',
         chainId: 80002,

src/__tests__/core/verify.pol.test.ts

@@ -36,8 +36,11 @@ describe('Polygon (POL) network support', () => {
 
   describe('W3C_TRANSFERABLE_RECORD_POL fixture structure', () => {
     it('should have chain POL and chainId 137 in credentialStatus', () => {
-      expect(W3C_TRANSFERABLE_RECORD_POL.credentialStatus.tokenNetwork.chain).toBe('POL');
-      expect(W3C_TRANSFERABLE_RECORD_POL.credentialStatus.tokenNetwork.chainId).toBe(137);
+      const credentialStatus = W3C_TRANSFERABLE_RECORD_POL.credentialStatus as unknown as {
+        tokenNetwork: { chain: string; chainId: number };
+      };
+      expect(credentialStatus.tokenNetwork.chain).toBe('POL');
+      expect(credentialStatus.tokenNetwork.chainId).toBe(137);
     });
 
     it('should have a DataIntegrityProof with ecdsa-sd-2023 cryptosuite', () => {

src/__tests__/core/verify.rpc-resilience.test.ts

@@ -0,0 +1,200 @@
+import { beforeEach, describe, it, vi } from 'vitest';
+import { verifyDocument } from '../..';
+import * as transferableRecordsUtils from '../../verify/fragments/document-status/transferableRecords/utils';
+import {
+  W3C_TRANSFERABLE_RECORD,
+  WRAPPED_DOCUMENT_DID_TOKEN_REGISTRY_V3,
+} from '../fixtures/fixtures';
+import { W3CCredentialStatusCode } from '../../verify/fragments/document-status/w3cCredentialStatus';
+
+/**
+ * Extra verify coverage that mocks / soft-asserts around flaky public Amoy RPC.
+ * Keeps src/__tests__/core/verify.test.ts aligned with main (live RPC snapshots).
+ */
+const providerUrl = 'https://rpc-amoy.polygon.technology';
+
+describe.concurrent('W3C verify (RPC resilience)', () => {
+  describe.concurrent('W3C_TRANSFERABLE_RECORD mocked mint checks', () => {
+    beforeEach(() => {
+      vi.clearAllMocks();
+      vi.resetAllMocks();
+    });
+
+    it(
+      'should return VALID status for TransferableRecords when mint check is mocked',
+      { timeout: 300000 },
+      async ({ expect }) => {
+        vi.spyOn(transferableRecordsUtils, 'isTokenMintedOnRegistry').mockResolvedValue({
+          minted: true,
+          address: '0x6c2a002A5833a100f38458c50F11E71Aa1A342c6',
+        });
+        expect(
+          await verifyDocument(W3C_TRANSFERABLE_RECORD as any, { rpcProviderUrl: providerUrl }),
+        ).toMatchInlineSnapshot(`
+          [
+            {
+              "data": true,
+              "name": "W3CSignatureIntegrity",
+              "status": "VALID",
+              "type": "DOCUMENT_INTEGRITY",
+            },
+            {
+              "name": "EcdsaW3CSignatureIntegrity",
+              "reason": {
+                "code": 0,
+                "codeString": "SKIPPED",
+                "message": "Document either has no proof or proof type is not 'DataIntegrityProof' or proof cryptosuite is not 'ecdsa-sd-2023'.",
+              },
+              "status": "SKIPPED",
+              "type": "DOCUMENT_INTEGRITY",
+            },
+            {
+              "name": "Bbs2023W3CSignatureIntegrity",
+              "reason": {
+                "code": 0,
+                "codeString": "SKIPPED",
+                "message": "Document either has no proof or proof type is not 'DataIntegrityProof' or proof cryptosuite is not 'bbs-2023'.",
+              },
+              "status": "SKIPPED",
+              "type": "DOCUMENT_INTEGRITY",
+            },
+            {
+              "name": "W3CCredentialStatus",
+              "reason": {
+                "code": 0,
+                "codeString": "SKIPPED",
+                "message": "Document does not have a valid credentialStatus or type.",
+              },
+              "status": "SKIPPED",
+              "type": "DOCUMENT_STATUS",
+            },
+            {
+              "data": {
+                "tokenRegistry": "0x6c2a002A5833a100f38458c50F11E71Aa1A342c6",
+              },
+              "name": "TransferableRecords",
+              "status": "VALID",
+              "type": "DOCUMENT_STATUS",
+            },
+            {
+              "name": "ObligationRecords",
+              "reason": {
+                "code": 0,
+                "codeString": "SKIPPED",
+                "message": "Document does not have ObligationRecords status",
+              },
+              "status": "SKIPPED",
+              "type": "DOCUMENT_STATUS",
+            },
+            {
+              "name": "W3CEmptyCredentialStatus",
+              "reason": {
+                "code": 0,
+                "codeString": "SKIPPED",
+                "message": "Document contains a credentialStatus.",
+              },
+              "status": "SKIPPED",
+              "type": "DOCUMENT_STATUS",
+            },
+            {
+              "data": true,
+              "name": "W3CIssuerIdentity",
+              "status": "VALID",
+              "type": "ISSUER_IDENTITY",
+            },
+          ]
+        `);
+      },
+    );
+
+    it('should return INVALID status for TransferableRecords when mint check is mocked as not minted', async ({
+      expect,
+    }) => {
+      vi.spyOn(transferableRecordsUtils, 'isTokenMintedOnRegistry').mockResolvedValue({
+        minted: false,
+        address: '0x6c2a002A5833a100f38458c50F11E71Aa1A342c6',
+        reason: {
+          code: W3CCredentialStatusCode.DOCUMENT_NOT_ISSUED,
+          codeString: 'DOCUMENT_NOT_MINTED',
+          message: 'Document has not been issued under token registry',
+        },
+      });
+      const tampered: any = {
+        ...W3C_TRANSFERABLE_RECORD,
+        credentialStatus: {
+          ...W3C_TRANSFERABLE_RECORD.credentialStatus,
+          tokenId: '123',
+        },
+      };
+      expect(await verifyDocument(tampered, { rpcProviderUrl: providerUrl })).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: 'TransferableRecords',
+            reason: {
+              code: W3CCredentialStatusCode.DOCUMENT_NOT_ISSUED,
+              codeString: 'DOCUMENT_NOT_MINTED',
+              message: 'Document has not been issued under token registry',
+            },
+            status: 'INVALID',
+            type: 'DOCUMENT_STATUS',
+          }),
+        ]),
+      );
+    });
+  });
+});
+
+describe.concurrent('V3 verify (RPC resilience)', () => {
+  it(
+    'should verify a DID_TOKEN_REGISTRY document with soft asserts for flaky Amoy RPC',
+    { timeout: 300000 },
+    async ({ expect }) => {
+      const fragments = await verifyDocument(WRAPPED_DOCUMENT_DID_TOKEN_REGISTRY_V3, {
+        rpcProviderUrl: providerUrl,
+      });
+
+      expect(fragments).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({
+            name: 'OpenAttestationHash',
+            status: 'VALID',
+            type: 'DOCUMENT_INTEGRITY',
+          }),
+          expect.objectContaining({
+            name: 'OpenAttestationEthereumDocumentStoreStatus',
+            status: 'SKIPPED',
+            type: 'DOCUMENT_STATUS',
+          }),
+          expect.objectContaining({
+            name: 'OpenAttestationDidSignedDocumentStatus',
+            status: 'SKIPPED',
+            type: 'DOCUMENT_STATUS',
+          }),
+          expect.objectContaining({
+            name: 'OpenAttestationDnsDidIdentityProof',
+            status: 'SKIPPED',
+            type: 'ISSUER_IDENTITY',
+          }),
+          expect.objectContaining({
+            name: 'OpencertsRegistryVerifier',
+            status: 'SKIPPED',
+            type: 'ISSUER_IDENTITY',
+          }),
+        ]),
+      );
+
+      // Token registry / DNS-TXT can ERROR when public Amoy RPC is flaky.
+      const tokenRegistryFragment = fragments.find(
+        (fragment) => fragment.name === 'OpenAttestationEthereumTokenRegistryStatus',
+      );
+      expect(tokenRegistryFragment).toBeDefined();
+      expect(['VALID', 'ERROR']).toContain(tokenRegistryFragment?.status);
+
+      const dnsTxtFragment = fragments.find(
+        (fragment) => fragment.name === 'OpenAttestationDnsTxtIdentityProof',
+      );
+      expect(dnsTxtFragment).toBeDefined();
+      expect(['VALID', 'ERROR']).toContain(dnsTxtFragment?.status);
+    },
+  );
+});