@awarizon/web3 1.0.1 → 1.1.0

package/dist/index.d.ts

@@ -1,7 +1,8 @@
-import { Chain, WalletClient, Address, Abi, PublicClient } from 'viem';
+import { Chain, WalletClient, Address, Abi, PublicClient, Hex } from 'viem';
 export { Abi, Address, Chain, Hash, TransactionReceipt, WalletClient } from 'viem';
-import { WalletEngine } from '@awarizon/wallet-engine';
+import { WalletEngine, CreatedWallet, ImportedWalletFromMnemonic, ImportedWalletFromPrivateKey, ExternalWalletClient } from '@awarizon/wallet-engine';
 export { ChainSwitchError, InvalidMnemonicError, InvalidPrivateKeyError, WalletEngine, WalletNotConnectedError } from '@awarizon/wallet-engine';
+import { TransactionResult } from '@awarizon/tx-engine';
 export { ContractExecutionError, GasEstimationError, SimulationError, TransactionEngine, TransactionResult, TransactionTimeoutError } from '@awarizon/tx-engine';
 export { DuplicateFunctionError, InvalidABIError, UnsupportedABIItemError, generateAllMethodSignatures, generateMethodSignature, isPayableFunction, isWriteFunction, parseABI } from '@awarizon/abi-engine';
 
