From 2ffa63df41022395cdfccdd7cf1f9de63b8d854c Mon Sep 17 00:00:00 2001
From: Andrew Miller <andrew@dragonchain.com>
Date: Tue, 2 Jun 2026 14:12:59 -0400
Subject: [PATCH] add getInterchain: trace a transaction/block to validator
 blocks + interchain anchors

New transaction.getInterchain and block.getInterchain call the prime-node
/api/v1/{transaction,block}/{id}/interchain endpoints, returning an
InterchainTrace { blockId, validatorBlocks, interchainTransactions }. Adds
VerificationBlock / InterchainTransaction / InterchainTrace interfaces and
method-existence assertions.
---
 src/block.ts       | 10 +++++++++-
 src/transaction.ts | 11 +++++++++++
 src/types.ts       | 41 +++++++++++++++++++++++++++++++++++++++++
 tests/sdk.test.ts  |  2 ++
 4 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/src/block.ts b/src/block.ts
index 52d1cf4..1e7a1bc 100644
--- a/src/block.ts
+++ b/src/block.ts
@@ -3,7 +3,7 @@
  */
 
 import { DragonchainClient } from './client';
-import { Block } from './types';
+import { Block, InterchainTrace } from './types';
 
 export class BlockClient {
   private client: DragonchainClient;
@@ -18,4 +18,12 @@ export class BlockClient {
   async get(blockId: string): Promise<Block> {
     return this.client.get<Block>(`/api/v1/block/${blockId}`);
   }
+
+  /**
+   * Traces a block to the validator (verification) blocks that validated it and
+   * the public-chain interchain anchors those validator blocks were bundled into.
+   */
+  async getInterchain(blockId: string): Promise<InterchainTrace> {
+    return this.client.get<InterchainTrace>(`/api/v1/block/${blockId}/interchain`);
+  }
 }
diff --git a/src/transaction.ts b/src/transaction.ts
index 7fa459c..a738e0f 100644
--- a/src/transaction.ts
+++ b/src/transaction.ts
@@ -11,6 +11,7 @@ import {
   TransactionBulkResponse,
   Transaction,
   ListTransactionsResponse,
+  InterchainTrace,
 } from './types';
 
 export class TransactionClient {
@@ -49,6 +50,16 @@ export class TransactionClient {
     return this.client.get<Transaction>(`/api/v1/transaction/${transactionId}`);
   }
 
+  /**
+   * Traces a transaction to the validator (verification) blocks that validated
+   * its prime block and the public-chain interchain anchors those validator
+   * blocks were bundled into. If the transaction is still pending (not yet in a
+   * block) the trace's arrays are empty.
+   */
+  async getInterchain(transactionId: string): Promise<InterchainTrace> {
+    return this.client.get<InterchainTrace>(`/api/v1/transaction/${transactionId}/interchain`);
+  }
+
   /**
    * Lists all transactions
    */
diff --git a/src/types.ts b/src/types.ts
index 8b87857..22d8810 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -142,6 +142,47 @@ export interface Block {
   proof: BlockProof;
 }
 
+// Interchain Trace Types
+
+/** A validator's verification of a prime block. */
+export interface VerificationBlock {
+  version: string;
+  primeChainId: string;
+  primeBlockId: string;
+  timestamp: string;
+  verifierPublicKey: string;
+  verifierSignature: string;
+}
+
+/**
+ * An anchor broadcast to a public blockchain (e.g. ETH/BTC) bundling one or more
+ * validator blocks. `validatorBlocks` holds the covered prime block ids;
+ * `coveredPrimeChainIds` the prime chains they belong to.
+ */
+export interface InterchainTransaction {
+  id: number;
+  version: string;
+  timestamp: string;
+  chainId: string;
+  transHash: string;
+  blockId: string;
+  validatorBlocks: string[];
+  validatorBlockhash: string;
+  signature: string;
+  coveredPrimeChainIds: string[];
+}
+
+/**
+ * Links a prime block to the validator (verification) blocks that validated it
+ * and the public-chain interchain anchors those validator blocks were bundled
+ * into. Returned by `transaction.getInterchain` and `block.getInterchain`.
+ */
+export interface InterchainTrace {
+  blockId: string;
+  validatorBlocks: VerificationBlock[];
+  interchainTransactions: InterchainTransaction[];
+}
+
 // System Types
 export interface SystemStatus {
   id: string;
diff --git a/tests/sdk.test.ts b/tests/sdk.test.ts
index da298d2..8380eba 100644
--- a/tests/sdk.test.ts
+++ b/tests/sdk.test.ts
@@ -47,6 +47,7 @@ describe('DragonchainSDK', () => {
       expect(typeof sdk.transaction.create).toBe('function');
       expect(typeof sdk.transaction.createBulk).toBe('function');
       expect(typeof sdk.transaction.get).toBe('function');
+      expect(typeof sdk.transaction.getInterchain).toBe('function');
       expect(typeof sdk.transaction.list).toBe('function');
     });
 
@@ -68,6 +69,7 @@ describe('DragonchainSDK', () => {
 
     it('should have block module with correct methods', () => {
       expect(typeof sdk.block.get).toBe('function');
+      expect(typeof sdk.block.getInterchain).toBe('function');
     });
 
     it('should have system module with correct methods', () => {