agentwallet-sdk 3.1.2 → 3.2.0

package/dist/identity/erc6551.d.ts

@@ -0,0 +1,441 @@
+/**
+ * MIT License
+ *
+ * Copyright (c) 2026 AgentNexus / agentwallet-sdk contributors
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+/**
+ * ERC-6551: Token Bound Accounts (TBA)
+ *
+ * Implements the ERC-6551 registry interaction layer, enabling any ERC-721 NFT
+ * to own a smart contract wallet. Each agent NFT (ERC-8004) gets a unique,
+ * deterministic TBA address derived from its contract + tokenId + chainId.
+ *
+ * Architecture:
+ *   ERC-8004 NFT → ERC-6551 TBA → AgentWallet (x402 + payments) → TaskBridge earnings
+ *
+ * Canonical registry: 0x000000006551c19487814612785009DA0394A50 (all EVM chains)
+ * Spec: https://eips.ethereum.org/EIPS/eip-6551
+ *
+ * @module identity/erc6551
+ */
+import { type Address, type Hash, type Hex, type WalletClient, type Chain } from 'viem';
+/**
+ * Canonical ERC-6551 Registry address — same on all EVM chains.
+ * Deployed via CREATE2 with deterministic address per EIP-6551.
+ */
+export declare const ERC6551_REGISTRY_ADDRESS: Address;
+/**
+ * Default ERC-6551 account implementation deployed by the reference implementation team.
+ * This is the Tokenbound reference implementation on Base mainnet.
+ * Audited by OpenZeppelin. Source: https://github.com/tokenbound/reference
+ */
+export declare const ERC6551_DEFAULT_IMPLEMENTATION: Address;
+/**
+ * Base mainnet chain ID.
+ */
+export declare const BASE_CHAIN_ID = 8453;
+/**
+ * Default salt for TBA derivation (matches Tokenbound reference tooling default).
+ */
+export declare const DEFAULT_SALT: Hex;
+/**
+ * Canonical ERC-6551 Registry ABI from EIP-6551 specification.
+ * Source: https://eips.ethereum.org/EIPS/eip-6551
+ */
+export declare const ERC6551RegistryAbi: readonly [{
+    readonly name: "createAccount";
+    readonly type: "function";
+    readonly stateMutability: "nonpayable";
+    readonly inputs: readonly [{
+        readonly name: "implementation";
+        readonly type: "address";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokenContract";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "account";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "implementation";
+        readonly type: "address";
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokenContract";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "AccountCreated";
+    readonly type: "event";
+    readonly inputs: readonly [{
+        readonly name: "account";
+        readonly type: "address";
+        readonly indexed: false;
+    }, {
+        readonly name: "implementation";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "salt";
+        readonly type: "bytes32";
+        readonly indexed: false;
+    }, {
+        readonly name: "chainId";
+        readonly type: "uint256";
+        readonly indexed: false;
+    }, {
+        readonly name: "tokenContract";
+        readonly type: "address";
+        readonly indexed: true;
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+        readonly indexed: true;
+    }];
+}];
+/**
+ * Minimal ABI for the ERC-6551 Account (TBA) — the wallet owned by the NFT.
+ * Implements IERC6551Account + IERC6551Executable per the reference implementation.
+ */
+export declare const ERC6551AccountAbi: readonly [{
+    readonly name: "execute";
+    readonly type: "function";
+    readonly stateMutability: "payable";
+    readonly inputs: readonly [{
+        readonly name: "to";
+        readonly type: "address";
+    }, {
+        readonly name: "value";
+        readonly type: "uint256";
+    }, {
+        readonly name: "data";
+        readonly type: "bytes";
+    }, {
+        readonly name: "operation";
+        readonly type: "uint8";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "result";
+        readonly type: "bytes";
+    }];
+}, {
+    readonly name: "token";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "chainId";
+        readonly type: "uint256";
+    }, {
+        readonly name: "tokenContract";
+        readonly type: "address";
+    }, {
+        readonly name: "tokenId";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "owner";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "address";
+    }];
+}, {
+    readonly name: "state";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [];
+    readonly outputs: readonly [{
+        readonly name: "";
+        readonly type: "uint256";
+    }];
+}, {
+    readonly name: "isValidSigner";
+    readonly type: "function";
+    readonly stateMutability: "view";
+    readonly inputs: readonly [{
+        readonly name: "signer";
+        readonly type: "address";
+    }, {
+        readonly name: "context";
+        readonly type: "bytes";
+    }];
+    readonly outputs: readonly [{
+        readonly name: "magicValue";
+        readonly type: "bytes4";
+    }];
+}];
+/**
+ * Configuration for the ERC6551Client.
+ */
+export interface TBAConfig {
+    /** ERC-6551 registry address. Defaults to canonical address if omitted. */
+    registryAddress?: Address;
+    /** TBA implementation contract address. Defaults to Tokenbound reference impl. */
+    implementationAddress?: Address;
+    /** Target chain. Defaults to 'base' (Base mainnet, chainId 8453). */
+    chain?: 'base' | 'base-sepolia' | 'ethereum' | 'arbitrum' | 'polygon';
+    /** RPC URL override. Uses chain default if omitted. */
+    rpcUrl?: string;
+}
+/**
+ * A fully resolved Token Bound Account.
+ */
+export interface TBAAccount {
+    /** The TBA's smart contract address (deterministic via CREATE2). */
+    address: Address;
+    /** The ERC-721 NFT contract that owns this TBA. */
+    nftContract: Address;
+    /** The ERC-721 token ID that owns this TBA. */
+    tokenId: bigint;
+    /** Salt used for TBA derivation. */
+    salt: Hex;
+    /** Chain ID on which this TBA lives. */
+    chainId: number;
+    /** Implementation contract used for this TBA. */
+    implementation: Address;
+    /** Whether this TBA is deployed on-chain (vs. just computed). */
+    isDeployed: boolean;
+    /** Current owner of the TBA (= NFT owner). Null if not yet resolved. */
+    owner: Address | null;
+}
+/**
+ * Result of an ERC-6551 TBA execution call.
+ */
+export interface TBAExecuteResult {
+    /** Transaction hash of the execute() call. */
+    txHash: Hash;
+    /** ABI-encoded return data from the called contract. */
+    returnData: Hex | null;
+}
+/**
+ * Parameters for executing a call from a TBA.
+ */
+export interface TBAExecuteParams {
+    /** Target contract address. */
+    to: Address;
+    /** ETH value to send (in wei). */
+    value?: bigint;
+    /** Calldata for the target. Use '0x' for plain ETH transfers. */
+    data?: Hex;
+    /** Operation type: 0 = CALL (default), 1 = DELEGATECALL. */
+    operation?: 0 | 1;
+}
+/**
+ * ERC-6551 Token Bound Account client.
+ *
+ * Enables any ERC-721 NFT to own a smart contract wallet (TBA). Used to attach
+ * an autonomous spending account to every agent identity NFT (ERC-8004).
+ *
+ * All write operations require a WalletClient — keys never leave the caller's device.
+ * The TBA address is deterministic: same NFT + same salt = same address, always.
+ *
+ * @example
+ * ```typescript
+ * import { ERC6551Client } from 'agentwallet-sdk';
+ *
+ * const client = new ERC6551Client({ chain: 'base' });
+ *
+ * // Compute the TBA address before deploying
+ * const tbaAddress = await client.getTBAAddress('0xNFTContract', 1n);
+ *
+ * // Deploy it on-chain
+ * const { address } = await client.createTBA(walletClient, '0xNFTContract', 1n);
+ *
+ * // Execute a call from the TBA (the agent acts)
+ * const result = await client.executeTBA(walletClient, address, {
+ *   to: '0xTarget',
+ *   value: parseEther('0.01'),
+ *   data: '0x',
+ * });
+ * ```
+ */
+export declare class ERC6551Client {
+    private readonly publicClient;
+    private readonly registryAddress;
+    private readonly implementationAddress;
+    private readonly chain;
+    private readonly chainId;
+    constructor(config?: TBAConfig);
+    /**
+     * Compute the deterministic TBA address for an NFT (off-chain, no RPC needed).
+     *
+     * Uses the ERC-6551 registry's CREATE2 formula:
+     *   address = keccak256(0xff ++ registry ++ salt' ++ keccak256(initCode))
+     * where salt' and initCode encode the chain + token details.
+     *
+     * This mirrors the registry's on-chain `account()` view function but does not
+     * require a network call. Use `getTBAAddress()` for on-chain verification.
+     *
+     * @param nftContract - Address of the ERC-721 contract
+     * @param tokenId - Token ID of the agent NFT
+     * @param salt - Optional salt (defaults to 0x000...0)
+     * @returns Deterministic TBA address
+     */
+    computeTBAAddress(nftContract: Address, tokenId: bigint, salt?: Hex): Address;
+    /**
+     * Get the deterministic TBA address for an NFT via on-chain registry view call.
+     *
+     * Calls the registry's `account()` view function — authoritative and gas-free.
+     * For offline computation, use `computeTBAAddress()` instead.
+     *
+     * @param nftContract - Address of the ERC-721 contract
+     * @param tokenId - Token ID of the agent NFT
+     * @param salt - Optional salt (defaults to 0x000...0)
+     * @returns Deterministic TBA address from registry
+     */
+    getTBAAddress(nftContract: Address, tokenId: bigint, salt?: Hex): Promise<Address>;
+    /**
+     * Deploy a Token Bound Account for an agent NFT.
+     *
+     * Calls `createAccount()` on the ERC-6551 registry. If the TBA is already
+     * deployed, the registry returns the existing address without reverting.
+     * Idempotent and safe to call multiple times.
+     *
+     * Non-custodial: the walletClient signs the transaction locally.
+     * The deployer does NOT need to own the NFT — anyone can deploy a TBA.
+     *
+     * @param walletClient - WalletClient to sign the deployment transaction
+     * @param nftContract - Address of the ERC-721 contract
+     * @param tokenId - Token ID of the agent NFT
+     * @param salt - Optional salt for address uniqueness (defaults to 0x000...0)
+     * @returns Deployed TBAAccount with address and deployment metadata
+     */
+    createTBA(walletClient: WalletClient, nftContract: Address, tokenId: bigint, salt?: Hex): Promise<TBAAccount>;
+    /**
+     * Execute a call from a Token Bound Account (the agent acts autonomously).
+     *
+     * The TBA's `execute()` function routes the call through the NFT owner
+     * authorization check before dispatching to the target contract.
+     *
+     * Only the NFT owner (or an approved ERC-6551 operator) can execute calls.
+     * This is the primary mechanism by which agents interact with DeFi protocols,
+     * TaskBridge, and other on-chain systems.
+     *
+     * @param walletClient - WalletClient owning the NFT (authorized to execute)
+     * @param tbaAddress - Address of the deployed TBA
+     * @param params - Call parameters (to, value, data, operation)
+     * @returns Transaction hash and raw return data
+     *
+     * @example
+     * ```typescript
+     * // Agent pays for a TaskBridge task
+     * const result = await client.executeTBA(walletClient, tbaAddress, {
+     *   to: TASKBRIDGE_CONTRACT,
+     *   value: parseEther('0.1'),
+     *   data: encodeFunctionData({ abi: TaskBridgeAbi, functionName: 'bidTask', args: [taskId] }),
+     * });
+     * ```
+     */
+    executeTBA(walletClient: WalletClient, tbaAddress: Address, params: TBAExecuteParams): Promise<TBAExecuteResult>;
+    /**
+     * Check whether a TBA is deployed on-chain.
+     *
+     * A TBA address can be computed deterministically before deployment.
+     * This function checks if the contract actually exists at that address.
+     *
+     * @param tbaAddress - TBA address to check
+     * @returns true if code exists at tbaAddress (TBA is deployed)
+     */
+    isTBADeployed(tbaAddress: Address): Promise<boolean>;
+    /**
+     * Get the current owner of a Token Bound Account.
+     *
+     * Returns the address that owns the underlying NFT, which is the authorized
+     * principal for this agent TBA. This is the human (or parent agent) who
+     * controls the agent.
+     *
+     * @param tbaAddress - Address of the deployed TBA
+     * @returns Address of the NFT owner (human principal)
+     */
+    getTBAOwner(tbaAddress: Address): Promise<Address>;
+    /**
+     * Get the full TBA account details for an NFT.
+     *
+     * Computes the deterministic address, checks deployment status, and resolves
+     * the owner if deployed. A single call to get everything you need about a TBA.
+     *
+     * @param nftContract - ERC-721 contract address
+     * @param tokenId - Token ID
+     * @param salt - Optional salt (defaults to 0x000...0)
+     * @returns Full TBAAccount details
+     */
+    getTBAAccount(nftContract: Address, tokenId: bigint, salt?: Hex): Promise<TBAAccount>;
+    /**
+     * Get the NFT token info bound to a deployed TBA.
+     *
+     * Calls the TBA's `token()` function to retrieve the NFT contract + tokenId
+     * that governs ownership of this account.
+     *
+     * @param tbaAddress - Address of the deployed TBA
+     * @returns Chain ID, NFT contract, and token ID
+     */
+    getTBAToken(tbaAddress: Address): Promise<{
+        chainId: bigint;
+        tokenContract: Address;
+        tokenId: bigint;
+    }>;
+    /**
+     * Get the current execution state (nonce) of a TBA.
+     * Increments on each execute() call — use for replay protection.
+     *
+     * @param tbaAddress - Address of the deployed TBA
+     * @returns Current state value (uint256)
+     */
+    getTBAState(tbaAddress: Address): Promise<bigint>;
+    /** Registry address used by this client. */
+    get registry(): Address;
+    /** Implementation address used by this client. */
+    get implementation(): Address;
+    /** Chain this client is connected to. */
+    get connectedChain(): Chain;
+    /** Chain ID this client is connected to. */
+    get connectedChainId(): number;
+}
+//# sourceMappingURL=erc6551.d.ts.map

package/dist/identity/erc6551.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"erc6551.d.ts","sourceRoot":"","sources":["../../src/identity/erc6551.ts"],"names":[],"mappings":"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"}