@xyyz1207/uptick-aawallet-mpc-sdk 1.0.0

package/README.md

@@ -0,0 +1,84 @@
+# AA Wallet SDK
+
+An ERC-4337 Account Abstraction wallet SDK with a minimal public API.
+This SDK is **only designed for the Uptick Network chain**.
+
+Common methods:
+
+- `init`: Initialize chain and sponsor configuration (bundler / paymaster / chainId / rpc / apiKey, etc.)
+- `createWallet`: Create and return the AA wallet address (auto-sponsored deployment when needed)
+- `sendTransaction`: Send a transaction with the AA wallet (single call or batched calls)
+
+The internal design follows a layered architecture:
+
+- `core`: Parameter normalization and input validation
+- `services`: Wallet and transaction flow orchestration
+- `sdk`: External SDK instance API (while keeping default singleton compatibility)
+
+## Installation & Import
+
+```bash
+npm install @uptickjs/aa-wallet-sdk
+```
+
+```js
+import { init, createWallet, sendTransaction } from '@uptickjs/aa-wallet-sdk';
+import { encodeFunctionData } from 'viem';
+```
+
+## API
+
+### 1) `init(config)`
+
+```js
+init({
+  chainId: 9000,
+  bundlerUrl: 'https://...',
+  paymasterServiceUrl: 'https://...',
+  bundlerApiKey: '',
+  paymasterApiKey: '',
+});
+```
+
+### 2) `createWallet(params)`
+
+```js
+const wallet = await createWallet({
+  ownerPrivateKey: '0x...',
+});
+```
+
+Return example:
+
+```js
+{
+  ownerAddress: "0x...",
+  aaWalletAddress: "0x...",
+  deployedOnChain: true,
+  deployTxHash: "0x..." // null if deployment is not triggered
+}
+```
+
+### 3) `sendTransaction(params)`
+
+```js
+const tx = await sendTransaction({
+  ownerPrivateKey: '0x...',
+  to: '0x...',
+  value: 0n,
+  data: '0x',
+});
+
+const data = encodeFunctionData({
+  abi: loadAbi,
+  functionName: 'transfer',
+  args: [params1,params2...],
+});
+
+const tx = await sendTransaction({
+  ownerPrivateKey: '0x...',
+  to: contractAddress,
+  value: 0n,
+  data: data,
+});
+```

package/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@xyyz1207/uptick-aawallet-mpc-sdk",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "ISC",
+  "description": "",
+  "dependencies": {
+    "dotenv": "^17.4.2",
+    "permissionless": "^0.3.5",
+    "viem": "^2.48.1"
+  }
+}

package/src/core/chain-presets.js

