@tonappchain/sdk 0.7.3-rc8 → 0.8.0-aa-alpha-test

package/dist/src/accountAbstraction/PermitFlow.js

@@ -0,0 +1,80 @@
+"use strict";
+// Higher-level helper for paymaster Mode 1 — TRANSFER_VIA_PERMIT.
+//
+// This mode needs a *double-signing* dance: both userOp.signature AND the inner signature
+// inside paymasterData depend on userOpHash, which itself depends on paymasterAndData (which
+// contains the inner signature). The flow:
+//
+//   1. Compute permit + permitHash.
+//   2. Build paymasterData with a placeholder inner sig (96 zero bytes).
+//   3. userOpHash_r1 = getUserOpHash(op with placeholder).
+//   4. sign Ed25519 over `userOpHash_r1 || permitHash`  -> (r1, s1).
+//   5. paymasterData.innerSig = r1 ‖ s1 ‖ userOpHash_r1.
+//   6. userOpHash_r2 = getUserOpHash(final op).
+//   7. sign Ed25519 over `userOpHash_r2 || permitHash`  -> (r2, s2).
+//   8. userOp.signature = r2 ‖ s2 ‖ permitHash.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSignedUserOpWithPermit = buildSignedUserOpWithPermit;
+exports.buildSignedUserOpWithPermitTonConnect = buildSignedUserOpWithPermitTonConnect;
+const ethers_1 = require("ethers");
+const Ed25519_1 = require("./Ed25519");
+const entryPointAbi_1 = require("./internal/entryPointAbi");
+const userOp_1 = require("./internal/userOp");
+const Permit2_1 = require("./Permit2");
+const TacERC20PaymasterAPI_1 = require("./TacERC20PaymasterAPI");
+const DEFAULT_PM_GAS = 100000;
+const PLACEHOLDER_INNER_SIG = '0x' + '00'.repeat(96);
+/**
+ * Build a fully-signed UserOp paying gas via TacERC20Paymaster's TRANSFER_VIA_PERMIT mode.
+ * Performs the two-round double-sign; the EntryPoint (for userOpHash) is derived from the
+ * accountAPI's entryPointAddress + provider.
+ */
+async function buildSignedUserOpWithPermit(input) {
+    const { accountAPI, paymaster, permitInput, ed25519Signer, txDetails } = input;
+    const pmVerifGas = input.paymasterVerificationGasLimit ?? DEFAULT_PM_GAS;
+    const pmPostOpGas = input.paymasterPostOpGasLimit ?? DEFAULT_PM_GAS;
+    const entryPoint = new ethers_1.Contract(accountAPI.entryPointAddress, entryPointAbi_1.IEntryPointABI, accountAPI.provider);
+    const { permit, permitHash } = (0, Permit2_1.buildPermitMessage)(permitInput);
+    // Round 1 — placeholder inner signature.
+    const userOp = await accountAPI.createUnsignedUserOp(txDetails);
+    userOp.paymaster = paymaster;
+    userOp.paymasterVerificationGasLimit = pmVerifGas;
+    userOp.paymasterPostOpGasLimit = pmPostOpGas;
+    userOp.paymasterData = (0, ethers_1.concat)([
+        (0, TacERC20PaymasterAPI_1.packModeByte)(TacERC20PaymasterAPI_1.TacPaymasterMode.TRANSFER_VIA_PERMIT),
+        (0, Permit2_1.packPermitData)(permit, PLACEHOLDER_INNER_SIG),
+    ]);
+    const userOpHashR1 = await entryPoint.getUserOpHash.staticCall((0, userOp_1.packUserOp)(userOp));
+    const sigR1 = await ed25519Signer((0, Ed25519_1.buildPermitBinding)(userOpHashR1, permitHash));
+    // Round 2 — final inner signature bound to userOpHash_r1.
+    const innerSig = (0, Ed25519_1.packPermit2InnerSignature)(sigR1, userOpHashR1);
+    userOp.paymasterData = (0, ethers_1.concat)([(0, TacERC20PaymasterAPI_1.packModeByte)(TacERC20PaymasterAPI_1.TacPaymasterMode.TRANSFER_VIA_PERMIT), (0, Permit2_1.packPermitData)(permit, innerSig)]);
+    const userOpHashR2 = await entryPoint.getUserOpHash.staticCall((0, userOp_1.packUserOp)(userOp));
+    const sigR2 = await ed25519Signer((0, Ed25519_1.buildPermitBinding)(userOpHashR2, permitHash));
+    userOp.signature = (0, Ed25519_1.packPermitBoundUserOpSignature)(sigR2, permitHash);
+    return userOp;
+}
+/** TonConnect-wallet variant of {@link buildSignedUserOpWithPermit}. */
+async function buildSignedUserOpWithPermitTonConnect(input) {
+    const { accountAPI, paymaster, permitInput, tonConnectSigner, txDetails } = input;
+    const pmVerifGas = input.paymasterVerificationGasLimit ?? DEFAULT_PM_GAS;
+    const pmPostOpGas = input.paymasterPostOpGasLimit ?? DEFAULT_PM_GAS;
+    const entryPoint = new ethers_1.Contract(accountAPI.entryPointAddress, entryPointAbi_1.IEntryPointABI, accountAPI.provider);
+    const { permit, permitHash } = (0, Permit2_1.buildPermitMessage)(permitInput);
+    const userOp = await accountAPI.createUnsignedUserOp(txDetails);
+    userOp.paymaster = paymaster;
+    userOp.paymasterVerificationGasLimit = pmVerifGas;
+    userOp.paymasterPostOpGasLimit = pmPostOpGas;
+    userOp.paymasterData = (0, ethers_1.concat)([
+        (0, TacERC20PaymasterAPI_1.packModeByte)(TacERC20PaymasterAPI_1.TacPaymasterMode.TRANSFER_VIA_PERMIT),
+        (0, Permit2_1.packPermitData)(permit, PLACEHOLDER_INNER_SIG),
+    ]);
+    const userOpHashR1 = await entryPoint.getUserOpHash.staticCall((0, userOp_1.packUserOp)(userOp));
+    const partsR1 = await tonConnectSigner((0, Ed25519_1.buildPermitBinding)(userOpHashR1, permitHash));
+    const innerSig = (0, Ed25519_1.packTonConnectPermit2InnerSignature)(partsR1, userOpHashR1);
+    userOp.paymasterData = (0, ethers_1.concat)([(0, TacERC20PaymasterAPI_1.packModeByte)(TacERC20PaymasterAPI_1.TacPaymasterMode.TRANSFER_VIA_PERMIT), (0, Permit2_1.packPermitData)(permit, innerSig)]);
+    const userOpHashR2 = await entryPoint.getUserOpHash.staticCall((0, userOp_1.packUserOp)(userOp));
+    const partsR2 = await tonConnectSigner((0, Ed25519_1.buildPermitBinding)(userOpHashR2, permitHash));
+    userOp.signature = (0, Ed25519_1.packTonConnectUserOpSignature)(partsR2, permitHash);
+    return userOp;
+}

