@ carbox3/cx3. js (英语)

官方节点Js SDK(CX3js 数据用于 碳X3 绿色链。 。 。 .

CX3js通过CX3Api网关将服务器侧应用连接到CarbonX3绿色链. 它作为 OAuth2 应用程序签名,在本地用 sep256k1 签名交易,将合同ABI 绑定为平版JavaScript 方法并部署"绿色链"符号标准. 请求是 REST + JSON 有命名参数,而不是二进制调取数据.

网络状态 : CarbonX3 绿色链目前作为一个开发网络运行(devnet; provider.getStatus() 返回当前链 id。 Devnet CX3,令牌和合约是没有货币价值的测试数据,在devnet被重置后可能会被清除.

特征

• OAuth2 应用程序访问:来自 CX3WebUI 的客户端证书;请求访问符,缓存并更新给您.
• 本地签名: 私人密钥留在您的进程中, 每张书写都带有钱包的 sep256k1 签名 .
• ABI 合同数字 : token.balanceOf(owner) 财务报告和审定财务报表 token.transfer(to, amount)从链上装入ABI.
• 调试部署: CX30,CX31,CX300,CX315和CX3192,外加绿色标准 CX337-CX341.
• 私人纪念品:部署它们,并在签署任何文件之前检查授权的钱包.
• 公共链读取:链态,钱包符和活性,CarbonFi池和CX3WASM接口(WIT).
• 包含类型脚本声明;与两者合作 require 财务报告和审定财务报表 import。 。 。 .

所需资源

• 节点.js 20.19 联合国 或以后(本国) fetch) (中文(简体) ).
• 在 CX3WebUI 中创建的应用程序(客户ID和客户端秘密)如下所述.

安装

npm install @carbonx3/cx3.js

创建应用程序

1. 打开 CX3 网络UI → 设置 – API – 应用程序 并连接应用程序的钱包.
2. 命名应用程序, 选择其范围并单击 创建 App。钱包在请求上签名.
3. 存储 客户端标识 (单位:千美元)cx3app_…)和 客户端秘密 (单位:千美元)cx3sec_…,只在服务器环境中显示一次).

钱包最多可容纳5个应用程序. 撤销同一页上的应用程序在一分钟内停止其访问符.

快开始

const { Cx3Provider, Cx3Wallet } = require("@carbonx3/cx3.js");

const provider = new Cx3Provider("https://cx3api.carbonx3.com", {
  clientId: process.env.CX3_CLIENT_ID,         // cx3app_…
  clientSecret: process.env.CX3_CLIENT_SECRET  // cx3sec_…
});
const wallet = new Cx3Wallet(process.env.CX3_PRIVATE_KEY, provider);

async function main() {
  // Native CX3 balance
  console.log(await provider.getBalance(wallet.address));

  // Token contract; its ABI is loaded from the chain
  const token = await provider.getContract(process.env.CONTRACT_ADDRESS, null, wallet);
  console.log(await token.balanceOf(wallet.address));

  // Wallet-signed token transfer (BigInt or decimal string)
  const tx = await token.transfer("0xRecipient…", 10n ** 18n);
  await tx.wait();

  // Native CX3 transfer
  await wallet.transferNative("0xRecipient…", 1.5);
}

main().catch((err) => {
  console.error(err.code || err.name, err.message);
  process.exitCode = 1;
});

ES模块也工作: import { Cx3Provider, Cx3Wallet } from "@carbonx3/cx3.js";。其余例子假设 async 上下文.

认证

OAuth2应用(推荐). 供应商交易所 clientId 财务报告和审定财务报表 clientSecret 时间 POST /oauth/token (客户证书赠款)1小时访问证,并作为 Authorization: Bearer …它在它到期前一分钟续签它 如果网关回答 invalid_token,取出新鲜的并重复一次。 秘密只传送到符号端点. scope: ["read"] 请求范围比应用程序要小。 当选项被省略时,提供者会读取 CX3_CLIENT_ID 财务报告和审定财务报表 CX3_CLIENT_SECRET。 。 。 .

访问令牌识别应用程序;每个书写仍然由钱包签名. 应用程序范围以外的路径答案 403 insufficient_scope,和为CarbonX3自己的服务预留的路线答案 403 ROUTE_NOT_ALLOWED。每个应用程序都有自己的费率限制(默认每分钟300个请求, 429 RATE_LIMITED) (中文(简体) ).

