agentwallet-sdk 3.1.1 → 3.2.0

package/dist/identity/agent-identity.d.ts

@@ -0,0 +1,276 @@
+/**
+ * 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.
+ */
+/**
+ * AgentIdentity — Unified ERC-8004 + ERC-6551 Identity Facade
+ *
+ * Combines the ERC-8004 Identity Registry (on-chain agent registration / NFT)
+ * with the ERC-6551 Token Bound Account (TBA) system into a single, ergonomic
+ * class. One call to register your agent, one call to deploy its autonomous wallet,
+ * and a single execute() for on-chain actions.
+ *
+ * Architecture:
+ *   AgentIdentity
+ *     ├── ERC8004Client  → registers agent NFT, manages off-chain metadata
+ *     └── ERC6551Client  → deploys TBA, executes calls from NFT-owned wallet
+ *
+ * @module identity/agent-identity
+ */
+import type { WalletClient, Address, Hex } from 'viem';
+import { ERC8004Client, type AgentRegistrationFile, type RegistrationResult } from './erc8004.js';
+import { ERC6551Client, type TBAAccount, type TBAExecuteParams, type TBAExecuteResult } from './erc6551.js';
+/**
+ * Supported chain names for AgentIdentity.
+ */
+export type AgentIdentityChain = 'base' | 'base-sepolia' | 'ethereum' | 'arbitrum' | 'polygon';
+/**
+ * Configuration for AgentIdentity.
+ */
+export interface AgentIdentityConfig {
+    /**
+     * The agent's signing WalletClient (controls the NFT and TBA).
+     * Keys never leave the device — all signing is local.
+     */
+    wallet: WalletClient;
+    /**
+     * Target chain. Defaults to 'base' (Base mainnet).
+     */
+    chain?: AgentIdentityChain;
+    /**
+     * ERC-8004 Identity Registry contract address.
+     * Required for ERC-8004 registration. Omit if only using ERC-6551.
+     */
+    registryAddress?: Address;
+    /**
+     * ERC-6551 registry override. Defaults to canonical registry.
+     * You almost never need to change this.
+     */
+    tbaRegistryAddress?: Address;
+    /**
+     * ERC-6551 account implementation override.
+     * Defaults to Tokenbound reference implementation on Base.
+     */
+    tbaImplementationAddress?: Address;
+    /**
+     * RPC URL override for both ERC-8004 and ERC-6551 clients.
+     */
+    rpcUrl?: string;
+    /**
+     * Salt for TBA derivation. Defaults to 0x000...0.
+     * Change this to create multiple TBAs for the same NFT.
+     */
+    tbaSalt?: Hex;
+}
+/**
+ * Full resolved agent identity state.
+ */
+export interface AgentIdentityState {
+    /** On-chain ERC-721 agent token ID (null before registration). */
+    agentId: bigint | null;
+    /** TBA address (null before deployTBA()). */
+    tbaAddress: Address | null;
+    /** Whether the ERC-8004 NFT is registered on-chain. */
+    isRegistered: boolean;
+    /** Whether the ERC-6551 TBA is deployed on-chain. */
+    isTBADeployed: boolean;
+    /** NFT owner address (= wallet account address). */
+    owner: Address | null;
+}
+/**
+ * AgentIdentity — unified ERC-8004 + ERC-6551 identity manager.
+ *
+ * Provides a single interface to manage an agent's complete on-chain identity:
+ * - ERC-8004: NFT registration with metadata and service endpoints
+ * - ERC-6551: Token Bound Account (TBA) — the agent's autonomous wallet
+ *
+ * @example
+ * ```typescript
+ * import { AgentIdentity } from 'agentwallet-sdk';
+ * import { createWalletClient, http } from 'viem';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ * import { base } from 'viem/chains';
+ *
+ * const wallet = createWalletClient({
+ *   account: privateKeyToAccount('0xYOUR_PRIVATE_KEY'),
+ *   chain: base,
+ *   transport: http(),
+ * });
+ *
+ * const identity = new AgentIdentity({
+ *   wallet,
+ *   chain: 'base',
+ *   registryAddress: '0xYOUR_ERC8004_REGISTRY',
+ * });
+ *
+ * // 1. Register agent NFT (ERC-8004)
+ * const { agentId } = await identity.register({
+ *   name: 'MyTradingAgent',
+ *   description: 'Autonomous DeFi trading agent',
+ *   x402Support: true,
+ * });
+ *
+ * // 2. Deploy TBA (ERC-6551) — NFT now owns an autonomous wallet
+ * await identity.deployTBA();
+ * console.log('Agent TBA:', identity.tbaAddress);
+ *
+ * // 3. Execute from TBA (agent acts on-chain)
+ * await identity.execute({
+ *   to: TASKBRIDGE_CONTRACT,
+ *   value: parseEther('0.01'),
+ *   data: encodedCalldata,
+ * });
+ * ```
+ */
+export declare class AgentIdentity {
+    private readonly wallet;
+    private readonly chain;
+    private readonly tbaSalt;
+    private readonly erc8004;
+    private readonly erc6551;
+    private _agentId;
+    private _nftContract;
+    private _tbaAccount;
+    constructor(config: AgentIdentityConfig);
+    /**
+     * Register this agent as an ERC-8004 identity NFT on-chain.
+     *
+     * Builds a spec-compliant agent registration file and mints an ERC-721 NFT
+     * via the ERC-8004 Identity Registry. After registration, the NFT represents
+     * the agent's permanent, portable on-chain identity.
+     *
+     * Non-custodial: the wallet signs the registration transaction locally.
+     *
+     * @param metadata - Agent metadata for the registration file
+     * @param agentURI - Optional external URI (IPFS/HTTPS). Auto-builds data URI if omitted.
+     * @returns Registration result with txHash and agentId
+     * @throws Error if no registryAddress was provided in config
+     */
+    register(metadata: Omit<AgentRegistrationFile, 'type'>, agentURI?: string): Promise<RegistrationResult>;
+    /**
+     * Restore a previously registered agent identity.
+     *
+     * Use this when you already have an agentId from a prior session.
+     * Sets the internal agentId so deployTBA() and execute() work correctly.
+     *
+     * @param agentId - Previously registered ERC-8004 token ID
+     * @param nftContract - The ERC-8004 registry contract (= registryAddress in config)
+     */
+    setAgentId(agentId: bigint, nftContract?: Address): void;
+    /**
+     * Deploy the Token Bound Account for this agent's NFT.
+     *
+     * The TBA address is deterministic — you can compute it before deployment
+     * via `computeTBAAddress()`. This call deploys the actual smart contract at
+     * that address, enabling the agent to act autonomously on-chain.
+     *
+     * Idempotent: calling deployTBA() on an already-deployed TBA is safe.
+     *
+     * @param nftContract - Override: NFT contract to bind the TBA to.
+     *   Defaults to the registryAddress (ERC-8004 registry is also the NFT contract).
+     * @param tokenId - Override: token ID. Defaults to the registered agentId.
+     * @returns Deployed TBAAccount
+     * @throws Error if agentId not set (call register() first or use setAgentId())
+     */
+    deployTBA(nftContract?: Address, tokenId?: bigint): Promise<TBAAccount>;
+    /**
+     * Compute the deterministic TBA address without deploying.
+     *
+     * Useful for pre-computing the address to fund it before deployment,
+     * or to check if a TBA already exists.
+     *
+     * @param nftContract - NFT contract (defaults to registryAddress)
+     * @param tokenId - Token ID (defaults to agentId)
+     * @returns Deterministic TBA address
+     */
+    computeTBAAddress(nftContract?: Address, tokenId?: bigint): Address;
+    /**
+     * Load TBA state without deploying — useful for resuming a session.
+     * Sets internal TBA state so execute() works without re-deploying.
+     *
+     * @param nftContract - NFT contract (defaults to registryAddress)
+     * @param tokenId - Token ID (defaults to agentId)
+     */
+    loadTBA(nftContract?: Address, tokenId?: bigint): Promise<TBAAccount>;
+    /**
+     * Execute a call from the agent's TBA (the agent acts autonomously).
+     *
+     * Routes the call through the TBA's `execute()` function, which verifies
+     * the caller owns the NFT before dispatching to the target contract.
+     *
+     * @param params - Call parameters (to, value, data, operation)
+     * @returns Transaction hash and return data
+     * @throws Error if TBA not deployed (call deployTBA() first)
+     *
+     * @example
+     * ```typescript
+     * // Agent bids on a TaskBridge task
+     * await identity.execute({
+     *   to: TASKBRIDGE_ADDRESS,
+     *   value: 0n,
+     *   data: encodeFunctionData({
+     *     abi: TaskBridgeAbi,
+     *     functionName: 'bid',
+     *     args: [taskId, bidAmount],
+     *   }),
+     * });
+     * ```
+     */
+    execute(params: TBAExecuteParams): Promise<TBAExecuteResult>;
+    /**
+     * The agent's ERC-8004 token ID (null before registration).
+     */
+    get agentId(): bigint | null;
+    /**
+     * The agent's TBA address (null before deployTBA() or loadTBA()).
+     */
+    get tbaAddress(): Address | null;
+    /**
+     * Full TBA account details (null before deployTBA() or loadTBA()).
+     */
+    get tbaAccount(): TBAAccount | null;
+    /**
+     * Whether the agent's ERC-8004 NFT is registered.
+     */
+    get isRegistered(): boolean;
+    /**
+     * Whether the agent's TBA is deployed on-chain.
+     */
+    get isTBADeployed(): boolean;
+    /**
+     * The wallet account address (human principal / NFT owner).
+     */
+    get ownerAddress(): Address | null;
+    /**
+     * Full identity state snapshot.
+     */
+    get state(): AgentIdentityState;
+    /**
+     * Direct access to the underlying ERC6551Client for advanced usage.
+     */
+    get erc6551Client(): ERC6551Client;
+    /**
+     * Direct access to the underlying ERC8004Client (null if no registryAddress provided).
+     */
+    get erc8004Client(): ERC8004Client | null;
+}
+//# sourceMappingURL=agent-identity.d.ts.map