@@ -0,0 +1,70 @@
+const COMMON_AA_PRESET = {
+  accountType: "safe",
+  safeVersion: "1.5.0",
+  entryPointVersion: "0.7",
+};
+
+/**
+ * 按 chainId 维护默认参数，调用方可在 init(config) 里覆盖。
+ */
+export const CHAIN_PRESETS = {
+  9000: {
+    chain: {
+      id: 9000,
+      name: "Uptick test",
+      rpcUrl: "http://54.254.15.166:10545",
+    },
+    aa: {
+      ...COMMON_AA_PRESET,
+      entryPointAddress: "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
+      factoryAddress: "0x91E60e0613810449d098b0b5Ec8b51A0FE8c8985",
+      safeProxyFactoryAddress: "0x34aeE8688B23516f9cD8F145D52D5a13080028D2",
+      safeSingletonAddress: "0x59CAB03C911eF5Ab4590Bb6c4F00B768C10F09D8",
+      safe4337ModuleAddress: "0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226",
+      safeModuleSetupAddress: "0x2dd68b007B46fBe91B9A7c3EDa5A7a1063cB5b47",
+      multiSendAddress: "0x4faF5C1F98B09F1494bDaf93c85E2A05FbC1e1Bd",
+      multiSendCallOnlyAddress: "0x756E377D1dcDC33bD973216E64D32bec6aB4b569",
+    },
+    deployment: {
+      enabled: true,
+      paymasterAddress: "0x80b00Dce53C4F717aECEb84881F4f8beA099189C",
+      paymasterVerificationGasLimit: "100000",
+      paymasterPostOpGasLimit: "50000",
+      gasLimitMultiplier: 120,
+      feeMultiplier: 130,
+      debug: false,
+    },
+  },
+  1170: {
+    chain: {
+      id: 1170,
+      name: "Uptick test",
+      rpcUrl: "https://json-rpc.origin.uptick.network",
+    },
+    aa: {
+      ...COMMON_AA_PRESET,
+      entryPointAddress: "0x0000000071727De22E5E9d8BAf0edAc6f37da032",
+      factoryAddress: "0x91E60e0613810449d098b0b5Ec8b51A0FE8c8985",
+      safeProxyFactoryAddress: "0x34aeE8688B23516f9cD8F145D52D5a13080028D2",
+      safeSingletonAddress: "0x59CAB03C911eF5Ab4590Bb6c4F00B768C10F09D8",
+      safe4337ModuleAddress: "0x75cf11467937ce3F2f357CE24ffc3DBF8fD5c226",
+      safeModuleSetupAddress: "0x2dd68b007B46fBe91B9A7c3EDa5A7a1063cB5b47",
+      multiSendAddress: "0x4faF5C1F98B09F1494bDaf93c85E2A05FbC1e1Bd",
+      multiSendCallOnlyAddress: "0x756E377D1dcDC33bD973216E64D32bec6aB4b569",
+    },
+    deployment: {
+      enabled: true,
+      paymasterAddress: "0x450AeF871cc771D4F0B7813f2BBef9a8c77611F7",
+      paymasterVerificationGasLimit: "100000",
+      paymasterPostOpGasLimit: "50000",
+      gasLimitMultiplier: 120,
+      feeMultiplier: 130,
+      debug: false,
+    },
+  },
+};
+
+export function getChainPreset(chainId) {
+  if (chainId == null) return null;
+  return CHAIN_PRESETS[Number(chainId)] ?? null;
+}

package/src/core/config.js