provider.bindApiKey(address) (或 wallet.bindApiKey())确认申请属于的钱包: { ok: true },否则 wallet_mismatch。 。 。 .

钱包 API 键 (legacy). A 类 cx3wk_… 来自同一设置页面的密钥在应用程序移动到 OAuth2 时仍然有效 。 通过它作为 apiKey (或设置) CX3_API_KEY;它作为 X-Api-Key 并携带钱包的每个范围.

const provider = new Cx3Provider("https://cx3api.carbonx3.com", { apiKey: process.env.CX3_API_KEY });

开发节点. new Cx3Provider(devNodeUrl, { devNode: true }) 向一个不认证运行的开发节点( 它) 说话 /api/v1 (原始内容存档于2018-10-21). routes.

需要全权证书. 没有应用程序、 API 密钥或 devNode: true,构造器抛出 CREDENTIALS_REQUIRED。 。 。 .

没有HTTP Basic. HTTP Basic是绿链节点和CarbonX3服务之间的内部登录,不是应用程序证书,所以SDK从未发送: auth 选项抛出 BASIC_AUTH_UNSUPPORTED,以及 headers 无法携带 Authorization 或者说 X-Api-Key。 。 。 .

读取链式数据

公共链条数据,服务于每个应用程序的网关(开发节点答案) DAPP_ONLY:

const status = await provider.getStatus();                               // { height, hash, timestamp, chainId, genesisHash }
const { tokens } = await provider.getTokens(wallet.address);             // every token with this wallet's balance
const page = await provider.getActivity(wallet.address, { limit: 20 });  // newest first, no block rewards
const older = await provider.getActivity(wallet.address, { before: page.nextBefore });
const { pairs } = await provider.getDexPairs();                          // CarbonFi pools
const lp = await provider.getLpBalance(pairs[0].id, wallet.address);     // LP balance in one pool
const { wit } = await provider.getWit(contractAddress);                  // CX3WASM interface (WIT)

与 read 范围 :

合同

const token = await provider.getContract(address, null, wallet);  // ABI from the chain

await token.balanceOf(owner);                        // view → read-only call
await token.call("balanceOf", { address: owner });   // named parameters (CX30)
const tx = await token.transfer(to, amount);         // transaction → wallet-signed send
await tx.wait();

支持的ABI 形状 :

1. 标准接口 JSON : { methods: { balanceOf: { type: "view", inputs: [...] } } }
2. 编译平面 ABI : [{ type: "function", name, inputs, stateMutability }]
3. CX3WASM 编译器 ABI : { functions: [{ name, params, view }] }

provider.getContract(address) 装入 ABI 链式调用合同的形状 2 编译为 CX3JS, 3 为 CX3WASM 。 内建链标准(ABI投入) ["params"])取一个命名对象: await lp.transfer({ to, amount })。与提供商创建的合同控件而非钱包只能读取;其写入 NO_SIGNER。 。 。 .

交易和收费

气体在CX3中支付给产生该块的验证器:用到的气体×气价(devnet默认为每气体0.0001 CX3).

• 本地转移使用21 000个气体: 2.1 CX3 软件。发送者需要金额加费用.
• 通过网关发送或部署的合同由链条自己的部署账户中继:电话仍然作为你的钱包运行(链条再次检查你的签名),你的钱包不为此支付瓦斯. 呼叫的气体限制(默认为10万)在发送呼叫时会将节点的试跑(一个需要更多呼叫的呼号被拒绝);在阻隔中,VM在自己的每呼叫限制下运行.

本地转移的平衡太少 INSUFFICIENT_BALANCE本地转让的天然气限制和天然气价格 0 (链的默认值:21 000和0.0001)或21 000-10 000,至少是0.0001的链底(GAS_LIMIT_TOO_LOW, (中文(简体) ), GAS_LIMIT_TOO_HIGH, (中文(简体) ), GAS_PRICE_TOO_LOW),其数量大于0,最多为小数点后6位,因为CX3有6. transferNative 签名前检查金额( q)INVALID_AMOUNT, (中文(简体) ), INVALID_AMOUNT_PRECISION) (中文(简体) ).

正在等待交易