@@ -12,6 +13,12 @@ interface AwarizonConfig {
      *  - a viem Chain object: `import { base } from "viem/chains"`
      */
     chain: Chain | string;
+    /**
+     * Awarizon API key (required).
+     * Generate one at https://awarizon.com/dashboard/api-keys
+     * Format: "awz_live_..."
+     */
+    apiKey: string;
     /**
      * Optional RPC URL override.
      * If omitted, the chain's default public RPC endpoint is used.
@@ -19,9 +26,14 @@ interface AwarizonConfig {
     rpcUrl?: string;
     /**
      * Optional pre-connected external signer.
-     * Equivalent to calling `sdk.connectWallet(signer)` after construction.
+     * Equivalent to calling `awarizon.connectWallet(signer)` after construction.
      */
     signer?: WalletClient;
+    /**
+     * Base URL of the Awarizon API. Defaults to "https://awarizon.com".
+     * Override for local development or staging environments.
+     */
+    baseUrl?: string;
 }
 interface ContractConfig<TAbi extends Abi = Abi> {
     /** The deployed contract address */
@@ -39,7 +51,7 @@ interface PayableOptions {
     gas?: bigint;
 }
 /**
- * The dynamically-generated contract instance returned by sdk.contract().
+ * The dynamically-generated contract instance returned by awarizon.contract().
  *
  * Every function in the ABI is exposed as a method:
  *  - read functions (view/pure) → return decoded values
@@ -65,6 +77,543 @@ interface SDKWalletInfo {
     chain: Chain;
     isExternal: boolean;
 }
+interface ContractRegistryEntry {
+    address: Address;
+    abi: Abi;
+}
+
+declare const ERC20_ABI: readonly [{
+    readonly type: "event";
+    readonly name: "Approval";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Transfer";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: false;
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "allowance";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "spender";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "spender";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "decimals";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint8";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "totalSupply";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transfer";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "sender";
+        readonly type: "address";
+    }, {
+        readonly name: "recipient";
+        readonly type: "address";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}];
+interface Erc20Contract {
+    name(): Promise<string>;
+    symbol(): Promise<string>;
+    decimals(): Promise<number>;
+    totalSupply(): Promise<bigint>;
+    balanceOf(owner: Address): Promise<bigint>;
+    allowance(owner: Address, spender: Address): Promise<bigint>;
+    transfer(to: Address, amount: bigint): Promise<TransactionResult>;
+    transferFrom(from: Address, to: Address, amount: bigint): Promise<TransactionResult>;
+    approve(spender: Address, amount: bigint): Promise<TransactionResult>;
+    on: ContractInstance['on'];
+    estimateGas: ContractInstance['estimateGas'];
+    readonly _address: Address;
+    readonly _abi: Abi;
+}
+declare const ERC721_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "name";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "symbol";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "tokenURI";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "totalSupply";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "ownerOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "getApproved";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "address";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isApprovedForAll";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly name: "operator";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "transferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "safeTransferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "approve";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "setApprovalForAll";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "event";
+    readonly name: "Transfer";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "Approval";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "approved";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "ApprovalForAll";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "owner";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+}];
+interface Erc721Contract {
+    name(): Promise<string>;
+    symbol(): Promise<string>;
+    tokenURI(tokenId: bigint): Promise<string>;
+    totalSupply(): Promise<bigint>;
+    ownerOf(tokenId: bigint): Promise<Address>;
+    balanceOf(owner: Address): Promise<bigint>;
+    getApproved(tokenId: bigint): Promise<Address>;
+    isApprovedForAll(owner: Address, operator: Address): Promise<boolean>;
+    transferFrom(from: Address, to: Address, tokenId: bigint): Promise<TransactionResult>;
+    safeTransferFrom(from: Address, to: Address, tokenId: bigint): Promise<TransactionResult>;
+    approve(to: Address, tokenId: bigint): Promise<TransactionResult>;
+    setApprovalForAll(operator: Address, approved: boolean): Promise<TransactionResult>;
+    on: ContractInstance['on'];
+    estimateGas: ContractInstance['estimateGas'];
+    readonly _address: Address;
+    readonly _abi: Abi;
+}
+declare const ERC1155_ABI: readonly [{
+    readonly type: "function";
+    readonly name: "uri";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "id";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "string";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOf";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "balanceOfBatch";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "accounts";
+        readonly type: "address[]";
+    }, {
+        readonly name: "ids";
+        readonly type: "uint256[]";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "uint256[]";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "isApprovedForAll";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly name: "operator";
+        readonly type: "address";
+    }];
+    readonly outputs: readonly [{
+        readonly type: "bool";
+    }];
+}, {
+    readonly type: "function";
+    readonly name: "setApprovalForAll";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "safeTransferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly name: "amount";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "function";
+    readonly name: "safeBatchTransferFrom";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "ids";
+        readonly type: "uint256[]";
+    }, {
+        readonly name: "amounts";
+        readonly type: "uint256[]";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [];
+}, {
+    readonly type: "event";
+    readonly name: "TransferSingle";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "id";
+        readonly type: "uint256";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "TransferBatch";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "from";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "ids";
+        readonly type: "uint256[]";
+    }, {
+        readonly name: "values";
+        readonly type: "uint256[]";
+    }];
+}, {
+    readonly type: "event";
+    readonly name: "ApprovalForAll";
+    readonly inputs: readonly [{
+        readonly indexed: true;
+        readonly name: "account";
+        readonly type: "address";
+    }, {
+        readonly indexed: true;
+        readonly name: "operator";
+        readonly type: "address";
+    }, {
+        readonly name: "approved";
+        readonly type: "bool";
+    }];
+}];
+interface Erc1155Contract {
+    uri(id: bigint): Promise<string>;
+    balanceOf(account: Address, id: bigint): Promise<bigint>;
+    balanceOfBatch(accounts: Address[], ids: bigint[]): Promise<bigint[]>;
+    isApprovedForAll(account: Address, operator: Address): Promise<boolean>;
+    setApprovalForAll(operator: Address, approved: boolean): Promise<TransactionResult>;
+    safeTransferFrom(from: Address, to: Address, id: bigint, amount: bigint, data: `0x${string}`): Promise<TransactionResult>;
+    safeBatchTransferFrom(from: Address, to: Address, ids: bigint[], amounts: bigint[], data: `0x${string}`): Promise<TransactionResult>;
+    on: ContractInstance['on'];
+    estimateGas: ContractInstance['estimateGas'];
+    readonly _address: Address;
+    readonly _abi: Abi;
+}
 
 declare class NetworkMismatchError extends Error {
     readonly code: "NETWORK_MISMATCH";
@@ -85,79 +634,233 @@ declare class UnsupportedChainError extends Error {
     readonly chain: string;
     constructor(chain: string);
 }
+declare class ApiKeyRequiredError extends Error {
+    readonly code: "API_KEY_REQUIRED";
+    constructor();
+}
+declare class InvalidApiKeyError extends Error {
+    readonly code: "INVALID_API_KEY";
+    constructor(message?: string);
+}
 
 /**
- * The primary entry point for the Awarizon Web3 SDK.
+ * Wraps WalletEngine and gates mutating operations (create, import) behind
+ * API key validation. Read-only operations (address, isConnected, etc.) are
+ * never gated since they need no network access.
+ */
+declare class WalletProxy {
+    private readonly engine;
+    private readonly ensureReady;
+    constructor(engine: WalletEngine, ensureReady: () => Promise<void>);
+    create(): Promise<CreatedWallet>;
+    importMnemonic(mnemonic: string, accountIndex?: number): Promise<ImportedWalletFromMnemonic>;
+    importPrivateKey(privateKey: Hex): Promise<ImportedWalletFromPrivateKey>;
+    address(): Address;
+    getSigner(): WalletClient;
+    getWalletClient(): WalletClient;
+    isConnected(): boolean;
+    hasExternalWallet(): boolean;
+    hasInternalWallet(): boolean;
+    connectExternal(c: ExternalWalletClient): void;
+    disconnectExternal(): void;
+    disconnect(): void;
+    switchChain(chain: Chain): Promise<void>;
+}
+/**
+ * Primary entry point for the Awarizon Web3 SDK.
+ *
+ * An API key is required — get yours at https://awarizon.com/dashboard/api-keys
  *
  * ```ts
- * const sdk = new AwarizonWeb3({ chain: "base" })
+ * const awarizon = new AwarizonWeb3({ chain: "base", apiKey: "awz_live_..." })
  *
  * // Internal wallet
- * const wallet = await sdk.wallet.create()
+ * const wallet = await awarizon.wallet.create()
  *
- * // Load a contract and call it
- * const staking = await sdk.contract({ address: "0x...", abi })
+ * // Load a contract
+ * const staking = await awarizon.contract({ address: "0x...", abi })
  * await staking.stake(100n)
- * const balance = await staking.getBalance(wallet.address)
- *
- * // Listen for events
  * staking.on("Staked", (log) => console.log(log))
  * ```
  */
 declare class AwarizonWeb3 {
-    /** The resolved viem Chain */
     readonly chain: Chain;
-    /** Internal wallet + signer management */
-    readonly wallet: WalletEngine;
-    /** The underlying viem PublicClient used for reads */
     readonly publicClient: PublicClient;
+    /** Wallet management — create, import, or connect external wallets */
+    readonly wallet: WalletProxy;
+    private readonly _engine;
+    private readonly _txEngine;
+    private readonly _telemetry;
+    private _contractCache;
+    private _registry;
     constructor(config: AwarizonConfig);
+    connectWallet(walletClient: WalletClient): this;
+    disconnectWallet(): this;
+    switchChain(chain: Chain | string): Promise<this>;
+    getWalletInfo(): SDKWalletInfo;
     /**
-     * Connect an external wallet client (wagmi, WalletConnect, viem, EIP-1193).
-     * The connected signer takes priority over any internal wallet.
+     * Load a deployed contract and return a fully typed, ABI-powered instance.
+     * Validates the API key on the first call — subsequent calls are instant.
+     *
+     * Results are cached by address — calling contract() twice with the same
+     * address and ABI object returns the same instance without rebuilding.
+     */
+    contract<TAbi extends Abi>(config: ContractConfig<TAbi>): Promise<ContractInstance>;
+    /**
+     * Load multiple contracts in parallel. Validates the API key once, then
+     * instantiates all contracts concurrently.
      *
      * @example
-     * sdk.connectWallet(walletClient)
+     * ```ts
+     * const [token, staking, nft] = await awarizon.contracts([
+     *   { address: tokenAddr, abi: ERC20_ABI },
+     *   { address: stakingAddr, abi: STAKING_ABI },
+     *   { address: nftAddr, abi: ERC721_ABI },
+     * ])
+     * ```
      */
-    connectWallet(walletClient: WalletClient): this;
+    contracts(configs: Array<{
+        address: Address;
+        abi: Abi;
+    }>): Promise<ContractInstance[]>;
     /**
-     * Disconnect the externally-connected wallet.
-     * Falls back to the internal wallet if one is loaded.
+     * Call a read-only (view/pure) contract function directly without loading
+     * a full contract instance. Best for one-off reads.
+     *
+     * @example
+     * ```ts
+     * const balance = await awarizon.read<bigint>({
+     *   address: tokenAddress,
+     *   abi: ERC20_ABI,
+     *   method: "balanceOf",
+     *   args: [userAddress],
+     * })
+     * ```
      */
-    disconnectWallet(): this;
+    read<T = unknown>(params: {
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+    }): Promise<T>;
     /**
-     * Switch the active chain.
-     * Rebuilds the PublicClient and internal WalletClient for the new chain.
+     * Execute a state-mutating contract function directly without loading a full
+     * contract instance. Best for one-off writes.
+     *
+     * @example
+     * ```ts
+     * const { hash, receipt } = await awarizon.write({
+     *   address: tokenAddress,
+     *   abi: ERC20_ABI,
+     *   method: "transfer",
+     *   args: [recipient, 100n],
+     * })
+     * ```
      */
-    switchChain(chain: Chain | string): Promise<this>;
+    write(params: {
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+        value?: bigint;
+        gas?: bigint;
+    }): Promise<TransactionResult>;
     /**
-     * Returns a summary of the currently active wallet.
-     * @throws {WalletNotConnectedError} if no wallet is connected
+     * Batch multiple read calls into a single RPC round-trip using multicall3.
+     * Falls back to parallel individual reads on chains where multicall3 is
+     * not deployed.
+     *
+     * @example
+     * ```ts
+     * const [balance, supply, allowance] = await awarizon.multicall([
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "balanceOf", args: [userAddr] },
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "totalSupply" },
+     *   { address: tokenAddr, abi: ERC20_ABI, method: "allowance", args: [userAddr, spenderAddr] },
+     * ])
+     * ```
      */
-    getWalletInfo(): SDKWalletInfo;
+    multicall(calls: Array<{
+        address: Address;
+        abi: Abi;
+        method: string;
+        args?: unknown[];
+    }>): Promise<unknown[]>;
     /**
-     * Load a deployed smart contract and return a fully typed, ABI-powered
-     * instance. Every function in the ABI is exposed as a direct method.
+     * Load an ERC-20 token with fully typed methods — no ABI import needed.
      *
-     * **Read functions** (view / pure) use the PublicClient — no signer needed.
-     * **Write functions** (nonpayable / payable) use the active WalletClient.
+     * ```ts
+     * const token = await awarizon.erc20("0x...")
+     * const balance = await token.balanceOf(userAddress)
+     * const symbol  = await token.symbol()
+     * await token.transfer(recipient, 100n)
+     * ```
+     */
+    erc20(address: Address): Promise<Erc20Contract>;
+    /**
+     * Load an ERC-721 NFT contract with fully typed methods — no ABI import needed.
      *
-     * @example
-     * const token = await sdk.contract({ address: "0x...", abi: ERC20_ABI })
-     * const balance = await token.balanceOf(address)   // read
-     * await token.transfer(to, 100n)                   // write
-     * token.on("Transfer", handler)                    // events
+     * ```ts
+     * const nft   = await awarizon.erc721("0x...")
+     * const owner = await nft.ownerOf(1n)
+     * const uri   = await nft.tokenURI(1n)
+     * await nft.transferFrom(from, to, 1n)
+     * ```
      */
-    contract<TAbi extends Abi>(config: ContractConfig<TAbi>): Promise<ContractInstance>;
+    erc721(address: Address): Promise<Erc721Contract>;
     /**
-     * Returns the chain ID of the current chain.
-     * Useful for runtime network validation.
+     * Load an ERC-1155 multi-token contract with fully typed methods — no ABI import needed.
+     *
+     * ```ts
+     * const items   = await awarizon.erc1155("0x...")
+     * const balance = await items.balanceOf(userAddress, 42n)
+     * const uri     = await items.uri(42n)
+     * await items.safeTransferFrom(from, to, 42n, 1n, "0x")
+     * ```
      */
-    get chainId(): number;
+    erc1155(address: Address): Promise<Erc1155Contract>;
+    /**
+     * Register a contract under a human-readable name.
+     * After registering, use `awarizon.use(name)` anywhere instead of repeating
+     * address + ABI every time.
+     *
+     * ```ts
+     * awarizon.register("USDC",  { address: "0x...", abi: erc20Abi })
+     * awarizon.register("Vault", { address: "0x...", abi: vaultAbi })
+     *
+     * const usdc  = await awarizon.use("USDC")
+     * const vault = await awarizon.use("Vault")
+     * ```
+     */
+    register(name: string, config: ContractRegistryEntry): this;
+    /**
+     * Retrieve a previously registered contract by name.
+     * Throws a descriptive error if the name was never registered.
+     *
+     * ```ts
+     * const usdc = await awarizon.use("USDC")
+     * await usdc.transfer(recipient, 100n)
+     * ```
+     */
+    use(name: string): Promise<ContractInstance>;
+    /**
+     * Remove a registered contract from the registry.
+     *
+     * ```ts
+     * awarizon.unregister("USDC")
+     * ```
+     */
+    unregister(name: string): this;
     /**
-     * Check whether any wallet (internal or external) is connected.
+     * Return all registered contract names.
      */
+    registeredContracts(): string[];
+    get chainId(): number;
     get isConnected(): boolean;
+    /**
+     * Flush pending telemetry and stop background timers.
+     * Call when tearing down a long-lived SDK instance (e.g. on server shutdown).
+     */
+    destroy(): Promise<void>;
 }
 
 declare const CHAINS: Record<string, Chain>;
@@ -173,4 +876,62 @@ declare function resolveChain(chain: Chain | string): Chain;
 /** Returns a list of all unique supported chain IDs */
 declare function getSupportedChainIds(): number[];
 
-export { type AwarizonConfig, AwarizonWeb3, CHAINS, type ContractConfig, type ContractInstance, ContractNotLoadedError, type EventUnsubscribe, NetworkMismatchError, type PayableOptions, ProviderError, type SDKWalletInfo, UnsupportedChainError, getSupportedChainIds, resolveChain };
+type TelemetryEventType = 'contract.read' | 'contract.write' | 'contract.gas_estimate' | 'wallet.create' | 'wallet.import' | 'chain.switch';
+interface TelemetryEvent {
+    type: TelemetryEventType;
+    chain: string;
+    chainId: number;
+    functionName?: string;
+    success: boolean;
+    durationMs: number;
+    ts: number;
+}
+/**
+ * Handles SDK-to-Awarizon API communication:
+ *   1. Validates the API key on first meaningful operation (5s timeout)
+ *   2. Batches usage events and flushes them fire-and-forget
+ *   3. Flushes remaining events via sendBeacon on browser page unload
+ *
+ * All telemetry failures are swallowed — they never surface to the caller.
+ * The only hard error is InvalidApiKeyError thrown from ensureValidated().
+ */
+declare class TelemetryClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private validated;
+    private validationPromise;
+    private queue;
+    private flushTimer;
+    private unloadListener;
+    constructor(apiKey: string, baseUrl?: string);
+    /**
+     * Ensures the API key has been validated against the Awarizon API.
+     * Idempotent — safe to call on every operation; only hits the network once.
+     * Times out after 5 seconds to avoid hanging in degraded network conditions.
+     *
+     * @throws {InvalidApiKeyError} if the key is invalid, revoked, or unreachable
+     */
+    ensureValidated(): Promise<void>;
+    /**
+     * Queue a usage event. Events are batched and sent periodically.
+     * Must only be called after ensureValidated() has resolved.
+     */
+    track(event: TelemetryEvent): void;
+    /**
+     * Flush pending events and stop background timers.
+     * Call when tearing down a long-lived SDK instance (e.g. server shutdown).
+     */
+    destroy(): Promise<void>;
+    private _validate;
+    private _startTimers;
+    private _stopTimers;
+    /**
+     * Unified flush. Pass `await = true` for graceful shutdown,
+     * `await = false` for fire-and-forget mid-session flushes.
+     */
+    private _flush;
+    /** Uses sendBeacon for guaranteed delivery on page unload */
+    private _flushBeacon;
+}
+
+export { ApiKeyRequiredError, type AwarizonConfig, AwarizonWeb3, CHAINS, type ContractConfig, type ContractInstance, ContractNotLoadedError, type ContractRegistryEntry, ERC1155_ABI, ERC20_ABI, ERC721_ABI, type Erc1155Contract, type Erc20Contract, type Erc721Contract, type EventUnsubscribe, InvalidApiKeyError, NetworkMismatchError, type PayableOptions, ProviderError, type SDKWalletInfo, TelemetryClient, type TelemetryEvent, type TelemetryEventType, UnsupportedChainError, getSupportedChainIds, resolveChain };