@@ -0,0 +1,159 @@
+import { getChainPreset } from "./chain-presets.js";
+
+function pickDefined(value, fallback) {
+  return value === undefined ? fallback : value;
+}
+
+export function normalizeSdkConfig(config) {
+  if (!config) throw new Error("init(config) 参数不能为空");
+  if (!config.chainId) throw new Error("缺少必填参数 chainId");
+
+  const preset = getChainPreset(config.chainId);
+  const chainId = Number(config.chainId);
+
+  const chain = {
+    id: chainId,
+    name: pickDefined(config.chainName, preset?.chain?.name ?? "AA Chain"),
+    rpcUrl: pickDefined(config.rpcUrl, preset?.chain?.rpcUrl),
+  };
+  if (!chain.rpcUrl) throw new Error(`chainId=${chainId} 缺少 rpcUrl 配置`);
+
+  const aa = {
+    ...(preset?.aa ?? {}),
+    ...(config.aa ?? {}),
+    accountType: pickDefined(
+      config.accountType,
+      pickDefined(config.aa?.accountType, preset?.aa?.accountType)
+    ),
+    safeVersion: pickDefined(
+      config.safeVersion,
+      pickDefined(config.aa?.safeVersion, preset?.aa?.safeVersion)
+    ),
+    entryPointVersion: pickDefined(
+      config.entryPointVersion,
+      pickDefined(config.aa?.entryPointVersion, preset?.aa?.entryPointVersion)
+    ),
+    entryPointAddress: pickDefined(
+      config.entryPointAddress,
+      pickDefined(config.aa?.entryPointAddress, preset?.aa?.entryPointAddress)
+    ),
+    factoryAddress: pickDefined(
+      config.factoryAddress,
+      pickDefined(config.aa?.factoryAddress, preset?.aa?.factoryAddress)
+    ),
+    safeProxyFactoryAddress: pickDefined(
+      config.safeProxyFactoryAddress,
+      pickDefined(
+        config.aa?.safeProxyFactoryAddress,
+        preset?.aa?.safeProxyFactoryAddress
+      )
+    ),
+    safeSingletonAddress: pickDefined(
+      config.safeSingletonAddress,
+      pickDefined(config.aa?.safeSingletonAddress, preset?.aa?.safeSingletonAddress)
+    ),
+    safe4337ModuleAddress: pickDefined(
+      config.safe4337ModuleAddress,
+      pickDefined(
+        config.aa?.safe4337ModuleAddress,
+        preset?.aa?.safe4337ModuleAddress
+      )
+    ),
+    safeModuleSetupAddress: pickDefined(
+      config.safeModuleSetupAddress,
+      pickDefined(config.aa?.safeModuleSetupAddress, preset?.aa?.safeModuleSetupAddress)
+    ),
+    multiSendAddress: pickDefined(
+      config.multiSendAddress,
+      pickDefined(config.aa?.multiSendAddress, preset?.aa?.multiSendAddress)
+    ),
+    multiSendCallOnlyAddress: pickDefined(
+      config.multiSendCallOnlyAddress,
+      pickDefined(
+        config.aa?.multiSendCallOnlyAddress,
+        preset?.aa?.multiSendCallOnlyAddress
+      )
+    ),
+  };
+
+  const deployment = {
+    ...(preset?.deployment ?? {}),
+    ...(config.deployment ?? {}),
+    enabled: pickDefined(
+      config.deploymentEnabled,
+      pickDefined(config.deployment?.enabled, preset?.deployment?.enabled ?? true)
+    ),
+    bundlerUrl: pickDefined(
+      config.bundlerUrl,
+      config.deployment?.bundlerUrl
+    ),
+    bundlerApiKey: pickDefined(
+      config.bundlerApiKey,
+      config.deployment?.bundlerApiKey
+    ),
+    paymasterServiceUrl: pickDefined(
+      config.paymasterServiceUrl,
+      config.deployment?.paymasterServiceUrl
+    ),
+    paymasterAddress: pickDefined(
+      config.paymasterAddress,
+      pickDefined(config.deployment?.paymasterAddress, preset?.deployment?.paymasterAddress)
+    ),
+    paymasterApiKey: pickDefined(
+      config.paymasterApiKey,
+      config.deployment?.paymasterApiKey
+    ),
+    paymasterVerificationGasLimit: pickDefined(
+      config.paymasterVerificationGasLimit,
+      pickDefined(
+        config.deployment?.paymasterVerificationGasLimit,
+        preset?.deployment?.paymasterVerificationGasLimit
+      )
+    ),
+    paymasterPostOpGasLimit: pickDefined(
+      config.paymasterPostOpGasLimit,
+      pickDefined(
+        config.deployment?.paymasterPostOpGasLimit,
+        preset?.deployment?.paymasterPostOpGasLimit
+      )
+    ),
+    gasLimitMultiplier: pickDefined(
+      config.gasLimitMultiplier,
+      pickDefined(
+        config.deployment?.gasLimitMultiplier,
+        preset?.deployment?.gasLimitMultiplier
+      )
+    ),
+    feeMultiplier: pickDefined(
+      config.feeMultiplier,
+      pickDefined(config.deployment?.feeMultiplier, preset?.deployment?.feeMultiplier)
+    ),
+    debug: pickDefined(
+      config.deployDebug,
+      pickDefined(config.deployment?.debug, preset?.deployment?.debug ?? false)
+    ),
+  };
+
+  if (!deployment.bundlerUrl) {
+    throw new Error("缺少必填参数 bundlerUrl");
+  }
+  if (!deployment.paymasterServiceUrl) {
+    throw new Error("缺少必填参数 paymasterServiceUrl");
+  }
+
+  return { chain, aa, deployment };
+}
+
+export function normalizeCalls({ to, value = 0n, data = '0x', calls }) {
+  const normalizedCalls =
+    calls && calls.length
+      ? calls
+      : to
+      ? [{ to, value: BigInt(value), data }]
+      : null;
+
+  if (!normalizedCalls) {
+    throw new Error('sendTransaction 需要传入 calls 或 to');
+  }
+  return normalizedCalls;
+}

