feat: Endorsement Chain

CLAUDE.md

@@ -29,6 +29,7 @@ Source map (`src/`):
 | Path | What |
 | --- | --- |
 | `src/core/verify.ts` | **`verifyDocument()`** — the unified verify entry point (OA + W3C). |
+| `src/core/endorsement-chain/useEndorsementChain.ts` | **`fetchEndorsementChain()`** — unified V4/V5/Obligation escrow path (auto-detects contract type). |
 | `src/verify/verify.ts` | `verificationBuilder`, `openAttestationVerifiers`, `w3cVerifiers`. |
 | `src/verify/fragments/` | Verifier fragments by dimension: `document-integrity`, `document-status`, `issuer-identity`, `presentation`. |
 | `src/w3c/` | The W3C surface: `sign`, `derive`, `verify`, **`presentation`** (VP wrappers), `types`. |
@@ -103,8 +104,40 @@ so an unsigned VP is still routed in and then judged INVALID by the integrity fr
 aligned to both enforce proof-presence + holder binding. If you touch one, keep the other
 in step.
 
+## Endorsement chain (`src/core/endorsement-chain/useEndorsementChain.ts`)
+
+**`fetchEndorsementChain()`** is the single public path for Token Registry V4/V5 and
+Obligation/BoE titles. It auto-detects the escrow contract via `supportsInterface`
+(including `supportInterfaceIdsV5.ObligationEscrow` around the obligation check).
+
+These public aliases were removed:
+
+| Removed | Use instead |
+| --- | --- |
+| `fetchObligationEndorsementChain` | `fetchEndorsementChain` |
+| `fetchEscrowTransfersObligation` | `fetchEscrowTransfersV5` (auto-detects obligation status events) |
+| `ObligationEscrowInterface` | `supportInterfaceIdsV5.ObligationEscrow` |
+
+Do **not** re-add the removed aliases. User-facing docs also live in `README.md`
+(Obligation Registry section).
+
 ## Gotchas (hard-won — add to this list)
 