package/dist/src/accountAbstraction/TacAccountAPI.d.ts

@@ -0,0 +1,53 @@
+import { BigNumberish } from 'ethers';
+import { BaseAccountAPI, BaseApiParams } from './BaseAccountAPI';
+import { Ed25519Signer, TonConnectSigner } from './Ed25519';
+import { FactoryParams } from './internal/userOp';
+/**
+ * Constructor params for {@link TacAccountAPI}. Exactly ONE of `signer` or
+ * `tonConnectSigner` must be provided.
+ *
+ * @param publicKey        Ed25519 public key as 32-byte hex (0x-prefixed). The
+ *                         deterministic AA address is derived from this key alone.
+ * @param signer           raw Ed25519 signer (returns `(r, s)` over a 32-byte message).
+ * @param tonConnectSigner TonConnect-wallet signer.
+ * @param factoryAddress   deployed `TacAccountFactory` address.
+ */
+export interface TacAccountApiParams extends BaseApiParams {
+    publicKey: string;
+    signer?: Ed25519Signer;
+    tonConnectSigner?: TonConnectSigner;
+    factoryAddress: string;
+}
+/**
+ * BaseAccountAPI implementation for TAC's Ed25519 + beacon-proxy accounts.
+ *
+ *   - account address is derived from the Ed25519 public key only
+ *     (`salt = keccak256(publicKey)` inside the factory)
+ *   - factoryData is `TacAccountFactory.getOrCreateAccount(publicKey)`
+ *   - signature is Ed25519 in the 64-byte raw format (this class), or the 96-byte /
+ *     TonConnect formats via {@link buildSignedUserOpWithPermit} for paymaster Mode 1
+ */
+export declare class TacAccountAPI extends BaseAccountAPI {
+    publicKey: string;
+    signer?: Ed25519Signer;
+    tonConnectSigner?: TonConnectSigner;
+    factoryAddress: string;
+    private accountContract?;
+    private factoryContract?;
+    constructor(params: TacAccountApiParams);
+    private _getAccountContract;
+    private _getFactory;
+    /** Derive the deterministic account address directly from the factory's view. */
+    getCounterFactualAddress(): Promise<string>;
+    /** initCode for an undeployed account: factory + `getOrCreateAccount(publicKey)` calldata. */
+    getFactoryData(): Promise<FactoryParams | null>;
+    /** Sequential nonce from the deployed account, or 0 if still phantom. */
+    getNonce(): Promise<bigint>;
+    /** Encode a single call as `TacBaseAccount.execute(target, value, data)` calldata. */
+    encodeExecute(target: string, value: BigNumberish, data: string): Promise<string>;
+    /**
+     * Sign userOpHash with the configured signer (64-byte raw, or TonConnect with
+     * `permitHash = 0`). For paymaster Mode 1 use {@link buildSignedUserOpWithPermit}.
+     */
+    signUserOpHash(userOpHash: string): Promise<string>;
+}