package/src/index.js

@@ -0,0 +1,32 @@
+import { createAaWalletSdk } from "./sdk.js";
+
+export { AaWalletSdk, createAaWalletSdk } from "./sdk.js";
+export {
+  createMpcViemLocalAccount,
+  createMpcOwnerFromRest,
+} from "./utils/aa-mpc.js";
+export { mpcGetWallet, mpcSignHash } from "./utils/mpc-client.js";
+export { createAaSmartAccountFromOwner } from "./utils/aa-wallet.js";
+
+const defaultSdk = createAaWalletSdk();
+
+/**
+ * 兼容模式：默认单例 init
+ */
+export function init(config) {
+  defaultSdk.init(config);
+}
+
+/**
+ * 兼容模式：默认单例 createWallet
+ */
+export async function createWallet(params) {
+  return defaultSdk.createWallet(params);
+}
+
+/**
+ * 兼容模式：默认单例 sendTransaction
+ */
+export async function sendTransaction(params) {
+  return defaultSdk.sendTransaction(params);
+}

package/src/sdk.js

@@ -0,0 +1,89 @@
+import { normalizeCalls, normalizeSdkConfig } from './core/config.js';
+import {
+  buildWalletContext,
+  ensureWalletDeployed,
+} from './services/wallet-service.js';
+import { sendCallsBySmartAccount } from './services/transaction-service.js';
+import { shouldAttemptSponsoredDeploy } from './utils/aa-deploy.js';
+
+export class AaWalletSdk {
+  constructor() {
+    this.config = null;
+  }
+
+  init(config) {
+    console.log('init 15', config);
+    this.config = normalizeSdkConfig(config);
+  }
+
+  getConfig() {
+    if (!this.config) {
+      throw new Error('SDK 未初始化，请先调用 init(config)');
+    }
+    return this.config;
+  }
+
+  async createWallet({ ownerPrivateKey, owner, index = 0 } = {}) {
+    const config = this.getConfig();
+    const {
+      publicClient,
+      owner: resolvedOwner,
+      smartAccount,
+    } = await buildWalletContext(config, { ownerPrivateKey, owner, index });
+    const { deployedOnChain, deployTxHash } = await ensureWalletDeployed(
+      config,
+      publicClient,
+      smartAccount,
+    );
+
+    return {
+      ownerAddress: resolvedOwner.address,
+      aaWalletAddress: smartAccount.address,
+      deployedOnChain,
+      deployTxHash,
+    };
+  }
+
+  async sendTransaction({
+    ownerPrivateKey,
+    owner,
+    index = 0,
+    to,
+    value = 0n,
+    data = '0x',
+    calls,
+  } = {}) {
+    const config = this.getConfig();
+    if (!shouldAttemptSponsoredDeploy(config.deployment)) {
+      throw new Error('缺少 bundler/paymaster 配置，无法发送赞助交易');
+    }
+    const normalizedCalls = normalizeCalls({ to, value, data, calls });
+    const {
+      publicClient,
+      owner: resolvedOwner,
+      smartAccount,
+    } = await buildWalletContext(config, { ownerPrivateKey, owner, index });
+    const { deployedOnChain } = await ensureWalletDeployed(
+      config,
+      publicClient,
+      smartAccount,
+    );
+    const txHash = await sendCallsBySmartAccount({
+      config,
+      publicClient,
+      smartAccount,
+      calls: normalizedCalls,
+    });
+
+    return {
+      ownerAddress: resolvedOwner.address,
+      aaWalletAddress: smartAccount.address,
+      deployedOnChain,
+      txHash,
+    };
+  }
+}
+
+export function createAaWalletSdk() {
+  return new AaWalletSdk();
+}

