Solar Contract SDK

一个用于与 Solar 智能合约交互的 TypeScript SDK，支持 Node.js 和浏览器环境。

安装

npm install solar-contract-sdk

使用方法

Node.js 环境

ESM 导入

import { badge, badgeMinter, badgeMinterMetaTx, registry } from 'solar-contract-sdk';

// 使用 badge 模块
const tokenName = await badge.name({
  clientConfig,
  contractAddress: '0x...'
});

// 使用 badgeMinter 模块
const mintResult = await badgeMinter.mintToken({
  clientConfig,
  contractAddress: '0x...',
  params: { /* ... */ },
  account: '0x...'
});

CommonJS 导入

const { badge, badgeMinter, badgeMinterMetaTx, registry } = require('solar-contract-sdk');

// 使用方式与 ESM 相同

浏览器环境

直接导入

<script type="module">
  import { badge, badgeMinter, badgeMinterMetaTx, registry } from 'solar-contract-sdk';
  
  // 使用方式与 Node.js 相同
  const tokenName = await badge.name({
    clientConfig,
    contractAddress: '0x...'
  });
</script>

通过 CDN 使用

<script type="module">
  // 从 CDN 导入（需要先发布到 npm）
  import { badge, badgeMinter, badgeMinterMetaTx, registry } from 'https://unpkg.com/solar-contract-sdk@latest/dist/index.browser.mjs';
</script>

API 文档

通用参数

所有函数都接受一个 IntraceParams 对象作为参数，包含以下字段：

• clientConfig: 客户端配置对象
• contractAddress: 合约地址（0x${string} 格式）
• params: 函数特定参数（可选）
• account: 用于写入操作的账户（可选，写入操作必需）

BadgeUnbounded 合约 (badge 模块)

读取方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | name | 无 | string | 获取代币名称 | | symbol | 无 | string | 获取代币符号 | | balanceOf | { owner: 0x${string} } | bigint | 获取指定地址的代币余额 | | ownerOf | { id: bigint } | 0x${string} | 获取指定代币ID的所有者 | | getApproved | { id: bigint } | 0x${string} | 获取指定代币ID的授权地址 | | isApprovedForAll | { owner: 0x${string}, operator: 0x${string} } | boolean | 检查操作者是否被所有者授权 | | exists | { tokenId: bigint } | boolean | 检查指定代币ID是否存在 | | isFungible | 无 | boolean | 检查代币是否可替代 | | isRevocable | 无 | boolean | 检查代币是否可撤销 | | isTransferable | 无 | boolean | 检查代币是否可转移 | | owner | 无 | 0x${string} | 获取合约所有者 | | ownershipHandoverExpiresAt | { pendingOwner: 0x${string} } | bigint | 获取所有权移交过期时间 | | registry | 无 | 0x${string} | 获取注册表地址 | | supportsInterface | { interfaceId: 0x${string} } | boolean | 检查是否支持指定接口 | | tokenURI | { tokenId: bigint } | string | 获取代币URI | | totalSupply | 无 | bigint | 获取总供应量 |

写入方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | approve | { account: 0x${string}, id: bigint } | 0x${string} | 授权指定地址操作代币 | | burn | { tokenId: bigint } | 0x${string} | 销毁代币 | | cancelOwnershipHandover | 无 | 0x${string} | 取消所有权移交 | | completeOwnershipHandover | { pendingOwner: 0x${string} } | 0x${string} | 完成所有权移交 | | mint | { to: 0x${string}, tokenId: bigint, classId: bigint } | 0x${string} | 铸造代币 | | mintBatch | { addrs: 0x${string}[], tokenIds: bigint[], classId: bigint } | 0x${string} | 批量铸造代币 | | renounceOwnership | 无 | 0x${string} | 放弃所有权 | | safeTransferFrom | { from: 0x${string}, to: 0x${string}, id: bigint, data?: 0x${string} } | 0x${string} | 安全转移代币 | | setApprovalForAll | { operator: 0x${string}, isApproved: boolean } | 0x${string} | 设置操作者授权状态 | | transferFrom | { from: 0x${string}, to: 0x${string}, id: bigint } | 0x${string} | 转移代币 | | transferOwnership | { newOwner: 0x${string} } | 0x${string} | 转移所有权 |

BadgeMinter 合约 (badgeMinter 模块)

