@opendatalabs/vana-sdk 0.1.0-alpha.ffe4659 → 2.1.0

package/dist/types/atomicStore.d.ts

@@ -0,0 +1,236 @@
+/**
+ * Atomic storage primitives for distributed state management.
+ *
+ * @module
+ */
+/**
+ * Interface for atomic storage operations required by the SDK's distributed components.
+ *
+ * @remarks
+ * Implementations of this interface MUST guarantee atomicity for all operations.
+ * These primitives are used by the SDK's internal components to coordinate
+ * distributed state in multi-instance deployments (e.g., serverless functions).
+ *
+ * The SDK provides a reference Redis implementation, but you can implement
+ * this interface using any storage backend that supports atomic operations:
+ * - PostgreSQL with advisory locks
+ * - DynamoDB with conditional writes
+ * - MongoDB with findAndModify
+ * - Zookeeper or etcd for coordination
+ *
+ * @example
+ * ```typescript
+ * // Using the Redis reference implementation
+ * import { RedisAtomicStore } from './lib/redisAtomicStore';
+ *
+ * const atomicStore = new RedisAtomicStore({
+ *   redis: process.env.REDIS_URL
+ * });
+ *
+ * const vana = Vana({
+ *   privateKey: process.env.RELAYER_PRIVATE_KEY,
+ *   atomicStore
+ * });
+ * ```
+ *
+ * @category Storage
+ */
+export interface IAtomicStore {
+    /**
+     * Atomically increments a counter and returns the new value.
+     *
+     * @remarks
+     * This operation MUST be atomic. If the key doesn't exist, it should be
+     * initialized to 0 before incrementing. The operation must return the
+     * value after incrementing.
+     *
+     * This is used primarily for nonce assignment where atomicity is critical
+     * to prevent conflicts under concurrent load.
+     *
+     * @param key - The key to increment
+     * @returns The new value after incrementing
+     *
+     * @example
+     * ```typescript
+     * // First call returns 1
+     * const nonce1 = await store.incr('nonce:0x123:1480');
+     * // Second call returns 2
+     * const nonce2 = await store.incr('nonce:0x123:1480');
+     * ```
+     */
+    incr(key: string): Promise<number>;
+    /**
+     * Attempts to acquire a distributed lock with automatic expiration.
+     *
+     * @remarks
+     * This operation MUST be atomic and follow the "SET NX EX" semantics:
+     * - Only succeeds if the lock doesn't exist (NX - "Not eXists")
+     * - Automatically expires after the specified TTL (EX - "EXpire")
+     * - Returns a unique lock ID on success for safe release
+     *
+     * The lock ID should be a unique value (e.g., UUID or timestamp+random)
+     * that prevents accidental release by other processes.
+     *
+     * @param key - The lock key
+     * @param ttlSeconds - Time-to-live in seconds (automatic expiration)
+     * @returns A unique lock ID if acquired, null if lock is already held
+     *
+     * @example
+     * ```typescript
+     * const lockId = await store.acquireLock('nonce:lock:0x123', 5);
+     * if (lockId) {
+     *   try {
+     *     // Critical section - only one process can be here
+     *     await performCriticalOperation();
+     *   } finally {
+     *     await store.releaseLock('nonce:lock:0x123', lockId);
+     *   }
+     * }
+     * ```
+     */
+    acquireLock(key: string, ttlSeconds: number): Promise<string | null>;
+    /**
+     * Releases a previously acquired lock.
+     *
+     * @remarks
+     * This operation MUST be atomic and safe. It should only succeed if the
+     * provided lockId matches the current lock value. This prevents accidental
+     * release of locks acquired by other processes.
+     *
+     * Implementations should use compare-and-delete semantics or a Lua script
+     * (in Redis) to ensure atomicity.
+     *
+     * @param key - The lock key
+     * @param lockId - The unique ID returned by acquireLock
+     *
+     * @example
+     * ```typescript
+     * const lockId = await store.acquireLock('lock:key', 5);
+     * if (lockId) {
+     *   // ... do work ...
+     *   await store.releaseLock('lock:key', lockId);
+     * }
+     * ```
+     */
+    releaseLock(key: string, lockId: string): Promise<void>;
+    /**
+     * Gets the value associated with a key.
+     *
+     * @remarks
+     * This is a simple read operation. It should return null if the key
+     * doesn't exist.
+     *
+     * @param key - The key to retrieve
+     * @returns The stored value, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const lastUsedNonce = await store.get('lastNonce:0x123:1480');
+     * ```
+     */
+    get(key: string): Promise<string | null>;
+    /**
+     * Sets a key-value pair.
+     *
+     * @remarks
+     * This is a simple write operation. It should overwrite any existing value.
+     *
+     * @param key - The key to set
+     * @param value - The value to store
+     *
+     * @example
+     * ```typescript
+     * await store.set('lastNonce:0x123:1480', '42');
+     * ```
+     */
+    set(key: string, value: string): Promise<void>;
+    /**
+     * Sets a key-value pair with expiration.
+     *
+     * @remarks
+     * This operation sets a value with automatic expiration after the specified TTL.
+     * Useful for temporary state that should be automatically cleaned up.
+     *
+     * @param key - The key to set
+     * @param value - The value to store
+     * @param ttlSeconds - Time-to-live in seconds
+     *
+     * @example
+     * ```typescript
+     * // Store operation state for 24 hours
+     * await store.setWithTTL('operation:123', JSON.stringify(state), 86400);
+     * ```
+     */
+    setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;
+    /**
+     * Deletes a key.
+     *
+     * @remarks
+     * This operation removes a key from storage. Should be idempotent
+     * (no error if key doesn't exist).
+     *
+     * @param key - The key to delete
+     *
+     * @example
+     * ```typescript
+     * await store.delete('temp:data:123');
+     * ```
+     */
+    delete?(key: string): Promise<void>;
+    /**
+     * Executes an atomic script (e.g., Lua in Redis, stored procedure in SQL).
+     *
+     * @remarks
+     * This is an optional method that allows execution of atomic scripts
+     * for complex operations that require multiple steps to be atomic.
+     * Not all stores support this - simple stores may omit it.
+     *
+     * For Redis: executes a Lua script
+     * For PostgreSQL: executes a stored procedure or CTE
+     * For DynamoDB: might use TransactWrite
+     *
+     * @param script - The script to execute
+     * @param keys - Array of keys the script will operate on
+     * @param args - Array of arguments to pass to the script
+     * @returns The script's return value
+     *
+     * @example
+     * ```typescript
+     * const result = await store.eval(
+     *   'return redis.call("INCR", KEYS[1])',
+     *   ['counter:users'],
+     *   []
+     * );
+     * ```
+     */
+    eval?(script: string, keys: string[], args: string[]): Promise<any>;
+}
+/**
+ * Extended atomic store interface with nonce support.
+ *
+ * @remarks
+ * Some atomic stores (like Redis) provide optimized atomic nonce assignment
+ * through native scripting capabilities. This interface extends the base
+ * IAtomicStore with this optional optimization.
+ *
+ * @internal
+ */
+export interface IAtomicStoreWithNonceSupport extends IAtomicStore {
+    /**
+     * Atomically assigns a nonce with gap prevention.
+     *
+     * @param key - The storage key for the last used nonce
+     * @param pendingCount - The current pending transaction count from blockchain
+     * @returns The assigned nonce
+     */
+    atomicAssignNonce(key: string, pendingCount: number): Promise<number>;
+}
+/**
+ * Type guard to check if an atomic store supports optimized nonce assignment.
+ *
+ * @param store - The atomic store to check
+ * @returns True if the store supports atomicAssignNonce
+ *
+ * @internal
+ */
+export declare function hasNonceSupport(store: IAtomicStore): store is IAtomicStoreWithNonceSupport;