package/dist/src/accountAbstraction/TacAccountAPI.js

@@ -0,0 +1,84 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TacAccountAPI = void 0;
+const ethers_1 = require("ethers");
+const abi_1 = require("./abi");
+const BaseAccountAPI_1 = require("./BaseAccountAPI");
+const Ed25519_1 = require("./Ed25519");
+const ZERO_HASH = '0x' + '00'.repeat(32);
+/**
+ * BaseAccountAPI implementation for TAC's Ed25519 + beacon-proxy accounts.
+ *
+ *   - account address is derived from the Ed25519 public key only
+ *     (`salt = keccak256(publicKey)` inside the factory)
+ *   - factoryData is `TacAccountFactory.getOrCreateAccount(publicKey)`
+ *   - signature is Ed25519 in the 64-byte raw format (this class), or the 96-byte /
+ *     TonConnect formats via {@link buildSignedUserOpWithPermit} for paymaster Mode 1
+ */
+class TacAccountAPI extends BaseAccountAPI_1.BaseAccountAPI {
+    constructor(params) {
+        super(params);
+        if ((params.signer == null) === (params.tonConnectSigner == null)) {
+            throw new Error('TacAccountAPI requires exactly one of `signer` or `tonConnectSigner`');
+        }
+        this.publicKey = params.publicKey;
+        this.signer = params.signer;
+        this.tonConnectSigner = params.tonConnectSigner;
+        this.factoryAddress = params.factoryAddress;
+    }
+    async _getAccountContract() {
+        if (this.accountContract == null) {
+            const addr = await this.getAccountAddress();
+            this.accountContract = new ethers_1.Contract(addr, abi_1.TacAccountABI, this.provider);
+        }
+        return this.accountContract;
+    }
+    _getFactory() {
+        if (this.factoryContract == null) {
+            this.factoryContract = new ethers_1.Contract(this.factoryAddress, abi_1.TacAccountFactoryABI, this.provider);
+        }
+        return this.factoryContract;
+    }
+    /** Derive the deterministic account address directly from the factory's view. */
+    async getCounterFactualAddress() {
+        return await this._getFactory().getAccountAddress.staticCall(this.publicKey);
+    }
+    /** initCode for an undeployed account: factory + `getOrCreateAccount(publicKey)` calldata. */
+    async getFactoryData() {
+        const factory = this._getFactory();
+        return {
+            factory: this.factoryAddress,
+            factoryData: factory.interface.encodeFunctionData('getOrCreateAccount', [this.publicKey]),
+        };
+    }
+    /** Sequential nonce from the deployed account, or 0 if still phantom. */
+    async getNonce() {
+        if (await this.checkAccountPhantom()) {
+            return 0n;
+        }
+        const accountContract = await this._getAccountContract();
+        return await accountContract.getFunction('getNonce()').staticCall();
+    }
+    /** Encode a single call as `TacBaseAccount.execute(target, value, data)` calldata. */
+    async encodeExecute(target, value, data) {
+        const accountContract = await this._getAccountContract();
+        return accountContract.interface.encodeFunctionData('execute', [target, value, data]);
+    }
+    /**
+     * Sign userOpHash with the configured signer (64-byte raw, or TonConnect with
+     * `permitHash = 0`). For paymaster Mode 1 use {@link buildSignedUserOpWithPermit}.
+     */
+    async signUserOpHash(userOpHash) {
+        if (this.signer != null) {
+            const sig = await this.signer(userOpHash);
+            return (0, Ed25519_1.packRawEd25519Signature)(sig);
+        }
+        if (this.tonConnectSigner != null) {
+            const binding = (0, Ed25519_1.buildPermitBinding)(userOpHash, ZERO_HASH);
+            const parts = await this.tonConnectSigner(binding);
+            return (0, Ed25519_1.packTonConnectUserOpSignature)(parts, ZERO_HASH);
+        }
+        throw new Error('TacAccountAPI: no signer configured');
+    }
+}
+exports.TacAccountAPI = TacAccountAPI;