合同发送默认等待其块(节点最多等待25秒) { wait: 0 } 它马上回来. tx.wait() 对交易状况进行投票,直至确认或永久失效:

• 待定没有失败. tx.status 实值 "pending" 页:1 { wait: 0 },用于队列发送(HTTP 202) queued: true代码 TX_TIMEOUT:不在节点等取的一块内)并取出被丢弃的发件. tx.success 留下来 true,以及 tx.wait() 跟踪交易。 队列或已丢弃的部署是 status: "pending" 也: 标志性工厂给予 result.contract 仅在 result.wait() 看到它确认.
• 已丢弃信件 . 发送从它的块被修剪的节点 回来作为HTTP 202与 tx.dropped === true 财务报告和审定财务报表 tx.finalAfter (ms epoch,约12分钟后签署时间戳). 在此之前,另一个验证器可能仍然包含它,所以默认 tx.wait() 继续等到 finalAfter 还有30秒 之后情况是 failed,以及 tx.wait() 拒绝方式 TX_FAILED。 。 。 .
• 只有最后的失败才拒绝 TX_FAILED。 。 。 . TX_TRACK_TIMEOUT (你自己的) timeoutMs,否则为60秒或至 finalAfter )表示交易仍未完成: receipt 已经 status: "pending", (中文(简体) ), dropped 财务报告和审定财务报表 finalAfter。网络错误、429或5xx答案,而投票不会结束等待.
• 在它还能运行的时候 别再签同样的电话了. 新的签名是第二次呼叫。 每一个发送的答案都携带着 tx.requestId,以及 provider.getRequest(tx.requestId, wallet.address) 告诉后来发生了什么: executed, (中文(简体) ), pending, (中文(简体) ), submitted 或者说 unknown。 。 。 .

const tx = await token.transfer(to, amount);
if (tx.dropped) console.log("Not in a block yet; final after", new Date(tx.finalAfter));
const receipt = await tx.wait();  // confirmed, or throws TX_FAILED / TX_TRACK_TIMEOUT

部署令牌

const { Cx3TokenFactory } = require("@carbonx3/cx3.js");

const factory = new Cx3TokenFactory(wallet);  // the application needs the deploy scope
const result = await factory.deployCX30({ name: "My Token", symbol: "MTK", initialSupply: "0" });
console.log(result.contractAddress);          // result.contract is a ready Contract handle

调用其块解答 HTTP 202 的节点 result.dropped === true, (中文(简体) ), status: "pending", (中文(简体) ), finalAfter 当知道时 contractAddress (否则) null它还没有部署,所以 result.contract 未设置. await result.wait() 跟着它 tx.wait() 你应当随从一种迹象,一旦它被证实, status 变成 "confirmed" 工厂也增加了 result.contract (和 result.authorized 用作私人物品) finalAfter 它拒绝 TX_FAILED在此之前,不要再次部署同一合同. wallet.deployContract() 结果相同 dropped, (中文(简体) ), finalAfter 财务报告和审定财务报表 wait()。 。 。 .

帮助者默认向CX3WASM部署. 该链条使CX30和CX337-CX341从字段取出;CX31,CX300,CX315和CX3192将其CX3Script源作为 sourceCode (否则链子会回答 STANDARD_NOT_WASM_DEPLOYABLE) (中文(简体) ).

托肯符号为大写字母 A-Z 数字 0-9 只有这个 SDK在签字前会检查这个INVALID_TOKEN_SYMBOL; 见 isValidTokenSymbol),链条每个符号保留一份合同(409 DUPLICATE_TOKEN_SYMBOL) (中文(简体) ).

私人纪念品

私人代币只由其所有人及其授权的钱包发送、接收和查看。 令牌合同在链上强制执行这一点,而SDK也遵循同样的规则:

• 列表 : getTokens 只向拥有者、经授权的钱包和持有者显示私人信使,并且只使用钱包自己签名的证明(抬头) X-CX3-Wallet-Proof,自2026-10-19; CX3 开始. 钱包发给自己的名单,所以申请会得到公开的代号; listContracts() 仅在应用程序的钱包是其所有者或授权的钱包时显示。 其持有者和原始状态答案 403 PRIVATE_TOKEN 除了所有者之外,每个应用程序都使用.
• 发送 : 之前为 transfer, (中文(简体) ), transferFrom 或者说 mint ,钱包询问是否授权两端。 如果不是,它会扔 PRIVATE_TOKEN_SENDER 或者说 PRIVATE_TOKEN_RECIPIENT 而不是签署一个寄件 街区会拒绝. { privateCheck: false } 跳过支票.
• 检查 : provider.isPrivateToken(token) 财务报告和审定财务报表 provider.isTokenAuthorized(token, wallet)返回时 true 给所有者或列出的钱包, false 否则 null 当节点不答.