package/dist/identity/agent-identity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-identity.d.ts","sourceRoot":"","sources":["../../src/identity/agent-identity.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAQ,GAAG,EAAE,MAAM,MAAM,CAAC;AAE7D,OAAO,EACL,aAAa,EAEb,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACxB,MAAM,cAAc,CAAC;AAEtB,OAAO,EACL,aAAa,EAGb,KAAK,UAAU,EACf,KAAK,gBAAgB,EACrB,KAAK,gBAAgB,EACtB,MAAM,cAAc,CAAC;AAItB;;GAEG;AACH,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAAC;AAE/F;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC;;;OAGG;IACH,MAAM,EAAE,YAAY,CAAC;IAErB;;OAEG;IACH,KAAK,CAAC,EAAE,kBAAkB,CAAC;IAE3B;;;OAGG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B;;;OAGG;IACH,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAE7B;;;OAGG;IACH,wBAAwB,CAAC,EAAE,OAAO,CAAC;IAEnC;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAEhB;;;OAGG;IACH,OAAO,CAAC,EAAE,GAAG,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,6CAA6C;IAC7C,UAAU,EAAE,OAAO,GAAG,IAAI,CAAC;IAC3B,uDAAuD;IACvD,YAAY,EAAE,OAAO,CAAC;IACtB,qDAAqD;IACrD,aAAa,EAAE,OAAO,CAAC;IACvB,oDAAoD;IACpD,KAAK,EAAE,OAAO,GAAG,IAAI,CAAC;CACvB;AAID;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAM;IAE9B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAgB;IAExC,OAAO,CAAC,QAAQ,CAAuB;IACvC,OAAO,CAAC,YAAY,CAAwB;IAC5C,OAAO,CAAC,WAAW,CAA2B;gBAElC,MAAM,EAAE,mBAAmB;IA4BvC;;;;;;;;;;;;;OAaG;IACG,QAAQ,CACZ,QAAQ,EAAE,IAAI,CAAC,qBAAqB,EAAE,MAAM,CAAC,EAC7C,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,kBAAkB,CAAC;IAqB9B;;;;;;;;OAQG;IACH,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,OAAO,GAAG,IAAI;IAOxD;;;;;;;;;;;;;;OAcG;IACG,SAAS,CACb,WAAW,CAAC,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,UAAU,CAAC;IA4BtB;;;;;;;;;OASG;IACH,iBAAiB,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO;IAWnE;;;;;;OAMG;IACG,OAAO,CAAC,WAAW,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC;IAmB3E;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,OAAO,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAalE;;OAEG;IACH,IAAI,OAAO,IAAI,MAAM,GAAG,IAAI,CAE3B;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,GAAG,IAAI,CAE/B;IAED;;OAEG;IACH,IAAI,UAAU,IAAI,UAAU,GAAG,IAAI,CAElC;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,CAE1B;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,OAAO,CAE3B;IAED;;OAEG;IACH,IAAI,YAAY,IAAI,OAAO,GAAG,IAAI,CAEjC;IAED;;OAEG;IACH,IAAI,KAAK,IAAI,kBAAkB,CAQ9B;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,aAAa,CAEjC;IAED;;OAEG;IACH,IAAI,aAAa,IAAI,aAAa,GAAG,IAAI,CAExC;CACF"}