package/dist/src/accountAbstraction/TacAccountSdk.d.ts

@@ -0,0 +1,101 @@
+import { AbstractProvider, BigNumberish } from 'ethers';
+import { Network } from '../structs/Struct';
+import { HttpRpcClient } from './HttpRpcClient';
+import { AaAddresses } from './networks';
+import { TacAccountAPI } from './TacAccountAPI';
+/** A single call to execute through the smart account. */
+export interface SendTx {
+    target: string;
+    data: string;
+    value?: BigNumberish;
+    /** Defaults to 1_000_000 (the SDK under-estimates the deploying op). */
+    gasLimit?: BigNumberish;
+}
+/** Extra options for the permit (Mode 1) flow — all optional. */
+export interface PermitOptions {
+    /** Token to pay gas in. Defaults to the paymaster's configured token. */
+    feeToken?: string;
+    /** Max token the paymaster may pull. Defaults to 1000 units of the fee token. */
+    maxFee?: BigNumberish;
+    /** Permit deadline (unix seconds). Defaults to no expiry. */
+    deadline?: BigNumberish;
+    paymasterVerificationGasLimit?: BigNumberish;
+    paymasterPostOpGasLimit?: BigNumberish;
+}
+/** The bundler's UserOperation receipt (subset). */
+export interface UserOpReceipt {
+    userOpHash: string;
+    success: boolean;
+    receipt: {
+        transactionHash: string;
+        blockNumber?: string;
+    };
+    actualGasCost?: string;
+    actualGasUsed?: string;
+}
+export interface UserOpSendResult {
+    userOpHash: string;
+    receipt: UserOpReceipt;
+}
+export interface TacAccountSdkParams {
+    network: Network;
+    /** TON mnemonic — the AA account identity. */
+    mnemonic: string;
+    /** Bundler RPC URL. Required to send (no public default is shipped). */
+    bundlerUrl?: string;
+    /** Override the TAC EVM provider (default: getDefaultProvider(network's TAC RPC)). */
+    provider?: AbstractProvider;
+    /** Override any AA contract address. */
+    addresses?: Partial<AaAddresses>;
+}
+/**
+ * High-level, network-defaulted entry point for the TAC AA bundler — mirrors
+ * `TacSdk.create({ network })`. Resolves provider + contract addresses from built-in
+ * per-network defaults and derives the signer from a mnemonic; the paymaster/permit data
+ * is built internally by the send methods.
+ *
+ * ```ts
+ * const aa = await TacAccountSdk.create({ network: Network.TESTNET, mnemonic, bundlerUrl });
+ * const { userOpHash, receipt } = await aa.sendUserOp({ target, value, data });
+ * ```
+ */
+export declare class TacAccountSdk {
+    readonly network: Network;
+    readonly provider: AbstractProvider;
+    readonly addresses: AaAddresses;
+    readonly chainId: number;
+    readonly bundlerUrl: string | undefined;
+    readonly account: TacAccountAPI;
+    private readonly _signer;
+    private readonly _publicKey;
+    private _bundler?;
+    private _address?;
+    private _tokenInfo?;
+    private _permitCounter;
+    private constructor();
+    static create(params: TacAccountSdkParams): Promise<TacAccountSdk>;
+    /** The deterministic smart-account address (derived from the TON public key). */
+    getAccountAddress(): Promise<string>;
+    /** Send a call paying gas natively (account must hold TAC). */
+    sendUserOp(tx: SendTx): Promise<UserOpSendResult>;
+    /** Send a call paying gas in an ERC-20 via the paymaster (Mode 1 — Permit2). */
+    sendUserOpWithPermit(tx: SendTx & PermitOptions): Promise<UserOpSendResult>;
+    /** Send a call paying gas from the account's pre-credited internal balance (Mode 2). */
+    sendUserOpViaInternalBalance(tx: SendTx): Promise<UserOpSendResult>;
+    /** Send a call where the paymaster pulls the fee token via a pre-set allowance (Mode 0). */
+    sendUserOpViaAllowance(tx: SendTx): Promise<UserOpSendResult>;
+    /** Poll the bundler for a UserOperation receipt. */
+    waitForReceipt(userOpHash: string, opts?: {
+        timeoutMs?: number;
+        intervalMs?: number;
+    }): Promise<UserOpReceipt>;
+    /** The bundler client (throws if no bundler URL was configured). */
+    bundler(): HttpRpcClient;
+    private _bundlerClient;
+    private _txDetails;
+    private _sendViaMode;
+    private _submit;
+    private _tokenInfoResolved;
+    /** Unique permit nonce (Permit2 replay protection): timestamp-ms high bits + a counter. */
+    private _newPermitNonce;
+}

