@d9-network/ink 0.0.1

package/src/types.ts

@@ -0,0 +1,274 @@
+/**
+ * Core type definitions for D9 Ink SDK
+ */
+
+import type {
+  InkCallableDescriptor,
+  InkDescriptors,
+  InkStorageDescriptor,
+  InkMetadata,
+  Event,
+} from "@polkadot-api/ink-contracts";
+import type { PolkadotClient, PolkadotSigner, SS58String } from "polkadot-api";
+import type { Observable } from "rxjs";
+import type { ContractError } from "./errors";
+import type {
+  DecodedContractEvent,
+  EventSubscriptionOptions,
+} from "./event-types";
+
+/**
+ * Decoder type for response decoding
+ */
+export type ResponseDecoder = { dec: (data: Uint8Array) => unknown };
+
+/**
+ * Query options for read operations (dry-run)
+ */
+export interface QueryOptions<Args = unknown> {
+  /** The origin account for the call */
+  origin: SS58String;
+  /** Arguments to pass to the contract message */
+  args?: Args;
+  /** Value to transfer with the call */
+  value?: bigint;
+  /** AbortSignal for cancellation */
+  signal?: AbortSignal;
+  /** Timeout in milliseconds */
+  timeout?: number;
+  /** Block hash to query at (default: finalized) */
+  at?: string;
+}
+
+/**
+ * Send options for write operations
+ */
+export interface SendOptions<Args = unknown> {
+  /** The origin account for the call */
+  origin: SS58String;
+  /** Arguments to pass to the contract message */
+  args?: Args;
+  /** Value to transfer with the call */
+  value?: bigint;
+  /** Gas limit (optional, will be estimated if not provided) */
+  gasLimit?: { refTime: bigint; proofSize: bigint };
+  /** Storage deposit limit */
+  storageDepositLimit?: bigint;
+}
+
+/**
+ * Sendable transaction that can be signed and submitted
+ */
+export interface SendableTransaction<T> {
+  /** Sign and submit the transaction */
+  signAndSubmit(signer: PolkadotSigner): Promise<TxResult<T>>;
+  /** Get the encoded call data */
+  getEncodedData(): Uint8Array;
+}
+
+/**
+ * Transaction result
+ */
+export interface TxResult<T> {
+  /** Whether the transaction was successful */
+  ok: boolean;
+  /** Transaction hash */
+  txHash: string;
+  /** Block information where tx was included */
+  block: {
+    hash: string;
+    number: number;
+  };
+  /** Decoded return value (if any) */
+  result?: T;
+  /** Events emitted by the transaction */
+  events: unknown[];
+  /** Dispatch error if failed */
+  dispatchError?: unknown;
+}
+
+/**
+ * Successful query result value
+ */
+export interface QuerySuccessValue<T> {
+  /** The decoded response from the contract */
+  value: T;
+  /** Events that would be emitted */
+  events: unknown[];
+  /** Gas consumed during dry-run */
+  gasConsumed: { refTime: bigint; proofSize: bigint };
+  /** Gas required for execution */
+  gasRequired: { refTime: bigint; proofSize: bigint };
+  /** Storage deposit required */
+  storageDeposit: bigint;
+  /** Create a sendable transaction from this query result */
+  send(): SendableTransaction<T>;
+}
+
+/**
+ * Query result - discriminated union for success/failure
+ * On success: QuerySuccessValue fields are spread to the same level as success
+ * On failure: error field contains the ContractError
+ */
+export type QueryResult<T> =
+  | ({ success: true } & QuerySuccessValue<T>)
+  | { success: false; error: ContractError };
+
+/**
+ * Storage query interface
+ */
+export interface ContractStorage {
+  /** Get the root storage value */
+  getRoot(): Promise<
+    { success: true; value: unknown } | { success: false; value: ContractError }
+  >;
+  /** Get a nested storage value by path */
+  getNested(
+    path: string,
+    ...keys: unknown[]
+  ): Promise<
+    { success: true; value: unknown } | { success: false; value: ContractError }
+  >;
+}
+
+/**
+ * Type helper to extract message args type
+ */
+type MessageArgs<
+  M extends InkCallableDescriptor,
+  K extends keyof M,
+> = M[K]["message"];
+
+/**
+ * ink! LangError type pattern
+ * papi generates LangError variants with { type: string; value?: unknown }
+ */
+type InkLangError = { type: string; value?: unknown };
+
+/**
+ * ink! MessageResult type pattern (Result<T, LangError>)
+ * papi generates this as { success: true; value: T } | { success: false; value: LangError }
+ */
+type InkMessageResult<T> =
+  | { success: true; value: T }
+  | { success: false; value: unknown };
+
+/**
+ * Type helper to unwrap ink! MessageResult (Result<T, LangError>)
+ * 1. Extract T from { success: true; value: T } | { success: false; value: ... }
+ * 2. Exclude LangError variants from T
+ */
+type UnwrapMessageResult<T> = T extends InkMessageResult<infer U>
+  ? Exclude<U, InkLangError>
+  : T;
+
+/**
+ * Type helper to extract message response type (with MessageResult unwrapped)
+ */
+type MessageResponse<
+  M extends InkCallableDescriptor,
+  K extends keyof M,
+> = UnwrapMessageResult<M[K]["response"]>;
+
+/**
+ * D9 Ink Contract interface
+ */
+export interface D9InkContract<M extends InkCallableDescriptor> {
+  /** Contract address */
+  readonly address: SS58String;
+  /** Contract metadata */
+  readonly metadata: InkMetadata;
+
+  /**
+   * Query a contract message (dry-run)
+   * @param method - The message label (e.g., "PSP22::balance_of")
+   * @param options - Query options including origin and args
+   */
+  query<K extends keyof M & string>(
+    method: K,
+    options: QueryOptions<MessageArgs<M, K>>,
+  ): Promise<QueryResult<MessageResponse<M, K>>>;
+
+  /**
+   * Create a sendable transaction for a contract message
+   * @param method - The message label (e.g., "PSP22::transfer")
+   * @param options - Send options including origin and args
+   */
+  send<K extends keyof M & string>(
+    method: K,
+    options: SendOptions<MessageArgs<M, K>>,
+  ): SendableTransaction<MessageResponse<M, K>>;
+
+  /**
+   * Get storage query interface
+   */
+  getStorage(): ContractStorage;
+
+  /**
+   * Filter events from a transaction result to only include this contract's events
+   */
+  filterEvents(events: unknown[]): DecodedContractEvent[];
+
+  /**
+   * Subscribe to contract events as an RxJS Observable
+   * @param options - Event subscription options (event labels to filter, etc.)
+   */
+  subscribeToEvents(
+    options?: Omit<EventSubscriptionOptions, "contractAddress">,
+  ): Observable<DecodedContractEvent>;
+}
+
+/**
+ * D9 Ink SDK options
+ */
+export interface D9InkSdkOptions {
+  /** Default query options */
+  defaultQueryOptions?: Partial<QueryOptions>;
+  /** Default send options */
+  defaultSendOptions?: Partial<SendOptions>;
+}
+
+/**
+ * D9 Ink SDK interface
+ */
+export interface D9InkSdk {
+  /**
+   * Get a contract instance for interacting with a deployed contract
+   * @param descriptor - The contract descriptor from @polkadot-api/descriptors
+   * @param address - The contract address (SS58 format)
+   */
+  getContract<
+    S extends InkStorageDescriptor,
+    M extends InkCallableDescriptor,
+    C extends InkCallableDescriptor,
+    E extends Event,
+  >(
+    descriptor: InkDescriptors<S, M, C, E>,
+    address: SS58String,
+  ): D9InkContract<M>;
+}
+
+export type D9InkContractFromDescriptor<D> = D extends InkDescriptors<infer _S, infer M, infer _C, infer _E> ? D9InkContract<M> : never;
+
+/**
+ * Internal options for contract creation
+ */
+export interface CreateContractOptions {
+  client: PolkadotClient;
+  typedApi?: unknown;
+  defaultQueryOptions?: Partial<QueryOptions>;
+  defaultSendOptions?: Partial<SendOptions>;
+}
+
+/**
+ * Type helper to infer the Messages type from an InkDescriptors
+ */
+export type InferMessages<D> =
+  D extends InkDescriptors<
+    InkStorageDescriptor,
+    infer M,
+    InkCallableDescriptor,
+    Event
+  >
+    ? M
+    : never;

