@trufnetwork/sdk-js 0.5.3 → 0.5.5

package/README.md

@@ -274,6 +274,39 @@ attestations.forEach(att => {
 });
 ```
 
+#### Parsing Attestation Payloads
+
+The SDK provides utilities to parse and verify signed attestation payloads:
+
+```typescript
+import { parseAttestationPayload } from "@trufnetwork/sdk-js";
+import { sha256, recoverAddress } from "ethers";
+
+// Get signed attestation
+const signed = await attestationAction.getSignedAttestation({
+  requestTxId: result.requestTxId,
+});
+
+// Extract canonical payload and signature
+const canonicalPayload = signed.payload.slice(0, -65);
+const signature = signed.payload.slice(-65);
+
+// Verify signature
+const digest = sha256(canonicalPayload);
+const validatorAddress = recoverAddress(digest, {
+  r: "0x" + Buffer.from(signature.slice(0, 32)).toString("hex"),
+  s: "0x" + Buffer.from(signature.slice(32, 64)).toString("hex"),
+  v: signature[64]
+});
+
+// Parse and decode the payload
+const parsed = parseAttestationPayload(canonicalPayload);
+console.log(`Validator: ${validatorAddress}`);
+console.log(`Query Results: ${parsed.result.length} rows`);
+```
+
+**📖 For complete documentation including signature verification, payload structure, result decoding, and EVM integration examples, see the [Attestation Payload Parsing](./docs/api-reference.md#attestation-payload-parsing) section in the API Reference.**
+
 #### Attestation Payload Structure
 
 The signed attestation payload is a binary blob containing:
@@ -284,13 +317,36 @@ The signed attestation payload is a binary blob containing:
 5. Stream ID (32 bytes, length-prefixed)
 6. Action ID (2 bytes)
 7. Arguments (variable, length-prefixed)
-8. Result (variable, length-prefixed)
+8. Result (variable, ABI-encoded, length-prefixed)
 9. Signature (65 bytes, secp256k1)
 
 This payload can be passed to EVM smart contracts for on-chain verification using `ecrecover`.
 
 For a complete example, see [examples/attestation](./examples/attestation).
 
+### Transaction Ledger Queries
+
+Query transaction history, fees, and distributions for auditing and analytics.
+
+```typescript
+// Get transaction details
+const transactionAction = client.loadTransactionAction();
+const txEvent = await transactionAction.getTransactionEvent({
+  txId: '0xabcdef...'
+});
+console.log(`Method: ${txEvent.method}, Fee: ${txEvent.feeAmount} wei`);
+console.log(`Timestamp (ms): ${txEvent.stampMs}`);
+
+// List fees paid by wallet
+const entries = await transactionAction.listTransactionFees({
+  wallet: address,
+  mode: 'paid',  // 'paid', 'received', or 'both'
+  limit: 10
+});
+```
+
+**📖 For complete documentation including parameters, return types, pagination, filtering modes, and real-world examples, see the [Transaction Ledger Queries](./docs/api-reference.md#transaction-ledger-queries) section in the API Reference.**
+
 ### Transaction Lifecycle and Best Practices ⚠️
 
 **Critical Understanding**: TN operations return success when transactions enter the mempool, NOT when they're executed on-chain. For operations where order matters, you must wait for transactions to be mined before proceeding.
@@ -428,7 +484,10 @@ For other bundlers or serverless platforms, consult their documentation on modul
 | Get stream taxonomy | `composedAction.getTaxonomiesForStreams({streams, latestOnly})` |
 | Request attestation | `attestationAction.requestAttestation({dataProvider, streamId, actionName, args, encryptSig, maxFee})` |
 | Get signed attestation | `attestationAction.getSignedAttestation({requestTxId})` |
+| Parse attestation payload | `parseAttestationPayload(canonicalPayload)` |
 | List attestations | `attestationAction.listAttestations({requester, limit, offset, orderBy})` |
+| Get transaction event | `transactionAction.getTransactionEvent({txId})` |
+| List transaction fees | `transactionAction.listTransactionFees({wallet, mode, limit, offset})` |
 | Destroy stream | `client.destroyStream(streamLocator)` |
 
 **Safe Operation Pattern:**

package/dist/cjs/contracts-api/transactionAction.cjs

@@ -23,6 +23,32 @@ __export(transactionAction_exports, {
   TransactionAction: () => TransactionAction
 });
 module.exports = __toCommonJS(transactionAction_exports);
+var INDEXER_BASE = "https://indexer.infra.truf.network";
+function normalizeTransactionId(txId) {
+  const lower = txId.toLowerCase();
+  return lower.startsWith("0x") ? lower : `0x${lower}`;
+}
+async function fetchTransactionStampMs(blockHeight, txId) {
+  const url = `${INDEXER_BASE}/v0/chain/transactions?from-block=${blockHeight}&to-block=${blockHeight}&order=desc`;
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      console.warn(`Indexer returned ${response.status} while fetching block ${blockHeight} for tx ${txId}`);
+      return 0;
+    }
+    const data = await response.json();
+    if (!data.ok || !Array.isArray(data.data)) {
+      console.warn(`Indexer payload malformed for block ${blockHeight} (tx ${txId})`);
+      return 0;
+    }
+    const normalizedTargetHash = normalizeTransactionId(txId);
+    const tx = data.data.find((entry) => normalizeTransactionId(entry.hash) === normalizedTargetHash);
+    return tx?.stamp_ms ?? 0;
+  } catch (error) {
+    console.warn(`Failed to fetch stamp_ms for tx ${txId} at block ${blockHeight}`, error);
+    return 0;
+  }
+}
 var TransactionAction = class _TransactionAction {
   kwilClient;
   kwilSigner;
@@ -114,9 +140,11 @@ var TransactionAction = class _TransactionAction {
     if (!Number.isFinite(blockHeight) || blockHeight < 0) {
       throw new Error(`Invalid block height: ${row.block_height} (tx: ${row.tx_id})`);
     }
+    const stampMs = await fetchTransactionStampMs(blockHeight, row.tx_id);
     return {
       txId: row.tx_id,
       blockHeight,
+      stampMs,
       method: row.method,
       caller: row.caller,
       feeAmount,

package/dist/cjs/contracts-api/transactionAction.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/contracts-api/transactionAction.ts"],
-  "sourcesContent": ["import { KwilSigner, NodeKwil, WebKwil, Types } from \"@trufnetwork/kwil-js\";\r\nimport { TransactionEvent, FeeDistribution, GetTransactionEventInput } from \"../types/transaction\";\r\n\r\n/**\r\n * Database row structure returned from get_transaction_event action\r\n */\r\ninterface TransactionEventRow {\r\n  tx_id: string;\r\n  block_height: string | number;\r\n  method: string;\r\n  caller: string;\r\n  fee_amount: string | number;\r\n  fee_recipient?: string | null;\r\n  metadata?: string | null;\r\n  fee_distributions: string;\r\n}\r\n\r\n/**\r\n * TransactionAction provides methods for querying transaction ledger data\r\n */\r\nexport class TransactionAction {\r\n  protected kwilClient: WebKwil | NodeKwil;\r\n  protected kwilSigner: KwilSigner;\r\n\r\n  constructor(kwilClient: WebKwil | NodeKwil, kwilSigner: KwilSigner) {\r\n    this.kwilClient = kwilClient;\r\n    this.kwilSigner = kwilSigner;\r\n  }\r\n\r\n  /**\r\n   * Fetches detailed transaction information by transaction hash\r\n   *\r\n   * @param input Transaction query input containing tx hash\r\n   * @returns Promise resolving to transaction event with fee details\r\n   * @throws Error if transaction not found or query fails\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const txAction = client.loadTransactionAction();\r\n   * const txEvent = await txAction.getTransactionEvent({\r\n   *   txId: \"0xabcdef123456...\"\r\n   * });\r\n   * console.log(`Method: ${txEvent.method}, Fee: ${txEvent.feeAmount} TRUF`);\r\n   * ```\r\n   */\r\n  async getTransactionEvent(input: GetTransactionEventInput): Promise<TransactionEvent> {\r\n    if (!input.txId || input.txId.trim() === \"\") {\r\n      throw new Error(\"tx_id is required\");\r\n    }\r\n\r\n    const result = await this.kwilClient.call(\r\n      {\r\n        namespace: \"main\",\r\n        name: \"get_transaction_event\",\r\n        inputs: {\r\n          $tx_id: input.txId,\r\n        },\r\n      },\r\n      this.kwilSigner\r\n    );\r\n\r\n    if (result.status !== 200) {\r\n      throw new Error(`Failed to get transaction event: HTTP ${result.status}`);\r\n    }\r\n\r\n    if (!result.data?.result || result.data.result.length === 0) {\r\n      throw new Error(`Transaction not found: ${input.txId}`);\r\n    }\r\n\r\n    const row = result.data.result[0] as TransactionEventRow;\r\n\r\n    // Validate required fields\r\n    if (!row.method || typeof row.method !== 'string' || row.method.trim() === '') {\r\n      throw new Error(`Missing or invalid method field (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    if (!row.caller || typeof row.caller !== 'string' || row.caller.trim() === '') {\r\n      throw new Error(`Missing or invalid caller field (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    if (row.fee_amount === null || row.fee_amount === undefined) {\r\n      throw new Error(`Missing fee_amount field (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    // Validate fee_amount is numeric (can be string or number)\r\n    const feeAmount = typeof row.fee_amount === 'string' ? row.fee_amount : String(row.fee_amount);\r\n    const feeAmountNum = Number(feeAmount);\r\n    if (isNaN(feeAmountNum) || !Number.isFinite(feeAmountNum)) {\r\n      throw new Error(`Invalid fee_amount (not numeric): ${row.fee_amount} (tx: ${row.tx_id})`);\r\n    }\r\n    if (feeAmountNum < 0) {\r\n      throw new Error(`Invalid fee_amount (negative): ${row.fee_amount} (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    // Parse fee_distributions string: \"recipient1:amount1,recipient2:amount2\"\r\n    const feeDistributions: FeeDistribution[] = [];\r\n    if (row.fee_distributions && row.fee_distributions !== \"\") {\r\n      const parts = row.fee_distributions.split(\",\");\r\n      for (const part of parts) {\r\n        const trimmedPart = part.trim();\r\n        if (trimmedPart) {\r\n          // Split only on first colon to handle addresses with colons\r\n          const colonIndex = trimmedPart.indexOf(\":\");\r\n          if (colonIndex === -1) {\r\n            throw new Error(`Invalid fee distribution format (missing colon): ${trimmedPart} (tx: ${row.tx_id})`);\r\n          }\r\n\r\n          const recipient = trimmedPart.substring(0, colonIndex).trim();\r\n          const amount = trimmedPart.substring(colonIndex + 1).trim();\r\n\r\n          if (!recipient || !amount) {\r\n            throw new Error(`Invalid fee distribution entry (empty recipient or amount): ${trimmedPart} (tx: ${row.tx_id})`);\r\n          }\r\n\r\n          // Validate amount is numeric and non-negative\r\n          const amt = Number(amount);\r\n          if (isNaN(amt) || !Number.isFinite(amt)) {\r\n            throw new Error(`Invalid fee distribution amount (not numeric): ${amount} (tx: ${row.tx_id})`);\r\n          }\r\n          if (amt < 0) {\r\n            throw new Error(`Invalid fee distribution amount (negative): ${amount} (tx: ${row.tx_id})`);\r\n          }\r\n\r\n          feeDistributions.push({ recipient, amount });\r\n        }\r\n      }\r\n    }\r\n\r\n    // Validate block height\r\n    const blockHeight = typeof row.block_height === 'number'\r\n      ? row.block_height\r\n      : parseInt(row.block_height, 10);\r\n    if (!Number.isFinite(blockHeight) || blockHeight < 0) {\r\n      throw new Error(`Invalid block height: ${row.block_height} (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    return {\r\n      txId: row.tx_id,\r\n      blockHeight,\r\n      method: row.method,\r\n      caller: row.caller,\r\n      feeAmount,\r\n      feeRecipient: row.fee_recipient || undefined,\r\n      metadata: row.metadata || undefined,\r\n      feeDistributions,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Creates a TransactionAction instance from an existing client and signer\r\n   *\r\n   * @param kwilClient The Kwil client (Web or Node)\r\n   * @param kwilSigner The Kwil signer for authentication\r\n   * @returns A new TransactionAction instance\r\n   */\r\n  static fromClient(kwilClient: WebKwil | NodeKwil, kwilSigner: KwilSigner): TransactionAction {\r\n    return new TransactionAction(kwilClient, kwilSigner);\r\n  }\r\n}\r\n"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAoBO,IAAM,oBAAN,MAAM,mBAAkB;AAAA,EACnB;AAAA,EACA;AAAA,EAEV,YAAY,YAAgC,YAAwB;AAClE,SAAK,aAAa;AAClB,SAAK,aAAa;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,MAAM,oBAAoB,OAA4D;AACpF,QAAI,CAAC,MAAM,QAAQ,MAAM,KAAK,KAAK,MAAM,IAAI;AAC3C,YAAM,IAAI,MAAM,mBAAmB;AAAA,IACrC;AAEA,UAAM,SAAS,MAAM,KAAK,WAAW;AAAA,MACnC;AAAA,QACE,WAAW;AAAA,QACX,MAAM;AAAA,QACN,QAAQ;AAAA,UACN,QAAQ,MAAM;AAAA,QAChB;AAAA,MACF;AAAA,MACA,KAAK;AAAA,IACP;AAEA,QAAI,OAAO,WAAW,KAAK;AACzB,YAAM,IAAI,MAAM,yCAAyC,OAAO,MAAM,EAAE;AAAA,IAC1E;AAEA,QAAI,CAAC,OAAO,MAAM,UAAU,OAAO,KAAK,OAAO,WAAW,GAAG;AAC3D,YAAM,IAAI,MAAM,0BAA0B,MAAM,IAAI,EAAE;AAAA,IACxD;AAEA,UAAM,MAAM,OAAO,KAAK,OAAO,CAAC;AAGhC,QAAI,CAAC,IAAI,UAAU,OAAO,IAAI,WAAW,YAAY,IAAI,OAAO,KAAK,MAAM,IAAI;AAC7E,YAAM,IAAI,MAAM,wCAAwC,IAAI,KAAK,GAAG;AAAA,IACtE;AAEA,QAAI,CAAC,IAAI,UAAU,OAAO,IAAI,WAAW,YAAY,IAAI,OAAO,KAAK,MAAM,IAAI;AAC7E,YAAM,IAAI,MAAM,wCAAwC,IAAI,KAAK,GAAG;AAAA,IACtE;AAEA,QAAI,IAAI,eAAe,QAAQ,IAAI,eAAe,QAAW;AAC3D,YAAM,IAAI,MAAM,iCAAiC,IAAI,KAAK,GAAG;AAAA,IAC/D;AAGA,UAAM,YAAY,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa,OAAO,IAAI,UAAU;AAC7F,UAAM,eAAe,OAAO,SAAS;AACrC,QAAI,MAAM,YAAY,KAAK,CAAC,OAAO,SAAS,YAAY,GAAG;AACzD,YAAM,IAAI,MAAM,qCAAqC,IAAI,UAAU,SAAS,IAAI,KAAK,GAAG;AAAA,IAC1F;AACA,QAAI,eAAe,GAAG;AACpB,YAAM,IAAI,MAAM,kCAAkC,IAAI,UAAU,SAAS,IAAI,KAAK,GAAG;AAAA,IACvF;AAGA,UAAM,mBAAsC,CAAC;AAC7C,QAAI,IAAI,qBAAqB,IAAI,sBAAsB,IAAI;AACzD,YAAM,QAAQ,IAAI,kBAAkB,MAAM,GAAG;AAC7C,iBAAW,QAAQ,OAAO;AACxB,cAAM,cAAc,KAAK,KAAK;AAC9B,YAAI,aAAa;AAEf,gBAAM,aAAa,YAAY,QAAQ,GAAG;AAC1C,cAAI,eAAe,IAAI;AACrB,kBAAM,IAAI,MAAM,oDAAoD,WAAW,SAAS,IAAI,KAAK,GAAG;AAAA,UACtG;AAEA,gBAAM,YAAY,YAAY,UAAU,GAAG,UAAU,EAAE,KAAK;AAC5D,gBAAM,SAAS,YAAY,UAAU,aAAa,CAAC,EAAE,KAAK;AAE1D,cAAI,CAAC,aAAa,CAAC,QAAQ;AACzB,kBAAM,IAAI,MAAM,+DAA+D,WAAW,SAAS,IAAI,KAAK,GAAG;AAAA,UACjH;AAGA,gBAAM,MAAM,OAAO,MAAM;AACzB,cAAI,MAAM,GAAG,KAAK,CAAC,OAAO,SAAS,GAAG,GAAG;AACvC,kBAAM,IAAI,MAAM,kDAAkD,MAAM,SAAS,IAAI,KAAK,GAAG;AAAA,UAC/F;AACA,cAAI,MAAM,GAAG;AACX,kBAAM,IAAI,MAAM,+CAA+C,MAAM,SAAS,IAAI,KAAK,GAAG;AAAA,UAC5F;AAEA,2BAAiB,KAAK,EAAE,WAAW,OAAO,CAAC;AAAA,QAC7C;AAAA,MACF;AAAA,IACF;AAGA,UAAM,cAAc,OAAO,IAAI,iBAAiB,WAC5C,IAAI,eACJ,SAAS,IAAI,cAAc,EAAE;AACjC,QAAI,CAAC,OAAO,SAAS,WAAW,KAAK,cAAc,GAAG;AACpD,YAAM,IAAI,MAAM,yBAAyB,IAAI,YAAY,SAAS,IAAI,KAAK,GAAG;AAAA,IAChF;AAEA,WAAO;AAAA,MACL,MAAM,IAAI;AAAA,MACV;AAAA,MACA,QAAQ,IAAI;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ;AAAA,MACA,cAAc,IAAI,iBAAiB;AAAA,MACnC,UAAU,IAAI,YAAY;AAAA,MAC1B;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAO,WAAW,YAAgC,YAA2C;AAC3F,WAAO,IAAI,mBAAkB,YAAY,UAAU;AAAA,EACrD;AACF;",
+  "sourcesContent": ["import { KwilSigner, NodeKwil, WebKwil } from \"@trufnetwork/kwil-js\";\r\nimport { TransactionEvent, FeeDistribution, GetTransactionEventInput } from \"../types/transaction\";\r\n\r\nconst INDEXER_BASE = \"https://indexer.infra.truf.network\";\r\n\r\nfunction normalizeTransactionId(txId: string): string {\r\n  const lower = txId.toLowerCase();\r\n  return lower.startsWith(\"0x\") ? lower : `0x${lower}`;\r\n}\r\n\r\nasync function fetchTransactionStampMs(blockHeight: number, txId: string): Promise<number> {\r\n  const url = `${INDEXER_BASE}/v0/chain/transactions?from-block=${blockHeight}&to-block=${blockHeight}&order=desc`;\r\n  try {\r\n    const response = await fetch(url);\r\n    if (!response.ok) {\r\n      console.warn(`Indexer returned ${response.status} while fetching block ${blockHeight} for tx ${txId}`);\r\n      return 0;\r\n    }\r\n\r\n    const data = await response.json() as {\r\n      ok: boolean;\r\n      data: Array<{\r\n        block_height: number;\r\n        hash: string;\r\n        stamp_ms: number | null;\r\n      }>;\r\n    };\r\n\r\n    if (!data.ok || !Array.isArray(data.data)) {\r\n      console.warn(`Indexer payload malformed for block ${blockHeight} (tx ${txId})`);\r\n      return 0;\r\n    }\r\n\r\n    const normalizedTargetHash = normalizeTransactionId(txId);\r\n    const tx = data.data.find(entry => normalizeTransactionId(entry.hash) === normalizedTargetHash);\r\n    return tx?.stamp_ms ?? 0;\r\n  } catch (error) {\r\n    console.warn(`Failed to fetch stamp_ms for tx ${txId} at block ${blockHeight}`, error);\r\n    return 0;\r\n  }\r\n}\r\n\r\n/**\r\n * Database row structure returned from get_transaction_event action\r\n */\r\ninterface TransactionEventRow {\r\n  tx_id: string;\r\n  block_height: string | number;\r\n  method: string;\r\n  caller: string;\r\n  fee_amount: string | number;\r\n  fee_recipient?: string | null;\r\n  metadata?: string | null;\r\n  fee_distributions: string;\r\n}\r\n\r\n/**\r\n * TransactionAction provides methods for querying transaction ledger data\r\n */\r\nexport class TransactionAction {\r\n  protected kwilClient: WebKwil | NodeKwil;\r\n  protected kwilSigner: KwilSigner;\r\n\r\n  constructor(kwilClient: WebKwil | NodeKwil, kwilSigner: KwilSigner) {\r\n    this.kwilClient = kwilClient;\r\n    this.kwilSigner = kwilSigner;\r\n  }\r\n\r\n  /**\r\n   * Fetches detailed transaction information by transaction hash\r\n   *\r\n   * @param input Transaction query input containing tx hash\r\n   * @returns Promise resolving to transaction event with fee details\r\n   * @throws Error if transaction not found or query fails\r\n   *\r\n   * @example\r\n   * ```typescript\r\n   * const txAction = client.loadTransactionAction();\r\n   * const txEvent = await txAction.getTransactionEvent({\r\n   *   txId: \"0xabcdef123456...\"\r\n   * });\r\n   * console.log(`Method: ${txEvent.method}, Fee: ${txEvent.feeAmount} TRUF`);\r\n   * ```\r\n   */\r\n  async getTransactionEvent(input: GetTransactionEventInput): Promise<TransactionEvent> {\r\n    if (!input.txId || input.txId.trim() === \"\") {\r\n      throw new Error(\"tx_id is required\");\r\n    }\r\n\r\n    const result = await this.kwilClient.call(\r\n      {\r\n        namespace: \"main\",\r\n        name: \"get_transaction_event\",\r\n        inputs: {\r\n          $tx_id: input.txId,\r\n        },\r\n      },\r\n      this.kwilSigner\r\n    );\r\n\r\n    if (result.status !== 200) {\r\n      throw new Error(`Failed to get transaction event: HTTP ${result.status}`);\r\n    }\r\n\r\n    if (!result.data?.result || result.data.result.length === 0) {\r\n      throw new Error(`Transaction not found: ${input.txId}`);\r\n    }\r\n\r\n    const row = result.data.result[0] as TransactionEventRow;\r\n\r\n    // Validate required fields\r\n    if (!row.method || typeof row.method !== 'string' || row.method.trim() === '') {\r\n      throw new Error(`Missing or invalid method field (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    if (!row.caller || typeof row.caller !== 'string' || row.caller.trim() === '') {\r\n      throw new Error(`Missing or invalid caller field (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    if (row.fee_amount === null || row.fee_amount === undefined) {\r\n      throw new Error(`Missing fee_amount field (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    // Validate fee_amount is numeric (can be string or number)\r\n    const feeAmount = typeof row.fee_amount === 'string' ? row.fee_amount : String(row.fee_amount);\r\n    const feeAmountNum = Number(feeAmount);\r\n    if (isNaN(feeAmountNum) || !Number.isFinite(feeAmountNum)) {\r\n      throw new Error(`Invalid fee_amount (not numeric): ${row.fee_amount} (tx: ${row.tx_id})`);\r\n    }\r\n    if (feeAmountNum < 0) {\r\n      throw new Error(`Invalid fee_amount (negative): ${row.fee_amount} (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    // Parse fee_distributions string: \"recipient1:amount1,recipient2:amount2\"\r\n    const feeDistributions: FeeDistribution[] = [];\r\n    if (row.fee_distributions && row.fee_distributions !== \"\") {\r\n      const parts = row.fee_distributions.split(\",\");\r\n      for (const part of parts) {\r\n        const trimmedPart = part.trim();\r\n        if (trimmedPart) {\r\n          // Split only on first colon to handle addresses with colons\r\n          const colonIndex = trimmedPart.indexOf(\":\");\r\n          if (colonIndex === -1) {\r\n            throw new Error(`Invalid fee distribution format (missing colon): ${trimmedPart} (tx: ${row.tx_id})`);\r\n          }\r\n\r\n          const recipient = trimmedPart.substring(0, colonIndex).trim();\r\n          const amount = trimmedPart.substring(colonIndex + 1).trim();\r\n\r\n          if (!recipient || !amount) {\r\n            throw new Error(`Invalid fee distribution entry (empty recipient or amount): ${trimmedPart} (tx: ${row.tx_id})`);\r\n          }\r\n\r\n          // Validate amount is numeric and non-negative\r\n          const amt = Number(amount);\r\n          if (isNaN(amt) || !Number.isFinite(amt)) {\r\n            throw new Error(`Invalid fee distribution amount (not numeric): ${amount} (tx: ${row.tx_id})`);\r\n          }\r\n          if (amt < 0) {\r\n            throw new Error(`Invalid fee distribution amount (negative): ${amount} (tx: ${row.tx_id})`);\r\n          }\r\n\r\n          feeDistributions.push({ recipient, amount });\r\n        }\r\n      }\r\n    }\r\n\r\n    // Validate block height\r\n    const blockHeight = typeof row.block_height === 'number'\r\n      ? row.block_height\r\n      : parseInt(row.block_height, 10);\r\n    if (!Number.isFinite(blockHeight) || blockHeight < 0) {\r\n      throw new Error(`Invalid block height: ${row.block_height} (tx: ${row.tx_id})`);\r\n    }\r\n\r\n    const stampMs = await fetchTransactionStampMs(blockHeight, row.tx_id);\r\n\r\n    return {\r\n      txId: row.tx_id,\r\n      blockHeight,\r\n      stampMs,\r\n      method: row.method,\r\n      caller: row.caller,\r\n      feeAmount,\r\n      feeRecipient: row.fee_recipient || undefined,\r\n      metadata: row.metadata || undefined,\r\n      feeDistributions,\r\n    };\r\n  }\r\n\r\n  /**\r\n   * Creates a TransactionAction instance from an existing client and signer\r\n   *\r\n   * @param kwilClient The Kwil client (Web or Node)\r\n   * @param kwilSigner The Kwil signer for authentication\r\n   * @returns A new TransactionAction instance\r\n   */\r\n  static fromClient(kwilClient: WebKwil | NodeKwil, kwilSigner: KwilSigner): TransactionAction {\r\n    return new TransactionAction(kwilClient, kwilSigner);\r\n  }\r\n}\r\n"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAGA,IAAM,eAAe;AAErB,SAAS,uBAAuB,MAAsB;AACpD,QAAM,QAAQ,KAAK,YAAY;AAC/B,SAAO,MAAM,WAAW,IAAI,IAAI,QAAQ,KAAK,KAAK;AACpD;AAEA,eAAe,wBAAwB,aAAqB,MAA+B;AACzF,QAAM,MAAM,GAAG,YAAY,qCAAqC,WAAW,aAAa,WAAW;AACnG,MAAI;AACF,UAAM,WAAW,MAAM,MAAM,GAAG;AAChC,QAAI,CAAC,SAAS,IAAI;AAChB,cAAQ,KAAK,oBAAoB,SAAS,MAAM,yBAAyB,WAAW,WAAW,IAAI,EAAE;AACrG,aAAO;AAAA,IACT;AAEA,UAAM,OAAO,MAAM,SAAS,KAAK;AASjC,QAAI,CAAC,KAAK,MAAM,CAAC,MAAM,QAAQ,KAAK,IAAI,GAAG;AACzC,cAAQ,KAAK,uCAAuC,WAAW,QAAQ,IAAI,GAAG;AAC9E,aAAO;AAAA,IACT;AAEA,UAAM,uBAAuB,uBAAuB,IAAI;AACxD,UAAM,KAAK,KAAK,KAAK,KAAK,WAAS,uBAAuB,MAAM,IAAI,MAAM,oBAAoB;AAC9F,WAAO,IAAI,YAAY;AAAA,EACzB,SAAS,OAAO;AACd,YAAQ,KAAK,mCAAmC,IAAI,aAAa,WAAW,IAAI,KAAK;AACrF,WAAO;AAAA,EACT;AACF;AAmBO,IAAM,oBAAN,MAAM,mBAAkB;AAAA,EACnB;AAAA,EACA;AAAA,EAEV,YAAY,YAAgC,YAAwB;AAClE,SAAK,aAAa;AAClB,SAAK,aAAa;AAAA,EACpB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAkBA,MAAM,oBAAoB,OAA4D;AACpF,QAAI,CAAC,MAAM,QAAQ,MAAM,KAAK,KAAK,MAAM,IAAI;AAC3C,YAAM,IAAI,MAAM,mBAAmB;AAAA,IACrC;AAEA,UAAM,SAAS,MAAM,KAAK,WAAW;AAAA,MACnC;AAAA,QACE,WAAW;AAAA,QACX,MAAM;AAAA,QACN,QAAQ;AAAA,UACN,QAAQ,MAAM;AAAA,QAChB;AAAA,MACF;AAAA,MACA,KAAK;AAAA,IACP;AAEA,QAAI,OAAO,WAAW,KAAK;AACzB,YAAM,IAAI,MAAM,yCAAyC,OAAO,MAAM,EAAE;AAAA,IAC1E;AAEA,QAAI,CAAC,OAAO,MAAM,UAAU,OAAO,KAAK,OAAO,WAAW,GAAG;AAC3D,YAAM,IAAI,MAAM,0BAA0B,MAAM,IAAI,EAAE;AAAA,IACxD;AAEA,UAAM,MAAM,OAAO,KAAK,OAAO,CAAC;AAGhC,QAAI,CAAC,IAAI,UAAU,OAAO,IAAI,WAAW,YAAY,IAAI,OAAO,KAAK,MAAM,IAAI;AAC7E,YAAM,IAAI,MAAM,wCAAwC,IAAI,KAAK,GAAG;AAAA,IACtE;AAEA,QAAI,CAAC,IAAI,UAAU,OAAO,IAAI,WAAW,YAAY,IAAI,OAAO,KAAK,MAAM,IAAI;AAC7E,YAAM,IAAI,MAAM,wCAAwC,IAAI,KAAK,GAAG;AAAA,IACtE;AAEA,QAAI,IAAI,eAAe,QAAQ,IAAI,eAAe,QAAW;AAC3D,YAAM,IAAI,MAAM,iCAAiC,IAAI,KAAK,GAAG;AAAA,IAC/D;AAGA,UAAM,YAAY,OAAO,IAAI,eAAe,WAAW,IAAI,aAAa,OAAO,IAAI,UAAU;AAC7F,UAAM,eAAe,OAAO,SAAS;AACrC,QAAI,MAAM,YAAY,KAAK,CAAC,OAAO,SAAS,YAAY,GAAG;AACzD,YAAM,IAAI,MAAM,qCAAqC,IAAI,UAAU,SAAS,IAAI,KAAK,GAAG;AAAA,IAC1F;AACA,QAAI,eAAe,GAAG;AACpB,YAAM,IAAI,MAAM,kCAAkC,IAAI,UAAU,SAAS,IAAI,KAAK,GAAG;AAAA,IACvF;AAGA,UAAM,mBAAsC,CAAC;AAC7C,QAAI,IAAI,qBAAqB,IAAI,sBAAsB,IAAI;AACzD,YAAM,QAAQ,IAAI,kBAAkB,MAAM,GAAG;AAC7C,iBAAW,QAAQ,OAAO;AACxB,cAAM,cAAc,KAAK,KAAK;AAC9B,YAAI,aAAa;AAEf,gBAAM,aAAa,YAAY,QAAQ,GAAG;AAC1C,cAAI,eAAe,IAAI;AACrB,kBAAM,IAAI,MAAM,oDAAoD,WAAW,SAAS,IAAI,KAAK,GAAG;AAAA,UACtG;AAEA,gBAAM,YAAY,YAAY,UAAU,GAAG,UAAU,EAAE,KAAK;AAC5D,gBAAM,SAAS,YAAY,UAAU,aAAa,CAAC,EAAE,KAAK;AAE1D,cAAI,CAAC,aAAa,CAAC,QAAQ;AACzB,kBAAM,IAAI,MAAM,+DAA+D,WAAW,SAAS,IAAI,KAAK,GAAG;AAAA,UACjH;AAGA,gBAAM,MAAM,OAAO,MAAM;AACzB,cAAI,MAAM,GAAG,KAAK,CAAC,OAAO,SAAS,GAAG,GAAG;AACvC,kBAAM,IAAI,MAAM,kDAAkD,MAAM,SAAS,IAAI,KAAK,GAAG;AAAA,UAC/F;AACA,cAAI,MAAM,GAAG;AACX,kBAAM,IAAI,MAAM,+CAA+C,MAAM,SAAS,IAAI,KAAK,GAAG;AAAA,UAC5F;AAEA,2BAAiB,KAAK,EAAE,WAAW,OAAO,CAAC;AAAA,QAC7C;AAAA,MACF;AAAA,IACF;AAGA,UAAM,cAAc,OAAO,IAAI,iBAAiB,WAC5C,IAAI,eACJ,SAAS,IAAI,cAAc,EAAE;AACjC,QAAI,CAAC,OAAO,SAAS,WAAW,KAAK,cAAc,GAAG;AACpD,YAAM,IAAI,MAAM,yBAAyB,IAAI,YAAY,SAAS,IAAI,KAAK,GAAG;AAAA,IAChF;AAEA,UAAM,UAAU,MAAM,wBAAwB,aAAa,IAAI,KAAK;AAEpE,WAAO;AAAA,MACL,MAAM,IAAI;AAAA,MACV;AAAA,MACA;AAAA,MACA,QAAQ,IAAI;AAAA,MACZ,QAAQ,IAAI;AAAA,MACZ;AAAA,MACA,cAAc,IAAI,iBAAiB;AAAA,MACnC,UAAU,IAAI,YAAY;AAAA,MAC1B;AAAA,IACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAO,WAAW,YAAgC,YAA2C;AAC3F,WAAO,IAAI,mBAAkB,YAAY,UAAU;AAAA,EACrD;AACF;",
   "names": []
 }

package/dist/cjs/internal.cjs

@@ -31,6 +31,7 @@ __export(internal_exports, {
   StreamType: () => import_contractValues.StreamType,
   deleteStream: () => import_deleteStream.deleteStream,
   deployStream: () => import_deployStream.deployStream,
+  parseAttestationPayload: () => import_AttestationEncoding.parseAttestationPayload,
   visibility: () => import_visibility.visibility
 });
 module.exports = __toCommonJS(internal_exports);
@@ -45,5 +46,6 @@ var import_deleteStream = require("./contracts-api/deleteStream.cjs");
 var import_StreamId = require("./util/StreamId.cjs");
 var import_EthereumAddress = require("./util/EthereumAddress.cjs");
 var import_visibility = require("./util/visibility.cjs");
+var import_AttestationEncoding = require("./util/AttestationEncoding.cjs");
 var import_contractValues = require("./contracts-api/contractValues.cjs");
 //# sourceMappingURL=internal.cjs.map

package/dist/cjs/internal.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../src/internal.ts"],
-  "sourcesContent": ["/**\r\n * Internal module to manage exports and break circular dependencies\r\n * This centralizes all exports to prevent circular import issues\r\n */\r\n\r\n// Base client and types\r\nexport { BaseTNClient } from \"./client/client\";\r\nexport type { TNClientOptions, SignerInfo, ListStreamsInput, GetLastTransactionsInput } from \"./client/client\";\r\n\r\n// Contract APIs\r\nexport { Action } from \"./contracts-api/action\";\r\nexport { PrimitiveAction } from \"./contracts-api/primitiveAction\";\r\nexport { ComposedAction } from \"./contracts-api/composedAction\";\r\nexport { RoleManagement } from \"./contracts-api/roleManagement\";\r\nexport { AttestationAction } from \"./contracts-api/attestationAction\";\r\nexport { deployStream } from \"./contracts-api/deployStream\";\r\nexport { deleteStream } from \"./contracts-api/deleteStream\";\r\n\r\n// Utility classes\r\nexport { StreamId } from \"./util/StreamId\";\r\nexport { EthereumAddress } from \"./util/EthereumAddress\";\r\nexport { visibility } from \"./util/visibility\";\r\n\r\n// Contract values and types\r\nexport { StreamType } from \"./contracts-api/contractValues\";\r\n\r\n// Stream types\r\nexport type { StreamLocator } from \"./types/stream\";\r\n\r\n// Action types\r\nexport type {\r\n  StreamRecord,\r\n  ListMetadataByHeightParams,\r\n  MetadataQueryResult,\r\n  GetRecordInput,\r\n  GetFirstRecordInput\r\n} from \"./contracts-api/action\";\r\n\r\n// Primitive action types\r\nexport type { InsertRecordInput } from \"./contracts-api/primitiveAction\";\r\n\r\n// Composed action types\r\nexport type {\r\n  TaxonomySet,\r\n  TaxonomyItem,\r\n  ListTaxonomiesByHeightParams,\r\n  GetTaxonomiesForStreamsParams,\r\n  TaxonomyQueryResult\r\n} from \"./contracts-api/composedAction\";\r\n\r\n// Role management types\r\nexport type {\r\n  GrantRoleInput,\r\n  RevokeRoleInput,\r\n  AreMembersOfInput,\r\n  WalletMembership\r\n} from \"./types/role\";\r\n\r\n// Attestation types\r\nexport type {\r\n  RequestAttestationInput,\r\n  RequestAttestationResult,\r\n  GetSignedAttestationInput,\r\n  SignedAttestationResult,\r\n  ListAttestationsInput,\r\n  AttestationMetadata\r\n} from \"./types/attestation\";\r\n\r\n// Visibility types\r\nexport type { VisibilityEnum } from \"./util/visibility\";"],
-  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,oBAA6B;AAI7B,oBAAuB;AACvB,6BAAgC;AAChC,4BAA+B;AAC/B,4BAA+B;AAC/B,+BAAkC;AAClC,0BAA6B;AAC7B,0BAA6B;AAG7B,sBAAyB;AACzB,6BAAgC;AAChC,wBAA2B;AAG3B,4BAA2B;",
+  "sourcesContent": ["/**\r\n * Internal module to manage exports and break circular dependencies\r\n * This centralizes all exports to prevent circular import issues\r\n */\r\n\r\n// Base client and types\r\nexport { BaseTNClient } from \"./client/client\";\r\nexport type { TNClientOptions, SignerInfo, ListStreamsInput, GetLastTransactionsInput } from \"./client/client\";\r\n\r\n// Contract APIs\r\nexport { Action } from \"./contracts-api/action\";\r\nexport { PrimitiveAction } from \"./contracts-api/primitiveAction\";\r\nexport { ComposedAction } from \"./contracts-api/composedAction\";\r\nexport { RoleManagement } from \"./contracts-api/roleManagement\";\r\nexport { AttestationAction } from \"./contracts-api/attestationAction\";\r\nexport { deployStream } from \"./contracts-api/deployStream\";\r\nexport { deleteStream } from \"./contracts-api/deleteStream\";\r\n\r\n// Utility classes\r\nexport { StreamId } from \"./util/StreamId\";\r\nexport { EthereumAddress } from \"./util/EthereumAddress\";\r\nexport { visibility } from \"./util/visibility\";\r\n\r\n// Attestation encoding/decoding utilities\r\nexport {\r\n  parseAttestationPayload\r\n} from \"./util/AttestationEncoding\";\r\n\r\nexport type {\r\n  DecodedRow,\r\n  ParsedAttestationPayload\r\n} from \"./util/AttestationEncoding\";\r\n\r\n// Contract values and types\r\nexport { StreamType } from \"./contracts-api/contractValues\";\r\n\r\n// Stream types\r\nexport type { StreamLocator } from \"./types/stream\";\r\n\r\n// Action types\r\nexport type {\r\n  StreamRecord,\r\n  ListMetadataByHeightParams,\r\n  MetadataQueryResult,\r\n  GetRecordInput,\r\n  GetFirstRecordInput\r\n} from \"./contracts-api/action\";\r\n\r\n// Primitive action types\r\nexport type { InsertRecordInput } from \"./contracts-api/primitiveAction\";\r\n\r\n// Composed action types\r\nexport type {\r\n  TaxonomySet,\r\n  TaxonomyItem,\r\n  ListTaxonomiesByHeightParams,\r\n  GetTaxonomiesForStreamsParams,\r\n  TaxonomyQueryResult\r\n} from \"./contracts-api/composedAction\";\r\n\r\n// Role management types\r\nexport type {\r\n  GrantRoleInput,\r\n  RevokeRoleInput,\r\n  AreMembersOfInput,\r\n  WalletMembership\r\n} from \"./types/role\";\r\n\r\n// Attestation types\r\nexport type {\r\n  RequestAttestationInput,\r\n  RequestAttestationResult,\r\n  GetSignedAttestationInput,\r\n  SignedAttestationResult,\r\n  ListAttestationsInput,\r\n  AttestationMetadata\r\n} from \"./types/attestation\";\r\n\r\n// Visibility types\r\nexport type { VisibilityEnum } from \"./util/visibility\";"],
+  "mappings": ";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAMA,oBAA6B;AAI7B,oBAAuB;AACvB,6BAAgC;AAChC,4BAA+B;AAC/B,4BAA+B;AAC/B,+BAAkC;AAClC,0BAA6B;AAC7B,0BAA6B;AAG7B,sBAAyB;AACzB,6BAAgC;AAChC,wBAA2B;AAG3B,iCAEO;AAQP,4BAA2B;",
   "names": []
 }

package/dist/cjs/types/transaction.cjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../src/types/transaction.ts"],
-  "sourcesContent": ["export interface LastTransaction {\r\n    /** Block height */\r\n    blockHeight: number;\r\n    /** Which action was taken */\r\n    method: string;\r\n    /** Address that sent the on\u2010chain tx */\r\n    sender: string;\r\n    /** Hash of the on\u2010chain transaction */\r\n    transactionHash: string;\r\n    /** Millisecond timestamp from the block header */\r\n    stampMs: number;\r\n}\r\n\r\n/**\r\n * Represents a single fee distribution\r\n */\r\nexport interface FeeDistribution {\r\n    /** Recipient Ethereum address */\r\n    recipient: string;\r\n    /** Amount as string (handles large numbers) */\r\n    amount: string;\r\n}\r\n\r\n/**\r\n * Represents a single transaction event from the ledger\r\n *\r\n * Fee Fields Relationship:\r\n * - feeAmount: Total fee charged for the transaction (as string to handle large numbers)\r\n * - feeRecipient: Primary fee recipient address (if single recipient). May be undefined for:\r\n *   1. Transactions from fee-exempt wallets (system:network_writer role)\r\n *   2. Transactions with multiple fee distributions (use feeDistributions instead)\r\n * - feeDistributions: Array of fee distributions to multiple recipients\r\n *   - Aggregated using string_agg() in get_transaction_event query\r\n *   - Parsed from \"recipient1:amount1,recipient2:amount2\" format\r\n *   - Sum of amounts in feeDistributions equals feeAmount (when present)\r\n *   - Empty array when there are no distributions or single recipient (use feeRecipient)\r\n */\r\nexport interface TransactionEvent {\r\n    /** Transaction hash (0x-prefixed) */\r\n    txId: string;\r\n    /** Block height when transaction was included */\r\n    blockHeight: number;\r\n    /** Method name (e.g., \"deployStream\", \"insertRecords\") */\r\n    method: string;\r\n    /** Ethereum address of caller (lowercase, 0x-prefixed) */\r\n    caller: string;\r\n    /**\r\n     * Total fee amount as string (handles large numbers with 18 decimals)\r\n     * Will be \"0\" for fee-exempt wallets (system:network_writer role)\r\n     */\r\n    feeAmount: string;\r\n    /**\r\n     * Primary fee recipient address (lowercase, 0x-prefixed)\r\n     * Undefined when:\r\n     * - Wallet is fee-exempt (feeAmount === \"0\")\r\n     * - Fee has multiple distributions (check feeDistributions)\r\n     */\r\n    feeRecipient?: string;\r\n    /** Optional metadata JSON (nullable) */\r\n    metadata?: string;\r\n    /**\r\n     * Array of fee distributions to multiple recipients\r\n     * Aggregated from transaction_event_distributions table using string_agg()\r\n     */\r\n    feeDistributions: FeeDistribution[];\r\n}\r\n\r\n/**\r\n * Input for getting transaction event\r\n */\r\nexport interface GetTransactionEventInput {\r\n    /** Transaction hash (with or without 0x prefix) */\r\n    txId: string;\r\n}\r\n"],
+  "sourcesContent": ["export interface LastTransaction {\r\n    /** Block height */\r\n    blockHeight: number;\r\n    /** Which action was taken */\r\n    method: string;\r\n    /** Address that sent the on\u2010chain tx */\r\n    sender: string;\r\n    /** Hash of the on\u2010chain transaction */\r\n    transactionHash: string;\r\n    /** Millisecond timestamp from the block header */\r\n    stampMs: number;\r\n}\r\n\r\n/**\r\n * Represents a single fee distribution\r\n */\r\nexport interface FeeDistribution {\r\n    /** Recipient Ethereum address */\r\n    recipient: string;\r\n    /** Amount as string (handles large numbers) */\r\n    amount: string;\r\n}\r\n\r\n/**\r\n * Represents a single transaction event from the ledger\r\n *\r\n * Fee Fields Relationship:\r\n * - feeAmount: Total fee charged for the transaction (as string to handle large numbers)\r\n * - feeRecipient: Primary fee recipient address (if single recipient). May be undefined for:\r\n *   1. Transactions from fee-exempt wallets (system:network_writer role)\r\n *   2. Transactions with multiple fee distributions (use feeDistributions instead)\r\n * - feeDistributions: Array of fee distributions to multiple recipients\r\n *   - Aggregated using string_agg() in get_transaction_event query\r\n *   - Parsed from \"recipient1:amount1,recipient2:amount2\" format\r\n *   - Sum of amounts in feeDistributions equals feeAmount (when present)\r\n *   - Empty array when there are no distributions or single recipient (use feeRecipient)\r\n */\r\nexport interface TransactionEvent {\r\n    /** Transaction hash (0x-prefixed) */\r\n    txId: string;\r\n    /** Block height when transaction was included */\r\n    blockHeight: number;\r\n    /**\r\n     * Millisecond timestamp from the block header via indexer lookup.\r\n     * Will be 0 when the indexer is unavailable.\r\n     */\r\n    stampMs: number;\r\n    /** Method name (e.g., \"deployStream\", \"insertRecords\") */\r\n    method: string;\r\n    /** Ethereum address of caller (lowercase, 0x-prefixed) */\r\n    caller: string;\r\n    /**\r\n     * Total fee amount as string (handles large numbers with 18 decimals)\r\n     * Will be \"0\" for fee-exempt wallets (system:network_writer role)\r\n     */\r\n    feeAmount: string;\r\n    /**\r\n     * Primary fee recipient address (lowercase, 0x-prefixed)\r\n     * Undefined when:\r\n     * - Wallet is fee-exempt (feeAmount === \"0\")\r\n     * - Fee has multiple distributions (check feeDistributions)\r\n     */\r\n    feeRecipient?: string;\r\n    /** Optional metadata JSON (nullable) */\r\n    metadata?: string;\r\n    /**\r\n     * Array of fee distributions to multiple recipients\r\n     * Aggregated from transaction_event_distributions table using string_agg()\r\n     */\r\n    feeDistributions: FeeDistribution[];\r\n}\r\n\r\n/**\r\n * Input for getting transaction event\r\n */\r\nexport interface GetTransactionEventInput {\r\n    /** Transaction hash (with or without 0x prefix) */\r\n    txId: string;\r\n}\r\n"],
   "mappings": ";;;;;;;;;;;;;;;;AAAA;AAAA;",
   "names": []
 }

