@d9-network/ink 1.1.0 → 1.2.0

package/dist/chunk-BiucMVzj.mjs

@@ -0,0 +1,18 @@
+//#region rolldown:runtime
+var __defProp = Object.defineProperty;
+var __exportAll = (all, symbols) => {
+	let target = {};
+	for (var name in all) {
+		__defProp(target, name, {
+			get: all[name],
+			enumerable: true
+		});
+	}
+	if (symbols) {
+		__defProp(target, Symbol.toStringTag, { value: "Module" });
+	}
+	return target;
+};
+
+//#endregion
+export { __exportAll as t };

package/dist/index-DgYVGyHC.d.cts

@@ -0,0 +1,593 @@
+import { HexString, SS58String } from "polkadot-api";
+import { Event, InkCallableDescriptor, InkDescriptors, InkMetadata, InkStorageDescriptor } from "@polkadot-api/ink-contracts";
+
+//#region rolldown:runtime
+
+//#endregion
+//#region src/call-types.d.ts
+/**
+ * Raw call data from a transaction
+ */
+interface RawContractCall {
+  /** The call data (SCALE encoded selector + args) */
+  data: Uint8Array;
+  /** Contract address being called */
+  contractAddress?: SS58String;
+  /** Transaction hash (if from a transaction) */
+  txHash?: string;
+  /** Block number (if from a transaction) */
+  blockNumber?: number;
+  /** Block hash (if from a transaction) */
+  blockHash?: string;
+}
+/**
+ * Extract message labels as a union type from InkCallableDescriptor
+ * e.g. ExtractMessageLabels<Messages> = "PSP22::transfer" | "PSP22::balance_of" | ...
+ */
+type ExtractMessageLabels<M extends InkCallableDescriptor> = keyof M & string;
+/**
+ * Type-safe parsed contract call with discriminated union
+ * Enables type narrowing: `if (call.type === "PSP22::transfer") { call.args.to }`
+ */
+type TypedContractCall<M extends InkCallableDescriptor> = { [K in keyof M & string]: {
+  /** Call type/method name (discriminant for type narrowing) */
+  type: K;
+  /** Decoded call arguments (type-safe based on method) */
+  args: M[K]["message"];
+  /** 4-byte selector */
+  selector: Uint8Array;
+  /** Original raw call data */
+  raw: RawContractCall;
+} }[keyof M & string];
+/**
+ * Call filter options
+ */
+interface CallFilterOptions {
+  /** Message labels to include (e.g., ["PSP22::transfer", "PSP22::approve"]) */
+  messageLabels?: string[];
+}
+/**
+ * Type-safe call filter options with literal message labels
+ * Provides compile-time validation of message label names
+ *
+ * @typeParam M - The InkCallableDescriptor type (message definitions)
+ *
+ * @example
+ * ```ts
+ * const options: TypedCallFilterOptions<typeof contracts.usdt.__types.messages> = {
+ *   messageLabels: ["PSP22::transfer", "PSP22::approve"], // Must be valid message names
+ * };
+ * ```
+ */
+interface TypedCallFilterOptions<M extends InkCallableDescriptor> {
+  /** Message labels to include (type-safe) */
+  messageLabels?: Array<ExtractMessageLabels<M>>;
+}
+/**
+ * Message info from metadata
+ */
+interface MessageInfo {
+  /** Message label (e.g., "PSP22::transfer") */
+  label: string;
+  /** 4-byte selector */
+  selector: Uint8Array;
+  /** Whether the message is mutable (writes state) */
+  mutates: boolean;
+  /** Whether the message is payable */
+  payable: boolean;
+  /** Argument definitions */
+  args: Array<{
+    label: string;
+    type: {
+      type: number;
+    };
+  }>;
+}
+//#endregion
+//#region src/calls.d.ts
+/**
+ * Type-safe call parser for a specific contract
+ *
+ * @typeParam S - The storage descriptor type
+ * @typeParam M - The InkCallableDescriptor type (message definitions)
+ * @typeParam C - The constructors descriptor type
+ * @typeParam E - The events Enum type
+ */
+declare class ContractCallParser<S extends InkStorageDescriptor = InkStorageDescriptor, M extends InkCallableDescriptor = InkCallableDescriptor, C extends InkCallableDescriptor = InkCallableDescriptor, E extends Event = Event> {
+  private messageDecoders;
+  private selectorToLabel;
+  private metadata;
+  constructor(descriptor: InkDescriptors<S, M, C, E>);
+  /**
+   * Parse raw call data into a type-safe contract call
+   *
+   * @param callData - The raw call data (selector + encoded args) or RawContractCall
+   * @returns Parsed call or null if cannot parse
+   *
+   * @example
+   * ```ts
+   * const call = parser.parseCall(callData);
+   * if (call?.type === "PSP22::transfer") {
+   *   // call.args is typed as { to: SS58String; value: bigint; data: Uint8Array }
+   *   console.log(call.args.to);
+   * }
+   * ```
+   */
+  parseCall(callData: Uint8Array | RawContractCall): TypedContractCall<M> | null;
+  /**
+   * Parse multiple calls and optionally filter by message labels
+   *
+   * @param calls - Array of raw call data
+   * @param options - Filter options
+   * @returns Array of parsed calls
+   */
+  parseCalls(calls: Array<Uint8Array | RawContractCall>, options?: CallFilterOptions): TypedContractCall<M>[];
+  /**
+   * Filter calls by specific type with proper type narrowing
+   *
+   * This method provides better type safety than parseCalls with messageLabels
+   * because TypeScript can narrow the return type to only the specified call type.
+   *
+   * @param calls - Array of raw call data
+   * @param label - The message label to filter by
+   * @returns Array of calls narrowed to the specific type
+   *
+   * @example
+   * ```ts
+   * const transfers = parser.filterByType(callDataArray, "PSP22::transfer");
+   *
+   * for (const t of transfers) {
+   *   // t.args is fully typed as PSP22::transfer args
+   *   console.log(t.args.to, t.args.value);
+   * }
+   * ```
+   */
+  filterByType<L extends string>(calls: Array<Uint8Array | RawContractCall>, label: L): Array<TypedContractCall<M> & {
+    type: L;
+  }>;
+  /**
+   * Get information about a message by label
+   */
+  getMessageInfo(label: string): MessageInfo | null;
+  /**
+   * Get all available message labels
+   */
+  getMessageLabels(): string[];
+  /**
+   * Check if a selector matches a specific message
+   */
+  matchesMessage(selector: Uint8Array, label: string): boolean;
+  /**
+   * Get selector for a message label
+   *
+   * @param label - Message label (e.g., "PSP22::transfer")
+   * @returns Selector as Uint8Array or null if not found
+   *
+   * @example
+   * ```ts
+   * const selector = parser.getSelector("PSP22::transfer");
+   * // selector is Uint8Array([0xdb, 0x20, 0xf9, 0xf5])
+   * ```
+   */
+  getSelector(label: string): Uint8Array | null;
+  /**
+   * Get selector as hex string for a message label
+   *
+   * @param label - Message label (e.g., "PSP22::transfer")
+   * @returns Selector hex string (without 0x) or null if not found
+   *
+   * @example
+   * ```ts
+   * const selectorHex = parser.getSelectorHex("PSP22::transfer");
+   * // selectorHex is "db20f9f5"
+   * ```
+   */
+  getSelectorHex(label: string): string | null;
+  /**
+   * Get the label for a selector
+   *
+   * @param selector - Selector as Uint8Array or hex string (with or without 0x)
+   * @returns Message label or null if not found
+   *
+   * @example
+   * ```ts
+   * const label = parser.getLabel("db20f9f5");
+   * // label is "PSP22::transfer"
+   *
+   * // Also works with Uint8Array
+   * const label2 = parser.getLabel(callData.slice(0, 4));
+   * ```
+   */
+  getLabel(selector: Uint8Array | string): string | null;
+  /**
+   * Get all selector-to-label mappings
+   *
+   * @returns Map of selector hex (without 0x) -> label
+   *
+   * @example
+   * ```ts
+   * const map = parser.getSelectorMap();
+   * for (const [selectorHex, label] of map) {
+   *   console.log(`${selectorHex} -> ${label}`);
+   * }
+   * ```
+   */
+  getSelectorMap(): Map<string, string>;
+  /**
+   * Check if a selector exists in this contract
+   *
+   * @param selector - Selector to check (Uint8Array or hex string)
+   * @returns True if selector is valid for this contract
+   *
+   * @example
+   * ```ts
+   * if (parser.hasSelector("db20f9f5")) {
+   *   // This selector is valid for this contract
+   * }
+   * ```
+   */
+  hasSelector(selector: Uint8Array | string): boolean;
+  /**
+   * Normalize selector to hex string (without 0x prefix)
+   */
+  private normalizeSelector;
+}
+/**
+ * Type guard for narrowing call types
+ *
+ * Use this function when you have a `TypedContractCall` and need to
+ * narrow it to a specific call type. This is useful when the type
+ * information is lost (e.g., after serialization or in generic functions).
+ *
+ * @typeParam M - The InkCallableDescriptor type (message definitions)
+ * @typeParam L - The specific message label to check
+ * @param call - The call to check
+ * @param label - The message label to match
+ * @returns True if the call type matches the label
+ *
+ * @example
+ * ```ts
+ * const call = parser.parseCall(callData);
+ *
+ * if (call && isCallType(call, "PSP22::transfer")) {
+ *   // TypeScript knows call.args is transfer args
+ *   console.log(call.args.to);
+ *   console.log(call.args.value);
+ * }
+ * ```
+ */
+declare function isCallType<M extends InkCallableDescriptor, L extends ExtractMessageLabels<M>>(call: TypedContractCall<M>, label: L): call is Extract<TypedContractCall<M>, {
+  type: L;
+}>;
+//#endregion
+//#region src/selectors.d.ts
+/**
+ * Information about a contract message selector
+ */
+interface SelectorInfo {
+  /** Message label (e.g., "PSP22::transfer") */
+  label: string;
+  /** 4-byte selector */
+  selector: Uint8Array;
+  /** Hex string without 0x prefix (e.g., "db20f9f5") */
+  selectorHex: string;
+  /** Whether the message mutates state */
+  mutates: boolean;
+  /** Whether the message is payable */
+  payable: boolean;
+}
+/**
+ * PSP22 standard selectors for quick reference
+ *
+ * These are derived from the PSP22 standard and are consistent across implementations.
+ * Use these when you need to quickly check if call data matches a specific PSP22 method.
+ *
+ * @example
+ * ```ts
+ * import { PSP22_SELECTORS, extractSelectorHex } from "@d9-network/ink";
+ *
+ * const selectorHex = extractSelectorHex(callData);
+ * if (selectorHex === PSP22_SELECTORS.transfer) {
+ *   // This is a PSP22::transfer call
+ * }
+ * ```
+ */
+declare const PSP22_SELECTORS: {
+  /** PSP22::total_supply - 0x162df8c2 */
+  readonly totalSupply: "162df8c2";
+  /** PSP22::balance_of - 0x6568382f */
+  readonly balanceOf: "6568382f";
+  /** PSP22::allowance - 0x4d47d921 */
+  readonly allowance: "4d47d921";
+  /** PSP22::transfer - 0xdb20f9f5 */
+  readonly transfer: "db20f9f5";
+  /** PSP22::transfer_from - 0x54b3c76e */
+  readonly transferFrom: "54b3c76e";
+  /** PSP22::approve - 0xb20f1bbd */
+  readonly approve: "b20f1bbd";
+  /** PSP22::increase_allowance - 0x96d6b57a */
+  readonly increaseAllowance: "96d6b57a";
+  /** PSP22::decrease_allowance - 0xfecb57d5 */
+  readonly decreaseAllowance: "fecb57d5";
+};
+/**
+ * PSP22 selector type for type safety
+ */
+type PSP22SelectorKey = keyof typeof PSP22_SELECTORS;
+/**
+ * Build a selector lookup map from contract metadata
+ *
+ * @param metadata - Contract metadata
+ * @returns Map of selector hex (without 0x) -> SelectorInfo
+ *
+ * @example
+ * ```ts
+ * import { contracts } from "@d9-network/spec";
+ * import { buildSelectorMap } from "@d9-network/ink";
+ *
+ * const selectors = buildSelectorMap(contracts.usdt.metadata);
+ * const info = selectors.get("db20f9f5");
+ * if (info) {
+ *   console.log(info.label); // "PSP22::transfer"
+ * }
+ * ```
+ */
+declare function buildSelectorMap(metadata: InkMetadata): Map<string, SelectorInfo>;
+/**
+ * Build a reverse lookup map (label -> selector info)
+ *
+ * @param metadata - Contract metadata
+ * @returns Map of label -> SelectorInfo
+ *
+ * @example
+ * ```ts
+ * const labelMap = buildLabelMap(contracts.usdt.metadata);
+ * const info = labelMap.get("PSP22::transfer");
+ * console.log(info?.selectorHex); // "db20f9f5"
+ * ```
+ */
+declare function buildLabelMap(metadata: InkMetadata): Map<string, SelectorInfo>;
+/**
+ * Get selector for a message label
+ *
+ * @param metadata - Contract metadata
+ * @param label - Message label (e.g., "PSP22::transfer")
+ * @returns Selector info or null if not found
+ *
+ * @example
+ * ```ts
+ * const info = getSelectorForLabel(contracts.usdt.metadata, "PSP22::transfer");
+ * console.log(info?.selectorHex); // "db20f9f5"
+ * ```
+ */
+declare function getSelectorForLabel(metadata: InkMetadata, label: string): SelectorInfo | null;
+/**
+ * Get message label for a selector
+ *
+ * @param metadata - Contract metadata
+ * @param selector - Selector as Uint8Array or hex string (with or without 0x)
+ * @returns Selector info or null if not found
+ *
+ * @example
+ * ```ts
+ * const info = getLabelForSelector(contracts.usdt.metadata, "db20f9f5");
+ * console.log(info?.label); // "PSP22::transfer"
+ *
+ * // Also works with Uint8Array
+ * const info2 = getLabelForSelector(contracts.usdt.metadata, callData.slice(0, 4));
+ * ```
+ */
+declare function getLabelForSelector(metadata: InkMetadata, selector: Uint8Array | string): SelectorInfo | null;
+/**
+ * Check if call data matches a specific message
+ *
+ * @param metadata - Contract metadata
+ * @param callData - Call data bytes or hex string
+ * @param label - Message label to check
+ * @returns True if the call data selector matches the label
+ *
+ * @example
+ * ```ts
+ * if (isMessageCall(contracts.usdt.metadata, callData, "PSP22::transfer")) {
+ *   // This is a transfer call
+ * }
+ * ```
+ */
+declare function isMessageCall(metadata: InkMetadata, callData: Uint8Array | string, label: string): boolean;
+/**
+ * Check if call data matches a PSP22 method
+ *
+ * @param callData - Call data bytes or hex string
+ * @param method - PSP22 method name (e.g., "transfer", "transferFrom")
+ * @returns True if the call data selector matches the PSP22 method
+ *
+ * @example
+ * ```ts
+ * if (isPSP22Call(callData, "transfer")) {
+ *   // This is a PSP22::transfer call
+ * }
+ * ```
+ */
+declare function isPSP22Call(callData: Uint8Array | string, method: PSP22SelectorKey): boolean;
+/**
+ * Get all selectors from contract metadata
+ *
+ * @param metadata - Contract metadata
+ * @returns Array of SelectorInfo for all messages
+ */
+declare function getAllSelectors(metadata: InkMetadata): SelectorInfo[];
+//#endregion
+//#region src/indexer/extrinsic-utils.d.ts
+/**
+ * Compute the blake2b-256 hash of an extrinsic
+ *
+ * This is the standard way to compute extrinsic hashes on Substrate chains.
+ *
+ * @param extrinsicHex - The raw extrinsic as a hex string (with or without 0x prefix)
+ * @returns The extrinsic hash as a hex string with 0x prefix
+ *
+ * @example
+ * ```ts
+ * import { computeExtrinsicHash } from "@d9-network/ink/indexer";
+ *
+ * const extrinsicHex = "0x..."; // from getBlockBody()
+ * const hash = computeExtrinsicHash(extrinsicHex);
+ * // hash is "0xabcd..." (64 hex chars)
+ * ```
+ */
+declare function computeExtrinsicHash(extrinsicHex: HexString | string): HexString;
+/**
+ * Options for parseContractCallFromHex
+ */
+interface ParseContractCallOptions {
+  /** Contract address to include in the raw call metadata */
+  contractAddress?: SS58String;
+  /** Caller/signer address */
+  caller?: SS58String;
+  /** Block number */
+  blockNumber?: number;
+  /** Block hash */
+  blockHash?: string;
+  /** Extrinsic hash */
+  txHash?: string;
+}
+/**
+ * Search parameters for finding contract call data in an extrinsic
+ */
+interface ContractCallSearchParams {
+  /** Target contract address (to match dest field) */
+  targetContract?: SS58String;
+  /** Known selector to search for (4 bytes hex without 0x) */
+  selector?: string;
+}
+/**
+ * Attempt to find and extract contract call data from a raw extrinsic hex
+ *
+ * This function searches the extrinsic hex for patterns that look like
+ * contract call data (selector followed by SCALE-encoded arguments).
+ *
+ * @param extrinsicHex - The raw extrinsic hex
+ * @param selector - The 4-byte selector hex to search for (without 0x)
+ * @returns The call data starting from the selector, or null if not found
+ */
+declare function extractCallDataFromHex(extrinsicHex: HexString | string, selector: string): Uint8Array | null;
+/**
+ * Parse a contract call from raw hex extrinsic data
+ *
+ * This is useful for indexers that receive extrinsics as raw hex strings
+ * from `getBlockBody()` and need to decode specific contract calls.
+ *
+ * @param extrinsicHex - The raw extrinsic hex
+ * @param callParser - A ContractCallParser instance for the target contract
+ * @param options - Additional options and metadata
+ * @returns Parsed contract call or null if parsing fails
+ *
+ * @example
+ * ```ts
+ * import { parseContractCallFromHex, ContractCallParser } from "@d9-network/ink/indexer";
+ * import { contracts } from "@d9-network/spec";
+ *
+ * const parser = new ContractCallParser(contracts.usdt);
+ * const call = parseContractCallFromHex(extrinsicHex, parser, {
+ *   contractAddress: USDT_ADDRESS,
+ *   caller: signerAddress,
+ * });
+ *
+ * if (call?.type === "PSP22::transfer") {
+ *   console.log(call.args.to, call.args.value);
+ * }
+ * ```
+ */
+declare function parseContractCallFromHex<M extends InkCallableDescriptor>(extrinsicHex: HexString | string, callParser: ContractCallParser<any, M, any, any>, options?: ParseContractCallOptions): TypedContractCall<M> | null;
+/**
+ * Extract selector hex from call data
+ *
+ * @param callData - Raw call data (Uint8Array or hex string)
+ * @returns 4-byte selector as hex string without 0x prefix, or null if too short
+ */
+declare function extractSelectorFromCallData(callData: Uint8Array | HexString | string): string | null;
+/**
+ * Check if extrinsic contains a specific selector
+ *
+ * @param extrinsicHex - Raw extrinsic hex
+ * @param selector - Selector to check for (with or without 0x)
+ * @returns True if selector is found in the extrinsic
+ */
+declare function hasSelector(extrinsicHex: HexString | string, selector: string): boolean;
+/**
+ * Check if extrinsic contains a PSP22 call
+ *
+ * @param extrinsicHex - Raw extrinsic hex
+ * @returns The PSP22 method name if found, null otherwise
+ */
+declare function findPSP22Selector(extrinsicHex: HexString | string): keyof typeof PSP22_SELECTORS | null;
+//#endregion
+//#region src/indexer/psp22.d.ts
+/**
+ * Decoded PSP22 transfer result
+ */
+interface DecodedPSP22Transfer {
+  /** Transfer type */
+  type: "transfer" | "transfer_from";
+  /** Source address (D9 format) */
+  from: SS58String;
+  /** Destination address (D9 format) */
+  to: SS58String;
+  /** Transfer amount */
+  value: bigint;
+}
+/**
+ * Options for PSP22 decoding
+ */
+interface DecodePSP22Options {
+  /**
+   * SS58 prefix for returned addresses.
+   * Defaults to D9_SS58_PREFIX (9).
+   */
+  ss58Prefix?: number;
+}
+/**
+ * Decode a PSP22 transfer or transfer_from call from raw extrinsic hex
+ *
+ * This function handles the common case of extracting PSP22 token transfers
+ * from raw blockchain data without needing the full contract metadata.
+ *
+ * PSP22::transfer args: (to: AccountId, value: u128, data: Vec<u8>)
+ * PSP22::transfer_from args: (from: AccountId, to: AccountId, value: u128, data: Vec<u8>)
+ *
+ * @param extrinsicHex - The raw extrinsic hex
+ * @param caller - The transaction signer (used as 'from' for transfer)
+ * @param options - Decoding options
+ * @returns Decoded transfer or null if not a PSP22 transfer
+ *
+ * @example
+ * ```ts
+ * import { decodePSP22Transfer } from "@d9-network/ink/indexer";
+ *
+ * const transfer = decodePSP22Transfer(extrinsicHex, signerAddress);
+ * if (transfer) {
+ *   console.log(`${transfer.from} -> ${transfer.to}: ${transfer.value}`);
+ * }
+ * ```
+ */
+declare function decodePSP22Transfer(extrinsicHex: HexString | string, caller: SS58String, options?: DecodePSP22Options): DecodedPSP22Transfer | null;
+/**
+ * Check if an extrinsic contains a PSP22 transfer call
+ *
+ * @param extrinsicHex - Raw extrinsic hex
+ * @returns True if contains PSP22::transfer or PSP22::transfer_from
+ */
+declare function isPSP22TransferExtrinsic(extrinsicHex: HexString | string): boolean;
+/**
+ * Get the PSP22 transfer type from extrinsic hex
+ *
+ * @param extrinsicHex - Raw extrinsic hex
+ * @returns "transfer", "transfer_from", or null
+ */
+declare function getPSP22TransferType(extrinsicHex: HexString | string): "transfer" | "transfer_from" | null;
+declare namespace index_d_exports {
+  export { ContractCallSearchParams, DecodePSP22Options, DecodedPSP22Transfer, ParseContractCallOptions, computeExtrinsicHash, decodePSP22Transfer, extractCallDataFromHex, extractSelectorFromCallData, findPSP22Selector, getPSP22TransferType, hasSelector, isPSP22TransferExtrinsic, parseContractCallFromHex };
+}
+//#endregion
+export { RawContractCall as A, isMessageCall as C, CallFilterOptions as D, isCallType as E, TypedContractCall as M, ExtractMessageLabels as O, getSelectorForLabel as S, ContractCallParser as T, SelectorInfo as _, getPSP22TransferType as a, getAllSelectors as b, ParseContractCallOptions as c, extractSelectorFromCallData as d, findPSP22Selector as f, PSP22_SELECTORS as g, PSP22SelectorKey as h, decodePSP22Transfer as i, TypedCallFilterOptions as j, MessageInfo as k, computeExtrinsicHash as l, parseContractCallFromHex as m, DecodePSP22Options as n, isPSP22TransferExtrinsic as o, hasSelector as p, DecodedPSP22Transfer as r, ContractCallSearchParams as s, index_d_exports as t, extractCallDataFromHex as u, buildLabelMap as v, isPSP22Call as w, getLabelForSelector as x, buildSelectorMap as y };
+//# sourceMappingURL=index-DgYVGyHC.d.cts.map