@orbinum/sdk 0.7.10 → 0.8.1

package/dist/index.d.mts

@@ -530,8 +530,6 @@ interface ShieldedCommitment {
     assetId: string;
     /** Origin of the commitment: direct shield, output of private transfer, or change from unshield. */
     source: 'shield' | 'transfer' | 'unshield';
-    /** SS58 or 0x-prefixed depositor address, null if not tracked. */
-    sender: string | null;
     /** 0x-prefixed encrypted memo hex, null if not present. */
     encryptedMemo: string | null;
     timestampMs: number | null;
@@ -728,17 +726,29 @@ interface RegisteredAsset {
     timestampMs: number | null;
 }
 /**
- * A single shielded activity event tied to an address.
- * The `kind` discriminant identifies whether it is a shield (commitment),
- * unshield, or private transfer event.
- */
-type ShieldedAddressEvent = ({
-    kind: 'commitment';
-} & ShieldedCommitment) | ({
-    kind: 'unshield';
-} & Unshield) | ({
-    kind: 'transfer';
-} & PrivateTransferTimestamp);
+ * One shielded-pool BOUNDARY event for an address, as served by
+ * `GET /shielded/address/:addr`. Only boundary facts are exposed — block,
+ * asset, amount (unshield), time, tx hash. Note internals (commitment hex,
+ * leaf index, nullifier, memo, sender/recipient) are never returned
+ * per-address: a public sender→leaf mapping would shrink the shielded pool's
+ * anonymity set. Private transfers carry no address and are never included.
+ */
+interface ShieldedAddressEvent {
+    /** 'shield' = deposit into the pool by this address; 'unshield' = withdrawal received by it. */
+    kind: 'shield' | 'unshield';
+    blockNumber: number;
+    extrinsicIndex: number | null;
+    /** Asset ID as decimal string. */
+    assetId: string;
+    /**
+     * Amount as decimal string (bigint-safe) for unshields.
+     * Always null for shields — the shield amount lives in the extrinsic, not the index.
+     */
+    amount: string | null;
+    timestampMs: number | null;
+    /** Blake2-256 hash of the enclosing extrinsic, 0x-prefixed. Null if not decoded. */
+    hash: string | null;
+}
 /** A validator node indexed from pallet-validator-set events. */
 interface IndexedValidator {
     account: string;
@@ -834,18 +844,35 @@ declare class IndexerClient {
      * For the current Orbinum testnet/mainnet scale this is the recommended approach.
      */
     getAllSpentNullifiers(): Promise<Set<string>>;
+    /** Server-enforced max items per by-nullifiers / by-commitments request. */
+    private static readonly TRANSFER_LOOKUP_CHUNK;
+    /**
+     * Chunked fetch for the transfer timestamp lookups. The reader silently
+     * truncates each request to 50 items, so larger inputs MUST be split or
+     * results are silently lost. Responses are merged per extrinsic
+     * (`blockNumber:extrinsicIndex`), concatenating the matched arrays, and
+     * sorted by block descending.
+     *
+     * Privacy note: these lookups send the wallet's own note identifiers to
+     * the indexer — a bounded, documented linkage tradeoff for timestamp
+     * recovery. They are NEVER used for spent-STATUS checks (PIR-A: status
+     * comes from the anonymous full-set `/shielded/nullifiers/all` download).
+     */
+    private fetchTransfersChunked;
     /**
      * Returns temporal metadata for private transfers that spent any of the given nullifiers.
      * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
      * between inputs and outputs to prevent graph reconstruction.
-     * Accepts up to 50 nullifiers (0x-prefixed hex).
+     * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+     * and merged per extrinsic.
      */
     getTransfersByNullifiers(nullifiers: string[]): Promise<PrivateTransferTimestamp[]>;
     /**
      * Returns temporal metadata for private transfers that produced any of the given commitments.
      * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
      * between outputs and inputs to prevent graph reconstruction.
-     * Accepts up to 50 commitments (0x-prefixed hex).
+     * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+     * and merged per extrinsic.
      */
     getTransfersByCommitments(commitments: string[]): Promise<PrivateTransferTimestamp[]>;
     /** Returns a paginated list of unshield events. */
@@ -881,11 +908,6 @@ declare class IndexerClient {
     }): Promise<PaginatedResult<IndexedBlock>>;
     /** Returns a single block by number or hash, or null if not found. */
     getBlock(numberOrHash: string | number): Promise<IndexedBlock | null>;
-    /** Returns a paginated list of shielded commitments initiated by an address. */
-    getAddressCommitments(address: string, params?: {
-        page?: number;
-        limit?: number;
-    }): Promise<PaginatedResult<ShieldedCommitment>>;
     /**
      * Returns a paginated list of unshield events where the given address is the recipient.
      * Accepts a 0x-prefixed EVM address or an SS58 Substrate address.
@@ -895,9 +917,11 @@ declare class IndexerClient {
         limit?: number;
     }): Promise<PaginatedResult<Unshield>>;
     /**
-     * Returns a paginated list of all shielded activity (commitments, unshields,
-     * private transfers) associated with the given address.
-     * Each item is tagged with a `kind` discriminant.
+     * Returns the shielded-pool BOUNDARY activity for an address: shields it
+     * deposited and unshields it received, tagged `kind: 'shield' | 'unshield'`.
+     * Only boundary fields are returned (block, asset, amount for unshields,
+     * timestamp, tx hash) — note internals are never served per-address, and
+     * private transfers carry no address at all (PIR-A).
      */
     getAddressShieldedActivity(address: string, params?: {
         page?: number;

package/dist/index.d.ts

@@ -530,8 +530,6 @@ interface ShieldedCommitment {
     assetId: string;
     /** Origin of the commitment: direct shield, output of private transfer, or change from unshield. */
     source: 'shield' | 'transfer' | 'unshield';
-    /** SS58 or 0x-prefixed depositor address, null if not tracked. */
-    sender: string | null;
     /** 0x-prefixed encrypted memo hex, null if not present. */
     encryptedMemo: string | null;
     timestampMs: number | null;
@@ -728,17 +726,29 @@ interface RegisteredAsset {
     timestampMs: number | null;
 }
 /**
- * A single shielded activity event tied to an address.
- * The `kind` discriminant identifies whether it is a shield (commitment),
- * unshield, or private transfer event.
- */
-type ShieldedAddressEvent = ({
-    kind: 'commitment';
-} & ShieldedCommitment) | ({
-    kind: 'unshield';
-} & Unshield) | ({
-    kind: 'transfer';
-} & PrivateTransferTimestamp);
+ * One shielded-pool BOUNDARY event for an address, as served by
+ * `GET /shielded/address/:addr`. Only boundary facts are exposed — block,
+ * asset, amount (unshield), time, tx hash. Note internals (commitment hex,
+ * leaf index, nullifier, memo, sender/recipient) are never returned
+ * per-address: a public sender→leaf mapping would shrink the shielded pool's
+ * anonymity set. Private transfers carry no address and are never included.
+ */
+interface ShieldedAddressEvent {
+    /** 'shield' = deposit into the pool by this address; 'unshield' = withdrawal received by it. */
+    kind: 'shield' | 'unshield';
+    blockNumber: number;
+    extrinsicIndex: number | null;
+    /** Asset ID as decimal string. */
+    assetId: string;
+    /**
+     * Amount as decimal string (bigint-safe) for unshields.
+     * Always null for shields — the shield amount lives in the extrinsic, not the index.
+     */
+    amount: string | null;
+    timestampMs: number | null;
+    /** Blake2-256 hash of the enclosing extrinsic, 0x-prefixed. Null if not decoded. */
+    hash: string | null;
+}
 /** A validator node indexed from pallet-validator-set events. */
 interface IndexedValidator {
     account: string;
@@ -834,18 +844,35 @@ declare class IndexerClient {
      * For the current Orbinum testnet/mainnet scale this is the recommended approach.
      */
     getAllSpentNullifiers(): Promise<Set<string>>;
+    /** Server-enforced max items per by-nullifiers / by-commitments request. */
+    private static readonly TRANSFER_LOOKUP_CHUNK;
+    /**
+     * Chunked fetch for the transfer timestamp lookups. The reader silently
+     * truncates each request to 50 items, so larger inputs MUST be split or
+     * results are silently lost. Responses are merged per extrinsic
+     * (`blockNumber:extrinsicIndex`), concatenating the matched arrays, and
+     * sorted by block descending.
+     *
+     * Privacy note: these lookups send the wallet's own note identifiers to
+     * the indexer — a bounded, documented linkage tradeoff for timestamp
+     * recovery. They are NEVER used for spent-STATUS checks (PIR-A: status
+     * comes from the anonymous full-set `/shielded/nullifiers/all` download).
+     */
+    private fetchTransfersChunked;
     /**
      * Returns temporal metadata for private transfers that spent any of the given nullifiers.
      * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
      * between inputs and outputs to prevent graph reconstruction.
-     * Accepts up to 50 nullifiers (0x-prefixed hex).
+     * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+     * and merged per extrinsic.
      */
     getTransfersByNullifiers(nullifiers: string[]): Promise<PrivateTransferTimestamp[]>;
     /**
      * Returns temporal metadata for private transfers that produced any of the given commitments.
      * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
      * between outputs and inputs to prevent graph reconstruction.
-     * Accepts up to 50 commitments (0x-prefixed hex).
+     * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+     * and merged per extrinsic.
      */
     getTransfersByCommitments(commitments: string[]): Promise<PrivateTransferTimestamp[]>;
     /** Returns a paginated list of unshield events. */
@@ -881,11 +908,6 @@ declare class IndexerClient {
     }): Promise<PaginatedResult<IndexedBlock>>;
     /** Returns a single block by number or hash, or null if not found. */
     getBlock(numberOrHash: string | number): Promise<IndexedBlock | null>;
-    /** Returns a paginated list of shielded commitments initiated by an address. */
-    getAddressCommitments(address: string, params?: {
-        page?: number;
-        limit?: number;
-    }): Promise<PaginatedResult<ShieldedCommitment>>;
     /**
      * Returns a paginated list of unshield events where the given address is the recipient.
      * Accepts a 0x-prefixed EVM address or an SS58 Substrate address.
@@ -895,9 +917,11 @@ declare class IndexerClient {
         limit?: number;
     }): Promise<PaginatedResult<Unshield>>;
     /**
-     * Returns a paginated list of all shielded activity (commitments, unshields,
-     * private transfers) associated with the given address.
-     * Each item is tagged with a `kind` discriminant.
+     * Returns the shielded-pool BOUNDARY activity for an address: shields it
+     * deposited and unshields it received, tagged `kind: 'shield' | 'unshield'`.
+     * Only boundary fields are returned (block, asset, amount for unshields,
+     * timestamp, tx hash) — note internals are never served per-address, and
+     * private transfers carry no address at all (PIR-A).
      */
     getAddressShieldedActivity(address: string, params?: {
         page?: number;

package/dist/index.js

@@ -1147,7 +1147,7 @@ var EvmExplorer = class _EvmExplorer {
 };
 
 // src/indexer/IndexerClient.ts
-var IndexerClient = class {
+var IndexerClient = class _IndexerClient {
   baseUrl;
   timeoutMs;
   constructor(config) {
@@ -1247,37 +1247,82 @@ var IndexerClient = class {
     return new Set(res.data.map((h) => h.toLowerCase()));
   }
   // ─── Private transfers ─────────────────────────────────────────────────────
+  /** Server-enforced max items per by-nullifiers / by-commitments request. */
+  static TRANSFER_LOOKUP_CHUNK = 50;
+  /**
+   * Chunked fetch for the transfer timestamp lookups. The reader silently
+   * truncates each request to 50 items, so larger inputs MUST be split or
+   * results are silently lost. Responses are merged per extrinsic
+   * (`blockNumber:extrinsicIndex`), concatenating the matched arrays, and
+   * sorted by block descending.
+   *
+   * Privacy note: these lookups send the wallet's own note identifiers to
+   * the indexer — a bounded, documented linkage tradeoff for timestamp
+   * recovery. They are NEVER used for spent-STATUS checks (PIR-A: status
+   * comes from the anonymous full-set `/shielded/nullifiers/all` download).
+   */
+  async fetchTransfersChunked(path, param, items, matchedField) {
+    if (items.length === 0) return [];
+    const normalized = items.map((i) => i.toLowerCase());
+    const chunks = [];
+    for (let i = 0; i < normalized.length; i += _IndexerClient.TRANSFER_LOOKUP_CHUNK) {
+      chunks.push(normalized.slice(i, i + _IndexerClient.TRANSFER_LOOKUP_CHUNK));
+    }
+    const responses = await Promise.all(
+      chunks.map((chunk) => {
+        const qs = this.buildQuery({ [param]: chunk.join(",") });
+        return this.get(
+          `${path}${qs}`
+        );
+      })
+    );
+    const byExtrinsic = /* @__PURE__ */ new Map();
+    for (const res of responses) {
+      for (const transfer of res.data) {
+        const key = `${transfer.blockNumber}:${transfer.extrinsicIndex ?? "null"}`;
+        const existing = byExtrinsic.get(key);
+        if (!existing) {
+          byExtrinsic.set(key, transfer);
+          continue;
+        }
+        const merged = /* @__PURE__ */ new Set([
+          ...existing[matchedField] ?? [],
+          ...transfer[matchedField] ?? []
+        ]);
+        existing[matchedField] = [...merged];
+      }
+    }
+    return [...byExtrinsic.values()].sort((a, b) => b.blockNumber - a.blockNumber);
+  }
   /**
    * Returns temporal metadata for private transfers that spent any of the given nullifiers.
    * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
    * between inputs and outputs to prevent graph reconstruction.
-   * Accepts up to 50 nullifiers (0x-prefixed hex).
+   * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+   * and merged per extrinsic.
    */
   async getTransfersByNullifiers(nullifiers) {
-    if (nullifiers.length === 0) return [];
-    const qs = this.buildQuery({
-      nullifiers: nullifiers.map((n) => n.toLowerCase()).join(",")
-    });
-    const res = await this.get(
-      `/shielded/transfers/by-nullifiers${qs}`
+    return this.fetchTransfersChunked(
+      "/shielded/transfers/by-nullifiers",
+      "nullifiers",
+      nullifiers,
+      "matchedNullifiers"
     );
-    return res.data;
   }
   /**
    * Returns temporal metadata for private transfers that produced any of the given commitments.
    * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
    * between outputs and inputs to prevent graph reconstruction.
-   * Accepts up to 50 commitments (0x-prefixed hex).
+   * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+   * and merged per extrinsic.
    */
   async getTransfersByCommitments(commitments) {
-    if (commitments.length === 0) return [];
-    const qs = this.buildQuery({
-      commitments: commitments.map((c) => c.toLowerCase()).join(",")
-    });
-    const res = await this.get(
-      `/shielded/transfers/by-commitments${qs}`
+    return this.fetchTransfersChunked(
+      "/shielded/transfers/by-commitments",
+      "commitments",
+      commitments,
+      "matchedCommitments"
     );
-    return res.data;
   }
   // ─── Unshields ─────────────────────────────────────────────────────────────
   /** Returns a paginated list of unshield events. */
@@ -1329,14 +1374,7 @@ var IndexerClient = class {
   async getBlock(numberOrHash) {
     return this.getOrNull(`/blocks/${encodeURIComponent(String(numberOrHash))}`);
   }
-  // ─── Address commitments ───────────────────────────────────────────────────
-  /** Returns a paginated list of shielded commitments initiated by an address. */
-  async getAddressCommitments(address, params) {
-    const qs = this.buildQuery({ page: params?.page, limit: params?.limit });
-    return this.get(
-      `/address/${encodeURIComponent(address.toLowerCase())}/shielded${qs}`
-    );
-  }
+  // ─── Address-scoped shielded activity ─────────────────────────────────────
   /**
    * Returns a paginated list of unshield events where the given address is the recipient.
    * Accepts a 0x-prefixed EVM address or an SS58 Substrate address.
@@ -1348,9 +1386,11 @@ var IndexerClient = class {
     );
   }
   /**
-   * Returns a paginated list of all shielded activity (commitments, unshields,
-   * private transfers) associated with the given address.
-   * Each item is tagged with a `kind` discriminant.
+   * Returns the shielded-pool BOUNDARY activity for an address: shields it
+   * deposited and unshields it received, tagged `kind: 'shield' | 'unshield'`.
+   * Only boundary fields are returned (block, asset, amount for unshields,
+   * timestamp, tx hash) — note internals are never served per-address, and
+   * private transfers carry no address at all (PIR-A).
    */
   async getAddressShieldedActivity(address, params) {
     const qs = this.buildQuery({ page: params?.page, limit: params?.limit });

package/dist/index.mjs

@@ -1020,7 +1020,7 @@ var EvmExplorer = class _EvmExplorer {
 };
 
 // src/indexer/IndexerClient.ts
-var IndexerClient = class {
+var IndexerClient = class _IndexerClient {
   baseUrl;
   timeoutMs;
   constructor(config) {
@@ -1120,37 +1120,82 @@ var IndexerClient = class {
     return new Set(res.data.map((h) => h.toLowerCase()));
   }
   // ─── Private transfers ─────────────────────────────────────────────────────
+  /** Server-enforced max items per by-nullifiers / by-commitments request. */
+  static TRANSFER_LOOKUP_CHUNK = 50;
+  /**
+   * Chunked fetch for the transfer timestamp lookups. The reader silently
+   * truncates each request to 50 items, so larger inputs MUST be split or
+   * results are silently lost. Responses are merged per extrinsic
+   * (`blockNumber:extrinsicIndex`), concatenating the matched arrays, and
+   * sorted by block descending.
+   *
+   * Privacy note: these lookups send the wallet's own note identifiers to
+   * the indexer — a bounded, documented linkage tradeoff for timestamp
+   * recovery. They are NEVER used for spent-STATUS checks (PIR-A: status
+   * comes from the anonymous full-set `/shielded/nullifiers/all` download).
+   */
+  async fetchTransfersChunked(path, param, items, matchedField) {
+    if (items.length === 0) return [];
+    const normalized = items.map((i) => i.toLowerCase());
+    const chunks = [];
+    for (let i = 0; i < normalized.length; i += _IndexerClient.TRANSFER_LOOKUP_CHUNK) {
+      chunks.push(normalized.slice(i, i + _IndexerClient.TRANSFER_LOOKUP_CHUNK));
+    }
+    const responses = await Promise.all(
+      chunks.map((chunk) => {
+        const qs = this.buildQuery({ [param]: chunk.join(",") });
+        return this.get(
+          `${path}${qs}`
+        );
+      })
+    );
+    const byExtrinsic = /* @__PURE__ */ new Map();
+    for (const res of responses) {
+      for (const transfer of res.data) {
+        const key = `${transfer.blockNumber}:${transfer.extrinsicIndex ?? "null"}`;
+        const existing = byExtrinsic.get(key);
+        if (!existing) {
+          byExtrinsic.set(key, transfer);
+          continue;
+        }
+        const merged = /* @__PURE__ */ new Set([
+          ...existing[matchedField] ?? [],
+          ...transfer[matchedField] ?? []
+        ]);
+        existing[matchedField] = [...merged];
+      }
+    }
+    return [...byExtrinsic.values()].sort((a, b) => b.blockNumber - a.blockNumber);
+  }
   /**
    * Returns temporal metadata for private transfers that spent any of the given nullifiers.
    * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
    * between inputs and outputs to prevent graph reconstruction.
-   * Accepts up to 50 nullifiers (0x-prefixed hex).
+   * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+   * and merged per extrinsic.
    */
   async getTransfersByNullifiers(nullifiers) {
-    if (nullifiers.length === 0) return [];
-    const qs = this.buildQuery({
-      nullifiers: nullifiers.map((n) => n.toLowerCase()).join(",")
-    });
-    const res = await this.get(
-      `/shielded/transfers/by-nullifiers${qs}`
+    return this.fetchTransfersChunked(
+      "/shielded/transfers/by-nullifiers",
+      "nullifiers",
+      nullifiers,
+      "matchedNullifiers"
     );
-    return res.data;
   }
   /**
    * Returns temporal metadata for private transfers that produced any of the given commitments.
    * Only blockNumber, extrinsicIndex, timestampMs, and hash are returned — no cross-link
    * between outputs and inputs to prevent graph reconstruction.
-   * Accepts up to 50 commitments (0x-prefixed hex).
+   * Inputs of any size are transparently chunked into requests of 50 (the server cap)
+   * and merged per extrinsic.
    */
   async getTransfersByCommitments(commitments) {
-    if (commitments.length === 0) return [];
-    const qs = this.buildQuery({
-      commitments: commitments.map((c) => c.toLowerCase()).join(",")
-    });
-    const res = await this.get(
-      `/shielded/transfers/by-commitments${qs}`
+    return this.fetchTransfersChunked(
+      "/shielded/transfers/by-commitments",
+      "commitments",
+      commitments,
+      "matchedCommitments"
     );
-    return res.data;
   }
   // ─── Unshields ─────────────────────────────────────────────────────────────
   /** Returns a paginated list of unshield events. */
@@ -1202,14 +1247,7 @@ var IndexerClient = class {
   async getBlock(numberOrHash) {
     return this.getOrNull(`/blocks/${encodeURIComponent(String(numberOrHash))}`);
   }
-  // ─── Address commitments ───────────────────────────────────────────────────
-  /** Returns a paginated list of shielded commitments initiated by an address. */
-  async getAddressCommitments(address, params) {
-    const qs = this.buildQuery({ page: params?.page, limit: params?.limit });
-    return this.get(
-      `/address/${encodeURIComponent(address.toLowerCase())}/shielded${qs}`
-    );
-  }
+  // ─── Address-scoped shielded activity ─────────────────────────────────────
   /**
    * Returns a paginated list of unshield events where the given address is the recipient.
    * Accepts a 0x-prefixed EVM address or an SS58 Substrate address.
@@ -1221,9 +1259,11 @@ var IndexerClient = class {
     );
   }
   /**
-   * Returns a paginated list of all shielded activity (commitments, unshields,
-   * private transfers) associated with the given address.
-   * Each item is tagged with a `kind` discriminant.
+   * Returns the shielded-pool BOUNDARY activity for an address: shields it
+   * deposited and unshields it received, tagged `kind: 'shield' | 'unshield'`.
+   * Only boundary fields are returned (block, asset, amount for unshields,
+   * timestamp, tx hash) — note internals are never served per-address, and
+   * private transfers carry no address at all (PIR-A).
    */
   async getAddressShieldedActivity(address, params) {
     const qs = this.buildQuery({ page: params?.page, limit: params?.limit });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orbinum/sdk",
-  "version": "0.7.10",
+  "version": "0.8.1",
   "description": "Official TypeScript SDK for Orbinum.",
   "author": "Orbinum",
   "license": "MIT",