const res = await factory.deployCX30({
  name: "Team Credit",
  symbol: "TEAMC",
  initialSupply: "1000000",
  visibility: "private",
  authorizedWallets: ["0x…", "0x…"]  // up to 200; one signed addToWhitelist each after the deploy
});
// res.authorized → [{ wallet, success, txHash }]
await res.contract.addToWhitelist("0xNew…", "");  // later, owner only; removeFromWhitelist removes one

私人 CX31, CX300, CX315 或 CX3192 将其 CX3WebUI 源作为 sourceCode;绿色标准没有私人变体. 私人从其他钱包的列表和手中保留了一枚令牌,但这并不使之成为秘密:块、转移和合同呼叫在链上可以读取,如: CX3 扫描。 。 。 .

签名

文摘为UTF-8字符串,与SHA-256并用secp256k1签名,字节与绿链节点验证内容相同. 每个类型都以自己的前缀(签名域)为起点,因此一种签名从未被验证为另一种; chainId 财务报告和审定财务报表 genesisHash 是网络的( c)provider.getChainIdentity(),由钱包方法本身获取)和地址为小写 0x + 40 六进制 :

• 部署: CX3_DEPLOY_V1| + 键 JSON.stringify([chainId, genesisHash, owner, standard, name, symbol, decimals, initialSupply, timestamp])
• 合同发送: CX3_CALL_V1| + 键 JSON.stringify([chainId, genesisHash, contractAddress, method, params, fromAddress, timestamp])。链条在中继交易中再次检查此签名:一个呼叫作为您的钱包运行.
• 所有者动作 : CX3_OWNER_V1| + 键 JSON.stringify([chainId, genesisHash, action, address, owner, timestamp])
• 站点消息 : 0x19 + 键 "CX3 Signed Message:\n" + UTF-8 长度 + 消息 (signPersonalMessage), CX3Wallet 扩展和应用程序标志的方式 cx3_sign_message
• 本地转移 : JSON.stringify({ type, fromAddress, toAddress, amount, nonce, timestamp, data, gasLimit, gasPrice, chainId, genesisHash }),有40hex地址,没有 0x· ; chainId 财务报告和审定财务报表 genesisHash (单位:千美元)0x + 64 hex)是网络的,来自 provider.getChainIdentity()

参数中的 BigInt 值在签名前被转换为小数字符串,准确的这些参数被发送出. 部署、合同发送和所有者签名都带有时间戳,并在网关钟后±5分钟内接受。 土生土长的转接只在其时间戳后60秒内被允许(池子在60秒后将其丢出),而一个街区只在其时间戳后10分钟内取出. 起源散列将原生的转移与一个网络和一个起源联系起来:在链子重置后,在它不再验证之前就签了转移. 一个地址是 0x + 最后20个字节 sha256(uncompressedPublicKey)。 。 。 .

同一构件导出 : buildDeployDigest, (中文(简体) ), buildSendDigest, (中文(简体) ), buildOwnerActionDigest (每个都把身份当作最后的论点), buildTransferPayload, (中文(简体) ), personalMessageBytes, (中文(简体) ), signMessage (按规定签署摘要), signPersonalMessage, (中文(简体) ), privateKeyToAddress 财务报告和审定财务报表 createPrivateKey。 。 。 .

处理错误

