getInterchain: perChain + chains options (default first anchor per chain); bump 1.5.0

transaction.getInterchain / block.getInterchain take an optional
{ perChain?, chains? } that maps to prime-node's ?perChain=&chains= params.
Default (no options) returns one anchor per chain. Shared buildInterchainQuery
helper + InterchainOptions type, exported; jest-tested.

README.md

@@ -145,6 +145,24 @@ await sdk.transactionType.delete('my-type');
 const block = await sdk.block.get('block-id');
 ```
 
+### Interchain trace
+
+`transaction.getInterchain` / `block.getInterchain` trace a prime block to the
+public-chain anchors covering it. By default they return the **first anchor per
+chain** (anchor proofs are chained, so the earliest per chain is the meaningful
+one). Tune with options:
+
+```typescript
+// Default: first anchor per chain (ETH, BTC, …)
+const trace = await sdk.block.getInterchain('42');
+
+// Up to 3 anchors per chain
+await sdk.block.getInterchain('42', { perChain: 3 });
+
+// All anchors, only the ETH-mainnet chain ("1"); "0" = BTC
+await sdk.block.getInterchain('42', { perChain: 0, chains: ['1'] });
+```
+
 ### Proof Measure (public, unauthenticated)
 
 `proof-measure` is a separate, **public, unauthenticated** Dragonchain service

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dragonchain-inc/prime-sdk",
-  "version": "1.4.0",
+  "version": "1.5.0",
   "description": "Official Dragonchain Prime SDK for Node.js and TypeScript",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

src/block.ts

@@ -3,6 +3,7 @@
  */
 
 import { DragonchainClient } from './client';
+import { InterchainOptions, buildInterchainQuery } from './interchain';
 import { Block, InterchainTrace } from './types';
 
 export class BlockClient {
@@ -23,7 +24,9 @@ export class BlockClient {
    * 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`);
+  async getInterchain(blockId: string, options?: InterchainOptions): Promise<InterchainTrace> {
+    return this.client.get<InterchainTrace>(
+      `/api/v1/block/${blockId}/interchain${buildInterchainQuery(options)}`
+    );
   }
 }

src/index.ts

@@ -85,6 +85,7 @@ export { BlockClient } from './block';
 export { SystemClient } from './system';
 export { ProofMeasureClient, PROOF_MEASURE_DEFAULT_BASE_URL } from './proofMeasure';
 export { UnauthHttpClient, UnauthClientConfig } from './unauthHttpClient';
+export { InterchainOptions, buildInterchainQuery } from './interchain';
 
 // Default export
 export default DragonchainSDK;

src/interchain.ts

@@ -0,0 +1,37 @@
+/**
+ * Options + query builder for the interchain-trace endpoints
+ * (transaction.getInterchain / block.getInterchain).
+ *
+ * Anchor proofs are chained, so by default the trace returns the first anchor
+ * per public chain; these options change how many and which chains are returned.
+ */
+
+export interface InterchainOptions {
+  /**
+   * Max interchain anchors returned per public chain, earliest-first.
+   * 1 = the first anchor per chain (the service default); 0 = all anchors.
+   */
+  perChain?: number;
+  /**
+   * Interchain chain ids to include ("1" = ETH mainnet, "0" = BTC; testnet ids
+   * differ). Omit to include every chain found.
+   */
+  chains?: string[];
+}
+
+/**
+ * Builds the "?perChain=...&chains=..." suffix for the interchain trace
+ * endpoints. Returns "" when no options are set (the server then applies its
+ * defaults: one anchor per chain, all chains).
+ */
+export function buildInterchainQuery(options?: InterchainOptions): string {
+  if (!options) return '';
+  const parts: string[] = [];
+  if (options.perChain !== undefined) {
+    parts.push(`perChain=${encodeURIComponent(String(options.perChain))}`);
+  }
+  if (options.chains && options.chains.length > 0) {
+    parts.push(`chains=${options.chains.map(encodeURIComponent).join(',')}`);
+  }
+  return parts.length ? `?${parts.join('&')}` : '';
+}

src/transaction.ts

@@ -3,6 +3,7 @@
  */
 
 import { DragonchainClient } from './client';
+import { InterchainOptions, buildInterchainQuery } from './interchain';
 import {
   ContentType,
   TransactionCreateRequest,
@@ -56,8 +57,13 @@ export class TransactionClient {
    * 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`);
+  async getInterchain(
+    transactionId: string,
+    options?: InterchainOptions
+  ): Promise<InterchainTrace> {
+    return this.client.get<InterchainTrace>(
+      `/api/v1/transaction/${transactionId}/interchain${buildInterchainQuery(options)}`
+    );
   }
 
   /**

tests/interchain.test.ts

@@ -0,0 +1,27 @@
+import { buildInterchainQuery } from '../src/interchain';
+
+describe('buildInterchainQuery', () => {
+  it('returns empty string with no options', () => {
+    expect(buildInterchainQuery()).toBe('');
+    expect(buildInterchainQuery({})).toBe('');
+  });
+
+  it('encodes perChain (including 0 for all)', () => {
+    expect(buildInterchainQuery({ perChain: 1 })).toBe('?perChain=1');
+    expect(buildInterchainQuery({ perChain: 0 })).toBe('?perChain=0');
+  });
+
+  it('joins chains with commas', () => {
+    expect(buildInterchainQuery({ chains: ['1', '0'] })).toBe('?chains=1,0');
+  });
+
+  it('combines perChain and chains', () => {
+    expect(buildInterchainQuery({ perChain: 2, chains: ['1', '0'] })).toBe(
+      '?perChain=2&chains=1,0'
+    );
+  });
+
+  it('ignores an empty chains array', () => {
+    expect(buildInterchainQuery({ chains: [] })).toBe('');
+  });
+});