package/dist/types/atomicStore.js

@@ -0,0 +1,7 @@
+function hasNonceSupport(store) {
+  return "atomicAssignNonce" in store && typeof store.atomicAssignNonce === "function";
+}
+export {
+  hasNonceSupport
+};
+//# sourceMappingURL=atomicStore.js.map

package/dist/types/atomicStore.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/atomicStore.ts"],"sourcesContent":["/**\n * Atomic storage primitives for distributed state management.\n *\n * @module\n */\n\n/**\n * Interface for atomic storage operations required by the SDK's distributed components.\n *\n * @remarks\n * Implementations of this interface MUST guarantee atomicity for all operations.\n * These primitives are used by the SDK's internal components to coordinate\n * distributed state in multi-instance deployments (e.g., serverless functions).\n *\n * The SDK provides a reference Redis implementation, but you can implement\n * this interface using any storage backend that supports atomic operations:\n * - PostgreSQL with advisory locks\n * - DynamoDB with conditional writes\n * - MongoDB with findAndModify\n * - Zookeeper or etcd for coordination\n *\n * @example\n * ```typescript\n * // Using the Redis reference implementation\n * import { RedisAtomicStore } from './lib/redisAtomicStore';\n *\n * const atomicStore = new RedisAtomicStore({\n *   redis: process.env.REDIS_URL\n * });\n *\n * const vana = Vana({\n *   privateKey: process.env.RELAYER_PRIVATE_KEY,\n *   atomicStore\n * });\n * ```\n *\n * @category Storage\n */\nexport interface IAtomicStore {\n  /**\n   * Atomically increments a counter and returns the new value.\n   *\n   * @remarks\n   * This operation MUST be atomic. If the key doesn't exist, it should be\n   * initialized to 0 before incrementing. The operation must return the\n   * value after incrementing.\n   *\n   * This is used primarily for nonce assignment where atomicity is critical\n   * to prevent conflicts under concurrent load.\n   *\n   * @param key - The key to increment\n   * @returns The new value after incrementing\n   *\n   * @example\n   * ```typescript\n   * // First call returns 1\n   * const nonce1 = await store.incr('nonce:0x123:1480');\n   * // Second call returns 2\n   * const nonce2 = await store.incr('nonce:0x123:1480');\n   * ```\n   */\n  incr(key: string): Promise<number>;\n\n  /**\n   * Attempts to acquire a distributed lock with automatic expiration.\n   *\n   * @remarks\n   * This operation MUST be atomic and follow the \"SET NX EX\" semantics:\n   * - Only succeeds if the lock doesn't exist (NX - \"Not eXists\")\n   * - Automatically expires after the specified TTL (EX - \"EXpire\")\n   * - Returns a unique lock ID on success for safe release\n   *\n   * The lock ID should be a unique value (e.g., UUID or timestamp+random)\n   * that prevents accidental release by other processes.\n   *\n   * @param key - The lock key\n   * @param ttlSeconds - Time-to-live in seconds (automatic expiration)\n   * @returns A unique lock ID if acquired, null if lock is already held\n   *\n   * @example\n   * ```typescript\n   * const lockId = await store.acquireLock('nonce:lock:0x123', 5);\n   * if (lockId) {\n   *   try {\n   *     // Critical section - only one process can be here\n   *     await performCriticalOperation();\n   *   } finally {\n   *     await store.releaseLock('nonce:lock:0x123', lockId);\n   *   }\n   * }\n   * ```\n   */\n  acquireLock(key: string, ttlSeconds: number): Promise<string | null>;\n\n  /**\n   * Releases a previously acquired lock.\n   *\n   * @remarks\n   * This operation MUST be atomic and safe. It should only succeed if the\n   * provided lockId matches the current lock value. This prevents accidental\n   * release of locks acquired by other processes.\n   *\n   * Implementations should use compare-and-delete semantics or a Lua script\n   * (in Redis) to ensure atomicity.\n   *\n   * @param key - The lock key\n   * @param lockId - The unique ID returned by acquireLock\n   *\n   * @example\n   * ```typescript\n   * const lockId = await store.acquireLock('lock:key', 5);\n   * if (lockId) {\n   *   // ... do work ...\n   *   await store.releaseLock('lock:key', lockId);\n   * }\n   * ```\n   */\n  releaseLock(key: string, lockId: string): Promise<void>;\n\n  /**\n   * Gets the value associated with a key.\n   *\n   * @remarks\n   * This is a simple read operation. It should return null if the key\n   * doesn't exist.\n   *\n   * @param key - The key to retrieve\n   * @returns The stored value, or null if not found\n   *\n   * @example\n   * ```typescript\n   * const lastUsedNonce = await store.get('lastNonce:0x123:1480');\n   * ```\n   */\n  get(key: string): Promise<string | null>;\n\n  /**\n   * Sets a key-value pair.\n   *\n   * @remarks\n   * This is a simple write operation. It should overwrite any existing value.\n   *\n   * @param key - The key to set\n   * @param value - The value to store\n   *\n   * @example\n   * ```typescript\n   * await store.set('lastNonce:0x123:1480', '42');\n   * ```\n   */\n  set(key: string, value: string): Promise<void>;\n\n  /**\n   * Sets a key-value pair with expiration.\n   *\n   * @remarks\n   * This operation sets a value with automatic expiration after the specified TTL.\n   * Useful for temporary state that should be automatically cleaned up.\n   *\n   * @param key - The key to set\n   * @param value - The value to store\n   * @param ttlSeconds - Time-to-live in seconds\n   *\n   * @example\n   * ```typescript\n   * // Store operation state for 24 hours\n   * await store.setWithTTL('operation:123', JSON.stringify(state), 86400);\n   * ```\n   */\n  setWithTTL?(key: string, value: string, ttlSeconds: number): Promise<void>;\n\n  /**\n   * Deletes a key.\n   *\n   * @remarks\n   * This operation removes a key from storage. Should be idempotent\n   * (no error if key doesn't exist).\n   *\n   * @param key - The key to delete\n   *\n   * @example\n   * ```typescript\n   * await store.delete('temp:data:123');\n   * ```\n   */\n  delete?(key: string): Promise<void>;\n\n  /**\n   * Executes an atomic script (e.g., Lua in Redis, stored procedure in SQL).\n   *\n   * @remarks\n   * This is an optional method that allows execution of atomic scripts\n   * for complex operations that require multiple steps to be atomic.\n   * Not all stores support this - simple stores may omit it.\n   *\n   * For Redis: executes a Lua script\n   * For PostgreSQL: executes a stored procedure or CTE\n   * For DynamoDB: might use TransactWrite\n   *\n   * @param script - The script to execute\n   * @param keys - Array of keys the script will operate on\n   * @param args - Array of arguments to pass to the script\n   * @returns The script's return value\n   *\n   * @example\n   * ```typescript\n   * const result = await store.eval(\n   *   'return redis.call(\"INCR\", KEYS[1])',\n   *   ['counter:users'],\n   *   []\n   * );\n   * ```\n   */\n  eval?(script: string, keys: string[], args: string[]): Promise<any>;\n}\n\n/**\n * Extended atomic store interface with nonce support.\n *\n * @remarks\n * Some atomic stores (like Redis) provide optimized atomic nonce assignment\n * through native scripting capabilities. This interface extends the base\n * IAtomicStore with this optional optimization.\n *\n * @internal\n */\nexport interface IAtomicStoreWithNonceSupport extends IAtomicStore {\n  /**\n   * Atomically assigns a nonce with gap prevention.\n   *\n   * @param key - The storage key for the last used nonce\n   * @param pendingCount - The current pending transaction count from blockchain\n   * @returns The assigned nonce\n   */\n  atomicAssignNonce(key: string, pendingCount: number): Promise<number>;\n}\n\n/**\n * Type guard to check if an atomic store supports optimized nonce assignment.\n *\n * @param store - The atomic store to check\n * @returns True if the store supports atomicAssignNonce\n *\n * @internal\n */\nexport function hasNonceSupport(\n  store: IAtomicStore,\n): store is IAtomicStoreWithNonceSupport {\n  return (\n    \"atomicAssignNonce\" in store &&\n    typeof (store as IAtomicStoreWithNonceSupport).atomicAssignNonce ===\n      \"function\"\n  );\n}\n"],"mappings":"AAqPO,SAAS,gBACd,OACuC;AACvC,SACE,uBAAuB,SACvB,OAAQ,MAAuC,sBAC7C;AAEN;","names":[]}