package/dist/src/accountAbstraction/TacAccountSdk.js

@@ -0,0 +1,163 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TacAccountSdk = void 0;
+const ethers_1 = require("ethers");
+const Artifacts_1 = require("../sdk/Artifacts");
+const HttpRpcClient_1 = require("./HttpRpcClient");
+const networks_1 = require("./networks");
+const PermitFlow_1 = require("./PermitFlow");
+const signer_1 = require("./signer");
+const TacAccountAPI_1 = require("./TacAccountAPI");
+const TacERC20PaymasterAPI_1 = require("./TacERC20PaymasterAPI");
+/**
+ * High-level, network-defaulted entry point for the TAC AA bundler — mirrors
+ * `TacSdk.create({ network })`. Resolves provider + contract addresses from built-in
+ * per-network defaults and derives the signer from a mnemonic; the paymaster/permit data
+ * is built internally by the send methods.
+ *
+ * ```ts
+ * const aa = await TacAccountSdk.create({ network: Network.TESTNET, mnemonic, bundlerUrl });
+ * const { userOpHash, receipt } = await aa.sendUserOp({ target, value, data });
+ * ```
+ */
+class TacAccountSdk {
+    constructor(network, provider, addresses, chainId, bundlerUrl, publicKey, signer) {
+        this.network = network;
+        this.provider = provider;
+        this.addresses = addresses;
+        this.chainId = chainId;
+        this.bundlerUrl = bundlerUrl;
+        this._permitCounter = 0;
+        this._publicKey = publicKey;
+        this._signer = signer;
+        this.account = new TacAccountAPI_1.TacAccountAPI({
+            provider,
+            entryPointAddress: addresses.entryPoint,
+            factoryAddress: addresses.accountFactory,
+            publicKey,
+            signer,
+        });
+    }
+    static async create(params) {
+        const cfg = networks_1.AA_NETWORKS[params.network];
+        if (cfg == null) {
+            throw new Error(`account abstraction is not available on network "${params.network}" yet`);
+        }
+        let provider = params.provider;
+        if (provider == null) {
+            const rpc = (0, Artifacts_1.getArtifacts)(params.network).TAC_RPC_ENDPOINT;
+            if (rpc == null) {
+                throw new Error(`no default TAC RPC for network "${params.network}"; pass a custom provider`);
+            }
+            provider = (0, ethers_1.getDefaultProvider)(rpc);
+        }
+        const addresses = {
+            entryPoint: params.addresses?.entryPoint ?? cfg.entryPoint,
+            accountFactory: params.addresses?.accountFactory ?? cfg.accountFactory,
+            paymaster: params.addresses?.paymaster ?? cfg.paymaster,
+            permit2: params.addresses?.permit2 ?? cfg.permit2,
+        };
+        const { publicKey, signer } = await (0, signer_1.aaSignerFromMnemonic)(params.mnemonic);
+        return new TacAccountSdk(params.network, provider, addresses, cfg.chainId, params.bundlerUrl ?? cfg.bundlerUrl, publicKey, signer);
+    }
+    /** The deterministic smart-account address (derived from the TON public key). */
+    async getAccountAddress() {
+        this._address ?? (this._address = await this.account.getAccountAddress());
+        return this._address;
+    }
+    /** Send a call paying gas natively (account must hold TAC). */
+    async sendUserOp(tx) {
+        const op = await this.account.createSignedUserOp(this._txDetails(tx));
+        return await this._submit(op);
+    }
+    /** Send a call paying gas in an ERC-20 via the paymaster (Mode 1 — Permit2). */
+    async sendUserOpWithPermit(tx) {
+        const token = await this._tokenInfoResolved();
+        const op = await (0, PermitFlow_1.buildSignedUserOpWithPermit)({
+            accountAPI: this.account,
+            paymaster: this.addresses.paymaster,
+            paymasterVerificationGasLimit: tx.paymasterVerificationGasLimit ?? 500000,
+            paymasterPostOpGasLimit: tx.paymasterPostOpGasLimit ?? 150000,
+            permitInput: {
+                permitted: [{ token: tx.feeToken ?? token.address, amount: tx.maxFee ?? (0, ethers_1.parseUnits)('1000', token.decimals) }],
+                nonce: this._newPermitNonce(),
+                deadline: tx.deadline ?? ethers_1.MaxUint256,
+                chainId: this.chainId,
+                verifyingContract: this.addresses.permit2,
+            },
+            ed25519Signer: this._signer,
+            txDetails: this._txDetails(tx),
+        });
+        return await this._submit(op);
+    }
+    /** Send a call paying gas from the account's pre-credited internal balance (Mode 2). */
+    async sendUserOpViaInternalBalance(tx) {
+        return await this._sendViaMode(tx, TacERC20PaymasterAPI_1.TacPaymasterMode.INTERNAL_BALANCE);
+    }
+    /** Send a call where the paymaster pulls the fee token via a pre-set allowance (Mode 0). */
+    async sendUserOpViaAllowance(tx) {
+        return await this._sendViaMode(tx, TacERC20PaymasterAPI_1.TacPaymasterMode.TRANSFER_FROM_REQUESTOR);
+    }
+    /** Poll the bundler for a UserOperation receipt. */
+    async waitForReceipt(userOpHash, opts) {
+        const client = this._bundlerClient();
+        const end = Date.now() + (opts?.timeoutMs ?? 120000);
+        while (Date.now() < end) {
+            const r = await client.getUserOperationReceipt(userOpHash);
+            if (r != null) {
+                return r;
+            }
+            await new Promise((res) => setTimeout(res, opts?.intervalMs ?? 3000));
+        }
+        throw new Error(`userOp ${userOpHash} not mined within timeout`);
+    }
+    /** The bundler client (throws if no bundler URL was configured). */
+    bundler() {
+        return this._bundlerClient();
+    }
+    // ── internals ──────────────────────────────────────────────────────────────
+    _bundlerClient() {
+        if (this.bundlerUrl == null || this.bundlerUrl === '') {
+            throw new Error('no bundler URL configured — pass `bundlerUrl` to TacAccountSdk.create({ ... })');
+        }
+        this._bundler ?? (this._bundler = new HttpRpcClient_1.HttpRpcClient(this.bundlerUrl, this.addresses.entryPoint, this.chainId));
+        return this._bundler;
+    }
+    _txDetails(tx) {
+        return { target: tx.target, value: tx.value ?? 0, data: tx.data, gasLimit: tx.gasLimit ?? 1000000 };
+    }
+    async _sendViaMode(tx, mode) {
+        const paymasterAPI = new TacERC20PaymasterAPI_1.TacERC20PaymasterAPI({ paymaster: this.addresses.paymaster, mode });
+        const account = new TacAccountAPI_1.TacAccountAPI({
+            provider: this.provider,
+            entryPointAddress: this.addresses.entryPoint,
+            factoryAddress: this.addresses.accountFactory,
+            publicKey: this._publicKey,
+            signer: this._signer,
+            accountAddress: await this.getAccountAddress(),
+            paymasterAPI,
+        });
+        const op = await account.createSignedUserOp(this._txDetails(tx));
+        return await this._submit(op);
+    }
+    async _submit(op) {
+        const userOpHash = await this._bundlerClient().sendUserOpToBundler(op);
+        const receipt = await this.waitForReceipt(userOpHash);
+        return { userOpHash, receipt };
+    }
+    async _tokenInfoResolved() {
+        if (this._tokenInfo == null) {
+            const pm = new ethers_1.Contract(this.addresses.paymaster, ['function token() view returns (address)'], this.provider);
+            const address = await pm.token();
+            const erc20 = new ethers_1.Contract(address, ['function decimals() view returns (uint8)'], this.provider);
+            const decimals = Number(await erc20.decimals());
+            this._tokenInfo = { address, decimals };
+        }
+        return this._tokenInfo;
+    }
+    /** Unique permit nonce (Permit2 replay protection): timestamp-ms high bits + a counter. */
+    _newPermitNonce() {
+        return (BigInt(Date.now()) << 16n) | BigInt(this._permitCounter++ & 0xffff);
+    }
+}
+exports.TacAccountSdk = TacAccountSdk;

