@d9-network/ink 0.0.1

package/src/decode.ts

@@ -0,0 +1,176 @@
+/**
+ * Decoding utilities for ContractsApi_call response
+ */
+
+import { Src } from "@subsquid/scale-codec";
+import { type Codec, u128, Tuple } from "@polkadot-api/substrate-bindings";
+
+/**
+ * Gas information from contract execution
+ */
+export interface GasInfo {
+  /** Gas consumed during execution */
+  gasConsumed: { refTime: bigint; proofSize: bigint };
+  /** Gas required for execution */
+  gasRequired: { refTime: bigint; proofSize: bigint };
+}
+
+/**
+ * Storage deposit information
+ */
+export interface StorageDepositInfo {
+  /** Storage deposit type: 0 = Refund, 1 = Charge */
+  type: "Refund" | "Charge";
+  /** Amount of storage deposit */
+  amount: bigint;
+}
+
+/**
+ * Full decoded result from ContractsApi_call
+ */
+export interface ContractCallResult {
+  /** Gas information */
+  gas: GasInfo;
+  /** Storage deposit information */
+  storageDeposit: StorageDepositInfo;
+  /** Debug message (if any) */
+  debugMessage: string;
+  /** Whether the execution was successful */
+  success: boolean;
+  /** Execution flags */
+  flags: number;
+  /** The raw execution result bytes (still wrapped in Result<T, LangError>) */
+  data: Uint8Array;
+}
+
+/**
+ * Decode the raw ContractsApi_call response.
+ *
+ * The response format is:
+ * - gasConsumed: Weight { ref_time: Compact<u64>, proof_size: Compact<u64> }
+ * - gasRequired: Weight
+ * - storageDeposit: StorageDeposit { variant: u8, amount: u128 }
+ * - debugMessage: String
+ * - result: Result<ExecReturnValue, DispatchError>
+ *   - ExecReturnValue: { flags: u32, data: Vec<u8> }
+ *
+ * @param result - The raw response bytes from state_call ContractsApi_call
+ * @returns Decoded contract call result
+ */
+export function decodeContractCallResult(result: Uint8Array): ContractCallResult {
+  const src = new Src(result);
+
+  // gasConsumed: Weight
+  const gasConsumedRefTime = BigInt(src.compact());
+  const gasConsumedProofSize = BigInt(src.compact());
+
+  // gasRequired: Weight
+  const gasRequiredRefTime = BigInt(src.compact());
+  const gasRequiredProofSize = BigInt(src.compact());
+
+  // storageDeposit: StorageDeposit
+  const storageDepositVariant = src.u8();
+  const storageDepositAmount = src.u128();
+
+  // debugMessage: String
+  const debugMessage = src.str();
+
+  // result: Result<ExecReturnValue, DispatchError>
+  const resultVariant = src.u8(); // 0 = Ok, 1 = Err
+  const success = resultVariant === 0;
+
+  // ExecReturnValue: { flags: u32, data: Vec<u8> }
+  const flags = src.u32();
+  const data = src.bytes(src.compactLength());
+
+  return {
+    gas: {
+      gasConsumed: {
+        refTime: gasConsumedRefTime,
+        proofSize: gasConsumedProofSize,
+      },
+      gasRequired: {
+        refTime: gasRequiredRefTime,
+        proofSize: gasRequiredProofSize,
+      },
+    },
+    storageDeposit: {
+      type: storageDepositVariant === 0 ? "Refund" : "Charge",
+      amount: storageDepositAmount,
+    },
+    debugMessage,
+    success,
+    flags,
+    data,
+  };
+}
+
+/**
+ * Legacy function - decode and return just the exec result data.
+ * @deprecated Use decodeContractCallResult for full information
+ */
+export function decodeResult(result: Uint8Array): Uint8Array {
+  const decoded = decodeContractCallResult(result);
+  return decoded.data;
+}
+
+/**
+ * Unwrap the inner value from Result<T, LangError> by checking the variant byte.
+ *
+ * Ink contracts wrap their return values in Result<T, LangError>.
+ * This function handles the unwrapping and throws an error for LangError.
+ *
+ * @param data - The exec result bytes (Result<T, LangError> encoded)
+ * @returns The inner value bytes (T encoded)
+ * @throws Error if the result is Err variant (LangError)
+ */
+export function unwrapInkResult(data: Uint8Array): Uint8Array {
+  if (data.length === 0) {
+    throw new Error("Empty result data");
+  }
+
+  const variant = data[0];
+
+  if (variant === 0) {
+    // Ok variant - return the inner data (skip the variant byte)
+    return data.slice(1);
+  } else if (variant === 1) {
+    // Err variant - LangError
+    throw new Error("Contract call returned LangError");
+  } else {
+    throw new Error(`Unknown result variant: ${variant}`);
+  }
+}
+
+/**
+ * Check if the result indicates a LangError
+ *
+ * @param data - The exec result bytes
+ * @returns True if it's a LangError (Err variant)
+ */
+export function isLangError(data: Uint8Array): boolean {
+  return data.length > 0 && data[0] === 1;
+}
+
+/**
+ * Decode ink contract message result using a custom SCALE codec.
+ * This bypasses polkadot-api's ink decoder which has issues with LangError type.
+ *
+ * @param data - The exec result bytes (Result<T, LangError> encoded)
+ * @param codec - The SCALE codec for the inner value type T
+ * @returns The decoded value
+ */
+export function decodeInkValue<T>(data: Uint8Array, codec: Codec<T>): T {
+  const innerData = unwrapInkResult(data);
+  return codec.dec(innerData);
+}
+
+/**
+ * Pre-defined codecs for common types
+ */
+export const InkCodecs = {
+  /** u128 codec for Balance type */
+  u128,
+  /** Tuple of two u128 values, commonly used for (Balance, Balance) */
+  balancePair: Tuple(u128, u128),
+};