读取方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | badgeUnbounded | 无 | 0x${string} | 获取 BadgeUnbounded 合约地址 | | owner | 无 | 0x${string} | 获取合约所有者 | | ownershipHandoverExpiresAt | { pendingOwner: 0x${string} } | bigint | 获取所有权移交过期时间 | | registry | 无 | 0x${string} | 获取注册表地址 |

写入方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | cancelOwnershipHandover | 无 | 0x${string} | 取消所有权移交 | | completeOwnershipHandover | { pendingOwner: 0x${string} } | 0x${string} | 完成所有权移交 | | mintToken | { to: 0x${string}, tokenId: bigint, classId: bigint } | 0x${string} | 铸造代币 | | registerClass | { profileId: bigint, classId: bigint, contractAddr: 0x${string} } | 0x${string} | 注册代币类别 | | registerClassAndMintToken | { profileId: bigint, classId: bigint, contractAddr: 0x${string}, to: 0x${string}, tokenId: bigint } | 0x${string} | 注册类别并铸造代币 | | renounceOwnership | 无 | 0x${string} | 放弃所有权 | | requestOwnershipHandover | 无 | 0x${string} | 请求所有权移交 | | transferOwnership | { newOwner: 0x${string} } | 0x${string} | 转移所有权 |

BadgeMinterMetaTx 合约 (badgeMinterMetaTx 模块)

读取方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | badgeMinter | 无 | 0x${string} | 获取 BadgeMinter 合约地址 | | getDomainSeparator | 无 | 0x${string} | 获取域分隔符 | | getNonce | { user: 0x${string} } | bigint | 获取用户nonce | | nonces | { user: 0x${string} } | bigint | 获取用户nonce（别名） | | owner | 无 | 0x${string} | 获取合约所有者 | | ownershipHandoverExpiresAt | { pendingOwner: 0x${string} } | bigint | 获取所有权移交过期时间 | | registry | 无 | 0x${string} | 获取注册表地址 |

写入方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | cancelOwnershipHandover | 无 | 0x${string} | 取消所有权移交 | | completeOwnershipHandover | { pendingOwner: 0x${string} } | 0x${string} | 完成所有权移交 | | executeMintToken | { signer: 0x${string}, profileId: bigint, to: 0x${string}, tokenId: bigint, classId: bigint, nonce: bigint, signature: 0x${string} } | 0x${string} | 执行元交易铸造代币 | | executeRegisterClass | { signer: 0x${string}, profileId: bigint, classId: bigint, contractAddr: 0x${string}, nonce: bigint, signature: 0x${string} } | 0x${string} | 执行元交易注册类别 | | executeRegisterClassAndMintToken | { signer: 0x${string}, profileId: bigint, classId: bigint, contractAddr: 0x${string}, to: 0x${string}, tokenId: bigint, nonce: bigint, signature: 0x${string} } | 0x${string} | 执行元交易注册类别并铸造代币 | | renounceOwnership | 无 | 0x${string} | 放弃所有权 | | requestOwnershipHandover | 无 | 0x${string} | 请求所有权移交 | | transferOwnership | { newOwner: 0x${string} } | 0x${string} | 转移所有权 |

ProfileRegistry 合约 (registry 模块)

读取方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | name | 无 | string | 获取代币名称 | | symbol | 无 | string | 获取代币符号 | | balanceOf | { owner: 0x${string} } | bigint | 获取指定地址的代币余额 | | ownerOf | { id: bigint } | 0x${string} | 获取指定代币ID的所有者 | | getApproved | { id: bigint } | 0x${string} | 获取指定代币ID的授权地址 | | isApprovedForAll | { owner: 0x${string}, operator: 0x${string} } | boolean | 检查操作者是否被所有者授权 | | owner | 无 | 0x${string} | 获取合约所有者 | | ownershipHandoverExpiresAt | { pendingOwner: 0x${string} } | bigint | 获取所有权移交过期时间 | | supportsInterface | { interfaceId: 0x${string} } | boolean | 检查是否支持指定接口 | | tokenURI | { tokenId: bigint } | string | 获取代币URI | | totalSupply | 无 | bigint | 获取总供应量 | | chainId | 无 | bigint | 获取链ID | | liveStatus | 无 | boolean | 获取活跃状态 | | getDefaultProfile | { addr: 0x${string} } | bigint | 获取默认配置文件 | | getTokenClassContract | { classId: bigint } | 0x${string} | 获取代币类别合约地址 | | getTokenClassFungible | { classId: bigint } | boolean | 获取代币类别是否可替代 | | getTokenClassOwnerProfileId | { classId: bigint } | bigint | 获取代币类别所有者配置文件ID | | getTokenClassRevocable | { classId: bigint } | boolean | 获取代币类别是否可撤销 | | getTokenClassSchema | { classId: bigint } | string | 获取代币类别模式 | | getTokenClassTransferable | { classId: bigint } | boolean | 获取代币类别是否可转移 | | getClassId | { contractAddr: 0x${string}, tokenId: bigint } | bigint | 获取类别ID | | getContractSchema | { contractAddr: 0x${string} } | string | 获取合约模式 | | getTokenSchema | { contractAddr: 0x${string}, tokenId: bigint } | string | 获取代币模式 | | isClassController | { classId: bigint, addr: 0x${string} } | boolean | 检查是否为类别控制器 | | isContractAllowed | { addr: 0x${string} } | boolean | 检查合约是否被允许 | | isProfileController | { addr: 0x${string} } | boolean | 检查是否为配置文件控制器 | | isProfileControllerorOwner | { profileId: bigint, addr: 0x${string} } | boolean | 检查是否为配置文件控制器或所有者 |