每个错误都是 Cx3Error 带有 code。 。 。 . Cx3HttpError 添加 HTTP status 和对策 body (与 requestId 合同发送; Cx3TxError 添加交易 receipt。如果节点拒绝使用 HTTP 200 返回,则发送或本地转移 tx.success === false 代码输入 tx.error,以及 tx.wait() 以 Cx3TxError 代码.

const { Cx3HttpError } = require("@carbonx3/cx3.js");

try {
  await token.transfer(to, amount);
} catch (err) {
  if (err instanceof Cx3HttpError && err.status === 403) console.error("Not allowed:", err.code);
  else throw err;
}

浏览器应用程序

此软件包用于Node.js服务器. 网页使用 CX3 IIFE 数据 (单位:千美元)window.cx3与 CX3Wallet 扩展: @carbonx3/cx3-iife 在npm和jsDelivr,或 下载它; 见 CX3 IIFE 指南。将应用程序的证书保存在您的服务器上,并保存在同一个来源的代理服务器后,从不在浏览器JavaScript中隐藏客户端,API密钥或私钥.

环境变量

类型脚本

类型声明(index.d.ts与包裹同船.

从0.2.x升级

0.3.0版本为网络新的签名格式(0.3.1到0.3.4只更改这个README,文件头和注释,而不是代码)签名本地传输. 以0.3.5计, bindApiKey 带有钱包的 API 密钥询问网关 /wallet/api-key/bind (此前,它曾要求 /whoami网关拒绝,所以总是失败。 在0.3.6时, wait() 跟踪发送或部署网关报告作为非最终报告(dropped直至其结束 finalAfter 而不是在60 s 之后失败, a TX_TIMEOUT 以散列方式回答, getRequest() 寻找一个签名的请求,和 transferNative 拒绝超过6个小数。 0.3.7 仅改变这项研究:本地转移的天然气价格下限为0.0001 (0.3.6 研究母公司说为0.00001)。 0.3.8 只更改此 README: CX3 IIFE 下载链接名称 cx3-0.2.9.min.js。 。 。 .

• 起源散列的签名. transferNative 询问网络的链式id和起源散列(provider.getChainIdentity()除非两者均作为 opts.chainId 财务报告和审定财务报表 opts.genesisHash.0.2.x 转让不再在链上核查.
• 没有退后链 ID. buildTransferPayload 掷出 NO_CHAIN_IDENTITY 无 chainId 财务报告和审定财务报表 genesisHash; 数据 CX3_CHAIN_ID 变量和 chainIdBind 选项已消失.
• 已打入文摘. 合同发送、部署和所有者行动标志 CX3_CALL_V1 编号 : CX3_DEPLOY_V1 编号 : CX3_OWNER_V1 带入网络的文摘(见签名) |- 0.2.x的合并文摘被拒绝. signSend, (中文(简体) ), signDeploy 财务报告和审定财务报表 signOwnerAction 选择 { chainId, genesisHash },否则,他们要求提供者(一分钟)。 这个 build*Digest 帮助者需要身份作为他们最后的论点.
• 站点信息. signPersonalMessage 标记钱包的签名方式 cx3_sign_message (与 0x19 前缀); signMessage 仍然签署一份文摘.

从0.1.x升级

CX3js在β (0.x)中,因此一个小版本可能包含断裂变化. 版本0.2.0:

• 需要全权证书. 供应商以 OAuth2 应用程序( 或带有钱包 API 密钥) 与 CX3Api 网关交谈并丢弃 CREDENTIALS_REQUIRED 没有一个。 没有认证需要的开发节点 devNode: true; 0.1.x 使用以下节点路线: /api/v1 默认.
• HTTP Basic被删除. 这个 auth 选项抛出 BASIC_AUTH_UNSUPPORTED,以及 headers 无法携带 Authorization 或者说 X-Api-Key。 。 。 .
• 节点.js 20.19或以后 需要(@noble/secp256k1 (第3条).
• 修补 : BigInt 参数作为小数字符串签名并发送,以及 transferNative 发送它标志的气田.
• 新建 : 公共链条读作(getStatus, (中文(简体) ), getTokens, (中文(简体) ), getActivity, (中文(简体) ), getDexPairs, (中文(简体) ), getLpBalance, (中文(简体) ), getWit),私人代币和 isValidTokenSymbol。 。 。 .

文档

• CX3js SDK 参考文献
• 部署后节点.js
• 用于浏览器的 CX3 IIFE
• CX3Script 开发站点
• 碳X3 绿色链

许可证

UNLICENSED:Mersolution科技有限公司的专有软件. 使用取决于 CX3 脚本使用术语 (项目03):你可以安装它,并将其与连接到CarbonX3 Green Chain的应用程序,包括商业应用程序进行未修改的运输;你不得自行修改、出售或再生,或与其他网络使用.