package/src/encode.ts

@@ -0,0 +1,128 @@
+/**
+ * Encoding utilities for ContractsApi_call state_call
+ */
+
+import type { Bytes } from "@subsquid/scale-codec";
+import { HexSink } from "@subsquid/scale-codec";
+import type { Binary } from "polkadot-api";
+import { fromHex } from "polkadot-api/utils";
+
+/**
+ * Encode a contract call for ContractsApi_call state_call.
+ *
+ * The encoded format matches the ContractsApi::call runtime API:
+ * - origin: AccountId (32 bytes)
+ * - dest: AccountId (32 bytes)
+ * - value: Balance (u128)
+ * - gas_limit: Option<Weight> (1 byte for None)
+ * - storage_deposit_limit: Option<Balance> (1 byte for None)
+ * - input_data: Vec<u8> (compact length + bytes)
+ *
+ * @param origin - The origin account (as Uint8Array or hex string)
+ * @param dest - The contract address (as Uint8Array or hex string)
+ * @param input - The encoded call data (selector + arguments)
+ * @param value - Optional value to transfer (default: 0)
+ * @returns Hex-encoded bytes for state_call
+ */
+export function encodeContractCall(
+  origin: Uint8Array | string,
+  dest: Uint8Array | string,
+  input: Binary | Uint8Array,
+  value: bigint = 0n,
+): Bytes {
+  const sink = new HexSink();
+
+  const originBytes = typeof origin === "string" ? fromHex(origin) : origin;
+  const destBytes = typeof dest === "string" ? fromHex(dest) : dest;
+  const inputBytes = "asBytes" in input ? input.asBytes() : input;
+
+  // origin: AccountId
+  sink.bytes(originBytes);
+  // dest: AccountId
+  sink.bytes(destBytes);
+  // value: Balance (u128)
+  sink.u128(value);
+  // gas_limit: Option<Weight> - None
+  sink.u8(0);
+  // storage_deposit_limit: Option<Balance> - None
+  sink.u8(0);
+  // input_data: Vec<u8>
+  sink.compact(inputBytes.length);
+  sink.bytes(inputBytes);
+
+  return sink.toHex();
+}
+
+/**
+ * Encode a contract call using the same address for origin and dest.
+ * This is a simplified version for query operations where the origin
+ * doesn't matter much.
+ *
+ * @param address - The contract address
+ * @param input - The encoded call data
+ * @param value - Optional value to transfer
+ * @returns Hex-encoded bytes for state_call
+ */
+export function encodeCall(
+  address: Uint8Array | string,
+  input: Binary | Uint8Array,
+  value: bigint = 0n,
+): Bytes {
+  return encodeContractCall(address, address, input, value);
+}
+
+/**
+ * Encode a contract call with specific gas limit and storage deposit limit.
+ *
+ * @param origin - The origin account
+ * @param dest - The contract address
+ * @param input - The encoded call data
+ * @param options - Call options including value, gas limit, storage deposit limit
+ * @returns Hex-encoded bytes for state_call
+ */
+export function encodeContractCallWithLimits(
+  origin: Uint8Array | string,
+  dest: Uint8Array | string,
+  input: Binary | Uint8Array,
+  options: {
+    value?: bigint;
+    gasLimit?: { refTime: bigint; proofSize: bigint };
+    storageDepositLimit?: bigint;
+  } = {},
+): Bytes {
+  const sink = new HexSink();
+
+  const originBytes = typeof origin === "string" ? fromHex(origin) : origin;
+  const destBytes = typeof dest === "string" ? fromHex(dest) : dest;
+  const inputBytes = "asBytes" in input ? input.asBytes() : input;
+
+  // origin: AccountId
+  sink.bytes(originBytes);
+  // dest: AccountId
+  sink.bytes(destBytes);
+  // value: Balance (u128)
+  sink.u128(options.value ?? 0n);
+
+  // gas_limit: Option<Weight>
+  if (options.gasLimit) {
+    sink.u8(1); // Some
+    sink.compact(options.gasLimit.refTime);
+    sink.compact(options.gasLimit.proofSize);
+  } else {
+    sink.u8(0); // None
+  }
+
+  // storage_deposit_limit: Option<Balance>
+  if (options.storageDepositLimit !== undefined) {
+    sink.u8(1); // Some
+    sink.u128(options.storageDepositLimit);
+  } else {
+    sink.u8(0); // None
+  }
+
+  // input_data: Vec<u8>
+  sink.compact(inputBytes.length);
+  sink.bytes(inputBytes);
+
+  return sink.toHex();
+}

