@awarizon/web3 1.0.1 → 1.1.0

package/dist/index.js

@@ -2,9 +2,9 @@
 
 var viem = require('viem');
 var walletEngine = require('@awarizon/wallet-engine');
+var txEngine = require('@awarizon/tx-engine');
 var chains = require('viem/chains');
 var abiEngine = require('@awarizon/abi-engine');
-var txEngine = require('@awarizon/tx-engine');
 
 // src/sdk.ts
 var CHAINS = {
@@ -57,6 +57,7 @@ var CHAINS = {
   fantom: chains.fantom,
   moonbeam: chains.moonbeam
 };
+var _chainAliases = Object.keys(CHAINS).sort().join(", ");
 function resolveChain(chain) {
   if (typeof chain === "object" && "id" in chain) {
     return chain;
@@ -64,10 +65,9 @@ function resolveChain(chain) {
   if (typeof chain === "string") {
     const resolved = CHAINS[chain.toLowerCase()] ?? CHAINS[chain];
     if (!resolved) {
-      const available = Object.keys(CHAINS).filter((k, i, arr) => arr.indexOf(k) === i).sort().join(", ");
       throw new Error(
         `[awarizon/web3] Unsupported chain: "${chain}".
-Available chains: ${available}`
+Available chains: ${_chainAliases}`
       );
     }
     return resolved;
@@ -82,37 +82,58 @@ function getSupportedChainIds() {
     return true;
   }).map((c) => c.id);
 }
-function buildContractInstance(address, abi, publicClient, getWalletClient) {
+function trackEvent(telemetry, type, chain, functionName, success, start) {
+  telemetry?.track({
+    type,
+    chain: chain?.name ?? "unknown",
+    chainId: chain?.id ?? 0,
+    functionName,
+    success,
+    durationMs: Date.now() - start,
+    ts: Date.now()
+  });
+}
+function buildContractInstance(address, abi, publicClient, txEngine, telemetry, chain) {
   const parsed = abiEngine.parseABI(abi);
-  const txEngine$1 = new txEngine.TransactionEngine(publicClient, getWalletClient);
+  const eventsMap = new Map(parsed.events.map((e) => [e.name, e]));
   const instance = {
     _address: address,
     _abi: abi
   };
   for (const fn of parsed.readFunctions) {
-    instance[fn.name] = buildReadMethod(fn, address, abi, txEngine$1);
+    instance[fn.name] = buildReadMethod(fn, address, abi, txEngine, telemetry, chain);
   }
   for (const fn of parsed.writeFunctions) {
-    instance[fn.name] = buildWriteMethod(fn, address, abi, txEngine$1);
+    instance[fn.name] = buildWriteMethod(fn, address, abi, txEngine, telemetry, chain);
   }
-  instance["on"] = buildEventSubscription(address, abi, parsed.events, publicClient);
+  instance["on"] = buildEventSubscription(address, abi, eventsMap, publicClient);
   instance["estimateGas"] = async (method, ...args) => {
-    const estimate = await txEngine$1.estimateGas({
-      address,
-      abi,
-      functionName: method,
-      args
-    });
-    return estimate.gas;
+    const start = Date.now();
+    try {
+      const estimate = await txEngine.estimateGas({ address, abi, functionName: method, args });
+      trackEvent(telemetry, "contract.gas_estimate", chain, method, true, start);
+      return estimate.gas;
+    } catch (error) {
+      trackEvent(telemetry, "contract.gas_estimate", chain, method, false, start);
+      throw error;
+    }
   };
   return instance;
 }
-function buildReadMethod(fn, address, abi, txEngine) {
+function buildReadMethod(fn, address, abi, txEngine, telemetry, chain) {
   return async (...args) => {
-    return txEngine.read({ address, abi, functionName: fn.name, args });
+    const start = Date.now();
+    try {
+      const result = await txEngine.read({ address, abi, functionName: fn.name, args });
+      trackEvent(telemetry, "contract.read", chain, fn.name, true, start);
+      return result;
+    } catch (error) {
+      trackEvent(telemetry, "contract.read", chain, fn.name, false, start);
+      throw error;
+    }
   };
 }
-function buildWriteMethod(fn, address, abi, txEngine) {
+function buildWriteMethod(fn, address, abi, txEngine, telemetry, chain) {
   const isPayable = fn.stateMutability === "payable";
   return async (...args) => {
     let callArgs = args;
@@ -126,14 +147,22 @@ function buildWriteMethod(fn, address, abi, txEngine) {
         gas = last.gas;
       }
     }
-    return txEngine.write({
-      address,
-      abi,
-      functionName: fn.name,
-      args: callArgs,
-      value,
-      gas
-    });
+    const start = Date.now();
+    try {
+      const result = await txEngine.write({
+        address,
+        abi,
+        functionName: fn.name,
+        args: callArgs,
+        value,
+        gas
+      });
+      trackEvent(telemetry, "contract.write", chain, fn.name, true, start);
+      return result;
+    } catch (error) {
+      trackEvent(telemetry, "contract.write", chain, fn.name, false, start);
+      throw error;
+    }
   };
 }
 function isPayableOptions(val) {
@@ -143,11 +172,11 @@ function isPayableOptions(val) {
   const hasGas = "gas" in obj && (obj.gas === void 0 || typeof obj.gas === "bigint");
   return hasValue || hasGas;
 }
-function buildEventSubscription(address, abi, events, publicClient) {
+function buildEventSubscription(address, abi, eventsMap, publicClient) {
   return (eventName, callback) => {
-    const abiEvent = events.find((e) => e.name === eventName);
+    const abiEvent = eventsMap.get(eventName);
     if (!abiEvent) {
-      const available = events.map((e) => e.name).join(", ") || "none";
+      const available = [...eventsMap.keys()].join(", ") || "none";
       throw new Error(
         `[awarizon/web3] Event "${eventName}" not found on contract ${address}.
 Available events: ${available}`
@@ -184,7 +213,7 @@ var ProviderError = class extends Error {
 };
 var ContractNotLoadedError = class extends Error {
   constructor(address) {
-    super(`[awarizon/web3] Contract at ${address} is not loaded. Call sdk.contract({ address, abi }) first.`);
+    super(`[awarizon/web3] Contract at ${address} is not loaded. Call awarizon.contract({ address, abi }) first.`);
     this.code = "CONTRACT_NOT_LOADED";
     this.name = "ContractNotLoadedError";
   }
@@ -197,101 +226,562 @@ var UnsupportedChainError = class extends Error {
     this.chain = chain;
   }
 };
+var ApiKeyRequiredError = class extends Error {
+  constructor() {
+    super(
+      '[awarizon/web3] An API key is required. Pass apiKey: "awz_live_..." to AwarizonWeb3({ ... }). Get yours at https://awarizon.com/dashboard/api-keys'
+    );
+    this.code = "API_KEY_REQUIRED";
+    this.name = "ApiKeyRequiredError";
+  }
+};
+var InvalidApiKeyError = class extends Error {
+  constructor(message = "Invalid or revoked API key.") {
+    super(`[awarizon/web3] ${message}`);
+    this.code = "INVALID_API_KEY";
+    this.name = "InvalidApiKeyError";
+  }
+};
 
-// src/sdk.ts
+// src/telemetry.ts
+var DEFAULT_BASE_URL = "https://awarizon.com";
+var FLUSH_INTERVAL_MS = 1e4;
+var MAX_BATCH_SIZE = 20;
+var VALIDATION_TIMEOUT = 5e3;
+var TelemetryClient = class {
+  constructor(apiKey, baseUrl = DEFAULT_BASE_URL) {
+    this.validated = false;
+    this.validationPromise = null;
+    this.queue = [];
+    this.flushTimer = null;
+    this.unloadListener = null;
+    this.apiKey = apiKey;
+    this.baseUrl = baseUrl.replace(/\/$/, "");
+  }
+  /**
+   * 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
+   */
+  async ensureValidated() {
+    if (this.validated) return;
+    if (this.validationPromise) return this.validationPromise;
+    this.validationPromise = this._validate().catch((err) => {
+      this.validationPromise = null;
+      throw err;
+    });
+    return this.validationPromise;
+  }
+  /**
+   * Queue a usage event. Events are batched and sent periodically.
+   * Must only be called after ensureValidated() has resolved.
+   */
+  track(event) {
+    if (!this.validated) return;
+    this.queue.push(event);
+    if (this.queue.length >= MAX_BATCH_SIZE) this._flush(false);
+  }
+  /**
+   * Flush pending events and stop background timers.
+   * Call when tearing down a long-lived SDK instance (e.g. server shutdown).
+   */
+  async destroy() {
+    this._stopTimers();
+    await this._flush(true);
+  }
+  // ─── Private ─────────────────────────────────────────────────────────────────
+  async _validate() {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), VALIDATION_TIMEOUT);
+    let res;
+    try {
+      res = await fetch(`${this.baseUrl}/api/v1/auth`, {
+        method: "GET",
+        headers: { Authorization: `Bearer ${this.apiKey}` },
+        signal: controller.signal
+      });
+    } catch (err) {
+      const msg = controller.signal.aborted ? `Awarizon API did not respond within ${VALIDATION_TIMEOUT / 1e3}s.` : `Could not reach Awarizon API: ${err.message}`;
+      throw new InvalidApiKeyError(msg);
+    } finally {
+      clearTimeout(timeout);
+    }
+    if (!res.ok) {
+      const body = await res.json().catch(() => ({}));
+      throw new InvalidApiKeyError(body.error ?? "Invalid or revoked API key.");
+    }
+    this.validated = true;
+    this._startTimers();
+  }
+  _startTimers() {
+    this.flushTimer = setInterval(() => {
+      if (this.queue.length > 0) this._flush(false);
+    }, FLUSH_INTERVAL_MS);
+    const timer = this.flushTimer;
+    if (typeof timer.unref === "function") timer.unref();
+    if (typeof window !== "undefined" && typeof navigator !== "undefined") {
+      this.unloadListener = () => this._flushBeacon();
+      window.addEventListener("beforeunload", this.unloadListener);
+    }
+  }
+  _stopTimers() {
+    if (this.flushTimer !== null) {
+      clearInterval(this.flushTimer);
+      this.flushTimer = null;
+    }
+    if (this.unloadListener !== null && typeof window !== "undefined") {
+      window.removeEventListener("beforeunload", this.unloadListener);
+      this.unloadListener = null;
+    }
+  }
+  _flush(awaited) {
+    if (this.queue.length === 0) return awaited ? Promise.resolve() : void 0;
+    const batch = this.queue.splice(0, MAX_BATCH_SIZE);
+    const promise = fetch(`${this.baseUrl}/api/v1/usage`, {
+      method: "POST",
+      headers: {
+        Authorization: `Bearer ${this.apiKey}`,
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({ events: batch })
+    }).then(() => {
+    }, () => {
+    });
+    return awaited ? promise : void 0;
+  }
+  /** Uses sendBeacon for guaranteed delivery on page unload */
+  _flushBeacon() {
+    if (this.queue.length === 0 || typeof navigator === "undefined") return;
+    const batch = this.queue.splice(0);
+    navigator.sendBeacon(
+      `${this.baseUrl}/api/v1/usage`,
+      new Blob([JSON.stringify({ events: batch })], { type: "application/json" })
+    );
+  }
+};
+var ERC20_ABI = viem.erc20Abi;
+var ERC721_ABI = [
+  { type: "function", name: "name", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+  { type: "function", name: "symbol", stateMutability: "view", inputs: [], outputs: [{ type: "string" }] },
+  { type: "function", name: "tokenURI", stateMutability: "view", inputs: [{ name: "tokenId", type: "uint256" }], outputs: [{ type: "string" }] },
+  { type: "function", name: "totalSupply", stateMutability: "view", inputs: [], outputs: [{ type: "uint256" }] },
+  { type: "function", name: "ownerOf", stateMutability: "view", inputs: [{ name: "tokenId", type: "uint256" }], outputs: [{ type: "address" }] },
+  { type: "function", name: "balanceOf", stateMutability: "view", inputs: [{ name: "owner", type: "address" }], outputs: [{ type: "uint256" }] },
+  { type: "function", name: "getApproved", stateMutability: "view", inputs: [{ name: "tokenId", type: "uint256" }], outputs: [{ type: "address" }] },
+  { type: "function", name: "isApprovedForAll", stateMutability: "view", inputs: [{ name: "owner", type: "address" }, { name: "operator", type: "address" }], outputs: [{ type: "bool" }] },
+  { type: "function", name: "transferFrom", stateMutability: "nonpayable", inputs: [{ name: "from", type: "address" }, { name: "to", type: "address" }, { name: "tokenId", type: "uint256" }], outputs: [] },
+  { type: "function", name: "safeTransferFrom", stateMutability: "nonpayable", inputs: [{ name: "from", type: "address" }, { name: "to", type: "address" }, { name: "tokenId", type: "uint256" }], outputs: [] },
+  { type: "function", name: "approve", stateMutability: "nonpayable", inputs: [{ name: "to", type: "address" }, { name: "tokenId", type: "uint256" }], outputs: [] },
+  { type: "function", name: "setApprovalForAll", stateMutability: "nonpayable", inputs: [{ name: "operator", type: "address" }, { name: "approved", type: "bool" }], outputs: [] },
+  { type: "event", name: "Transfer", inputs: [{ indexed: true, name: "from", type: "address" }, { indexed: true, name: "to", type: "address" }, { indexed: true, name: "tokenId", type: "uint256" }] },
+  { type: "event", name: "Approval", inputs: [{ indexed: true, name: "owner", type: "address" }, { indexed: true, name: "approved", type: "address" }, { indexed: true, name: "tokenId", type: "uint256" }] },
+  { type: "event", name: "ApprovalForAll", inputs: [{ indexed: true, name: "owner", type: "address" }, { indexed: true, name: "operator", type: "address" }, { name: "approved", type: "bool" }] }
+];
+var ERC1155_ABI = [
+  { type: "function", name: "uri", stateMutability: "view", inputs: [{ name: "id", type: "uint256" }], outputs: [{ type: "string" }] },
+  { type: "function", name: "balanceOf", stateMutability: "view", inputs: [{ name: "account", type: "address" }, { name: "id", type: "uint256" }], outputs: [{ type: "uint256" }] },
+  { type: "function", name: "balanceOfBatch", stateMutability: "view", inputs: [{ name: "accounts", type: "address[]" }, { name: "ids", type: "uint256[]" }], outputs: [{ type: "uint256[]" }] },
+  { type: "function", name: "isApprovedForAll", stateMutability: "view", inputs: [{ name: "account", type: "address" }, { name: "operator", type: "address" }], outputs: [{ type: "bool" }] },
+  { type: "function", name: "setApprovalForAll", stateMutability: "nonpayable", inputs: [{ name: "operator", type: "address" }, { name: "approved", type: "bool" }], outputs: [] },
+  { type: "function", name: "safeTransferFrom", stateMutability: "nonpayable", inputs: [{ name: "from", type: "address" }, { name: "to", type: "address" }, { name: "id", type: "uint256" }, { name: "amount", type: "uint256" }, { name: "data", type: "bytes" }], outputs: [] },
+  { type: "function", name: "safeBatchTransferFrom", stateMutability: "nonpayable", inputs: [{ name: "from", type: "address" }, { name: "to", type: "address" }, { name: "ids", type: "uint256[]" }, { name: "amounts", type: "uint256[]" }, { name: "data", type: "bytes" }], outputs: [] },
+  { type: "event", name: "TransferSingle", inputs: [{ indexed: true, name: "operator", type: "address" }, { indexed: true, name: "from", type: "address" }, { indexed: true, name: "to", type: "address" }, { name: "id", type: "uint256" }, { name: "value", type: "uint256" }] },
+  { type: "event", name: "TransferBatch", inputs: [{ indexed: true, name: "operator", type: "address" }, { indexed: true, name: "from", type: "address" }, { indexed: true, name: "to", type: "address" }, { name: "ids", type: "uint256[]" }, { name: "values", type: "uint256[]" }] },
+  { type: "event", name: "ApprovalForAll", inputs: [{ indexed: true, name: "account", type: "address" }, { indexed: true, name: "operator", type: "address" }, { name: "approved", type: "bool" }] }
+];
+var WalletProxy = class {
+  constructor(engine, ensureReady) {
+    this.engine = engine;
+    this.ensureReady = ensureReady;
+  }
+  // ── Gated async operations ──────────────────────────────────────────────────
+  async create() {
+    await this.ensureReady();
+    return this.engine.create();
+  }
+  async importMnemonic(mnemonic, accountIndex) {
+    await this.ensureReady();
+    return this.engine.importMnemonic(mnemonic, accountIndex);
+  }
+  async importPrivateKey(privateKey) {
+    await this.ensureReady();
+    return this.engine.importPrivateKey(privateKey);
+  }
+  // ── Pass-throughs (sync, no network) ───────────────────────────────────────
+  address() {
+    return this.engine.address();
+  }
+  getSigner() {
+    return this.engine.getWalletClient();
+  }
+  getWalletClient() {
+    return this.engine.getWalletClient();
+  }
+  isConnected() {
+    return this.engine.isConnected();
+  }
+  hasExternalWallet() {
+    return this.engine.hasExternalWallet();
+  }
+  hasInternalWallet() {
+    return this.engine.hasInternalWallet();
+  }
+  connectExternal(c) {
+    this.engine.connectExternal(c);
+  }
+  disconnectExternal() {
+    this.engine.disconnectExternal();
+  }
+  disconnect() {
+    this.engine.disconnect();
+  }
+  async switchChain(chain) {
+    return this.engine.switchChain(chain);
+  }
+};
 var AwarizonWeb3 = class {
   constructor(config) {
+    // Contract instances are cached by address — same address returns same instance.
+    // Cache is cleared on switchChain() since contracts are chain-specific.
+    this._contractCache = /* @__PURE__ */ new Map();
+    // Named contract registry — register once, reference by name anywhere.
+    this._registry = /* @__PURE__ */ new Map();
+    if (!config.apiKey) throw new ApiKeyRequiredError();
     this.chain = resolveChain(config.chain);
     this.publicClient = viem.createPublicClient({
       chain: this.chain,
       transport: viem.http(config.rpcUrl)
     });
-    this.wallet = new walletEngine.WalletEngine({
+    this._engine = new walletEngine.WalletEngine({
       chain: this.chain,
       publicClient: this.publicClient,
       rpcUrl: config.rpcUrl
     });
+    this._txEngine = new txEngine.TransactionEngine(
+      this.publicClient,
+      () => this._engine.getWalletClient()
+    );
+    this._telemetry = new TelemetryClient(config.apiKey, config.baseUrl);
+    this.wallet = new WalletProxy(
+      this._engine,
+      () => this._telemetry.ensureValidated()
+    );
     if (config.signer) {
-      this.wallet.connectExternal(config.signer);
+      this._engine.connectExternal(config.signer);
     }
   }
   // ─── Wallet API surface ─────────────────────────────────────────────────────
-  /**
-   * Connect an external wallet client (wagmi, WalletConnect, viem, EIP-1193).
-   * The connected signer takes priority over any internal wallet.
-   *
-   * @example
-   * sdk.connectWallet(walletClient)
-   */
   connectWallet(walletClient) {
-    this.wallet.connectExternal(walletClient);
+    this._engine.connectExternal(walletClient);
     return this;
   }
-  /**
-   * Disconnect the externally-connected wallet.
-   * Falls back to the internal wallet if one is loaded.
-   */
   disconnectWallet() {
-    this.wallet.disconnectExternal();
+    this._engine.disconnectExternal();
     return this;
   }
-  /**
-   * Switch the active chain.
-   * Rebuilds the PublicClient and internal WalletClient for the new chain.
-   */
   async switchChain(chain) {
+    await this._telemetry.ensureValidated();
     const resolved = resolveChain(chain);
-    await this.wallet.switchChain(resolved);
+    await this._engine.switchChain(resolved);
+    this._contractCache.clear();
     return this;
   }
-  /**
-   * Returns a summary of the currently active wallet.
-   * @throws {WalletNotConnectedError} if no wallet is connected
-   */
   getWalletInfo() {
     return {
-      address: this.wallet.address(),
+      address: this._engine.address(),
       chain: this.chain,
-      isExternal: this.wallet.hasExternalWallet()
+      isExternal: this._engine.hasExternalWallet()
     };
   }
   // ─── Contract API ───────────────────────────────────────────────────────────
   /**
-   * Load a deployed smart contract and return a fully typed, ABI-powered
-   * instance. Every function in the ABI is exposed as a direct method.
-   *
-   * **Read functions** (view / pure) use the PublicClient — no signer needed.
-   * **Write functions** (nonpayable / payable) use the active WalletClient.
+   * Load a deployed contract and return a fully typed, ABI-powered instance.
+   * Validates the API key on the first call — subsequent calls are instant.
    *
-   * @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
+   * Results are cached by address — calling contract() twice with the same
+   * address and ABI object returns the same instance without rebuilding.
    */
   async contract(config) {
+    await this._telemetry.ensureValidated();
     if (!config.address || !config.abi) {
-      throw new Error("[awarizon/web3] sdk.contract() requires both address and abi");
+      throw new Error("[awarizon/web3] awarizon.contract() requires both address and abi");
     }
-    return buildContractInstance(
+    const key = config.address.toLowerCase();
+    const cached = this._contractCache.get(key);
+    if (cached && cached.abiRef === config.abi) return cached.instance;
+    const instance = buildContractInstance(
       config.address,
       config.abi,
       this.publicClient,
-      () => this.wallet.getWalletClient()
+      this._txEngine,
+      this._telemetry,
+      this.chain
     );
+    this._contractCache.set(key, { abiRef: config.abi, instance });
+    return instance;
+  }
+  /**
+   * Load multiple contracts in parallel. Validates the API key once, then
+   * instantiates all contracts concurrently.
+   *
+   * @example
+   * ```ts
+   * const [token, staking, nft] = await awarizon.contracts([
+   *   { address: tokenAddr, abi: ERC20_ABI },
+   *   { address: stakingAddr, abi: STAKING_ABI },
+   *   { address: nftAddr, abi: ERC721_ABI },
+   * ])
+   * ```
+   */
+  async contracts(configs) {
+    return Promise.all(configs.map((c) => this.contract(c)));
+  }
+  /**
+   * 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],
+   * })
+   * ```
+   */
+  async read(params) {
+    await this._telemetry.ensureValidated();
+    const start = Date.now();
+    try {
+      const result = await this._txEngine.read({
+        address: params.address,
+        abi: params.abi,
+        functionName: params.method,
+        args: params.args ?? []
+      });
+      this._telemetry.track({
+        type: "contract.read",
+        chain: this.chain.name,
+        chainId: this.chain.id,
+        functionName: params.method,
+        success: true,
+        durationMs: Date.now() - start,
+        ts: Date.now()
+      });
+      return result;
+    } catch (err) {
+      this._telemetry.track({
+        type: "contract.read",
+        chain: this.chain.name,
+        chainId: this.chain.id,
+        functionName: params.method,
+        success: false,
+        durationMs: Date.now() - start,
+        ts: Date.now()
+      });
+      throw err;
+    }
+  }
+  /**
+   * 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],
+   * })
+   * ```
+   */
+  async write(params) {
+    await this._telemetry.ensureValidated();
+    const start = Date.now();
+    try {
+      const result = await this._txEngine.write({
+        address: params.address,
+        abi: params.abi,
+        functionName: params.method,
+        args: params.args ?? [],
+        value: params.value,
+        gas: params.gas
+      });
+      this._telemetry.track({
+        type: "contract.write",
+        chain: this.chain.name,
+        chainId: this.chain.id,
+        functionName: params.method,
+        success: true,
+        durationMs: Date.now() - start,
+        ts: Date.now()
+      });
+      return result;
+    } catch (err) {
+      this._telemetry.track({
+        type: "contract.write",
+        chain: this.chain.name,
+        chainId: this.chain.id,
+        functionName: params.method,
+        success: false,
+        durationMs: Date.now() - start,
+        ts: Date.now()
+      });
+      throw err;
+    }
+  }
+  /**
+   * 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] },
+   * ])
+   * ```
+   */
+  async multicall(calls) {
+    await this._telemetry.ensureValidated();
+    const contracts = calls.map((c) => ({
+      address: c.address,
+      abi: c.abi,
+      functionName: c.method,
+      args: c.args ?? []
+    }));
+    try {
+      const results = await this.publicClient.multicall({
+        contracts,
+        allowFailure: false
+      });
+      return results;
+    } catch {
+      return Promise.all(
+        contracts.map(
+          (c) => this.publicClient.readContract(c)
+        )
+      );
+    }
+  }
+  // ─── ERC Standard Clients ───────────────────────────────────────────────────
+  /**
+   * Load an ERC-20 token with fully typed methods — no ABI import needed.
+   *
+   * ```ts
+   * const token = await awarizon.erc20("0x...")
+   * const balance = await token.balanceOf(userAddress)
+   * const symbol  = await token.symbol()
+   * await token.transfer(recipient, 100n)
+   * ```
+   */
+  async erc20(address) {
+    const instance = await this.contract({ address, abi: ERC20_ABI });
+    return instance;
   }
   /**
-   * Returns the chain ID of the current chain.
-   * Useful for runtime network validation.
+   * Load an ERC-721 NFT contract with fully typed methods — no ABI import needed.
+   *
+   * ```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)
+   * ```
    */
+  async erc721(address) {
+    const instance = await this.contract({ address, abi: ERC721_ABI });
+    return instance;
+  }
+  /**
+   * 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")
+   * ```
+   */
+  async erc1155(address) {
+    const instance = await this.contract({ address, abi: ERC1155_ABI });
+    return instance;
+  }
+  // ─── Named Contract Registry ────────────────────────────────────────────────
+  /**
+   * 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, config) {
+    this._registry.set(name, config);
+    return 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)
+   * ```
+   */
+  async use(name) {
+    const config = this._registry.get(name);
+    if (!config) {
+      const registered = [...this._registry.keys()].join(", ") || "none";
+      throw new Error(
+        `[awarizon/web3] Contract "${name}" is not registered.
+Call awarizon.register("${name}", { address, abi }) first.
+Currently registered: ${registered}`
+      );
+    }
+    return this.contract(config);
+  }
+  /**
+   * Remove a registered contract from the registry.
+   *
+   * ```ts
+   * awarizon.unregister("USDC")
+   * ```
+   */
+  unregister(name) {
+    this._registry.delete(name);
+    return this;
+  }
+  /**
+   * Return all registered contract names.
+   */
+  registeredContracts() {
+    return [...this._registry.keys()];
+  }
+  // ─── Accessors ──────────────────────────────────────────────────────────────
   get chainId() {
     return this.chain.id;
   }
+  get isConnected() {
+    return this._engine.isConnected();
+  }
   /**
-   * Check whether any wallet (internal or external) is connected.
+   * Flush pending telemetry and stop background timers.
+   * Call when tearing down a long-lived SDK instance (e.g. on server shutdown).
    */
-  get isConnected() {
-    return this.wallet.isConnected();
+  async destroy() {
+    await this._telemetry.destroy();
   }
 };
 
@@ -315,6 +805,26 @@ Object.defineProperty(exports, "WalletNotConnectedError", {
   enumerable: true,
   get: function () { return walletEngine.WalletNotConnectedError; }
 });
+Object.defineProperty(exports, "ContractExecutionError", {
+  enumerable: true,
+  get: function () { return txEngine.ContractExecutionError; }
+});
+Object.defineProperty(exports, "GasEstimationError", {
+  enumerable: true,
+  get: function () { return txEngine.GasEstimationError; }
+});
+Object.defineProperty(exports, "SimulationError", {
+  enumerable: true,
+  get: function () { return txEngine.SimulationError; }
+});
+Object.defineProperty(exports, "TransactionEngine", {
+  enumerable: true,
+  get: function () { return txEngine.TransactionEngine; }
+});
+Object.defineProperty(exports, "TransactionTimeoutError", {
+  enumerable: true,
+  get: function () { return txEngine.TransactionTimeoutError; }
+});
 Object.defineProperty(exports, "DuplicateFunctionError", {
   enumerable: true,
   get: function () { return abiEngine.DuplicateFunctionError; }
@@ -347,31 +857,17 @@ Object.defineProperty(exports, "parseABI", {
   enumerable: true,
   get: function () { return abiEngine.parseABI; }
 });
-Object.defineProperty(exports, "ContractExecutionError", {
-  enumerable: true,
-  get: function () { return txEngine.ContractExecutionError; }
-});
-Object.defineProperty(exports, "GasEstimationError", {
-  enumerable: true,
-  get: function () { return txEngine.GasEstimationError; }
-});
-Object.defineProperty(exports, "SimulationError", {
-  enumerable: true,
-  get: function () { return txEngine.SimulationError; }
-});
-Object.defineProperty(exports, "TransactionEngine", {
-  enumerable: true,
-  get: function () { return txEngine.TransactionEngine; }
-});
-Object.defineProperty(exports, "TransactionTimeoutError", {
-  enumerable: true,
-  get: function () { return txEngine.TransactionTimeoutError; }
-});
+exports.ApiKeyRequiredError = ApiKeyRequiredError;
 exports.AwarizonWeb3 = AwarizonWeb3;
 exports.CHAINS = CHAINS;
 exports.ContractNotLoadedError = ContractNotLoadedError;
+exports.ERC1155_ABI = ERC1155_ABI;
+exports.ERC20_ABI = ERC20_ABI;
+exports.ERC721_ABI = ERC721_ABI;
+exports.InvalidApiKeyError = InvalidApiKeyError;
 exports.NetworkMismatchError = NetworkMismatchError;
 exports.ProviderError = ProviderError;
+exports.TelemetryClient = TelemetryClient;
 exports.UnsupportedChainError = UnsupportedChainError;
 exports.getSupportedChainIds = getSupportedChainIds;
 exports.resolveChain = resolveChain;