package/src/services/transaction-service.js

@@ -0,0 +1,17 @@
+import { sendSponsoredAaCallViaPaymaster } from "../utils/aa-deploy.js";
+
+export async function sendCallsBySmartAccount({
+  config,
+  publicClient,
+  smartAccount,
+  calls,
+}) {
+  const callData = await smartAccount.encodeCalls(calls);
+  const txHash = await sendSponsoredAaCallViaPaymaster({
+    publicClient,
+    smartAccount,
+    deployment: config.deployment,
+    callData,
+  });
+  return txHash;
+}

package/src/services/wallet-service.js

@@ -0,0 +1,65 @@
+import {
+  createAaPublicClient,
+  createAaSmartAccountFromOwner,
+  createAaWallet,
+  createChainFromConfig,
+} from "../utils/aa-wallet.js";
+import {
+  deployAaWalletViaPaymaster,
+  shouldAttemptSponsoredDeploy,
+} from "../utils/aa-deploy.js";
+
+/**
+ * @param {object} config
+ * @param {{ ownerPrivateKey?: `0x${string}`; owner?: import("viem/accounts").LocalAccount; index?: number }} options
+ */
+export async function buildWalletContext(config, options) {
+  const index = options.index ?? 0;
+  const { ownerPrivateKey, owner } = options;
+
+  if (!ownerPrivateKey && !owner) {
+    throw new Error("缺少 ownerPrivateKey 或 owner（例如 MPC LocalAccount）");
+  }
+  if (ownerPrivateKey && owner) {
+    throw new Error("请勿同时传入 ownerPrivateKey 与 owner");
+  }
+
+  const publicClient = createAaPublicClient(config.chain);
+  const { owner: resolvedOwner, smartAccount } = owner
+    ? await createAaSmartAccountFromOwner({
+        publicClient,
+        owner,
+        index,
+        aa: config.aa,
+      })
+    : await createAaWallet({
+        publicClient,
+        privateKey: /** @type {`0x${string}`} */ (ownerPrivateKey),
+        index,
+        aa: config.aa,
+      });
+
+  return { publicClient, owner: resolvedOwner, smartAccount };
+}
+
+export async function ensureWalletDeployed(
+  config,
+  publicClient,
+  smartAccount
+) {
+  let deployedOnChain = await smartAccount.isDeployed();
+  let deployTxHash = null;
+
+  if (!deployedOnChain && shouldAttemptSponsoredDeploy(config.deployment)) {
+    const chain = createChainFromConfig(config.chain);
+    deployTxHash = await deployAaWalletViaPaymaster({
+      publicClient,
+      chain,
+      smartAccount,
+      deployment: config.deployment,
+    });
+    deployedOnChain = await smartAccount.isDeployed();
+  }
+
+  return { deployedOnChain, deployTxHash };
+}

package/src/utils/aa-call.js