package/src/errors.ts

@@ -0,0 +1,220 @@
+/**
+ * Structured error types for contract operations.
+ * Provides detailed error information for debugging and handling.
+ */
+
+/**
+ * Error types for contract operations
+ */
+export type ContractErrorType =
+  | "METADATA_ERROR" // Missing or invalid contract metadata
+  | "ENCODE_ERROR" // Failed to encode call data
+  | "DECODE_ERROR" // Failed to decode response
+  | "NETWORK_ERROR" // Network or RPC error
+  | "CONTRACT_ERROR" // Contract returned an error
+  | "LANG_ERROR" // Ink LangError (CouldNotReadInput, etc.)
+  | "TIMEOUT_ERROR" // Request timeout
+  | "ABORTED" // Request was aborted
+  | "SIGNER_ERROR" // Signer related error
+  | "TX_ERROR"; // Transaction submission error
+
+/**
+ * Base error class for all contract-related errors
+ */
+export class ContractError extends Error {
+  public readonly timestamp: Date;
+
+  public override readonly cause?: Error;
+
+  constructor(
+    message: string,
+    public readonly type: ContractErrorType,
+    public readonly label?: string,
+    public readonly details?: unknown,
+    cause?: Error,
+  ) {
+    super(message, { cause });
+    this.name = "ContractError";
+    this.timestamp = new Date();
+
+    // Maintains proper stack trace for where error was thrown
+    if (Error.captureStackTrace) {
+      Error.captureStackTrace(this, ContractError);
+    }
+  }
+
+  /**
+   * Create a formatted error message for logging
+   */
+  toLogString(): string {
+    const parts = [
+      `[${this.type}]`,
+      this.label ? `${this.label}:` : "",
+      this.message,
+    ].filter(Boolean);
+
+    if (this.details) {
+      parts.push(`Details: ${JSON.stringify(this.details)}`);
+    }
+
+    return parts.join(" ");
+  }
+
+  /**
+   * Convert to a plain object for serialization
+   */
+  toJSON(): Record<string, unknown> {
+    return {
+      name: this.name,
+      type: this.type,
+      message: this.message,
+      label: this.label,
+      details: this.details,
+      timestamp: this.timestamp.toISOString(),
+      stack: this.stack,
+    };
+  }
+}
+
+/**
+ * Error thrown when contract metadata is missing or invalid
+ */
+export class MetadataError extends ContractError {
+  constructor(message: string, details?: unknown) {
+    super(message, "METADATA_ERROR", undefined, details);
+    this.name = "MetadataError";
+  }
+}
+
+/**
+ * Error thrown when encoding call data fails
+ */
+export class EncodeError extends ContractError {
+  constructor(label: string, message: string, details?: unknown) {
+    super(message, "ENCODE_ERROR", label, details);
+    this.name = "EncodeError";
+  }
+}
+
+/**
+ * Error thrown when decoding response fails
+ */
+export class DecodeError extends ContractError {
+  constructor(label: string, message: string, details?: unknown) {
+    super(message, "DECODE_ERROR", label, details);
+    this.name = "DecodeError";
+  }
+}
+
+/**
+ * Error thrown for network/RPC errors
+ */
+export class NetworkError extends ContractError {
+  constructor(message: string, cause?: Error, details?: unknown) {
+    super(message, "NETWORK_ERROR", undefined, details, cause);
+    this.name = "NetworkError";
+  }
+}
+
+/**
+ * Error thrown when contract returns an error result
+ */
+export class ContractExecutionError extends ContractError {
+  constructor(
+    label: string,
+    public readonly errorValue: unknown,
+  ) {
+    super(
+      `Contract execution failed: ${JSON.stringify(errorValue)}`,
+      "CONTRACT_ERROR",
+      label,
+      errorValue,
+    );
+    this.name = "ContractExecutionError";
+  }
+}
+
+/**
+ * Error thrown for Ink LangError
+ */
+export class LangError extends ContractError {
+  constructor(
+    label: string,
+    public readonly variant: number,
+  ) {
+    const variantName =
+      variant === 1 ? "CouldNotReadInput" : `Unknown(${variant})`;
+    super(`Ink LangError: ${variantName}`, "LANG_ERROR", label, {
+      variant,
+      variantName,
+    });
+    this.name = "LangError";
+  }
+}
+
+/**
+ * Error thrown when request times out
+ */
+export class TimeoutError extends ContractError {
+  constructor(
+    label: string,
+    public readonly timeoutMs: number,
+  ) {
+    super(`Request timed out after ${timeoutMs}ms`, "TIMEOUT_ERROR", label, {
+      timeoutMs,
+    });
+    this.name = "TimeoutError";
+  }
+}
+
+/**
+ * Error thrown when request is aborted
+ */
+export class AbortedError extends ContractError {
+  constructor(label: string, reason?: string) {
+    super(reason || "Request was aborted", "ABORTED", label, { reason });
+    this.name = "AbortedError";
+  }
+}
+
+/**
+ * Error thrown for signer-related issues
+ */
+export class SignerError extends ContractError {
+  constructor(message: string, details?: unknown) {
+    super(message, "SIGNER_ERROR", undefined, details);
+    this.name = "SignerError";
+  }
+}
+
+/**
+ * Error thrown when transaction submission fails
+ */
+export class TransactionError extends ContractError {
+  constructor(
+    label: string,
+    message: string,
+    public readonly txHash?: string,
+    details?: unknown,
+  ) {
+    super(message, "TX_ERROR", label, { ...(details as object), txHash });
+    this.name = "TransactionError";
+  }
+}
+
+/**
+ * Type guard to check if an error is a ContractError
+ */
+export function isContractError(error: unknown): error is ContractError {
+  return error instanceof ContractError;
+}
+
+/**
+ * Type guard to check for specific error types
+ */
+export function isErrorType<T extends ContractErrorType>(
+  error: unknown,
+  type: T,
+): error is ContractError & { type: T } {
+  return isContractError(error) && error.type === type;
+}