package/dist/types/blockchain.cjs

@@ -0,0 +1,17 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var blockchain_exports = {};
+module.exports = __toCommonJS(blockchain_exports);
+//# sourceMappingURL=blockchain.cjs.map

package/dist/types/blockchain.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/blockchain.ts"],"sourcesContent":["/**\n * Defines core blockchain interaction types.\n *\n * @remarks\n * This module provides fundamental types for blockchain transactions,\n * including transaction requests, confirmation options, and results.\n * These types form the basis for all blockchain interactions in the SDK.\n *\n * @category Types\n * @module types/blockchain\n */\n\nimport type { Hash, Address } from \"viem\";\n\n/**\n * Represents a submitted blockchain transaction awaiting confirmation.\n *\n * @remarks\n * Returned immediately after transaction submission, before confirmation.\n * Use `waitForTransactionEvents` to wait for confirmation and retrieve events.\n *\n * @category Blockchain\n */\nexport interface TransactionRequest {\n  /** Transaction hash */\n  hash: Hash;\n  /** Account that initiated the transaction */\n  from: Address;\n  /** Contract that was called */\n  contractName: string;\n  /** Function that was called */\n  functionName: string;\n  /** Function arguments (for debugging/logging) */\n  args?: readonly unknown[];\n}\n\n/**\n * Configures transaction confirmation waiting behavior.\n *\n * @remarks\n * Controls how long and how often to check for transaction confirmation.\n * Adjust based on network congestion and application requirements.\n *\n * @category Blockchain\n */\nexport interface TransactionWaitOptions {\n  /** Number of confirmations to wait for (default: 1) */\n  confirmations?: number;\n  /** Timeout in milliseconds (default: 30000) */\n  timeout?: number;\n  /** Polling interval in milliseconds (default: 4000) */\n  pollingInterval?: number;\n}\n\n/**\n * Represents a confirmed blockchain transaction with metadata.\n *\n * @remarks\n * Contains essential transaction information after confirmation including\n * gas usage, block number, and function details. Extended by specific\n * result types with parsed events.\n *\n * @category Blockchain\n */\nexport interface TransactionResult {\n  /** Transaction hash */\n  transactionHash: Hash;\n  /** Block number where transaction was included */\n  blockNumber: bigint;\n  /** Gas used by the transaction */\n  gasUsed: bigint;\n  /** Account that initiated the transaction */\n  from: Address;\n  /** Contract that was called */\n  contractName: string;\n  /** Function that was called */\n  functionName: string;\n}\n\n/**\n * @remarks\n * Event typing strategy:\n * - Event arguments are dynamically typed based on contract mappings\n * - `parseTransaction` returns `expectedEvents` with typed args for mapped functions\n * - `allEvents` contains all parsed events from the transaction\n * - This approach lets the mapping file drive types rather than requiring\n *   specific result interfaces per event type\n *\n * @internal\n */\n"],"mappings":";;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/types/blockchain.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Defines core blockchain interaction types.
+ *
+ * @remarks
+ * This module provides fundamental types for blockchain transactions,
+ * including transaction requests, confirmation options, and results.
+ * These types form the basis for all blockchain interactions in the SDK.
+ *
+ * @category Types
+ * @module types/blockchain
+ */
+import type { Hash, Address } from "viem";
+/**
+ * Represents a submitted blockchain transaction awaiting confirmation.
+ *
+ * @remarks
+ * Returned immediately after transaction submission, before confirmation.
+ * Use `waitForTransactionEvents` to wait for confirmation and retrieve events.
+ *
+ * @category Blockchain
+ */
+export interface TransactionRequest {
+    /** Transaction hash */
+    hash: Hash;
+    /** Account that initiated the transaction */
+    from: Address;
+    /** Contract that was called */
+    contractName: string;
+    /** Function that was called */
+    functionName: string;
+    /** Function arguments (for debugging/logging) */
+    args?: readonly unknown[];
+}
+/**
+ * Configures transaction confirmation waiting behavior.
+ *
+ * @remarks
+ * Controls how long and how often to check for transaction confirmation.
+ * Adjust based on network congestion and application requirements.
+ *
+ * @category Blockchain
+ */
+export interface TransactionWaitOptions {
+    /** Number of confirmations to wait for (default: 1) */
+    confirmations?: number;
+    /** Timeout in milliseconds (default: 30000) */
+    timeout?: number;
+    /** Polling interval in milliseconds (default: 4000) */
+    pollingInterval?: number;
+}
+/**
+ * Represents a confirmed blockchain transaction with metadata.
+ *
+ * @remarks
+ * Contains essential transaction information after confirmation including
+ * gas usage, block number, and function details. Extended by specific
+ * result types with parsed events.
+ *
+ * @category Blockchain
+ */
+export interface TransactionResult {
+    /** Transaction hash */
+    transactionHash: Hash;
+    /** Block number where transaction was included */
+    blockNumber: bigint;
+    /** Gas used by the transaction */
+    gasUsed: bigint;
+    /** Account that initiated the transaction */
+    from: Address;
+    /** Contract that was called */
+    contractName: string;
+    /** Function that was called */
+    functionName: string;
+}
+/**
+ * @remarks
+ * Event typing strategy:
+ * - Event arguments are dynamically typed based on contract mappings
+ * - `parseTransaction` returns `expectedEvents` with typed args for mapped functions
+ * - `allEvents` contains all parsed events from the transaction
+ * - This approach lets the mapping file drive types rather than requiring
+ *   specific result interfaces per event type
+ *
+ * @internal
+ */

