Feature/endorsement chain

package.json

@@ -35,7 +35,7 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^5.3.8",
-    "@trustvc/trustvc": "^2.16.0-beta.4",
+    "@trustvc/trustvc": "2.16.0-beta.5",
     "@types/yargs": "^17.0.32",
     "chalk": "^4.1.2",
     "dotenv": "^16.0.0",

src/commands/helpers.ts

@@ -8,6 +8,7 @@ import {
   v5SupportInterfaceIds,
   DocumentStore__factory,
   encrypt,
+  getTitleEscrowAddress,
 } from '@trustvc/trustvc';
 
 // Internal utilities
@@ -462,19 +463,24 @@ interface ConnectToObligationEscrowArgs {
 }
 
 /**
- * Resolves ObligationEscrow via ownerOf(tokenId) on the obligation registry and connects.
+ * Resolves ObligationEscrow via getTitleEscrowAddress (handles inactive/burned titles
+ * via factory CREATE2) and connects — same as websites / demo dry-run resolution.
  */
 export const connectToObligationEscrow = async ({
   tokenId,
   address,
   wallet,
 }: ConnectToObligationEscrowArgs) => {
   try {
-    signale.info(`Connecting to obligation registry at: ${address}`);
-    const registry = new ethers.Contract(address, TrustVCToken__factory.abi, wallet as any);
+    const provider = wallet.provider;
+    if (!provider) {
+      throw new Error('Provider is required to resolve obligation escrow address');
+    }
 
-    signale.info(`Fetching obligation escrow address for tokenId: ${tokenId}`);
-    const escrowAddress = await registry.ownerOf(tokenId);
+    signale.info(`Resolving obligation escrow for tokenId: ${tokenId} on ${address}`);
+    const escrowAddress = await getTitleEscrowAddress(address, tokenId, provider as any, {
+      titleEscrowVersion: 'v5',
+    });
     signale.info(`Obligation escrow address: ${escrowAddress}`);
 
     if (!escrowAddress || escrowAddress === ZeroAddress) {

src/commands/obligation-escrow/endorsement-chain.ts

@@ -0,0 +1,80 @@
+import { info, success } from 'signale';
+import { fetchEndorsementChain } from '@trustvc/trustvc';
+import { BaseObligationEscrowCommand } from '../../types';
+import {
+  extractObligationDocumentInfo,
+  getSupportedNetwork,
+  promptAndReadDocument,
+  verifyDocumentSignature,
+} from '../../utils';
+import { runObligationEscrowCommand } from './shared';
+
+export const command = 'endorsement-chain';
+export const describe =
+  'Fetch BoE obligation endorsement chain (transfers + status events) via network Infura/RPC';
+
+/** Read-only — document only; decrypt remarks with credential `id`. */
+export type ObligationEscrowEndorsementChainCommand = Pick<
+  BaseObligationEscrowCommand,
+  'network' | 'obligationRegistryAddress' | 'tokenId' | 'encryptionKey'
+>;
+
+export const handler = async (): Promise<void> =>
+  runObligationEscrowCommand(promptForInputs, endorsementChainHandler);
+
+export const promptForInputs = async (): Promise<ObligationEscrowEndorsementChainCommand> => {
+  const document = await promptAndReadDocument();
+  await verifyDocumentSignature(document);
+  const { obligationRegistry, tokenId, network, documentId } =
+    await extractObligationDocumentInfo(document);
+  return {
+    network,
+    obligationRegistryAddress: obligationRegistry,
+    tokenId,
+    encryptionKey: documentId,
+  };
+};
+
+export const endorsementChainHandler = async (args: ObligationEscrowEndorsementChainCommand) => {
+  const { obligationRegistryAddress, tokenId, network, encryptionKey } = args;
+  // Always use ChainInfo/Infura-style network RPC — never a wallet provider (MetaMask range caps).
+  const provider = getSupportedNetwork(network).provider();
+
+  info(`Fetching endorsement chain for ${tokenId} on ${obligationRegistryAddress} (${network})…`);
+  const chain = await fetchEndorsementChain(
+    obligationRegistryAddress,
+    tokenId,
+    provider as any,
+    encryptionKey,
+  );
+
+  success(`Endorsement chain (${chain.length} event${chain.length === 1 ? '' : 's'})`);
+  let lastOwner = '';
+  let lastHolder = '';
+  const isZero = (value?: string) => !value || /^0x0{40}$/i.test(value);
+  chain.forEach((event, index) => {
+    const isShred =
+      event.type === 'RETURN_TO_ISSUER_ACCEPTED' || event.type === 'SURRENDER_ACCEPTED';
+    // eBoE shred keeps last owner/holder on the shred row.
+    const owner = isZero(event.owner) ? lastOwner : event.owner || lastOwner;
+    const holder = isZero(event.holder) ? lastHolder : event.holder || lastHolder;
+    if (!isZero(owner)) lastOwner = owner;
+    if (!isZero(holder)) lastHolder = holder;
+    if (isShred) {
+      lastOwner = '';
+      lastHolder = '';
+    }
+
+    const when = event.timestamp ? new Date(event.timestamp).toISOString() : 'unknown-time';
+    info(`  ${index + 1}. [${event.type}] block=${event.blockNumber} @ ${when}`);
+    info(`     Owner:  ${owner || '-'}`);
+    info(`     Holder: ${holder || '-'}`);
+    if (isShred && event.terminationReason && event.terminationReason !== 'None') {
+      const reasonLabel =
+        event.terminationReason === 'ReturnToIssuer' ? 'Return to issuer' : event.terminationReason;
+      info(`     Reason: ${reasonLabel}`);
+    }
+    if (event.remark) info(`     Remark: ${event.remark}`);
+    if (event.transactionHash) info(`     Tx:     ${event.transactionHash}`);
+  });
+};

src/commands/obligation-escrow/status.ts

@@ -2,11 +2,13 @@ import { info, success } from 'signale';
 import {
   ObligationDocumentStatus,
   ObligationEscrowTerminationReason,
+  getTitleEscrowAddress,
   getObligationEscrowTerminationReason,
   getObligationRegistryStatus,
   isObligationRegistryRegistered,
+  v5Contracts,
 } from '@trustvc/trustvc';
-import { VoidSigner, ZeroAddress } from 'ethers';
+import { Contract, VoidSigner, ZeroAddress } from 'ethers';
 import { BaseObligationEscrowCommand } from '../../types';
 import {
   extractObligationDocumentInfo,
@@ -17,6 +19,8 @@ import {
 } from '../../utils';
 import { runObligationEscrowCommand } from './shared';
 
+const { ObligationEscrow__factory } = v5Contracts;
+
 export const command = 'status';
 export const describe = 'Read BoE obligation escrow status / registration / termination reason';
 
@@ -60,16 +64,43 @@ export const statusHandler = async (args: ObligationEscrowStatusCommand) => {
   const readOnlySigner = new VoidSigner(ZeroAddress, provider);
   const opts = { obligationRegistryAddress, tokenId };
 
-  const status = await getObligationRegistryStatus(opts, toSdkSigner(readOnlySigner), { tokenId });
-  const registered = await isObligationRegistryRegistered(opts, toSdkSigner(readOnlySigner), {
-    tokenId,
-  });
-  const reason = await getObligationEscrowTerminationReason(opts, toSdkSigner(readOnlySigner), {
-    tokenId,
-  });
+  const [status, registered, reason, escrowAddress] = await Promise.all([
+    getObligationRegistryStatus(opts, toSdkSigner(readOnlySigner), { tokenId }),
+    isObligationRegistryRegistered(opts, toSdkSigner(readOnlySigner), { tokenId }),
+    getObligationEscrowTerminationReason(opts, toSdkSigner(readOnlySigner), { tokenId }),
+    getTitleEscrowAddress(obligationRegistryAddress, tokenId, provider as any, {
+      titleEscrowVersion: 'v5',
+    }),
+  ]);
+
+  const isZero = (value?: string) => !value || value === ZeroAddress;
+
+  let beneficiary = '';
+  let holder = '';
+  let nominee = '';
+  try {
+    const escrow = new Contract(escrowAddress, ObligationEscrow__factory.abi, provider);
+    const [currentBeneficiary, currentHolder, currentNominee, lastBeneficiary, lastHolder] =
+      await Promise.all([
+        escrow.beneficiary(),
+        escrow.holder(),
+        escrow.nominee(),
+        escrow.lastBeneficiary(),
+        escrow.lastHolder(),
+      ]);
+    beneficiary = isZero(currentBeneficiary) ? lastBeneficiary : currentBeneficiary;
+    holder = isZero(currentHolder) ? lastHolder : currentHolder;
+    nominee = currentNominee;
+  } catch {
+    // Escrow may be inactive / not readable after shred — still print registry-level status.
+  }
 
   success(`Obligation ${tokenId} on ${obligationRegistryAddress}`);
+  info(`  Escrow: ${escrowAddress}`);
   info(`  Status: ${STATUS_LABEL[status] ?? status} (${status})`);
   info(`  Registered: ${registered}`);
   info(`  Termination reason: ${REASON_LABEL[reason] ?? reason} (${reason})`);
+  if (!isZero(beneficiary)) info(`  Owner (beneficiary): ${beneficiary}`);
+  if (!isZero(holder)) info(`  Holder: ${holder}`);
+  if (nominee && nominee !== ZeroAddress) info(`  Nominee: ${nominee}`);
 };

src/commands/verify.ts

@@ -126,18 +126,6 @@ export const verify = async (signedVC: SignedVerifiableCredential, options: Veri
   ];
   fragments.forEach(logResultStatus);
 
-  const obligationStatus = getObligationDocumentStatus(result);
-  if (obligationStatus) {
-    const parts = [`registry=${obligationStatus.obligationRegistry}`];
-    if (obligationStatus.status !== undefined) {
-      parts.push(`status=${obligationStatus.status}`);
-    }
-    if (obligationStatus.terminationReason !== undefined) {
-      parts.push(`terminationReason=${obligationStatus.terminationReason}`);
-    }
-    signale.info(`Obligation document status: ${parts.join(' ')}`);
-  }
-
   if (isPresentation && fragments.every((fragment) => fragment.status === 'VALID')) {
     logPresentationCredentialCount(fragments[0]);
   }

tests/commands/obligation-escrow/endorsement-chain.test.ts

@@ -0,0 +1,105 @@
+import { beforeEach, describe, expect, it, MockedFunction, vi } from 'vitest';
+import { endorsementChainHandler } from '../../../src/commands/obligation-escrow/endorsement-chain';
+import { NetworkCmdName } from '../../../src/utils';
+
+vi.mock('signale', async (importOriginal) => {
+  const originalSignale = await importOriginal<typeof import('signale')>();
+  return {
+    ...originalSignale,
+    Signale: class MockSignale {
+      await = vi.fn();
+      success = vi.fn();
+      error = vi.fn();
+      info = vi.fn();
+      warn = vi.fn();
+      constructor() {}
+    },
+    error: vi.fn(),
+    info: vi.fn(),
+    success: vi.fn(),
+    warn: vi.fn(),
+    await: vi.fn(),
+    default: {
+      await: vi.fn(),
+      success: vi.fn(),
+      error: vi.fn(),
+      info: vi.fn(),
+      warn: vi.fn(),
+    },
+  };
+});
+
+vi.mock('@trustvc/trustvc', async () => {
+  const actual = await vi.importActual<typeof import('@trustvc/trustvc')>('@trustvc/trustvc');
+  return {
+    ...actual,
+    fetchEndorsementChain: vi.fn().mockResolvedValue([
+      {
+        type: 'INITIAL',
+        blockNumber: 1,
+        timestamp: 1_700_000_000_000,
+        owner: '0xOwner',
+        holder: '0xHolder',
+        remark: 'minted',
+        transactionHash: '0xtx1',
+      },
+      {
+        type: 'RETURN_TO_ISSUER_ACCEPTED',
+        blockNumber: 2,
+        timestamp: 1_700_000_100_000,
+        owner: '0xOwner',
+        holder: '0xHolder',
+        remark: 'burned',
+        transactionHash: '0xtx2',
+        terminationReason: 'Discharged',
+      },
+    ]),
+  };
+});
+
+vi.mock('../../../src/utils', async (importOriginal) => {
+  const actual = await importOriginal<typeof import('../../../src/utils')>();
+  return {
+    ...actual,
+    getSupportedNetwork: vi.fn().mockReturnValue({
+      provider: () => ({ mock: 'infura-provider' }),
+      networkId: 11155111,
+    }),
+    getErrorMessage: (e: unknown) => (e instanceof Error ? e.message : String(e)),
+  };
+});
+
+describe('obligation-escrow/endorsement-chain', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('fetches chain via network Infura/RPC using document id as keyId', async () => {
+    const trustvc = await import('@trustvc/trustvc');
+    const signale = await import('signale');
+    await endorsementChainHandler({
+      network: NetworkCmdName.Sepolia,
+      obligationRegistryAddress: '0xRegistry',
+      tokenId: '0x1',
+      encryptionKey: 'urn:uuid:test-doc-id',
+    });
+
+    expect(trustvc.fetchEndorsementChain as MockedFunction<any>).toHaveBeenCalledWith(
+      '0xRegistry',
+      '0x1',
+      { mock: 'infura-provider' },
+      'urn:uuid:test-doc-id',
+    );
+
+    const infoMock = signale.info as MockedFunction<any>;
+    const infoMessages = infoMock.mock.calls.map((args) => String(args[0]));
+    expect(infoMessages.some((msg) => msg.includes('Owner:') && msg.includes('0xOwner'))).toBe(
+      true,
+    );
+    expect(infoMessages.some((msg) => msg.includes('Holder:') && msg.includes('0xHolder'))).toBe(
+      true,
+    );
+    expect(infoMessages.some((msg) => msg.includes('Reason: Discharged'))).toBe(true);
+    expect(infoMessages.some((msg) => msg.includes('Remark: burned'))).toBe(true);
+  });
+});