package/src/event-types.ts

@@ -0,0 +1,75 @@
+/**
+ * Event type definitions for ink! contracts
+ */
+import type { SS58String } from "polkadot-api";
+
+/**
+ * Raw event data from chain
+ */
+export interface RawContractEvent {
+	/** Block number where event was emitted */
+	blockNumber: number;
+	/** Block hash */
+	blockHash: string;
+	/** Event index in block */
+	eventIndex: number;
+	/** Contract address that emitted the event */
+	contractAddress: SS58String;
+	/** Event data (SCALE encoded) */
+	data: Uint8Array;
+	/** Event topics (indexed fields) */
+	topics: Uint8Array[];
+}
+
+/**
+ * Decoded contract event
+ */
+export interface DecodedContractEvent<T = unknown> {
+	/** Event label from metadata (e.g., "Transfer", "Approval") */
+	label: string;
+	/** Decoded event data */
+	data: T;
+	/** Original raw event */
+	raw: RawContractEvent;
+}
+
+/**
+ * Event filter options
+ */
+export interface EventFilterOptions {
+	/** Contract address to filter by */
+	contractAddress?: SS58String;
+	/** Event labels to include (e.g., ["Transfer", "Approval"]) */
+	eventLabels?: string[];
+	/** From block number (inclusive) */
+	fromBlock?: number;
+	/** To block number (inclusive) */
+	toBlock?: number;
+}
+
+/**
+ * Event subscription options
+ */
+export interface EventSubscriptionOptions {
+	/** Contract address to subscribe to */
+	contractAddress: SS58String;
+	/** Event labels to subscribe to (undefined = all events) */
+	eventLabels?: string[];
+	/** Include historical events from this block */
+	fromBlock?: number;
+	/**
+	 * Function to fetch System.Events at a given block hash
+	 * This is required because PolkadotClient doesn't expose typed API directly
+	 *
+	 * @example
+	 * ```ts
+	 * const options = {
+	 *   contractAddress: usdtAddress,
+	 *   getEvents: async (blockHash) => {
+	 *     return await api.query.System.Events.getValue({ at: blockHash });
+	 *   }
+	 * };
+	 * ```
+	 */
+	getEvents: (blockHash: string) => Promise<unknown[]>;
+}