package/dist/types/blockchain.js

@@ -0,0 +1 @@
+//# sourceMappingURL=blockchain.js.map

package/dist/types/blockchain.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/types/chains-additional.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/types/chains.cjs

@@ -0,0 +1,36 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var chains_exports = {};
+__export(chains_exports, {
+  isVanaChain: () => isVanaChain,
+  isVanaChainId: () => isVanaChainId
+});
+module.exports = __toCommonJS(chains_exports);
+function isVanaChainId(chainId) {
+  return chainId === 14800 || chainId === 1480;
+}
+function isVanaChain(chain) {
+  return isVanaChainId(chain.id);
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  isVanaChain,
+  isVanaChainId
+});
+//# sourceMappingURL=chains.cjs.map

package/dist/types/chains.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Represents the supported Vana network chain identifiers.\n *\n * @remarks\n * The Vana protocol operates on two primary networks:\n * - `14800`: Moksha testnet for development and testing\n * - `1480`: Vana mainnet for production deployment\n *\n * Use these chain IDs when configuring the SDK or checking network compatibility.\n *\n * @category Blockchain\n * @see {@link https://docs.vana.org/docs/networks | Network Documentation}\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Extends viem's Chain type with Vana-specific chain constraints.\n *\n * @remarks\n * Ensures type safety for Vana-specific chains by restricting the chain ID\n * to supported networks. This type provides full viem Chain compatibility\n * while guaranteeing the chain is a valid Vana network.\n *\n * @category Blockchain\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Maps Vana chain IDs to their complete chain configurations.\n *\n * @remarks\n * Provides type-safe access to chain configurations indexed by chain ID.\n * Use this for dynamic chain selection based on runtime chain ID values.\n *\n * @category Blockchain\n * @example\n * ```typescript\n * const configs: ChainConfig = {\n *   14800: mokshaTestnet,\n *   1480: vanaMainnet\n * };\n * const chain = configs[chainId];\n * ```\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Validates whether a chain ID represents a supported Vana network.\n *\n * @remarks\n * Type guard for runtime validation of chain IDs from external sources.\n * Use when accepting user input or processing network configurations.\n *\n * @param chainId - The chain ID to validate\n * @returns `true` if the chain ID is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * const chainId = parseInt(process.env.CHAIN_ID);\n *\n * if (!isVanaChainId(chainId)) {\n *   throw new Error(`Unsupported chain ID: ${chainId}`);\n * }\n *\n * // TypeScript now knows chainId is VanaChainId\n * const config = getChainConfig(chainId);\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Validates whether a Chain object represents a supported Vana network.\n *\n * @remarks\n * Type guard for validating viem Chain objects as Vana chains.\n * Ensures both type safety and runtime validation for chain compatibility.\n *\n * @param chain - The chain object to validate\n * @returns `true` if the chain is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * import { mainnet, mokshaTestnet } from 'viem/chains';\n *\n * if (isVanaChain(chain)) {\n *   // TypeScript knows this is a VanaChain\n *   console.log(`Connected to Vana network: ${chain.id}`);\n * } else {\n *   console.error('Please connect to a Vana network');\n * }\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AA4EO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AA0BO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}

package/dist/types/chains.d.ts

@@ -0,0 +1,98 @@
+import type { Chain } from "viem";
+/**
+ * Represents the supported Vana network chain identifiers.
+ *
+ * @remarks
+ * The Vana protocol operates on two primary networks:
+ * - `14800`: Moksha testnet for development and testing
+ * - `1480`: Vana mainnet for production deployment
+ *
+ * Use these chain IDs when configuring the SDK or checking network compatibility.
+ *
+ * @category Blockchain
+ * @see {@link https://docs.vana.org/docs/networks | Network Documentation}
+ */
+export type VanaChainId = 14800 | 1480;
+/**
+ * Extends viem's Chain type with Vana-specific chain constraints.
+ *
+ * @remarks
+ * Ensures type safety for Vana-specific chains by restricting the chain ID
+ * to supported networks. This type provides full viem Chain compatibility
+ * while guaranteeing the chain is a valid Vana network.
+ *
+ * @category Blockchain
+ */
+export type VanaChain = Chain & {
+    id: VanaChainId;
+};
+/**
+ * Maps Vana chain IDs to their complete chain configurations.
+ *
+ * @remarks
+ * Provides type-safe access to chain configurations indexed by chain ID.
+ * Use this for dynamic chain selection based on runtime chain ID values.
+ *
+ * @category Blockchain
+ * @example
+ * ```typescript
+ * const configs: ChainConfig = {
+ *   14800: mokshaTestnet,
+ *   1480: vanaMainnet
+ * };
+ * const chain = configs[chainId];
+ * ```
+ */
+export type ChainConfig = {
+    [K in VanaChainId]: VanaChain;
+};
+/**
+ * Validates whether a chain ID represents a supported Vana network.
+ *
+ * @remarks
+ * Type guard for runtime validation of chain IDs from external sources.
+ * Use when accepting user input or processing network configurations.
+ *
+ * @param chainId - The chain ID to validate
+ * @returns `true` if the chain ID is a supported Vana network, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * const chainId = parseInt(process.env.CHAIN_ID);
+ *
+ * if (!isVanaChainId(chainId)) {
+ *   throw new Error(`Unsupported chain ID: ${chainId}`);
+ * }
+ *
+ * // TypeScript now knows chainId is VanaChainId
+ * const config = getChainConfig(chainId);
+ * ```
+ *
+ * @category Blockchain
+ */
+export declare function isVanaChainId(chainId: number): chainId is VanaChainId;
+/**
+ * Validates whether a Chain object represents a supported Vana network.
+ *
+ * @remarks
+ * Type guard for validating viem Chain objects as Vana chains.
+ * Ensures both type safety and runtime validation for chain compatibility.
+ *
+ * @param chain - The chain object to validate
+ * @returns `true` if the chain is a supported Vana network, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { mainnet, mokshaTestnet } from 'viem/chains';
+ *
+ * if (isVanaChain(chain)) {
+ *   // TypeScript knows this is a VanaChain
+ *   console.log(`Connected to Vana network: ${chain.id}`);
+ * } else {
+ *   console.error('Please connect to a Vana network');
+ * }
+ * ```
+ *
+ * @category Blockchain
+ */
+export declare function isVanaChain(chain: Chain): chain is VanaChain;

package/dist/types/chains.js

@@ -0,0 +1,11 @@
+function isVanaChainId(chainId) {
+  return chainId === 14800 || chainId === 1480;
+}
+function isVanaChain(chain) {
+  return isVanaChainId(chain.id);
+}
+export {
+  isVanaChain,
+  isVanaChainId
+};
+//# sourceMappingURL=chains.js.map

package/dist/types/chains.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/types/chains.ts"],"sourcesContent":["import type { Chain } from \"viem\";\n\n/**\n * Represents the supported Vana network chain identifiers.\n *\n * @remarks\n * The Vana protocol operates on two primary networks:\n * - `14800`: Moksha testnet for development and testing\n * - `1480`: Vana mainnet for production deployment\n *\n * Use these chain IDs when configuring the SDK or checking network compatibility.\n *\n * @category Blockchain\n * @see {@link https://docs.vana.org/docs/networks | Network Documentation}\n */\nexport type VanaChainId = 14800 | 1480;\n\n/**\n * Extends viem's Chain type with Vana-specific chain constraints.\n *\n * @remarks\n * Ensures type safety for Vana-specific chains by restricting the chain ID\n * to supported networks. This type provides full viem Chain compatibility\n * while guaranteeing the chain is a valid Vana network.\n *\n * @category Blockchain\n */\nexport type VanaChain = Chain & {\n  id: VanaChainId;\n};\n\n/**\n * Maps Vana chain IDs to their complete chain configurations.\n *\n * @remarks\n * Provides type-safe access to chain configurations indexed by chain ID.\n * Use this for dynamic chain selection based on runtime chain ID values.\n *\n * @category Blockchain\n * @example\n * ```typescript\n * const configs: ChainConfig = {\n *   14800: mokshaTestnet,\n *   1480: vanaMainnet\n * };\n * const chain = configs[chainId];\n * ```\n */\nexport type ChainConfig = {\n  [K in VanaChainId]: VanaChain;\n};\n\n/**\n * Validates whether a chain ID represents a supported Vana network.\n *\n * @remarks\n * Type guard for runtime validation of chain IDs from external sources.\n * Use when accepting user input or processing network configurations.\n *\n * @param chainId - The chain ID to validate\n * @returns `true` if the chain ID is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * const chainId = parseInt(process.env.CHAIN_ID);\n *\n * if (!isVanaChainId(chainId)) {\n *   throw new Error(`Unsupported chain ID: ${chainId}`);\n * }\n *\n * // TypeScript now knows chainId is VanaChainId\n * const config = getChainConfig(chainId);\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChainId(chainId: number): chainId is VanaChainId {\n  return chainId === 14800 || chainId === 1480;\n}\n\n/**\n * Validates whether a Chain object represents a supported Vana network.\n *\n * @remarks\n * Type guard for validating viem Chain objects as Vana chains.\n * Ensures both type safety and runtime validation for chain compatibility.\n *\n * @param chain - The chain object to validate\n * @returns `true` if the chain is a supported Vana network, `false` otherwise\n *\n * @example\n * ```typescript\n * import { mainnet, mokshaTestnet } from 'viem/chains';\n *\n * if (isVanaChain(chain)) {\n *   // TypeScript knows this is a VanaChain\n *   console.log(`Connected to Vana network: ${chain.id}`);\n * } else {\n *   console.error('Please connect to a Vana network');\n * }\n * ```\n *\n * @category Blockchain\n */\nexport function isVanaChain(chain: Chain): chain is VanaChain {\n  return isVanaChainId(chain.id);\n}\n"],"mappings":"AA4EO,SAAS,cAAc,SAAyC;AACrE,SAAO,YAAY,SAAS,YAAY;AAC1C;AA0BO,SAAS,YAAY,OAAkC;AAC5D,SAAO,cAAc,MAAM,EAAE;AAC/B;","names":[]}

package/dist/types/config.cjs

@@ -0,0 +1,51 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var config_exports = {};
+__export(config_exports, {
+  hasStorageConfig: () => hasStorageConfig,
+  isAddressOnlyConfig: () => isAddressOnlyConfig,
+  isChainConfig: () => isChainConfig,
+  isReadOnlyConfig: () => isReadOnlyConfig,
+  isWalletConfig: () => isWalletConfig
+});
+module.exports = __toCommonJS(config_exports);
+function isWalletConfig(config) {
+  return "walletClient" in config;
+}
+function isReadOnlyConfig(config) {
+  return "publicClient" in config && "address" in config && !("walletClient" in config);
+}
+function isAddressOnlyConfig(config) {
+  return "address" in config && !("publicClient" in config) && !("walletClient" in config) && !("chainId" in config);
+}
+function isChainConfig(config) {
+  return "chainId" in config && !("walletClient" in config);
+}
+function hasStorageConfig(config) {
+  return config.storage?.providers !== void 0 && Object.keys(config.storage.providers).length > 0;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  hasStorageConfig,
+  isAddressOnlyConfig,
+  isChainConfig,
+  isReadOnlyConfig,
+  isWalletConfig
+});
+//# sourceMappingURL=config.cjs.map