写入方法

| 函数名 | 参数 | 返回类型 | 描述 | |--------|------|----------|------| | approve | { account: 0x${string}, id: bigint } | 0x${string} | 授权指定地址操作代币 | | burn | { tokenId: bigint } | 0x${string} | 销毁代币 | | cancelOwnershipHandover | 无 | 0x${string} | 取消所有权移交 | | completeOwnershipHandover | { pendingOwner: 0x${string} } | 0x${string} | 完成所有权移交 | | createProfile | { to: 0x${string}, profileId: bigint, isDefault: boolean } | 0x${string} | 创建配置文件 | | registerClass | { _profileId: bigint, classId: bigint, _contract: 0x${string} } | 0x${string} | 注册代币类别 | | registerClassAndSchema | { _profileId: bigint, classId: bigint, _contract: 0x${string}, schema: string } | 0x${string} | 注册类别和模式 | | registerToken | { classId: bigint, tokenId: bigint } | 0x${string} | 注册代币 | | renounceOwnership | 无 | 0x${string} | 放弃所有权 | | requestOwnershipHandover | 无 | 0x${string} | 请求所有权移交 | | safeTransferFrom | { from: 0x${string}, to: 0x${string}, id: bigint, data?: 0x${string} } | 0x${string} | 安全转移代币 | | setApprovalForAll | { operator: 0x${string}, isApproved: boolean } | 0x${string} | 设置操作者授权状态 | | setContractAllowed | { addr: 0x${string}, status: boolean } | 0x${string} | 设置合约允许状态 | | setContractSchema | { contractAddr: 0x${string}, schema: string } | 0x${string} | 设置合约模式 | | setProfileController | { addr: 0x${string}, status: boolean } | 0x${string} | 设置配置文件控制器 | | setTokenClassSchema | { classId: bigint, schema: string } | 0x${string} | 设置代币类别模式 | | setTokenURI | { uri_: string } | 0x${string} | 设置代币URI | | start | 无 | 0x${string} | 启动注册表 | | stop | 无 | 0x${string} | 停止注册表 | | transferFrom | { from: 0x${string}, to: 0x${string}, id: bigint } | 0x${string} | 转移代币 | | transferOwnership | { newOwner: 0x${string} } | 0x${string} | 转移所有权 |

使用示例

基本读取操作

import { badge } from 'solar-contract-sdk';

// 获取代币名称
const tokenName = await badge.name({
  clientConfig,
  contractAddress: '0x...'
});

// 获取代币余额
const balance = await badge.balanceOf({
  clientConfig,
  contractAddress: '0x...',
  params: {
    owner: '0x...'
  }
});

基本写入操作

import { badgeMinter } from 'solar-contract-sdk';

// 铸造代币
const hash = await badgeMinter.mintToken({
  clientConfig,
  contractAddress: '0x...',
  params: {
    to: '0x...',
    tokenId: 123n,
    classId: 456n
  },
  account: privateKeyAccount
});

错误处理

所有写入操作都需要提供 account 参数，如果未提供会抛出错误：

try {
  const hash = await badge.mint({
    clientConfig,
    contractAddress: '0x...',
    params: { /* ... */ }
    // 缺少 account 参数
  });
} catch (error) {
  console.error('Account is required for write operations');
}

类型定义

SDK 使用 TypeScript 提供完整的类型支持，包括：

• IntraceParams<T>: 通用参数接口
• ClientConfig: 客户端配置接口
• 所有函数参数和返回值的类型定义

许可证

MIT