@d9-network/ink 0.0.5 → 0.0.7

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { Binary, PolkadotClient, PolkadotSigner, SS58String } from "polkadot-api";
+import { Binary, Enum, HexString, PolkadotClient, PolkadotSigner, SS58String } from "polkadot-api";
 import { Event, InkCallableDescriptor, InkDescriptors, InkMetadata, InkStorageDescriptor } from "@polkadot-api/ink-contracts";
 import { Bytes } from "@subsquid/scale-codec";
 import * as _polkadot_api_substrate_bindings0 from "@polkadot-api/substrate-bindings";
@@ -104,8 +104,8 @@ declare function isContractError(error: unknown): error is ContractError;
 /**
  * Type guard to check for specific error types
  */
-declare function isErrorType<T extends ContractErrorType>(error: unknown, type: T): error is ContractError & {
-  type: T;
+declare function isErrorType<T$1 extends ContractErrorType>(error: unknown, type: T$1): error is ContractError & {
+  type: T$1;
 };
 //#endregion
 //#region src/event-types.d.ts
@@ -127,13 +127,42 @@ interface RawContractEvent {
   topics: Uint8Array[];
 }
 /**
- * Decoded contract event
+ * Extract the definition object from an Enum type or InkEvent type
+ * e.g. ExtractEnumDef<Enum<{A: X, B: Y}>> = {A: X, B: Y}
+ *
+ * For non-Enum types (e.g., InkEvent { type: string; value: unknown }),
+ * returns a generic event definition.
+ */
+type ExtractEnumDef<E> = E extends Enum<infer T> ? T : E extends Event ? Record<string, unknown> : never;
+/**
+ * Extract event labels as a union type from an Enum type
+ * e.g. ExtractEventLabels<Enum<{Transfer: X, Approval: Y}>> = "Transfer" | "Approval"
+ */
+type ExtractEventLabels<E extends Event> = keyof ExtractEnumDef<E> & string;
+/**
+ * Type-safe contract event with discriminated union
+ * Enables type narrowing: `if (event.type === "Transfer") { event.value.from }`
+ */
+type TypedContractEvent<E extends Event> = E extends Enum<infer T> ? { [K in keyof T & string]: {
+  /** Event type (discriminant for type narrowing) */
+  type: K;
+  /** Decoded event data (type-safe based on event type) */
+  value: T[K];
+  /** Original raw event */
+  raw: RawContractEvent;
+} }[keyof T & string] : {
+  type: string;
+  value: unknown;
+  raw: RawContractEvent;
+};
+/**
+ * Decoded contract event (legacy, use TypedContractEvent for type safety)
  */
-interface DecodedContractEvent<T = unknown> {
+interface DecodedContractEvent<T$1 = unknown> {
   /** Event label from metadata (e.g., "Transfer", "Approval") */
   label: string;
   /** Decoded event data */
-  data: T;
+  data: T$1;
   /** Original raw event */
   raw: RawContractEvent;
 }
@@ -150,6 +179,29 @@ interface EventFilterOptions {
   /** To block number (inclusive) */
   toBlock?: number;
 }
+/**
+ * Type-safe event filter options with literal event labels
+ * Provides compile-time validation of event label names
+ *
+ * @typeParam E - The event type representing all possible events
+ *
+ * @example
+ * ```ts
+ * const options: TypedEventFilterOptions<typeof contracts.usdt.__types.event> = {
+ *   eventLabels: ["Transfer", "Approval"], // Must be valid event names
+ * };
+ * ```
+ */
+interface TypedEventFilterOptions<E extends Event> {
+  /** Contract address to filter by */
+  contractAddress?: SS58String;
+  /** Event labels to include (type-safe) */
+  eventLabels?: Array<ExtractEventLabels<E>>;
+  /** From block number (inclusive) */
+  fromBlock?: number;
+  /** To block number (inclusive) */
+  toBlock?: number;
+}
 /**
  * Event subscription options
  */
@@ -177,6 +229,196 @@ interface EventSubscriptionOptions {
   getEvents: (blockHash: string) => Promise<unknown[]>;
 }
 //#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$1 extends InkCallableDescriptor> = keyof M$1 & string;
+/**
+ * Type-safe parsed contract call with discriminated union
+ * Enables type narrowing: `if (call.type === "PSP22::transfer") { call.args.to }`
+ */
+type TypedContractCall<M$1 extends InkCallableDescriptor> = { [K in keyof M$1 & string]: {
+  /** Call type/method name (discriminant for type narrowing) */
+  type: K;
+  /** Decoded call arguments (type-safe based on method) */
+  args: M$1[K]["message"];
+  /** 4-byte selector */
+  selector: Uint8Array;
+  /** Original raw call data */
+  raw: RawContractCall;
+} }[keyof M$1 & 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$1 extends InkCallableDescriptor> {
+  /** Message labels to include (type-safe) */
+  messageLabels?: Array<ExtractMessageLabels<M$1>>;
+}
+/**
+ * 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/message-builder.d.ts
+/**
+ * Message attributes from metadata
+ */
+interface MessageAttributes {
+  /** Whether the message mutates state */
+  mutates: boolean;
+  /** Whether the message is payable */
+  payable: boolean;
+  /** Whether this is the default message */
+  default: boolean;
+}
+/**
+ * Type-safe message interface with encode/decode methods
+ *
+ * @typeParam M - The InkCallableDescriptor type (message definitions)
+ * @typeParam L - The specific message label
+ */
+interface TypedMessage<M$1 extends InkCallableDescriptor, L extends keyof M$1 & string> {
+  /**
+   * Encode message arguments to Binary
+   *
+   * @param args - The message arguments (fully typed)
+   * @returns Encoded call data as Binary
+   *
+   * @example
+   * ```ts
+   * const transfer = builder.message("PSP22::transfer");
+   * const encoded = transfer.encode({
+   *   to: recipientAddress,
+   *   value: 1000n,
+   *   data: new Uint8Array(),
+   * });
+   * ```
+   */
+  encode: {} extends M$1[L]["message"] ? (args?: M$1[L]["message"]) => Binary : (args: M$1[L]["message"]) => Binary;
+  /**
+   * Decode response to typed value
+   *
+   * @param response - The response data
+   * @returns Decoded response value
+   */
+  decode: (response: Binary | Uint8Array) => M$1[L]["response"];
+  /** Message attributes (mutates, payable, default) */
+  attributes: MessageAttributes;
+  /** 4-byte selector */
+  selector: Uint8Array;
+  /** Message label */
+  label: L;
+}
+/**
+ * Contract message builder interface
+ *
+ * @typeParam M - The InkCallableDescriptor type (message definitions)
+ */
+interface ContractMessageBuilder<M$1 extends InkCallableDescriptor> {
+  /**
+   * Get a type-safe message interface for a specific message
+   *
+   * @param label - The message label (e.g., "PSP22::transfer")
+   * @returns Typed message interface with encode/decode methods
+   *
+   * @example
+   * ```ts
+   * const transfer = builder.message("PSP22::transfer");
+   * const encoded = transfer.encode({ to, value, data });
+   * const decoded = transfer.decode(response);
+   * ```
+   */
+  message<L extends ExtractMessageLabels<M$1>>(label: L): TypedMessage<M$1, L>;
+  /**
+   * Get all available message labels
+   *
+   * @returns Array of message labels
+   */
+  getMessageLabels(): Array<ExtractMessageLabels<M$1>>;
+}
+/**
+ * Create a type-safe message builder from a contract descriptor
+ *
+ * @typeParam S - Storage descriptor type
+ * @typeParam M - Messages descriptor type
+ * @typeParam C - Constructors descriptor type
+ * @typeParam E - Events Enum type
+ * @param descriptor - The ink! contract descriptor containing metadata
+ * @returns A ContractMessageBuilder instance
+ *
+ * @example
+ * ```ts
+ * import { createMessageBuilder } from '@d9-network/ink';
+ * import { contracts } from '@polkadot-api/descriptors';
+ *
+ * const builder = createMessageBuilder(contracts.usdt);
+ *
+ * // Get a typed message interface
+ * const transfer = builder.message("PSP22::transfer");
+ *
+ * // Encode with full type checking on args
+ * const encoded = transfer.encode({
+ *   to: recipientAddress,   // Must be SS58String
+ *   value: 1000000n,        // Must be bigint
+ *   data: new Uint8Array(), // Must be Uint8Array
+ * });
+ *
+ * // Decode response with full type inference
+ * const response = transfer.decode(resultBytes);
+ * ```
+ */
+declare function createMessageBuilder<S extends InkStorageDescriptor, M$1 extends InkCallableDescriptor, C extends InkCallableDescriptor, E extends Enum<any>>(descriptor: InkDescriptors<S, M$1, C, E>): ContractMessageBuilder<M$1>;
+//#endregion
 //#region src/types.d.ts
 /**
  * Decoder type for response decoding
@@ -222,16 +464,16 @@ interface SendOptions<Args = unknown> {
 /**
  * Sendable transaction that can be signed and submitted
  */
-interface SendableTransaction<T> {
+interface SendableTransaction<T$1> {
   /** Sign and submit the transaction */
-  signAndSubmit(signer: PolkadotSigner): Promise<TxResult<T>>;
+  signAndSubmit(signer: PolkadotSigner): Promise<TxResult<T$1>>;
   /** Get the encoded call data */
   getEncodedData(): Uint8Array;
 }
 /**
  * Transaction result
  */
-interface TxResult<T> {
+interface TxResult<T$1> {
   /** Whether the transaction was successful */
   ok: boolean;
   /** Transaction hash */
@@ -242,7 +484,7 @@ interface TxResult<T> {
     number: number;
   };
   /** Decoded return value (if any) */
-  result?: T;
+  result?: T$1;
   /** Events emitted by the transaction */
   events: unknown[];
   /** Dispatch error if failed */
@@ -251,9 +493,9 @@ interface TxResult<T> {
 /**
  * Successful query result value
  */
-interface QuerySuccessValue<T> {
+interface QuerySuccessValue<T$1> {
   /** The decoded response from the contract */
-  value: T;
+  value: T$1;
   /** Events that would be emitted */
   events: unknown[];
   /** Gas consumed during dry-run */
@@ -269,16 +511,16 @@ interface QuerySuccessValue<T> {
   /** Storage deposit required */
   storageDeposit: bigint;
   /** Create a sendable transaction from this query result */
-  send(): SendableTransaction<T>;
+  send(): SendableTransaction<T$1>;
 }
 /**
  * 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
  */
-type QueryResult<T> = ({
+type QueryResult<T$1> = ({
   success: true;
-} & QuerySuccessValue<T>) | {
+} & QuerySuccessValue<T$1>) | {
   success: false;
   error: ContractError;
 };
@@ -306,7 +548,7 @@ interface ContractStorage {
 /**
  * Type helper to extract message args type
  */
-type MessageArgs<M$1 extends InkCallableDescriptor, K extends keyof M$1> = M$1[K]["message"];
+type MessageArgs<M$1 extends InkCallableDescriptor, K$1 extends keyof M$1> = M$1[K$1]["message"];
 /**
  * ink! LangError type pattern
  * papi generates LangError variants with { type: string; value?: unknown }
@@ -319,9 +561,9 @@ type InkLangError = {
  * ink! MessageResult type pattern (Result<T, LangError>)
  * papi generates this as { success: true; value: T } | { success: false; value: LangError }
  */
-type InkMessageResult<T> = {
+type InkMessageResult<T$1> = {
   success: true;
-  value: T;
+  value: T$1;
 } | {
   success: false;
   value: unknown;
@@ -331,15 +573,18 @@ type InkMessageResult<T> = {
  * 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 UnwrapMessageResult<T$1> = T$1 extends InkMessageResult<infer U> ? Exclude<U, InkLangError> : T$1;
 /**
  * Type helper to extract message response type (with MessageResult unwrapped)
  */
-type MessageResponse<M$1 extends InkCallableDescriptor, K extends keyof M$1> = UnwrapMessageResult<M$1[K]["response"]>;
+type MessageResponse<M$1 extends InkCallableDescriptor, K$1 extends keyof M$1> = UnwrapMessageResult<M$1[K$1]["response"]>;
 /**
  * D9 Ink Contract interface
+ *
+ * @typeParam M - The callable descriptor type (message definitions)
+ * @typeParam E - The event type for type-safe event filtering
  */
-interface D9InkContract<M$1 extends InkCallableDescriptor> {
+interface D9InkContract<M$1 extends InkCallableDescriptor, E extends Event = Event> {
   /** Contract address */
   readonly address: SS58String;
   /** Contract metadata */
@@ -349,26 +594,82 @@ interface D9InkContract<M$1 extends InkCallableDescriptor> {
    * @param method - The message label (e.g., "PSP22::balance_of")
    * @param options - Query options including origin and args
    */
-  query<K extends keyof M$1 & string>(method: K, options: QueryOptions<MessageArgs<M$1, K>>): Promise<QueryResult<MessageResponse<M$1, K>>>;
+  query<K$1 extends keyof M$1 & string>(method: K$1, options: QueryOptions<MessageArgs<M$1, K$1>>): Promise<QueryResult<MessageResponse<M$1, K$1>>>;
   /**
    * 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$1 & string>(method: K, options: SendOptions<MessageArgs<M$1, K>>): SendableTransaction<MessageResponse<M$1, K>>;
+  send<K$1 extends keyof M$1 & string>(method: K$1, options: SendOptions<MessageArgs<M$1, K$1>>): SendableTransaction<MessageResponse<M$1, K$1>>;
   /**
    * Get storage query interface
    */
   getStorage(): ContractStorage;
   /**
    * Filter events from a transaction result to only include this contract's events
+   * Returns type-safe events that can be narrowed using `event.type`
+   *
+   * @example
+   * ```ts
+   * const events = contract.filterEvents(txResult.events);
+   * for (const event of events) {
+   *   if (event.type === "Transfer") {
+   *     console.log(event.value.from, event.value.to, event.value.value);
+   *   }
+   * }
+   * ```
    */
-  filterEvents(events: unknown[]): DecodedContractEvent[];
+  filterEvents(events: unknown[]): TypedContractEvent<E>[];
   /**
    * 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>;
+  subscribeToEvents(options?: Omit<EventSubscriptionOptions, "contractAddress">): Observable<TypedContractEvent<E>>;
+  /**
+   * Get a type-safe message builder for a specific message
+   *
+   * Provides a polkadot-api compatible API for encoding and decoding
+   * contract messages with full TypeScript type inference.
+   *
+   * @param label - The message label (e.g., "PSP22::transfer")
+   * @returns Typed message interface with encode/decode methods
+   *
+   * @example
+   * ```ts
+   * const transfer = contract.message("PSP22::transfer");
+   *
+   * // Encode with full type checking on args
+   * const encoded = transfer.encode({
+   *   to: recipientAddress,
+   *   value: 1000000n,
+   *   data: new Uint8Array(),
+   * });
+   *
+   * // Decode response with full type inference
+   * const decoded = transfer.decode(responseBytes);
+   * ```
+   */
+  message<L extends ExtractMessageLabels<M$1>>(label: L): TypedMessage<M$1, L>;
+  /**
+   * Filter events by specific type with proper type narrowing
+   *
+   * @param events - Array of chain events to filter
+   * @param label - The event label to filter by
+   * @returns Array of events narrowed to the specific type
+   *
+   * @example
+   * ```ts
+   * const transfers = contract.filterEventsByType(txResult.events, "Transfer");
+   *
+   * for (const t of transfers) {
+   *   // t.value is fully typed as Transfer event data
+   *   console.log(t.value.from, "->", t.value.to, ":", t.value.value);
+   * }
+   * ```
+   */
+  filterEventsByType<L extends string>(events: unknown[], label: L): Array<TypedContractEvent<E> & {
+    type: L;
+  }>;
 }
 /**
  * D9 Ink SDK options
@@ -388,9 +689,12 @@ interface D9InkSdk {
    * @param descriptor - The contract descriptor from @polkadot-api/descriptors
    * @param address - The contract address (SS58 format)
    */
-  getContract<S extends InkStorageDescriptor, M$1 extends InkCallableDescriptor, C extends InkCallableDescriptor, E extends Event>(descriptor: InkDescriptors<S, M$1, C, E>, address: SS58String): D9InkContract<M$1>;
+  getContract<S extends InkStorageDescriptor, M$1 extends InkCallableDescriptor, C extends InkCallableDescriptor, E extends Event>(descriptor: InkDescriptors<S, M$1, C, E>, address: SS58String): D9InkContract<M$1, E>;
 }
-type D9InkContractFromDescriptor<D> = D extends InkDescriptors<infer _S, infer M, infer _C, infer _E> ? D9InkContract<M> : never;
+/**
+ * Type helper to extract D9InkContract type from an InkDescriptors
+ */
+type D9InkContractFromDescriptor<D> = D extends InkDescriptors<infer _S, infer M, infer _C, infer E> ? D9InkContract<M, E extends Event ? E : Event> : never;
 /**
  * Internal options for contract creation
  */
@@ -403,7 +707,149 @@ interface CreateContractOptions {
 /**
  * Type helper to infer the Messages type from an InkDescriptors
  */
-type InferMessages<D> = D extends InkDescriptors<InkStorageDescriptor, infer M, InkCallableDescriptor, Event> ? M : never;
+type InferMessages<D> = D extends InkDescriptors<InkStorageDescriptor, infer M, InkCallableDescriptor, any> ? M : never;
+/**
+ * Type helper to infer the Events type from an InkDescriptors
+ */
+type InferEvents<D> = D extends InkDescriptors<InkStorageDescriptor, InkCallableDescriptor, InkCallableDescriptor, infer E> ? E extends Event ? E : never : never;
+//#endregion
+//#region src/rpc-types.d.ts
+/**
+ * Block header structure
+ */
+interface BlockHeader {
+  parentHash: HexString;
+  number: HexString;
+  stateRoot: HexString;
+  extrinsicsRoot: HexString;
+  digest: {
+    logs: HexString[];
+  };
+}
+/**
+ * System health information
+ */
+interface SystemHealth {
+  peers: number;
+  isSyncing: boolean;
+  shouldHavePeers: boolean;
+}
+/**
+ * Runtime version information
+ */
+interface RuntimeVersion {
+  specName: string;
+  implName: string;
+  authoringVersion: number;
+  specVersion: number;
+  implVersion: number;
+  apis: [HexString, number][];
+  transactionVersion: number;
+  stateVersion: number;
+}
+/**
+ * Storage change set
+ */
+interface StorageChangeSet {
+  block: HexString;
+  changes: [HexString, HexString | null][];
+}
+/**
+ * RPC method signatures: method name -> [params tuple, return type]
+ *
+ * This interface maps known Substrate RPC methods to their parameter and return types.
+ * Methods not in this list will fall back to unknown types.
+ */
+interface SubstrateRpcMethods {
+  chain_getBlockHash: [[blockNumber?: number], HexString | null];
+  chain_getHeader: [[hash?: HexString], BlockHeader | null];
+  chain_getBlock: [[hash?: HexString], {
+    block: {
+      header: BlockHeader;
+      extrinsics: HexString[];
+    };
+    justifications: unknown;
+  } | null];
+  chain_getFinalizedHead: [[], HexString];
+  state_call: [[method: string, data: HexString, at?: HexString], HexString];
+  state_getStorage: [[key: HexString, at?: HexString], HexString | null];
+  state_getStorageAt: [[key: HexString, at: HexString], HexString | null];
+  state_getStorageHash: [[key: HexString, at?: HexString], HexString | null];
+  state_getStorageSize: [[key: HexString, at?: HexString], number | null];
+  state_getMetadata: [[at?: HexString], HexString];
+  state_getRuntimeVersion: [[at?: HexString], RuntimeVersion];
+  state_queryStorageAt: [[keys: HexString[], at?: HexString], StorageChangeSet[]];
+  system_chain: [[], string];
+  system_name: [[], string];
+  system_version: [[], string];
+  system_health: [[], SystemHealth];
+  system_properties: [[], Record<string, unknown>];
+  system_peers: [[], {
+    peerId: string;
+    roles: string;
+    bestHash: HexString;
+    bestNumber: number;
+  }[]];
+  system_chainType: [[], string];
+  author_submitExtrinsic: [[extrinsic: HexString], HexString];
+  author_pendingExtrinsics: [[], HexString[]];
+  author_removeExtrinsic: [[bytesOrHash: (HexString | {
+    Hash: HexString;
+  })[]], number];
+  payment_queryInfo: [[extrinsic: HexString, at?: HexString], {
+    weight: {
+      refTime: number;
+      proofSize: number;
+    };
+    class: string;
+    partialFee: string;
+  }];
+  payment_queryFeeDetails: [[extrinsic: HexString, at?: HexString], {
+    inclusionFee: {
+      baseFee: string;
+      lenFee: string;
+      adjustedWeightFee: string;
+    } | null;
+  }];
+}
+/**
+ * Known RPC method names (for autocomplete)
+ */
+type KnownRpcMethod = keyof SubstrateRpcMethods;
+/**
+ * Extract parameter types for a known RPC method
+ */
+type RpcParams<M$1 extends KnownRpcMethod> = SubstrateRpcMethods[M$1][0];
+/**
+ * Extract return type for a known RPC method
+ */
+type RpcReturn<M$1 extends KnownRpcMethod> = SubstrateRpcMethods[M$1][1];
+/**
+ * Type-safe RPC request interface
+ *
+ * Provides full type inference for known RPC methods while allowing
+ * arbitrary method calls with explicit type parameters.
+ *
+ * @example
+ * ```ts
+ * // Known method: types are inferred
+ * const hash = await rpc("chain_getBlockHash", [12345]);
+ * // hash: HexString | null
+ *
+ * // Unknown method: provide explicit types
+ * const result = await rpc<MyType>("custom_method", [arg1, arg2]);
+ * ```
+ */
+interface TypedRpcRequest {
+  /**
+   * Call a known RPC method with full type inference
+   */
+  <M$1 extends KnownRpcMethod>(method: M$1, params: RpcParams<M$1>): Promise<RpcReturn<M$1>>;
+  /**
+   * Call an unknown RPC method with explicit type parameters
+   */
+  <Reply = unknown, Params extends unknown[] = unknown[]>(method: string, params: Params): Promise<Reply>;
+}
 //#endregion
 //#region src/sdk.d.ts
 /**
@@ -416,6 +862,28 @@ interface CreateD9InkSdkOptions extends D9InkSdkOptions {
    */
   typedApi?: unknown;
 }
+/**
+ * Extended D9 Ink SDK interface with typed RPC access
+ */
+interface D9InkSdkWithRpc extends D9InkSdk {
+  /**
+   * Type-safe RPC request function
+   *
+   * Provides autocomplete for known Substrate RPC methods and type inference
+   * for parameters and return values.
+   *
+   * @example
+   * ```ts
+   * // Known method with full type inference
+   * const hash = await sdk.rpc("chain_getBlockHash", [12345]);
+   * // hash: HexString | null
+   *
+   * // Custom method with explicit types
+   * const custom = await sdk.rpc<MyType>("custom_method", [arg]);
+   * ```
+   */
+  rpc: TypedRpcRequest;
+}
 /**
  * Create a D9 Ink SDK instance.
  *
@@ -457,15 +925,15 @@ interface CreateD9InkSdkOptions extends D9InkSdkOptions {
  *
  * @param client - The PolkadotClient instance
  * @param options - Optional SDK configuration
- * @returns D9 Ink SDK instance
+ * @returns D9 Ink SDK instance with typed RPC access
  */
-declare function createD9InkSdk(client: PolkadotClient, options?: CreateD9InkSdkOptions): D9InkSdk;
+declare function createD9InkSdk(client: PolkadotClient, options?: CreateD9InkSdkOptions): D9InkSdkWithRpc;
 //#endregion
 //#region src/contract.d.ts
 /**
  * Create a D9 Ink Contract instance
  */
-declare function createD9InkContract<S extends InkStorageDescriptor, M$1 extends InkCallableDescriptor, C extends InkCallableDescriptor, E extends Event>(descriptor: InkDescriptors<S, M$1, C, E>, address: SS58String, options: CreateContractOptions): D9InkContract<M$1>;
+declare function createD9InkContract<S extends InkStorageDescriptor, M$1 extends InkCallableDescriptor, C extends InkCallableDescriptor, E extends Event>(descriptor: InkDescriptors<S, M$1, C, E>, address: SS58String, options: CreateContractOptions): D9InkContract<M$1, E>;
 //#endregion
 //#region src/encode.d.ts
 /**
@@ -603,7 +1071,7 @@ declare function isLangError(data: Uint8Array): boolean;
  * @param codec - The SCALE codec for the inner value type T
  * @returns The decoded value
  */
-declare function decodeInkValue<T>(data: Uint8Array, codec: Codec<T>): T;
+declare function decodeInkValue<T$1>(data: Uint8Array, codec: Codec<T$1>): T$1;
 /**
  * Pre-defined codecs for common types
  */
@@ -663,27 +1131,93 @@ declare function buildAllEventDecoders(metadata: InkMetadata): Map<string, (data
  * @returns Event signature as Uint8Array (32 bytes)
  */
 declare function getEventSignature(eventLabel: string): Uint8Array;
+/**
+ * Create ASCII-encoded event topic (D9 chain format)
+ *
+ * D9 chain uses a format where:
+ * - First byte is 0x00 (null)
+ * - Remaining 31 bytes are ASCII characters of `ContractName::EventLabel`
+ * - Total is exactly 32 bytes (truncated/padded as needed)
+ *
+ * @param contractName - Contract name (e.g., "MarketMaker", "Usdt")
+ * @param eventLabel - Event label (e.g., "Transfer", "USDTToD9Conversion")
+ * @returns 32-byte topic with null prefix and ASCII-encoded path
+ */
+declare function createAsciiEventTopic(contractName: string, eventLabel: string): Uint8Array;
 //#endregion
 //#region src/events.d.ts
 /**
- * Event parser for a specific contract
+ * Type-safe event parser for a specific contract
+ *
+ * @typeParam S - The storage descriptor type
+ * @typeParam M - The messages descriptor type
+ * @typeParam C - The constructors descriptor type
+ * @typeParam E - The event type representing all possible events for this contract
  */
-declare class ContractEventParser {
+declare class ContractEventParser<S extends InkStorageDescriptor = InkStorageDescriptor, M$1 extends InkCallableDescriptor = InkCallableDescriptor, C extends InkCallableDescriptor = InkCallableDescriptor, E extends Event = Event> {
   private eventDecoders;
   private eventSignatures;
   private contractAddressBytes;
   private contractAddress;
   private metadata;
-  constructor(metadata: InkMetadata, contractAddress: SS58String);
+  constructor(descriptor: InkDescriptors<S, M$1, C, E>, contractAddress: SS58String);
   /**
-   * Parse a raw chain event into a contract event (if it matches)
+   * Parse a raw chain event into a type-safe contract event (if it matches)
    * Returns null if the event is not from this contract or cannot be parsed
+   *
+   * @example
+   * ```ts
+   * const event = parser.parseEvent(chainEvent);
+   * if (event?.type === "Transfer") {
+   *   // event.value is now typed as { from: SS58String; to: SS58String; value: bigint }
+   *   console.log(event.value.from);
+   * }
+   * ```
+   */
+  parseEvent(chainEvent: unknown): TypedContractEvent<E> | null;
+  /**
+   * Extract event label from ASCII-encoded topic (D9 chain format)
+   *
+   * D9 chain uses a format where:
+   * - First byte is 0x00 (null)
+   * - Remaining 31 bytes are ASCII characters of `ContractName::EventLabel`
+   * - Total is exactly 32 bytes (truncated/padded as needed)
+   *
+   * @param topic - The 32-byte topic from the event
+   * @returns The extracted event label, or null if not in ASCII format
    */
-  parseEvent(chainEvent: unknown): DecodedContractEvent | null;
+  private extractEventLabelFromAsciiTopic;
   /**
-   * Filter a batch of events
+   * Filter a batch of events and return type-safe results
+   *
+   * @param chainEvents - Array of chain events to filter
+   * @param options - Optional filter criteria
+   * @returns Array of type-safe contract events
+   */
+  filterEvents(chainEvents: unknown[], options?: EventFilterOptions): TypedContractEvent<E>[];
+  /**
+   * Filter events by specific type with proper type narrowing
+   *
+   * This method provides better type safety than filterEvents with eventLabels
+   * because TypeScript can narrow the return type to only the specified event type.
+   *
+   * @param chainEvents - Array of chain events to filter
+   * @param label - The event label to filter by
+   * @returns Array of events narrowed to the specific type
+   *
+   * @example
+   * ```ts
+   * const transfers = parser.filterByType(events, "Transfer");
+   *
+   * for (const t of transfers) {
+   *   // t.value is fully typed as Transfer event data
+   *   console.log(t.value.from, "->", t.value.to, ":", t.value.value);
+   * }
+   * ```
    */
-  filterEvents(chainEvents: unknown[], options?: EventFilterOptions): DecodedContractEvent[];
+  filterByType<L extends string>(chainEvents: unknown[], label: L): Array<TypedContractEvent<E> & {
+    type: L;
+  }>;
   /**
    * Get the contract address as SS58 string
    */
@@ -697,37 +1231,76 @@ declare class ContractEventParser {
    * Compare two Uint8Arrays for equality
    */
   private bytesEqual;
-  /**
-   * Build event signature map from metadata
-   */
-  private static buildEventSignatureMap;
 }
+/**
+ * Type guard for narrowing event types
+ *
+ * Use this function when you have a `TypedContractEvent` and need to
+ * narrow it to a specific event type. This is useful when the type
+ * information is lost (e.g., after serialization or in generic functions).
+ *
+ * @typeParam E - The Enum type representing all possible events
+ * @typeParam L - The specific event label to check
+ * @param event - The event to check
+ * @param label - The event label to match
+ * @returns True if the event type matches the label
+ *
+ * @example
+ * ```ts
+ * const event = parser.parseEvent(chainEvent);
+ *
+ * if (event && isEventType(event, "Transfer")) {
+ *   // TypeScript knows event.value is Transfer event data
+ *   console.log(event.value.from);
+ *   console.log(event.value.to);
+ *   console.log(event.value.value);
+ * }
+ * ```
+ */
+declare function isEventType<E extends Event, L extends ExtractEventLabels<E>>(event: TypedContractEvent<E>, label: L): event is Extract<TypedContractEvent<E>, {
+  type: L;
+}>;
 //#endregion
 //#region src/subscriptions.d.ts
 /**
  * Create an observable stream of contract events
  *
  * @param client - Polkadot API client
- * @param metadata - Contract metadata
+ * @param descriptor - Contract descriptor
  * @param options - Subscription options
- * @returns Observable stream of decoded contract events
+ * @returns Observable stream of type-safe contract events
  */
-declare function createContractEventStream(client: PolkadotClient, metadata: InkMetadata, options: EventSubscriptionOptions): Observable<DecodedContractEvent>;
+declare function createContractEventStream<S extends InkStorageDescriptor = InkStorageDescriptor, M$1 extends InkCallableDescriptor = InkCallableDescriptor, C extends InkCallableDescriptor = InkCallableDescriptor, E extends Event = Event>(client: PolkadotClient, descriptor: InkDescriptors<S, M$1, C, E>, options: EventSubscriptionOptions): Observable<TypedContractEvent<E>>;
+/**
+ * PSP22 Transfer event type
+ */
+interface PSP22TransferEvent {
+  type: "Transfer";
+  value: {
+    from?: SS58String | null;
+    to?: SS58String | null;
+    value: bigint;
+  };
+  raw: {
+    blockNumber: number;
+    blockHash: string;
+    eventIndex: number;
+    contractAddress: SS58String;
+    data: Uint8Array;
+    topics: Uint8Array[];
+  };
+}
 /**
  * Convenience helper to create a Transfer event stream for PSP22 tokens
  *
  * @param client - Polkadot API client
- * @param metadata - PSP22 contract metadata
+ * @param descriptor - PSP22 contract descriptor
  * @param contractAddress - PSP22 contract address
  * @param getEvents - Function to fetch System.Events at a block hash
  * @param watchAddress - Optional address to filter transfers (only events involving this address)
  * @returns Observable stream of Transfer events
  */
-declare function createPSP22TransferStream(client: PolkadotClient, metadata: InkMetadata, contractAddress: SS58String, getEvents: (blockHash: string) => Promise<unknown[]>, watchAddress?: SS58String): Observable<DecodedContractEvent<{
-  from?: SS58String | null;
-  to?: SS58String | null;
-  value: bigint;
-}>>;
+declare function createPSP22TransferStream<S extends InkStorageDescriptor = InkStorageDescriptor, M$1 extends InkCallableDescriptor = InkCallableDescriptor, C extends InkCallableDescriptor = InkCallableDescriptor, E extends Event = Event>(client: PolkadotClient, descriptor: InkDescriptors<S, M$1, C, E>, contractAddress: SS58String, getEvents: (blockHash: string) => Promise<unknown[]>, watchAddress?: SS58String): Observable<PSP22TransferEvent>;
 /**
  * Create a native token (D9) transfer event stream
  *
@@ -746,5 +1319,241 @@ declare function createNativeTransferStream(client: PolkadotClient, getEvents: (
   blockHash: string;
 }>;
 //#endregion
-export { AbortedError, type ContractCallResult, ContractError, type ContractErrorType, ContractEventParser, ContractExecutionError, type ContractStorage, type CreateContractOptions, type CreateD9InkSdkOptions, type D9InkContract, type D9InkContractFromDescriptor, type D9InkSdk, type D9InkSdkOptions, DecodeError, type DecodedContractEvent, EncodeError, type EventFilterOptions, type EventSubscriptionOptions, type GasInfo, type InferMessages, InkCodecs, LangError, MetadataError, NetworkError, type QueryOptions, type QueryResult, type QuerySuccessValue, type RawContractEvent, type ResponseDecoder, type SendOptions, type SendableTransaction, SignerError, type StorageDepositInfo, TimeoutError, TransactionError, type TxResult, buildAllEventDecoders, buildAllMessageDecoders, buildEventDecoder, buildMessageDecoder, createCodecRegistry, createContractEventStream, createD9InkContract, createD9InkSdk, createNativeTransferStream, createPSP22TransferStream, decodeContractCallResult, decodeInkValue, decodeResult, encodeCall, encodeContractCall, encodeContractCallWithLimits, getEventSignature, isContractError, isErrorType, isLangError, unwrapInkResult };
+//#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$1 extends InkCallableDescriptor = InkCallableDescriptor, C extends InkCallableDescriptor = InkCallableDescriptor, E extends Event = Event> {
+  private messageDecoders;
+  private selectorToLabel;
+  private metadata;
+  constructor(descriptor: InkDescriptors<S, M$1, 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$1> | 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$1>[];
+  /**
+   * 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$1> & {
+    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;
+}
+/**
+ * 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$1 extends InkCallableDescriptor, L extends ExtractMessageLabels<M$1>>(call: TypedContractCall<M$1>, label: L): call is Extract<TypedContractCall<M$1>, {
+  type: L;
+}>;
+//#endregion
+//#region src/rpc.d.ts
+/**
+ * Create a type-safe RPC request function from a PolkadotClient
+ *
+ * This wraps the client's `_request` method with proper TypeScript types,
+ * providing autocomplete for known RPC methods and type inference for
+ * parameters and return values.
+ *
+ * @param client - The PolkadotClient instance
+ * @returns A type-safe RPC request function
+ *
+ * @example
+ * ```ts
+ * const rpc = createTypedRpc(client);
+ *
+ * // Autocomplete for method names, typed params and return
+ * const hash = await rpc("chain_getBlockHash", [12345]);
+ * // hash: HexString | null
+ *
+ * const header = await rpc("chain_getHeader", [hash]);
+ * // header: BlockHeader | null
+ *
+ * // Custom methods still work with explicit types
+ * const custom = await rpc<MyType>("my_custom_method", [arg]);
+ * ```
+ */
+declare function createTypedRpc(client: PolkadotClient): TypedRpcRequest;
+//#endregion
+//#region src/utils/fees.d.ts
+/**
+ * Gas weight representation
+ */
+interface GasWeight {
+  refTime: bigint;
+  proofSize: bigint;
+}
+/**
+ * Estimated transaction cost breakdown
+ */
+interface EstimatedCost {
+  /** Cost from gas consumption */
+  gasCost: bigint;
+  /** Storage deposit (may be refunded) */
+  storageDeposit: bigint;
+  /** Total estimated cost (gas + storage) */
+  total: bigint;
+}
+/**
+ * Formatted gas information for display
+ */
+interface FormattedGasInfo {
+  /** Human-readable ref_time */
+  refTime: string;
+  /** Human-readable proof_size */
+  proofSize: string;
+}
+/**
+ * Estimate the transaction cost from gas info and storage deposit
+ *
+ * Note: This is an approximation. Actual fees depend on chain configuration
+ * and may vary slightly.
+ *
+ * @param gasInfo - Gas information from contract query
+ * @param storageDeposit - Storage deposit amount (positive for charge, negative for refund)
+ * @returns Estimated cost breakdown
+ *
+ * @example
+ * ```typescript
+ * const result = await contract.query("PSP22::transfer", { origin, args });
+ * if (result.success) {
+ *   const cost = estimateTransactionCost(
+ *     { gasConsumed: result.gasConsumed, gasRequired: result.gasRequired },
+ *     result.storageDeposit
+ *   );
+ *   console.log(`Estimated cost: ${formatBalance(cost.total, { decimals: 12 })} D9`);
+ * }
+ * ```
+ */
+declare function estimateTransactionCost(gasInfo: GasInfo, storageDeposit: bigint): EstimatedCost;
+/**
+ * Format gas information for human-readable display
+ *
+ * @param gasInfo - Gas information from contract query
+ * @returns Formatted strings for ref_time and proof_size
+ *
+ * @example
+ * ```typescript
+ * const formatted = formatGasInfo(result.gasRequired);
+ * console.log(`Gas: refTime=${formatted.refTime}, proofSize=${formatted.proofSize}`);
+ * ```
+ */
+declare function formatGasInfo(gasInfo: GasInfo["gasRequired"]): FormattedGasInfo;
+/**
+ * Apply a safety margin to gas limits
+ *
+ * It's recommended to add a small margin to gas estimates to account for
+ * slight variations in execution. 10% (multiplier = 1.1) is a common choice.
+ *
+ * @param gas - The gas weight to adjust
+ * @param multiplier - The multiplier to apply (default: 1.1 for 10% margin)
+ * @returns Adjusted gas weight with margin applied
+ *
+ * @example
+ * ```typescript
+ * const result = await contract.query("PSP22::transfer", { origin, args });
+ * if (result.success) {
+ *   // Add 10% safety margin
+ *   const safeGas = applyGasMargin(result.gasRequired, 1.1);
+ *   await contract.send("PSP22::transfer", {
+ *     origin,
+ *     args,
+ *     gasLimit: safeGas,
+ *   });
+ * }
+ * ```
+ */
+declare function applyGasMargin(gas: GasWeight, multiplier?: number): GasWeight;
+/**
+ * Compare two gas weights
+ *
+ * @param a - First gas weight
+ * @param b - Second gas weight
+ * @returns -1 if a < b, 0 if equal, 1 if a > b (compares refTime first, then proofSize)
+ */
+declare function compareGasWeight(a: GasWeight, b: GasWeight): -1 | 0 | 1;
+/**
+ * Check if gas weight exceeds a limit
+ *
+ * @param gas - The gas to check
+ * @param limit - The limit to compare against
+ * @returns True if gas exceeds the limit in either dimension
+ */
+declare function gasExceedsLimit(gas: GasWeight, limit: GasWeight): boolean;
+//#endregion
+export { AbortedError, type BlockHeader, type CallFilterOptions, ContractCallParser, type ContractCallResult, ContractError, type ContractErrorType, ContractEventParser, ContractExecutionError, type ContractMessageBuilder, type ContractStorage, type CreateContractOptions, type CreateD9InkSdkOptions, type D9InkContract, type D9InkContractFromDescriptor, type D9InkSdk, type D9InkSdkOptions, type D9InkSdkWithRpc, DecodeError, type DecodedContractEvent, EncodeError, EstimatedCost, type EventFilterOptions, type EventSubscriptionOptions, type ExtractEnumDef, type ExtractEventLabels, type ExtractMessageLabels, FormattedGasInfo, type GasInfo, GasWeight, type InferEvents, type InferMessages, InkCodecs, type KnownRpcMethod, LangError, type MessageAttributes, type MessageInfo, MetadataError, NetworkError, type QueryOptions, type QueryResult, type QuerySuccessValue, type RawContractCall, type RawContractEvent, type ResponseDecoder, type RpcParams, type RpcReturn, type RuntimeVersion, type SendOptions, type SendableTransaction, SignerError, type StorageChangeSet, type StorageDepositInfo, type SubstrateRpcMethods, type SystemHealth, TimeoutError, TransactionError, type TxResult, type TypedCallFilterOptions, type TypedContractCall, type TypedContractEvent, type TypedEventFilterOptions, type TypedMessage, type TypedRpcRequest, applyGasMargin, buildAllEventDecoders, buildAllMessageDecoders, buildEventDecoder, buildMessageDecoder, compareGasWeight, createAsciiEventTopic, createCodecRegistry, createContractEventStream, createD9InkContract, createD9InkSdk, createMessageBuilder, createNativeTransferStream, createPSP22TransferStream, createTypedRpc, decodeContractCallResult, decodeInkValue, decodeResult, encodeCall, encodeContractCall, encodeContractCallWithLimits, estimateTransactionCost, formatGasInfo, gasExceedsLimit, getEventSignature, isCallType, isContractError, isErrorType, isEventType, isLangError, unwrapInkResult };
 //# sourceMappingURL=index.d.mts.map