package/dist/identity/agent-identity.js

@@ -0,0 +1,300 @@
+/**
+ * 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.
+ */
+import { ERC8004Client, } from './erc8004.js';
+import { ERC6551Client, DEFAULT_SALT, } from './erc6551.js';
+// ─── AgentIdentity ────────────────────────────────────────────────────────────
+/**
+ * AgentIdentity — unified ERC-8004 + ERC-6551 identity manager.
+ *
+ * Provides a single interface to manage an agent's complete on-chain identity:
+ * - ERC-8004: NFT registration with metadata and service endpoints
+ * - ERC-6551: Token Bound Account (TBA) — the agent's autonomous wallet
+ *
+ * @example
+ * ```typescript
+ * import { AgentIdentity } from 'agentwallet-sdk';
+ * import { createWalletClient, http } from 'viem';
+ * import { privateKeyToAccount } from 'viem/accounts';
+ * import { base } from 'viem/chains';
+ *
+ * const wallet = createWalletClient({
+ *   account: privateKeyToAccount('0xYOUR_PRIVATE_KEY'),
+ *   chain: base,
+ *   transport: http(),
+ * });
+ *
+ * const identity = new AgentIdentity({
+ *   wallet,
+ *   chain: 'base',
+ *   registryAddress: '0xYOUR_ERC8004_REGISTRY',
+ * });
+ *
+ * // 1. Register agent NFT (ERC-8004)
+ * const { agentId } = await identity.register({
+ *   name: 'MyTradingAgent',
+ *   description: 'Autonomous DeFi trading agent',
+ *   x402Support: true,
+ * });
+ *
+ * // 2. Deploy TBA (ERC-6551) — NFT now owns an autonomous wallet
+ * await identity.deployTBA();
+ * console.log('Agent TBA:', identity.tbaAddress);
+ *
+ * // 3. Execute from TBA (agent acts on-chain)
+ * await identity.execute({
+ *   to: TASKBRIDGE_CONTRACT,
+ *   value: parseEther('0.01'),
+ *   data: encodedCalldata,
+ * });
+ * ```
+ */
+export class AgentIdentity {
+    constructor(config) {
+        this._agentId = null;
+        this._nftContract = null;
+        this._tbaAccount = null;
+        this.wallet = config.wallet;
+        this.chain = config.chain ?? 'base';
+        this.tbaSalt = config.tbaSalt ?? DEFAULT_SALT;
+        // ERC-8004 client — optional (some agents may only use ERC-6551)
+        if (config.registryAddress) {
+            this.erc8004 = new ERC8004Client({
+                registryAddress: config.registryAddress,
+                chain: this.chain,
+                rpcUrl: config.rpcUrl,
+            });
+            this._nftContract = config.registryAddress;
+        }
+        else {
+            this.erc8004 = null;
+        }
+        // ERC-6551 client — always initialized
+        this.erc6551 = new ERC6551Client({
+            chain: this.chain,
+            registryAddress: config.tbaRegistryAddress,
+            implementationAddress: config.tbaImplementationAddress,
+            rpcUrl: config.rpcUrl,
+        });
+    }
+    // ─── ERC-8004: Registration ───────────────────────────────────────────────
+    /**
+     * Register this agent as an ERC-8004 identity NFT on-chain.
+     *
+     * Builds a spec-compliant agent registration file and mints an ERC-721 NFT
+     * via the ERC-8004 Identity Registry. After registration, the NFT represents
+     * the agent's permanent, portable on-chain identity.
+     *
+     * Non-custodial: the wallet signs the registration transaction locally.
+     *
+     * @param metadata - Agent metadata for the registration file
+     * @param agentURI - Optional external URI (IPFS/HTTPS). Auto-builds data URI if omitted.
+     * @returns Registration result with txHash and agentId
+     * @throws Error if no registryAddress was provided in config
+     */
+    async register(metadata, agentURI) {
+        if (!this.erc8004) {
+            throw new Error('AgentIdentity: registryAddress is required for ERC-8004 registration. ' +
+                'Provide it in the constructor config.');
+        }
+        const result = await this.erc8004.registerAgent(this.wallet, metadata, agentURI);
+        if (result.agentId !== null) {
+            this._agentId = result.agentId;
+        }
+        return result;
+    }
+    /**
+     * Restore a previously registered agent identity.
+     *
+     * Use this when you already have an agentId from a prior session.
+     * Sets the internal agentId so deployTBA() and execute() work correctly.
+     *
+     * @param agentId - Previously registered ERC-8004 token ID
+     * @param nftContract - The ERC-8004 registry contract (= registryAddress in config)
+     */
+    setAgentId(agentId, nftContract) {
+        this._agentId = agentId;
+        if (nftContract)
+            this._nftContract = nftContract;
+    }
+    // ─── ERC-6551: TBA Deployment ─────────────────────────────────────────────
+    /**
+     * Deploy the Token Bound Account for this agent's NFT.
+     *
+     * The TBA address is deterministic — you can compute it before deployment
+     * via `computeTBAAddress()`. This call deploys the actual smart contract at
+     * that address, enabling the agent to act autonomously on-chain.
+     *
+     * Idempotent: calling deployTBA() on an already-deployed TBA is safe.
+     *
+     * @param nftContract - Override: NFT contract to bind the TBA to.
+     *   Defaults to the registryAddress (ERC-8004 registry is also the NFT contract).
+     * @param tokenId - Override: token ID. Defaults to the registered agentId.
+     * @returns Deployed TBAAccount
+     * @throws Error if agentId not set (call register() first or use setAgentId())
+     */
+    async deployTBA(nftContract, tokenId) {
+        const resolvedContract = nftContract ?? this._nftContract;
+        const resolvedTokenId = tokenId ?? this._agentId;
+        if (!resolvedContract) {
+            throw new Error('AgentIdentity: NFT contract address unknown. ' +
+                'Provide registryAddress in config or pass nftContract to deployTBA().');
+        }
+        if (resolvedTokenId === null) {
+            throw new Error('AgentIdentity: agentId not set. ' +
+                'Call register() first or use setAgentId() to restore a prior identity.');
+        }
+        const tbaAccount = await this.erc6551.createTBA(this.wallet, resolvedContract, resolvedTokenId, this.tbaSalt);
+        this._tbaAccount = tbaAccount;
+        return tbaAccount;
+    }
+    /**
+     * Compute the deterministic TBA address without deploying.
+     *
+     * Useful for pre-computing the address to fund it before deployment,
+     * or to check if a TBA already exists.
+     *
+     * @param nftContract - NFT contract (defaults to registryAddress)
+     * @param tokenId - Token ID (defaults to agentId)
+     * @returns Deterministic TBA address
+     */
+    computeTBAAddress(nftContract, tokenId) {
+        const resolvedContract = nftContract ?? this._nftContract;
+        const resolvedTokenId = tokenId ?? this._agentId;
+        if (!resolvedContract || resolvedTokenId === null) {
+            throw new Error('AgentIdentity: nftContract and tokenId required to compute TBA address.');
+        }
+        return this.erc6551.computeTBAAddress(resolvedContract, resolvedTokenId, this.tbaSalt);
+    }
+    /**
+     * Load TBA state without deploying — useful for resuming a session.
+     * Sets internal TBA state so execute() works without re-deploying.
+     *
+     * @param nftContract - NFT contract (defaults to registryAddress)
+     * @param tokenId - Token ID (defaults to agentId)
+     */
+    async loadTBA(nftContract, tokenId) {
+        const resolvedContract = nftContract ?? this._nftContract;
+        const resolvedTokenId = tokenId ?? this._agentId;
+        if (!resolvedContract || resolvedTokenId === null) {
+            throw new Error('AgentIdentity: nftContract and tokenId required to load TBA.');
+        }
+        const tbaAccount = await this.erc6551.getTBAAccount(resolvedContract, resolvedTokenId, this.tbaSalt);
+        this._tbaAccount = tbaAccount;
+        return tbaAccount;
+    }
+    // ─── ERC-6551: Execution ──────────────────────────────────────────────────
+    /**
+     * Execute a call from the agent's TBA (the agent acts autonomously).
+     *
+     * Routes the call through the TBA's `execute()` function, which verifies
+     * the caller owns the NFT before dispatching to the target contract.
+     *
+     * @param params - Call parameters (to, value, data, operation)
+     * @returns Transaction hash and return data
+     * @throws Error if TBA not deployed (call deployTBA() first)
+     *
+     * @example
+     * ```typescript
+     * // Agent bids on a TaskBridge task
+     * await identity.execute({
+     *   to: TASKBRIDGE_ADDRESS,
+     *   value: 0n,
+     *   data: encodeFunctionData({
+     *     abi: TaskBridgeAbi,
+     *     functionName: 'bid',
+     *     args: [taskId, bidAmount],
+     *   }),
+     * });
+     * ```
+     */
+    async execute(params) {
+        const tbaAddress = this.tbaAddress;
+        if (!tbaAddress) {
+            throw new Error('AgentIdentity: TBA not deployed. Call deployTBA() first or loadTBA() to restore.');
+        }
+        return this.erc6551.executeTBA(this.wallet, tbaAddress, params);
+    }
+    // ─── State accessors ──────────────────────────────────────────────────────
+    /**
+     * The agent's ERC-8004 token ID (null before registration).
+     */
+    get agentId() {
+        return this._agentId;
+    }
+    /**
+     * The agent's TBA address (null before deployTBA() or loadTBA()).
+     */
+    get tbaAddress() {
+        return this._tbaAccount?.address ?? null;
+    }
+    /**
+     * Full TBA account details (null before deployTBA() or loadTBA()).
+     */
+    get tbaAccount() {
+        return this._tbaAccount;
+    }
+    /**
+     * Whether the agent's ERC-8004 NFT is registered.
+     */
+    get isRegistered() {
+        return this._agentId !== null;
+    }
+    /**
+     * Whether the agent's TBA is deployed on-chain.
+     */
+    get isTBADeployed() {
+        return this._tbaAccount?.isDeployed === true;
+    }
+    /**
+     * The wallet account address (human principal / NFT owner).
+     */
+    get ownerAddress() {
+        return this.wallet.account?.address ?? null;
+    }
+    /**
+     * Full identity state snapshot.
+     */
+    get state() {
+        return {
+            agentId: this._agentId,
+            tbaAddress: this.tbaAddress,
+            isRegistered: this.isRegistered,
+            isTBADeployed: this.isTBADeployed,
+            owner: this.ownerAddress,
+        };
+    }
+    /**
+     * Direct access to the underlying ERC6551Client for advanced usage.
+     */
+    get erc6551Client() {
+        return this.erc6551;
+    }
+    /**
+     * Direct access to the underlying ERC8004Client (null if no registryAddress provided).
+     */
+    get erc8004Client() {
+        return this.erc8004;
+    }
+}
+//# sourceMappingURL=agent-identity.js.map

package/dist/identity/agent-identity.js.map

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