MossAccountOS SDK

基于 Next.js + TypeScript 的 MossAccountOS 智能合约钱包集成库，提供简单易用的接口来集成智能合约钱包功能。

功能特性

• 🔗 多钱包支持: 支持 MetaMask、Rabby、Coinbase 等多种钱包
• 🌿 Moss 智能钱包: 智能合约钱包，支持 EOA 连接，dApp 中暴露 SCW 地址
• 🎨 RainbowKit 集成: 自定义 Connector 与主题，显示网络与余额
• ⚡ TypeScript 支持: 完整的类型定义和智能提示
• 🎯 精简设计: 只保留核心功能，无冗余代码
• 🧩 wagmi/RainbowKit 适配: 内置 createMossConnector 自定义 Connector，无需 ERC‑4337 也可将 SCW 接入 wagmi

快速开始

1. 安装依赖

npm install

2. 启动开发服务器

npm run dev

3. 使用 SDK

import { MossAccountOSSDK } from '@/lib/MossAccountOSSDK';

const sdk = new MossAccountOSSDK({
    rpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY',
    chainId: 11155111, // Sepolia 测试网
    contracts: {
        factory: '0x105a96155d0aB35520b6577090df1966Cb0e63CC',
        implementation: '0x6eD93218C1B0c6b88D2CC98f5644A68626BFDaB7',
        registry: '0xf103F1DB0a89581dC32C91738c3d1EBFA6956ad2'
    }
});

4. 使用 React Hooks

import { useMossAccountOS } from '@/hooks/useMossAccountOS';

function MyComponent() {
    const {
        isConnected,
        account,
        smartWalletAddress,
        connectWallet,
        checkSmartWallet,
        createSmartWallet
    } = useMossAccountOS();

    return (
        <div>
            {isConnected ? (
                <div>
                    <p>已连接: {account}</p>
                    <button onClick={checkSmartWallet}>检查智能钱包</button>
                    <button onClick={createSmartWallet}>创建智能钱包</button>
                </div>
            ) : (
                <button onClick={connectWallet}>连接钱包</button>
            )}
        </div>
    );
}

5. 直接使用 SDK

try {
    const account = await sdk.connectWallet();
    console.log('连接成功:', account);
} catch (error) {
    console.error('连接失败:', error.message);
}

4. 计算智能钱包地址

try {
    const smartWalletAddress = await sdk.getSmartWalletAddress(account);
    console.log('智能钱包地址:', smartWalletAddress);
} catch (error) {
    console.error('计算失败:', error.message);
}

5. 创建智能钱包

try {
    const txHash = await sdk.createSmartWallet(account);
    console.log('交易哈希:', txHash);
    
    // 等待交易确认
    const receipt = await sdk.waitForTransaction(txHash);
    if (receipt.status === 'success') {
        console.log('智能钱包创建成功！');
    }
} catch (error) {
    console.error('创建失败:', error.message);
}

API 参考

构造函数

new MossAccountOSSDK(config: SDKConfig)

参数:

• config.rpcUrl (string, 可选): RPC 端点 URL
• config.chainId (number, 可选): 链 ID
• config.provider (EIP1193Provider, 可选): 钱包 Provider
• config.contracts (object, 可选): 合约地址配置

方法

connectWallet()

连接 Web3 钱包

返回值: Promise<string> - 用户地址

checkNetwork()

检查当前网络是否正确

返回值: Promise<number> - 当前链 ID

getSmartWalletAddress(owner)

计算智能钱包地址

参数:

• owner (string|string[]): 所有者地址或地址数组

返回值: Promise<string> - 智能钱包地址

createSmartWallet(owner)

创建智能钱包

参数:

• owner (string|string[]): 所有者地址或地址数组

返回值: Promise<string> - 交易哈希

getImplementationAddress()

获取实现合约地址

返回值: Promise<string> - 实现合约地址

getBalance(address)

获取账户余额

参数:

• address (string): 账户地址

返回值: Promise<bigint> - 余额（Wei）