package/test/events.test.ts

@@ -0,0 +1,325 @@
+/**
+ * Event parsing and subscription tests
+ */
+import { describe, it, expect, beforeAll, afterAll } from "bun:test";
+import { ss58Decode } from "@polkadot-labs/hdkd-helpers";
+import { contracts, d9, getMetadata } from "@polkadot-api/descriptors";
+import { createClient } from "polkadot-api";
+import { getWsProvider } from "polkadot-api/ws-provider";
+import { withPolkadotSdkCompat } from "polkadot-api/polkadot-sdk-compat";
+import { withLegacy } from "@polkadot-api/legacy-provider";
+import {
+  ContractEventParser,
+  buildEventDecoder,
+  buildAllEventDecoders,
+  getEventSignature,
+  createD9InkSdk,
+} from "../src";
+
+const TEST_ADDRESSES = {
+  testUser: "zcb3U8vYqWLmd5huhyS7nMiMnqDQfWJrmjQcpMhkWmn7krH",
+  usdtContract: "uLj9DRUujbpCyK7USZY5ebGbxdtKoWvdRvGyyUsoLWDsNng",
+};
+
+const ENDPOINT = process.env.TEST_ENDPOINT || "wss://mainnet.d9network.com:40300";
+
+describe("Event Decoder Building", () => {
+  it("should build event decoder for Transfer event from USDT metadata", () => {
+    const metadata = contracts.usdt.metadata!;
+
+    // Build decoder for Transfer event
+    const decoder = buildEventDecoder(metadata, "Transfer");
+
+    expect(decoder).toBeDefined();
+    expect(typeof decoder).toBe("function");
+  });
+
+  it("should build all event decoders from USDT metadata", () => {
+    const metadata = contracts.usdt.metadata!;
+
+    const decoders = buildAllEventDecoders(metadata);
+
+    expect(decoders).toBeDefined();
+    expect(decoders.size).toBeGreaterThan(0);
+
+    // Check that Transfer event decoder exists
+    expect(decoders.has("Transfer")).toBe(true);
+    expect(decoders.has("Approval")).toBe(true);
+  });
+
+  it("should generate consistent event signatures", () => {
+    const sig1 = getEventSignature("Transfer");
+    const sig2 = getEventSignature("Transfer");
+
+    expect(sig1).toBeInstanceOf(Uint8Array);
+    expect(sig1.length).toBe(32); // blake2_256 produces 32 bytes
+    expect(sig1).toEqual(sig2); // Same label should produce same signature
+  });
+
+  it("should generate different signatures for different events", () => {
+    const transferSig = getEventSignature("Transfer");
+    const approvalSig = getEventSignature("Approval");
+
+    expect(transferSig).not.toEqual(approvalSig);
+  });
+});
+
+describe("ContractEventParser", () => {
+  it("should create parser instance", () => {
+    const metadata = contracts.usdt.metadata!;
+    const parser = new ContractEventParser(metadata, TEST_ADDRESSES.usdtContract);
+
+    expect(parser).toBeDefined();
+  });
+
+  it("should parse mock ContractEmitted event", () => {
+    const metadata = contracts.usdt.metadata!;
+    const parser = new ContractEventParser(metadata, TEST_ADDRESSES.usdtContract);
+
+    // Get contract address bytes
+    const [contractBytes] = ss58Decode(TEST_ADDRESSES.usdtContract);
+
+    // Get Transfer event signature
+    const transferSig = getEventSignature("Transfer");
+
+    // Create a mock Transfer event
+    // PSP22 Transfer event structure: { from: Option<AccountId>, to: Option<AccountId>, value: u128 }
+    // For simplicity, we'll test with minimal data
+    const mockEventData = new Uint8Array([
+      0, // from: None (Option discriminator)
+      0, // to: None
+      1,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0,
+      0, // value: 1 (u128 little-endian)
+    ]);
+
+    const mockChainEvent = {
+      event: {
+        type: "Contracts",
+        value: {
+          type: "ContractEmitted",
+          value: {
+            contract: contractBytes,
+            data: mockEventData,
+          },
+        },
+      },
+      topics: [transferSig],
+      blockNumber: 12345,
+      blockHash: "0x0000000000000000000000000000000000000000000000000000000000000000",
+      eventIndex: 0,
+    };
+
+    const parsed = parser.parseEvent(mockChainEvent);
+
+    // Event should be parsed successfully
+    expect(parsed).toBeDefined();
+    if (parsed) {
+      expect(parsed.label).toBe("Transfer");
+      expect(parsed.data).toBeDefined();
+      expect(parsed.raw.blockNumber).toBe(12345);
+      expect(parsed.raw.contractAddress).toBe(TEST_ADDRESSES.usdtContract);
+    }
+  });
+
+  it("should return null for non-Contracts events", () => {
+    const metadata = contracts.usdt.metadata!;
+    const parser = new ContractEventParser(metadata, TEST_ADDRESSES.usdtContract);
+
+    const mockEvent = {
+      event: {
+        type: "Balances", // Different pallet
+        value: {
+          type: "Transfer",
+          value: {},
+        },
+      },
+      topics: [],
+      blockNumber: 12345,
+      blockHash: "0x00",
+      eventIndex: 0,
+    };
+
+    const parsed = parser.parseEvent(mockEvent);
+    expect(parsed).toBeNull();
+  });
+
+  it("should return null for different contract address", () => {
+    const metadata = contracts.usdt.metadata!;
+    const parser = new ContractEventParser(metadata, TEST_ADDRESSES.usdtContract);
+
+    // Different contract address
+    const [differentContract] = ss58Decode(TEST_ADDRESSES.testUser);
+    const transferSig = getEventSignature("Transfer");
+
+    const mockEvent = {
+      event: {
+        type: "Contracts",
+        value: {
+          type: "ContractEmitted",
+          value: {
+            contract: differentContract, // Different contract
+            data: new Uint8Array([0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
+          },
+        },
+      },
+      topics: [transferSig],
+      blockNumber: 12345,
+      blockHash: "0x00",
+      eventIndex: 0,
+    };
+
+    const parsed = parser.parseEvent(mockEvent);
+    expect(parsed).toBeNull(); // Should filter out different contract
+  });
+
+  it("should filter events by label", () => {
+    const metadata = contracts.usdt.metadata!;
+    const parser = new ContractEventParser(metadata, TEST_ADDRESSES.usdtContract);
+
+    const [contractBytes] = ss58Decode(TEST_ADDRESSES.usdtContract);
+    const transferSig = getEventSignature("Transfer");
+
+    const mockTransferEvent1 = {
+      event: {
+        type: "Contracts",
+        value: {
+          type: "ContractEmitted",
+          value: {
+            contract: contractBytes,
+            data: new Uint8Array([0, 0, 1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
+          },
+        },
+      },
+      topics: [transferSig],
+      blockNumber: 100,
+      blockHash: "0x00",
+      eventIndex: 0,
+    };
+
+    const mockTransferEvent2 = {
+      event: {
+        type: "Contracts",
+        value: {
+          type: "ContractEmitted",
+          value: {
+            contract: contractBytes,
+            data: new Uint8Array([0, 0, 10, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0]),
+          },
+        },
+      },
+      topics: [transferSig],
+      blockNumber: 101,
+      blockHash: "0x00",
+      eventIndex: 1,
+    };
+
+    // Non-contract event should be filtered out
+    const mockBalancesEvent = {
+      event: {
+        type: "Balances",
+        value: {
+          type: "Transfer",
+          value: {},
+        },
+      },
+      topics: [],
+      blockNumber: 102,
+      blockHash: "0x00",
+      eventIndex: 2,
+    };
+
+    const filtered = parser.filterEvents(
+      [mockTransferEvent1, mockTransferEvent2, mockBalancesEvent],
+      {
+        eventLabels: ["Transfer"],
+      },
+    );
+
+    expect(filtered.length).toBe(2);
+    expect(filtered[0]?.label).toBe("Transfer");
+    expect(filtered[1]?.label).toBe("Transfer");
+  });
+});
+
+describe.skipIf(!process.env.TEST_CHAIN_INTEGRATION)("Event Subscription Integration", () => {
+  let client: ReturnType<typeof createClient>;
+  let inkSdk: ReturnType<typeof createD9InkSdk>;
+
+  beforeAll(() => {
+    const provider = getWsProvider(ENDPOINT, {
+      innerEnhancer: withLegacy(),
+    });
+
+    client = createClient(withPolkadotSdkCompat(provider), {
+      async getMetadata(codeHash) {
+        const metadata = await getMetadata(codeHash);
+        return metadata ?? null;
+      },
+    });
+
+    const api = client.getTypedApi(d9);
+    inkSdk = createD9InkSdk(client, { typedApi: api });
+  });
+
+  afterAll(() => {
+    client.destroy();
+  });
+
+  it(
+    "should have subscribeToEvents method on contract",
+    () => {
+      const usdtContract = inkSdk.getContract(contracts.usdt, TEST_ADDRESSES.usdtContract);
+
+      expect(usdtContract.subscribeToEvents).toBeDefined();
+      expect(typeof usdtContract.subscribeToEvents).toBe("function");
+    },
+    { timeout: 10000 },
+  );
+
+  it(
+    "should create event subscription observable",
+    () => {
+      const usdtContract = inkSdk.getContract(contracts.usdt, TEST_ADDRESSES.usdtContract);
+
+      const api = client.getTypedApi(d9);
+
+      const subscription = usdtContract.subscribeToEvents({
+        eventLabels: ["Transfer"],
+        getEvents: async (blockHash: string) => {
+          return await api.query.System.Events.getValue({ at: blockHash });
+        },
+      });
+
+      expect(subscription).toBeDefined();
+      expect(typeof subscription.subscribe).toBe("function");
+
+      // Subscribe and immediately unsubscribe
+      const sub = subscription.subscribe({
+        next: (event) => {
+          console.log("Received event:", event);
+        },
+        error: (err) => {
+          console.error("Subscription error:", err);
+        },
+      });
+
+      // Cleanup
+      sub.unsubscribe();
+    },
+    { timeout: 10000 },
+  );
+});