+- **Endorsement chain has one public path.** See
+  [Endorsement chain](#endorsement-chain-srccoreendorsement-chainuseendorsementchaints)
+  — do not re-add `fetchObligationEndorsementChain`, `fetchEscrowTransfersObligation`,
+  or `ObligationEscrowInterface`.
+- **Obligation mint merges to INITIAL.** ObligationEscrow emits `StatusInitialized`
+  in the same tx as `TokenReceived(isMinting)` (often *before* it in log order).
+  `mergeTransfersV5` must prefer `INITIAL` so owner/holder/remarks match classic ETR
+  mint rows. Do not let `STATUS_INITIALIZED` win that merge.
+- **eBoE shred last parties + reason come from the contract.** ObligationEscrow
+  persists `lastBeneficiary` / `lastHolder` in `_deactivate` and emits them on
+  `Shred` with `TerminationReason`. SDK maps those onto `RETURN_TO_ISSUER_ACCEPTED`
+  (`owner`/`holder`/`terminationReason`). Do not reconstruct parties from transfer
+  history as the primary source of truth. Classic ETR shred UI still blanks parties
+  (no reason field). **ABI break:** redeploy or upgrade obligation registries /
+  escrow impl before validating against live docs.
 - **Selective disclosure keeps the subject `id`.** If a credential was issued *with* a
   `credentialSubject.id`, deriving it (even revealing only other fields) **retains that
   id**. To test/produce a credential with *no* subject id, it must be issued without one.

README.md

@@ -905,12 +905,19 @@ Escrow calls accept `{ obligationRegistryAddress, tokenId }` or `{ obligationEsc
 **Endorsement chain** — pass the `TrustVCToken` address to existing helpers:
 
 ```ts
-import { fetchEndorsementChain, fetchObligationEndorsementChain } from '@trustvc/trustvc';
+import { fetchEndorsementChain } from '@trustvc/trustvc';
 
-const chain = await fetchEndorsementChain(obligationRegistry, tokenId, provider);
-// or: fetchObligationEndorsementChain(obligationRegistry, tokenId, provider, { encryptionId })
+const chain = await fetchEndorsementChain(obligationRegistry, tokenId, provider, encryptionKeyId);
 ```
 
+Obligation / BoE titles use the same functions as Token Registry V5 (`fetchEndorsementChain` auto-detects `ObligationEscrow`). These public aliases were removed:
+
+| Removed | Use instead |
+| --- | --- |
+| `fetchObligationEndorsementChain` | `fetchEndorsementChain` |
+| `fetchEscrowTransfersObligation` | `fetchEscrowTransfersV5` (auto-detects obligation status events) |
+| `ObligationEscrowInterface` | `v5SupportInterfaceIds.ObligationEscrow` |
+
 **Low-level contracts** (`@trustvc/trustvc/token-registry-v5/contracts`):
 
 ```ts

package.json

@@ -123,7 +123,7 @@
     "@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.6.0-beta.2",
+    "@tradetrust-tt/token-registry-v5": "npm:@tradetrust-tt/token-registry@^5.6.0-beta.3",
     "@tradetrust-tt/tradetrust": "^6.10.3",
     "@tradetrust-tt/tt-verify": "^9.7.5",
     "@trustvc/document-store": "^1.0.3",

src/__tests__/e2e/obligation-registry-functions/fixtures.ts

@@ -6,7 +6,7 @@ import {
   mintObligationRegistry,
 } from '../../../obligation-registry-functions';
 import type { TransactionOptions } from '../../../obligation-registry-functions/types';
-import { getObligationEscrowAddress } from '../../../core';
+import { getTitleEscrowAddress } from '../../../core';
 import { getSignersV5, getSignersV6, providerV5, providerV6 } from '../fixtures';
 import { createSampleBoeTxOptions } from '../fixtures/sample-boe-credential';
 
@@ -95,7 +95,7 @@ export const getObligationE2EEscrowAddress = async (
   setup: ObligationE2ESetup,
   tokenId: string | number,
 ): Promise<string> => {
-  return getObligationEscrowAddress(setup.obligationRegistry, String(tokenId), setup.provider, {
+  return getTitleEscrowAddress(setup.obligationRegistry, String(tokenId), setup.provider, {
     titleEscrowVersion: 'v5',
   });
 };

src/__tests__/fixtures/endorsement-chain.ts

@@ -1334,7 +1334,7 @@ export const testCases = [
       {
         blockNumber: 15068712,
         holder: '0xCA93690Bb57EEaB273c796a9309246BC0FB93649',
-        owner: '0xe0A71284EF59483795053266CB796B65E48B5124',
+        owner: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
         remark: 'Transfer Holdership',
         timestamp: 1732987703000,
         transactionHash: '0xadb9231bece27ae3aac4e2483752046014e983b80d54dfc490e3459da451dbfa',
@@ -1364,7 +1364,7 @@ export const testCases = [
       {
         blockNumber: 15069476,
         holder: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
-        owner: '0xe0A71284EF59483795053266CB796B65E48B5124',
+        owner: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
         remark: 'Transfer Holder',
         timestamp: 1732989327000,
         transactionHash: '0x2d53578ffe1889dd82eecd5e923dabb06b57eb67a2d16e2c8b210e02b398c5c5',
@@ -1374,7 +1374,7 @@ export const testCases = [
       {
         blockNumber: 15069490,
         holder: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
-        owner: '0xe0A71284EF59483795053266CB796B65E48B5124',
+        owner: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
         remark: 'Return To Issuer',
         timestamp: 1732989357000,
         transactionHash: '0x8e575e2a281d3bce5d6e4b6298e1e54b9c49bad0ef135ae9e68fc9d02ccc1ba1',
@@ -1384,7 +1384,7 @@ export const testCases = [
       {
         blockNumber: 15069501,
         holder: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
-        owner: '0xe0A71284EF59483795053266CB796B65E48B5124',
+        owner: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
         remark: 'Reject Return To Issuer',
         timestamp: 1732989379000,
         transactionHash: '0x3bf456d1fa29e4b7cfc3cbfc3a568f5c2c4e1dd8454d25f8822eea3b65c66956',
@@ -1394,7 +1394,7 @@ export const testCases = [
       {
         blockNumber: 15069511,
         holder: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
-        owner: '0xe0A71284EF59483795053266CB796B65E48B5124',
+        owner: '0x433097a1C1b8a3e9188d8C54eCC057B1D69f1638',
         remark: 'Return To Issuer',
         timestamp: 1732989401000,
         transactionHash: '0x99e56c4a1ddcf1a8031402a46eb41b4c41f1379f420287aaa57cad0e18ed85ce',

src/__tests__/obligation-registry-functions/fixtures.ts

@@ -37,7 +37,7 @@ vi.mock('../../utils/ethers', async (importOriginal) => {
 
 vi.mock('../../core', () => ({
   encrypt: vi.fn(() => 'encrypted_remarks'),
-  getObligationEscrowAddress: vi.fn(),
+  getTitleEscrowAddress: vi.fn(),
   checkSupportsInterface: vi.fn(),
 }));
 

src/__tests__/obligation-registry-functions/lifecycle.test.ts

@@ -42,7 +42,7 @@ describe.each(providers)(
         } as unknown as Network);
       }
 
-      vi.spyOn(coreModule, 'getObligationEscrowAddress').mockResolvedValue(
+      vi.spyOn(coreModule, 'getTitleEscrowAddress').mockResolvedValue(
         MOCK_OBLIGATION_ESCROW_ADDRESS,
       );
       mockObligationEscrowContract.callStatic.accept.mockResolvedValue(true);

src/__tests__/obligation-registry-functions/rejectTransfers.test.ts

@@ -41,7 +41,7 @@ describe.each(providers)(
         } as unknown as Network);
       }
 
-      vi.spyOn(coreModule, 'getObligationEscrowAddress').mockResolvedValue(
+      vi.spyOn(coreModule, 'getTitleEscrowAddress').mockResolvedValue(
         MOCK_OBLIGATION_ESCROW_ADDRESS,
       );
       mockObligationEscrowContract.callStatic.rejectTransferHolder.mockResolvedValue(true);
@@ -72,7 +72,7 @@ describe.each(providers)(
       );
 
       expect(result).toEqual('reject_transfer_beneficiary_tx_hash');
-      expect(coreModule.getObligationEscrowAddress).toHaveBeenCalled();
+      expect(coreModule.getTitleEscrowAddress).toHaveBeenCalled();
     });
 
     it('rejectTransferOwnersObligationRegistry without remarks', async () => {

src/__tests__/obligation-registry-functions/returnToken.test.ts

@@ -43,7 +43,7 @@ describe.each(providers)(
         } as unknown as Network);
       }
 
-      vi.spyOn(coreModule, 'getObligationEscrowAddress').mockResolvedValue(
+      vi.spyOn(coreModule, 'getTitleEscrowAddress').mockResolvedValue(
         MOCK_OBLIGATION_ESCROW_ADDRESS,
       );
       vi.spyOn(coreModule, 'checkSupportsInterface').mockResolvedValue(true);

src/__tests__/obligation-registry-functions/status.test.ts

@@ -38,7 +38,7 @@ describe.each(providers)(
         vi.spyOn(Provider, 'getNetwork').mockResolvedValue({ chainId: 1 } as unknown as Network);
       }
 
-      vi.spyOn(coreModule, 'getObligationEscrowAddress').mockResolvedValue(
+      vi.spyOn(coreModule, 'getTitleEscrowAddress').mockResolvedValue(
         MOCK_OBLIGATION_ESCROW_ADDRESS,
       );
       mockObligationEscrowContract.status.mockResolvedValue(ObligationDocumentStatus.Accepted);

src/__tests__/obligation-registry-functions/transfers.test.ts

@@ -43,7 +43,7 @@ describe.each(providers)(
         } as unknown as Network);
       }
 
-      vi.spyOn(coreModule, 'getObligationEscrowAddress').mockResolvedValue(
+      vi.spyOn(coreModule, 'getTitleEscrowAddress').mockResolvedValue(
         MOCK_OBLIGATION_ESCROW_ADDRESS,
       );
       Object.values(mockObligationEscrowContract.callStatic).forEach((fn) =>
@@ -74,7 +74,7 @@ describe.each(providers)(
       );
 
       expect(result).toEqual('transfer_holder_tx_hash');
-      expect(coreModule.getObligationEscrowAddress).toHaveBeenCalled();
+      expect(coreModule.getTitleEscrowAddress).toHaveBeenCalled();
     });
 
     it('transferBeneficiaryObligationRegistry without remarks', async () => {

src/constants.ts

@@ -1 +1,48 @@
 export const DEFAULT_KEY = '4d5a4e3f2f6d2b0a1f2e9b8f8a3c7a0b8d4f5c2e7b1a1c3f2e7b8c2d5a4f7e3e';
+
+// Match JSON-RPC / HTTP codes as standalone tokens (not inside block numbers, gas, chain IDs).
+const rpcCode = (code: string): string => `(?:^|[^0-9])${code}(?![0-9])`;
+
+export const INFURA_FREE_TIER_RANGE_RE = new RegExp(
+  `free tier plan|10\\s*block difference|block range should work:\\s*\\[0x0,\\s*0x9\\]|Upgrade to PAYG|${rpcCode('-32600')}`,
+  'i',
+);
+// reponse extracted from infura logs and also alchemy logs
+export const RANGE_TOO_LARGE_ERROR_RE = new RegExp(
+  [
+    'query returned more than',
+    'too large',
+    'block range',
+    '10,?000 results',
+    'response size',
+    'exceeds limit',
+    '10\\s*block',
+    'free tier',
+    'block difference',
+    'Upgrade to PAYG',
+    rpcCode('-32012'),
+    rpcCode('-32600'),
+  ].join('|'),
+  'i',
+);
+// response extracted from infura logs and also alchemy logs
+export const RATE_LIMIT_ERROR_RE = new RegExp(
+  [
+    `rate-?limit`,
+    `too many requests`,
+    `could not coalesce`,
+    rpcCode('429'),
+    rpcCode('-32005'),
+  ].join('|'),
+  'i',
+);
+
+export const INITIAL_CHUNK_SIZE = 10_000;
+export const FREE_TIER_MAX_CHUNK_SIZE = 10;
+export const MIN_CHUNK_SIZE = 1;
+export const MAX_CHUNK_SIZE = 50_000;
+export const DEFAULT_MAX_BLOCKS_TO_SCAN = 200_000;
+export const FREE_TIER_MAX_REQUESTS = 5_000;
+export const FREE_TIER_MAX_DURATION_MS = 60_000;
+export const RATE_LIMIT_MAX_RETRIES = 3;
+export const RATE_LIMIT_BASE_DELAY_MS = 500;