package/dist/src/accountAbstraction/TacERC20PaymasterAPI.d.ts

@@ -0,0 +1,59 @@
+import { BigNumberish, BytesLike } from 'ethers';
+import { PaymasterAPI, PaymasterParams } from './PaymasterAPI';
+/**
+ * Mode discriminator consumed by `TacERC20Paymaster._parsePaymasterAndData`. The mode byte
+ * sits at index 52 of the full `paymasterAndData` (after `paymaster(20) ‖ pmVerifGas(16) ‖
+ * pmPostOpGas(16)`); everything after it is mode-specific.
+ */
+export declare enum TacPaymasterMode {
+    /**
+     * Paymaster pulls the token from the account via `transferFrom` during validation.
+     * The account MUST have pre-approved the paymaster on the token. `paymasterData = 0x00`.
+     */
+    TRANSFER_FROM_REQUESTOR = 0,
+    /**
+     * Paymaster receives a Permit2 `PermitBatchTransferFrom` + signature inside
+     * `paymasterData`. Requires the two-round double-sign — use
+     * {@link buildSignedUserOpWithPermit}, not this API directly.
+     * `paymasterData = 0x01 ‖ abi.encode(PermitBatchTransferFrom, signatureBlob)`.
+     */
+    TRANSFER_VIA_PERMIT = 1,
+    /**
+     * Paymaster debits the account's pre-funded `internalBalance` (credited off-band by
+     * the paymaster owner). No approval, no token transfer. `paymasterData = 0x02`.
+     */
+    INTERNAL_BALANCE = 2
+}
+export interface TacERC20PaymasterApiParams {
+    paymaster: string;
+    mode: TacPaymasterMode;
+    paymasterVerificationGasLimit?: BigNumberish;
+    paymasterPostOpGasLimit?: BigNumberish;
+}
+/**
+ * PaymasterAPI for TAC's `TacERC20Paymaster`. One instance per mode.
+ * Modes 0 (TRANSFER_FROM_REQUESTOR) and 2 (INTERNAL_BALANCE) compose directly into a
+ * `TacAccountAPI` via its `paymasterAPI`; Mode 1 needs {@link buildSignedUserOpWithPermit}.
+ */
+export declare class TacERC20PaymasterAPI extends PaymasterAPI {
+    paymaster: string;
+    mode: TacPaymasterMode;
+    paymasterVerificationGasLimit: BigNumberish;
+    paymasterPostOpGasLimit: BigNumberish;
+    constructor(params: TacERC20PaymasterApiParams);
+    getTemporaryPaymasterData(): Promise<PaymasterParams | null>;
+    getPaymasterData(): Promise<PaymasterParams | null>;
+    private _buildPaymasterData;
+}
+/** Pack a single-byte mode discriminator: `0x00`, `0x01`, or `0x02`. */
+export declare function packModeByte(mode: TacPaymasterMode): string;
+/**
+ * Assemble the full on-chain `paymasterAndData` field
+ * (`paymaster ‖ pmVerifGasLimit ‖ pmPostOpGasLimit ‖ modeByte ‖ extra`).
+ */
+export declare function packPaymasterAndData(params: {
+    paymaster: string;
+    paymasterVerificationGasLimit: BigNumberish;
+    paymasterPostOpGasLimit: BigNumberish;
+    paymasterData: BytesLike;
+}): string;