package/dist/cjs/util/AttestationEncoding.cjs

@@ -20,11 +20,20 @@ var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: tru
 // src/util/AttestationEncoding.ts
 var AttestationEncoding_exports = {};
 __export(AttestationEncoding_exports, {
+  decodeABIDatapoints: () => decodeABIDatapoints,
+  decodeCanonicalQueryResult: () => decodeCanonicalQueryResult,
+  decodeEncodedValue: () => decodeEncodedValue,
+  decodedValueToJS: () => decodedValueToJS,
   encodeActionArgs: () => encodeActionArgs,
+  parseAttestationPayload: () => parseAttestationPayload,
+  readUint16BE: () => readUint16BE,
+  readUint16LE: () => readUint16LE,
+  readUint32BE: () => readUint32BE,
   readUint32LE: () => readUint32LE
 });
 module.exports = __toCommonJS(AttestationEncoding_exports);
 var import_kwil_js = require("@trufnetwork/kwil-js");
+var import_ethers = require("ethers");
 var import_meta = {};
 function encodeActionArgs(args) {
   const encodedArgs = [];
@@ -61,6 +70,303 @@ function writeUint32LE(buffer, value, offset) {
 function readUint32LE(buffer, offset) {
   return (buffer[offset] | buffer[offset + 1] << 8 | buffer[offset + 2] << 16 | buffer[offset + 3] << 24) >>> 0;
 }
+function readUint16LE(buffer, offset) {
+  return (buffer[offset] | buffer[offset + 1] << 8) >>> 0;
+}
+function readUint32BE(buffer, offset) {
+  return (buffer[offset] << 24 | buffer[offset + 1] << 16 | buffer[offset + 2] << 8 | buffer[offset + 3]) >>> 0;
+}
+function readUint16BE(buffer, offset) {
+  return (buffer[offset] << 8 | buffer[offset + 1]) >>> 0;
+}
+function decodeDataType(buffer, offset) {
+  const version = readUint16BE(buffer, offset);
+  offset += 2;
+  if (version !== 0) {
+    throw new Error(`Unsupported DataType version: ${version}`);
+  }
+  const nameLen = readUint32BE(buffer, offset);
+  offset += 4;
+  const nameBytes = buffer.slice(offset, offset + nameLen);
+  const name = new TextDecoder().decode(nameBytes);
+  offset += nameLen;
+  const is_array = buffer[offset] === 1;
+  offset += 1;
+  const metadata0 = readUint16BE(buffer, offset);
+  offset += 2;
+  const metadata1 = readUint16BE(buffer, offset);
+  offset += 2;
+  return {
+    type: {
+      name,
+      is_array,
+      metadata: [metadata0, metadata1]
+    },
+    offset
+  };
+}
+function decodeEncodedValue(buffer, offset = 0) {
+  const version = readUint16LE(buffer, offset);
+  offset += 2;
+  if (version !== 0) {
+    throw new Error(`Unsupported EncodedValue version: ${version}`);
+  }
+  const typeLen = readUint32LE(buffer, offset);
+  offset += 4;
+  const typeBytes = buffer.slice(offset, offset + typeLen);
+  const { type } = decodeDataType(typeBytes, 0);
+  offset += typeLen;
+  const dataLen = readUint16LE(buffer, offset);
+  offset += 2;
+  const data = [];
+  for (let i = 0; i < dataLen; i++) {
+    const itemLen = readUint32LE(buffer, offset);
+    offset += 4;
+    const itemBytes = buffer.slice(offset, offset + itemLen);
+    data.push(itemBytes);
+    offset += itemLen;
+  }
+  return {
+    value: { type, data },
+    offset
+  };
+}
+function decodedValueToJS(decoded) {
+  if (decoded.data.length === 0) {
+    return null;
+  }
+  const firstItem = decoded.data[0];
+  if (firstItem.length === 0 || firstItem[0] === 0) {
+    return null;
+  }
+  const valueBytes = firstItem.slice(1);
+  const typeName = decoded.type.name.toLowerCase();
+  if (decoded.type.is_array) {
+    const result = [];
+    for (const item of decoded.data) {
+      if (item.length === 0 || item[0] === 0) {
+        result.push(null);
+      } else {
+        const itemBytes = item.slice(1);
+        result.push(decodeSingleValue(typeName, itemBytes));
+      }
+    }
+    return result;
+  }
+  return decodeSingleValue(typeName, valueBytes);
+}
+function decodeSingleValue(typeName, bytes) {
+  switch (typeName) {
+    case "text":
+    case "uuid":
+      return new TextDecoder().decode(bytes);
+    case "int":
+    case "int8":
+    case "integer":
+      if (bytes.length === 8) {
+        const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+        return view.getBigInt64(0, false);
+      }
+      throw new Error(`Invalid integer byte length: expected 8, got ${bytes.length}`);
+    case "bool":
+    case "boolean":
+      return bytes.length > 0 && bytes[0] === 1;
+    case "numeric":
+    case "decimal":
+      return new TextDecoder().decode(bytes);
+    case "bytea":
+    case "blob":
+      return bytes;
+    default:
+      try {
+        return new TextDecoder().decode(bytes);
+      } catch {
+        return bytes;
+      }
+  }
+}
+function decodeCanonicalQueryResult(data) {
+  let offset = 0;
+  if (data.length < 4) {
+    throw new Error("Data too short for row count");
+  }
+  const rowCount = readUint32LE(data, offset);
+  offset += 4;
+  const rows = [];
+  for (let i = 0; i < rowCount; i++) {
+    if (offset + 4 > data.length) {
+      throw new Error(`Data too short for column count at row ${i}`);
+    }
+    const colCount = readUint32LE(data, offset);
+    offset += 4;
+    const values = [];
+    for (let j = 0; j < colCount; j++) {
+      if (offset + 4 > data.length) {
+        throw new Error(`Data too short for column ${j} length at row ${i}`);
+      }
+      const colLen = readUint32LE(data, offset);
+      offset += 4;
+      if (offset + colLen > data.length) {
+        throw new Error(`Data too short for column ${j} bytes at row ${i}`);
+      }
+      const colBytes = data.slice(offset, offset + colLen);
+      const { value: decodedValue } = decodeEncodedValue(colBytes, 0);
+      const jsValue = decodedValueToJS(decodedValue);
+      values.push(jsValue);
+      offset += colLen;
+    }
+    rows.push({ values });
+  }
+  return rows;
+}
+function decodeABIDatapoints(data) {
+  if (!data || data.length === 0) {
+    return [];
+  }
+  const abiCoder = import_ethers.AbiCoder.defaultAbiCoder();
+  try {
+    const decoded = abiCoder.decode(
+      ["uint256[]", "int256[]"],
+      data
+    );
+    const timestamps = decoded[0];
+    const values = decoded[1];
+    if (timestamps.length !== values.length) {
+      throw new Error(`Timestamp/value array length mismatch: ${timestamps.length} vs ${values.length}`);
+    }
+    const rows = [];
+    for (let i = 0; i < timestamps.length; i++) {
+      rows.push({
+        values: [
+          timestamps[i].toString(),
+          // Convert from 18-decimal fixed point to decimal string
+          formatFixedPoint(values[i], 18)
+        ]
+      });
+    }
+    return rows;
+  } catch (err) {
+    throw new Error(`Failed to decode ABI datapoints: ${err}`);
+  }
+}
+function formatFixedPoint(value, decimals) {
+  const isNegative = value < 0n;
+  const absValue = isNegative ? -value : value;
+  const divisor = 10n ** BigInt(decimals);
+  const integerPart = absValue / divisor;
+  const fractionalPart = absValue % divisor;
+  const fractionalStr = fractionalPart.toString().padStart(decimals, "0");
+  const trimmedFractional = fractionalStr.replace(/0+$/, "");
+  if (trimmedFractional === "") {
+    return `${isNegative ? "-" : ""}${integerPart}`;
+  }
+  return `${isNegative ? "-" : ""}${integerPart}.${trimmedFractional}`;
+}
+function parseAttestationPayload(payload) {
+  let offset = 0;
+  if (payload.length < 1) {
+    throw new Error("Payload too short for version");
+  }
+  const version = payload[offset];
+  offset += 1;
+  if (offset >= payload.length) {
+    throw new Error("Payload too short for algorithm");
+  }
+  const algorithm = payload[offset];
+  offset += 1;
+  if (offset + 8 > payload.length) {
+    throw new Error("Payload too short for block height");
+  }
+  const blockHeightHigh = readUint32BE(payload, offset);
+  const blockHeightLow = readUint32BE(payload, offset + 4);
+  const blockHeight = BigInt(blockHeightHigh) << 32n | BigInt(blockHeightLow);
+  offset += 8;
+  if (offset + 4 > payload.length) {
+    throw new Error("Payload too short for data provider length");
+  }
+  const dataProviderLen = readUint32BE(payload, offset);
+  offset += 4;
+  if (offset + dataProviderLen > payload.length) {
+    throw new Error("Payload too short for data provider");
+  }
+  const dataProviderBytes = payload.slice(offset, offset + dataProviderLen);
+  let dataProvider;
+  if (dataProviderLen === 20) {
+    dataProvider = "0x" + Array.from(dataProviderBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+  } else {
+    try {
+      const decoded = new TextDecoder().decode(dataProviderBytes);
+      if (decoded.startsWith("0x") && /^0x[0-9a-fA-F]+$/.test(decoded)) {
+        dataProvider = decoded;
+      } else {
+        dataProvider = decoded;
+      }
+    } catch {
+      dataProvider = "0x" + Array.from(dataProviderBytes).map((b) => b.toString(16).padStart(2, "0")).join("");
+    }
+  }
+  offset += dataProviderLen;
+  if (offset + 4 > payload.length) {
+    throw new Error("Payload too short for stream ID length");
+  }
+  const streamIdLen = readUint32BE(payload, offset);
+  offset += 4;
+  if (offset + streamIdLen > payload.length) {
+    throw new Error("Payload too short for stream ID");
+  }
+  const streamIdBytes = payload.slice(offset, offset + streamIdLen);
+  const streamId = new TextDecoder().decode(streamIdBytes);
+  offset += streamIdLen;
+  if (offset + 2 > payload.length) {
+    throw new Error("Payload too short for action ID");
+  }
+  const actionId = readUint16BE(payload, offset);
+  offset += 2;
+  if (offset + 4 > payload.length) {
+    throw new Error("Payload too short for arguments length");
+  }
+  const argsLen = readUint32BE(payload, offset);
+  offset += 4;
+  if (offset + argsLen > payload.length) {
+    throw new Error("Payload too short for arguments");
+  }
+  const argsBytes = payload.slice(offset, offset + argsLen);
+  offset += argsLen;
+  let args = [];
+  if (argsLen > 0) {
+    let argsOffset = 0;
+    const argCount = readUint32LE(argsBytes, argsOffset);
+    argsOffset += 4;
+    for (let i = 0; i < argCount; i++) {
+      const argLen = readUint32LE(argsBytes, argsOffset);
+      argsOffset += 4;
+      const argBytes = argsBytes.slice(argsOffset, argsOffset + argLen);
+      const { value: decodedArg } = decodeEncodedValue(argBytes, 0);
+      args.push(decodedValueToJS(decodedArg));
+      argsOffset += argLen;
+    }
+  }
+  if (offset + 4 > payload.length) {
+    throw new Error("Payload too short for result length");
+  }
+  const resultLen = readUint32BE(payload, offset);
+  offset += 4;
+  if (offset + resultLen > payload.length) {
+    throw new Error("Payload too short for result");
+  }
+  const resultBytes = payload.slice(offset, offset + resultLen);
+  const result = decodeABIDatapoints(resultBytes);
+  return {
+    version,
+    algorithm,
+    blockHeight,
+    dataProvider,
+    streamId,
+    actionId,
+    arguments: args,
+    result
+  };
+}
 if (import_meta.vitest) {
   const { describe, it, expect } = import_meta.vitest;
   describe("encodeActionArgs", () => {
@@ -153,5 +459,40 @@ if (import_meta.vitest) {
       expect(buffer[3]).toBe(18);
     });
   });
+  describe("readUint16LE and readUint16BE", () => {
+    it("should read uint16 little-endian correctly", () => {
+      const buffer = new Uint8Array([120, 86]);
+      expect(readUint16LE(buffer, 0)).toBe(22136);
+    });
+    it("should read uint16 big-endian correctly", () => {
+      const buffer = new Uint8Array([86, 120]);
+      expect(readUint16BE(buffer, 0)).toBe(22136);
+    });
+  });
+  describe("readUint32BE", () => {
+    it("should read uint32 big-endian correctly", () => {
+      const buffer = new Uint8Array([18, 52, 86, 120]);
+      expect(readUint32BE(buffer, 0)).toBe(305419896);
+    });
+  });
+  describe("decodeCanonicalQueryResult", () => {
+    it("should decode empty result (0 rows)", () => {
+      const buffer = new Uint8Array(4);
+      writeUint32LE(buffer, 0, 0);
+      const result = decodeCanonicalQueryResult(buffer);
+      expect(result.length).toBe(0);
+    });
+    it("should throw on invalid data", () => {
+      const buffer = new Uint8Array(2);
+      expect(() => decodeCanonicalQueryResult(buffer)).toThrow("Data too short for row count");
+    });
+  });
+  describe("parseAttestationPayload", () => {
+    it.todo("should parse payload with ABI-encoded result (TODO: need to construct synthetic test data with valid ABI encoding - see examples/attestation/index.ts for working integration test)");
+    it("should throw on invalid version", () => {
+      const payload = new Uint8Array(1);
+      expect(() => parseAttestationPayload(payload)).toThrow();
+    });
+  });
 }
 //# sourceMappingURL=AttestationEncoding.cjs.map