@@ -0,0 +1,159 @@
+import { encodeFunctionData } from "viem";
+import { createAaWallet, createAaPublicClient } from "./aa-wallet.js";
+import {
+  deployAaWalletViaPaymaster,
+  sendSponsoredAaCallViaPaymaster,
+  shouldAttemptSponsoredDeploy,
+} from "./aa-deploy.js";
+
+const erc20Abi = [
+  {
+    type: "function",
+    name: "approve",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "spender", type: "address" },
+      { name: "value", type: "uint256" },
+    ],
+    outputs: [{ name: "", type: "bool" }],
+  },
+  {
+    type: "function",
+    name: "transfer",
+    stateMutability: "nonpayable",
+    inputs: [
+      { name: "to", type: "address" },
+      { name: "value", type: "uint256" },
+    ],
+    outputs: [{ name: "", type: "bool" }],
+  },
+];
+
+/**
+ * 通过 AA 钱包调用目标合约（默认通过 paymaster 代付）。
+ *
+ * @param {object} params
+ * @param {object} params.config 与运行时配置结构一致
+ * @param {number} [params.accountIndex=0] 使用第几个 owner 账户
+ * @param {{ to: `0x${string}`; value?: bigint; data?: `0x${string}` }[]} params.calls
+ * @returns {Promise<{ ownerAddress: `0x${string}`; aaWalletAddress: `0x${string}`; txHash: `0x${string}`; deployedOnChain: boolean }>}
+ */
+export async function callContractByAaWallet({
+  config,
+  accountIndex = 0,
+  calls,
+}) {
+  const account = config.accounts?.[accountIndex];
+  if (!account) {
+    throw new Error(`accounts[${accountIndex}] 不存在`);
+  }
+
+  if (!shouldAttemptSponsoredDeploy(config.deployment)) {
+    throw new Error("deployment 未启用或缺少 bundler/paymaster 配置");
+  }
+
+  const publicClient = createAaPublicClient(config.chain);
+  const { owner, smartAccount } = await createAaWallet({
+    publicClient,
+    privateKey: account.privateKey,
+    index: account.index,
+    aa: config.aa,
+  });
+
+  let deployedOnChain = await smartAccount.isDeployed();
+  if (!deployedOnChain) {
+    await deployAaWalletViaPaymaster({
+      publicClient,
+      smartAccount,
+      deployment: config.deployment,
+    });
+    deployedOnChain = await smartAccount.isDeployed();
+  }
+
+  const callData = await smartAccount.encodeCalls(calls);
+  const txHash = await sendSponsoredAaCallViaPaymaster({
+    publicClient,
+    smartAccount,
+    deployment: config.deployment,
+    callData,
+  });
+
+  return {
+    ownerAddress: owner.address,
+    aaWalletAddress: smartAccount.address,
+    txHash,
+    deployedOnChain,
+  };
+}
+
+/**
+ * AA 钱包执行 ERC20 transfer。
+ *
+ * @param {object} params
+ * @param {object} params.config 与运行时配置结构一致
+ * @param {`0x${string}`} params.tokenAddress
+ * @param {`0x${string}`} params.to
+ * @param {bigint} params.amount
+ * @param {number} [params.accountIndex=0]
+ */
+export async function transferErc20ByAaWallet({
+  config,
+  tokenAddress,
+  to,
+  amount,
+  accountIndex = 0,
+}) {
+  const data = encodeFunctionData({
+    abi: erc20Abi,
+    functionName: "transfer",
+    args: [to, amount],
+  });
+
+  return callContractByAaWallet({
+    config,
+    accountIndex,
+    calls: [
+      {
+        to: tokenAddress,
+        value: 0n,
+        data,
+      },
+    ],
+  });
+}
+
+/**
+ * AA 钱包执行 ERC20 approve。
+ *
+ * @param {object} params
+ * @param {object} params.config 与运行时配置结构一致
+ * @param {`0x${string}`} params.tokenAddress
+ * @param {`0x${string}`} params.spender
+ * @param {bigint} params.amount
+ * @param {number} [params.accountIndex=0]
+ */
+export async function approveErc20ByAaWallet({
+  config,
+  tokenAddress,
+  spender,
+  amount,
+  accountIndex = 0,
+}) {
+  const data = encodeFunctionData({
+    abi: erc20Abi,
+    functionName: "approve",
+    args: [spender, amount],
+  });
+
+  return callContractByAaWallet({
+    config,
+    accountIndex,
+    calls: [
+      {
+        to: tokenAddress,
+        value: 0n,
+        data,
+      },
+    ],
+  });
+}