waitForTransaction(txHash, timeoutMs?)

等待交易确认

参数:

• txHash (string): 交易哈希
• timeoutMs (number, 可选): 超时时间（毫秒），默认 300000

返回值: Promise<TransactionReceipt> - 交易收据

checkSmartWalletExists(address)

检查智能钱包是否存在

参数:

• address (string): 智能钱包地址

返回值: Promise<boolean> - 是否存在

示例

访问主页面体验完整功能：

• 主页面: http://localhost:3000 - 包含钱包连接和智能钱包操作
• React Hooks: 使用 useMossAccountOS Hook 进行状态管理
• 组件: 示例页面直接集成 ConnectButton 与转账面板

在 wagmi + RainbowKit 中接入 Moss SCW

当前示例采用轻量模式：EOA 付 gas，SCW 负责出账，兼容传统 DApp。

• 连接器：src/wagmi/createMossConnector.ts
• Provider：src/wagmi/MossEip1193Provider.ts

行为说明：

• eth_accounts/eth_requestAccounts 返回 SCW 地址
• eth_sendTransaction 转为 EOA -> SCW.execute(...)，gas 由 EOA 支付，但出账资产是 SCW

提示：RainbowKit 与 wagmi 不是项目依赖，若需跑示例请在你的应用中安装依赖：wagmi、viem、@rainbow-me/rainbowkit。

主要能力：

• 将 eth_accounts/eth_requestAccounts 返回的地址替换为 SCW 地址；
• 拦截 eth_sendTransaction，把 from=SCW 的交易转换为 owner -> SCW.execute(target,value,data)；
• 拦截 personal_sign/eth_signTypedData*，返回符合 MossAccountOS ERC‑1271 的签名（默认由 owner 以 EIP‑712 eth_signTypedData_v4 对外层 MossAccountOSMessage(hash) 结构签名，并封装为合约 SignatureWrapper；兼容性不足时自动回退 eth_sign）。

注意：这条路径由 EOA 直接支付 gas，更贴合多数传统 DApp 的交互模型。

网络配置

Sepolia 测试网

const sdk = new MossAccountOSSDK({
    rpcUrl: 'https://eth-sepolia.g.alchemy.com/v2/YOUR_API_KEY',
    chainId: 11155111,
    contracts: {
        factory: '0x105a96155d0aB35520b6577090df1966Cb0e63CC',
        implementation: '0x6eD93218C1B0c6b88D2CC98f5644A68626BFDaB7',
        registry: '0xf103F1DB0a89581dC32C91738c3d1EBFA6956ad2'
    }
});

错误处理

SDK 使用 SDKError 类进行错误处理，包含以下错误类型：

• WALLET_NOT_INSTALLED - 未检测到 Web3 钱包
• WALLET_NOT_CONNECTED - 用户拒绝连接钱包或连接失败
• WRONG_NETWORK - 网络不匹配
• RPC_CALL_FAILED - 区块链 RPC 调用失败
• TRANSACTION_FAILED - 交易失败
• INVALID_ADDRESS - 无效地址
• TIMEOUT - 操作超时

try {
    await sdk.connectWallet();
} catch (error) {
    if (error instanceof SDKError) {
        console.error('错误代码:', error.code);
        console.error('错误信息:', error.message);
    }
}

开发

本地开发

1. 安装依赖：

npm install

2. 启动开发服务器：

npm run dev

3. 访问主页面：

http://localhost:3000

构建生产版本

npm run build
npm start

合约地址

当前部署的合约地址（Sepolia 测试网）：

合约类型	地址
MossAccountOS 实现	0x6eD93218C1B0c6b88D2CC98f5644A68626BFDaB7
MossAccountOSFactory	0x105a96155d0aB35520b6577090df1966Cb0e63CC
示例智能钱包	0x6df6F755404c3A6D23b3B008dbB085aecAC5fc0e
LogicRegistry	0xf103F1DB0a89581dC32C91738c3d1EBFA6956ad2

许可证

MIT License