package/dist/src/accountAbstraction/TacERC20PaymasterAPI.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TacERC20PaymasterAPI = exports.TacPaymasterMode = void 0;
+exports.packModeByte = packModeByte;
+exports.packPaymasterAndData = packPaymasterAndData;
+const ethers_1 = require("ethers");
+const PaymasterAPI_1 = require("./PaymasterAPI");
+/**
+ * Mode discriminator consumed by `TacERC20Paymaster._parsePaymasterAndData`. The mode byte
+ * sits at index 52 of the full `paymasterAndData` (after `paymaster(20) ‖ pmVerifGas(16) ‖
+ * pmPostOpGas(16)`); everything after it is mode-specific.
+ */
+var TacPaymasterMode;
+(function (TacPaymasterMode) {
+    /**
+     * Paymaster pulls the token from the account via `transferFrom` during validation.
+     * The account MUST have pre-approved the paymaster on the token. `paymasterData = 0x00`.
+     */
+    TacPaymasterMode[TacPaymasterMode["TRANSFER_FROM_REQUESTOR"] = 0] = "TRANSFER_FROM_REQUESTOR";
+    /**
+     * Paymaster receives a Permit2 `PermitBatchTransferFrom` + signature inside
+     * `paymasterData`. Requires the two-round double-sign — use
+     * {@link buildSignedUserOpWithPermit}, not this API directly.
+     * `paymasterData = 0x01 ‖ abi.encode(PermitBatchTransferFrom, signatureBlob)`.
+     */
+    TacPaymasterMode[TacPaymasterMode["TRANSFER_VIA_PERMIT"] = 1] = "TRANSFER_VIA_PERMIT";
+    /**
+     * Paymaster debits the account's pre-funded `internalBalance` (credited off-band by
+     * the paymaster owner). No approval, no token transfer. `paymasterData = 0x02`.
+     */
+    TacPaymasterMode[TacPaymasterMode["INTERNAL_BALANCE"] = 2] = "INTERNAL_BALANCE";
+})(TacPaymasterMode || (exports.TacPaymasterMode = TacPaymasterMode = {}));
+const DEFAULT_PM_VERIFICATION_GAS_LIMIT = 100000;
+const DEFAULT_PM_POST_OP_GAS_LIMIT = 100000;
+/**
+ * PaymasterAPI for TAC's `TacERC20Paymaster`. One instance per mode.
+ * Modes 0 (TRANSFER_FROM_REQUESTOR) and 2 (INTERNAL_BALANCE) compose directly into a
+ * `TacAccountAPI` via its `paymasterAPI`; Mode 1 needs {@link buildSignedUserOpWithPermit}.
+ */
+class TacERC20PaymasterAPI extends PaymasterAPI_1.PaymasterAPI {
+    constructor(params) {
+        super();
+        this.paymaster = params.paymaster;
+        this.mode = params.mode;
+        this.paymasterVerificationGasLimit = params.paymasterVerificationGasLimit ?? DEFAULT_PM_VERIFICATION_GAS_LIMIT;
+        this.paymasterPostOpGasLimit = params.paymasterPostOpGasLimit ?? DEFAULT_PM_POST_OP_GAS_LIMIT;
+    }
+    async getTemporaryPaymasterData() {
+        return await this.getPaymasterData();
+    }
+    async getPaymasterData() {
+        return {
+            paymaster: this.paymaster,
+            paymasterVerificationGasLimit: this.paymasterVerificationGasLimit,
+            paymasterPostOpGasLimit: this.paymasterPostOpGasLimit,
+            paymasterData: this._buildPaymasterData(),
+        };
+    }
+    _buildPaymasterData() {
+        switch (this.mode) {
+            case TacPaymasterMode.TRANSFER_FROM_REQUESTOR:
+            case TacPaymasterMode.INTERNAL_BALANCE:
+                return packModeByte(this.mode);
+            case TacPaymasterMode.TRANSFER_VIA_PERMIT:
+                throw new Error('TacPaymasterMode.TRANSFER_VIA_PERMIT requires the double-signing flow. ' +
+                    'Use buildSignedUserOpWithPermit(...) instead of composing this PaymasterAPI into a TacAccountAPI.');
+            default:
+                throw new Error(`unknown TacPaymasterMode: ${this.mode}`);
+        }
+    }
+}
+exports.TacERC20PaymasterAPI = TacERC20PaymasterAPI;
+/** Pack a single-byte mode discriminator: `0x00`, `0x01`, or `0x02`. */
+function packModeByte(mode) {
+    return (0, ethers_1.zeroPadValue)((0, ethers_1.toBeHex)(mode), 1);
+}
+/**
+ * Assemble the full on-chain `paymasterAndData` field
+ * (`paymaster ‖ pmVerifGasLimit ‖ pmPostOpGasLimit ‖ modeByte ‖ extra`).
+ */
+function packPaymasterAndData(params) {
+    return (0, ethers_1.concat)([
+        params.paymaster,
+        (0, ethers_1.zeroPadValue)((0, ethers_1.toBeHex)(params.paymasterVerificationGasLimit), 16),
+        (0, ethers_1.zeroPadValue)((0, ethers_1.toBeHex)(params.paymasterPostOpGasLimit), 16),
+        params.paymasterData,
+    ]);
+}

package/dist/src/accountAbstraction/TransactionDetailsForUserOp.d.ts

@@ -0,0 +1,10 @@
+import { BigNumberish } from 'ethers';
+export interface TransactionDetailsForUserOp {
+    target: string;
+    data: string;
+    value?: BigNumberish;
+    gasLimit?: BigNumberish;
+    maxFeePerGas?: BigNumberish;
+    maxPriorityFeePerGas?: BigNumberish;
+    nonce?: BigNumberish;
+}

package/dist/src/accountAbstraction/TransactionDetailsForUserOp.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/accountAbstraction/abi.d.ts

@@ -0,0 +1,3 @@
+export declare const TacAccountFactoryABI: string[];
+export declare const TacAccountABI: string[];
+export declare const TacERC20PaymasterABI: string[];