# @carbonx3/cx3\.js 中文文档

规范地址：https://npmcn.com/package/%40carbonx3/cx3.js/

版本：0\.3\.8
npm 元数据更新时间：2026-11-01T15:22:35.715Z
中文译文更新时间：2026-11-09T18:20:01.205Z
软件包许可：UNLICENSED

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40carbonx3/cx3.js
原文对照：https://npmcn.com/package/%40carbonx3/cx3.js/?lang=original
项目主页：https://cx3script.com/

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：125 kB，14 个文件
- 模块格式：ESM + CJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=20\.19\.0
- 运行依赖：1 个
- 首次发布：2026-09-06T13:20:43.749Z
- 最新版本发布：2026-11-01T15:22:35.502Z
- 近 30 天下载量：1966（2026-10-09 至 2026-11-07，npm 官方下载统计）
- 已发布版本数：12（近 12 个月 12 个）

## 中文简介

官方Node.js SDK (CX3js) for CarbonX3 Green 链: OAuth2 应用访问, 本地 sep256k1 签名, ABI 约束合同和信使在 REST + JSON 上部署

## 安装

```sh
npm install @carbonx3/cx3.js
```

也可以使用：`pnpm add @carbonx3/cx3.js`、`yarn add @carbonx3/cx3.js`、`bun add @carbonx3/cx3.js`

## README

# @ carbox3/cx3. js (英语)

[![npm version](https://img.shields.io/npm/v/@carbonx3/cx3.js.svg)](https://www.npmjs.com/package/@carbonx3/cx3.js) [![Node.js version](https://img.shields.io/node/v/@carbonx3/cx3.js.svg)](https://nodejs.org/) [![Types](https://img.shields.io/npm/types/@carbonx3/cx3.js.svg)](https://www.npmjs.com/package/@carbonx3/cx3.js)

官方节点Js SDK(**CX3js 数据**用于 [碳X3 绿色链](https://carbonx3.com/)。 。 。 .

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和客户端秘密)如下所述.

## 安装

```bash
npm install @carbonx3/cx3.js
```

## 创建应用程序

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

| 范围 | 赠款 |
| --- | --- |
| `read` | 余额、非现金、合同、ABI、事件、转让、交易和只读电话 |
| `write` | 钱包签署的合同发送和本地CX3转让 |
| `deploy` | 合同部署,加上暂停、不暂停和删除(所有者签署) |

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

## 快开始

```javascript
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` 并携带钱包的每个范围.

```javascript
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`:

```javascript
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` 范围 :

| 方法 | 回返 |
| --- | --- |
| `getBalance(address)`, (中文(简体) ), `getBalanceAndNonce(address)`, (中文(简体) ), `getNonce(address)`, (中文(简体) ), `getPendingNonce(address)` | 原生 CX3 平衡与非组合 |
| `getContractInfo(address)`, (中文(简体) ), `getAbi(address)`, (中文(简体) ), `listContracts({ limit, offset, owner, standard, type, live })` | 合同登记条目和ABI |
| `call(address, method, params)` | 只读调用;结果为 `value` |
| `getEvents(address, { type, limit, offset })`, (中文(简体) ), `getTransfers(address, { limit, offset })`, (中文(简体) ), `getHolders(address, { limit, offset })` | 合同历史 |
| `getAddressTransactions(address, limit)`, (中文(简体) ), `getTxStatus(txHash)` | 交易 |
| `getRequest(requestId, from)` | 签了合同的寄件结果如何(公开;见 [正在等待交易](https://npmcn.com/package/%40carbonx3/cx3.js/#readme-waiting-for-a-transaction)(中文(简体) ) |

## 合同

```javascript
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`。 。 。 .

```javascript
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
```

## 部署令牌

```javascript
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
```

| 帮助 | 标准 |
| --- | --- |
| `deployCX30` | 硬币 |
| `deployCX31` | 单位/会计代号 |
| `deployCX300` | 现实世界资产 |
| `deployCX315` | 忠诚 |
| `deployCX3192` | 灵魂身份 |
| `deployCX337` . `deployCX341` | 绿色标准:CBAM证明、可持续性报告、供应链、重要性评估、绿色索赔 |

调用其块解答 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` 当节点不答.

```javascript
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 扫描](https://cx3scan.carbonx3.com/)。 。 。 .

## 签名

文摘为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` 代码.

```javascript
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;
}
```

| 代码 | 含义 |
| --- | --- |
| `CREDENTIALS_REQUIRED` | 没有应用程序、 API 密钥或 `devNode` 已经给出 |
| `INVALID_CLIENT_CREDENTIALS` | 客户身份或秘密不在 `cx3app_…` 编号 : `cx3sec_…` 格式 |
| `invalid_client` | 符号端点拒绝了申请( 错误的秘密, 或者被撤销) |
| `insufficient_scope`, (中文(简体) ), `ROUTE_NOT_ALLOWED` | 路线需要另一个范围, 或不对应用程序开放( 403) |
| `RATE_LIMITED` | 申请的费率限额已经达到(429) |
| `INSUFFICIENT_BALANCE`, (中文(简体) ), `GAS_PRICE_TOO_LOW` | 本地汇款人的汇款人无法支付加天然气,或者天然气价格低于链式底价 |
| `INVALID_AMOUNT`, (中文(简体) ), `INVALID_AMOUNT_PRECISION` | 原生数量不大于0,或小数6个以上(CX3有6个); `transferNative` 签名前先检查两个 |
| `GAS_LIMIT_TOO_LOW`, (中文(简体) ), `GAS_LIMIT_TOO_HIGH` | 本土转移的气体限制在21000到100000之外 |
| `GAS_LIMIT_EXCEEDED` | 一个合同发送 `gasLimit` 高于链条的最大值(400, `max` (在体内) |
| `INVALID_NONCE_ORDER` | 本地转移的"非ce"不是下一种(`expectedNonce` (在答复中) |
| `DATA_TOO_LARGE`, (中文(简体) ), `DATA_TOO_DEEP` | 一个交易 `data` 太大或巢穴太深 |
| `INVALID_TOKEN_SYMBOL`, (中文(简体) ), `DUPLICATE_TOKEN_SYMBOL` | 符号不是 `A-Z` 编号 : `0-9`,或已在使用(409) |
| `PRIVATE_TOKEN_SENDER`, (中文(简体) ), `PRIVATE_TOKEN_RECIPIENT`, (中文(简体) ), `PRIVATE_TOKEN` | 私人令牌规则(见上文) |
| `TX_TIMEOUT` | 节点的25秒等在块前结束:已排队,不是最终. 正在等待一个带有此代码的发送回复 `tx.wait()` 遵循它;没有散列,结果将公开 `requestId`(中文(简体) ) |
| `TX_FAILED` | 交易失败( 仅在其 `finalAfter`(中文(简体) ) |
| `TX_TRACK_TIMEOUT` | `tx.wait()` 当交易尚未完成时停止: 没有失败, 请不要再签名 |
| `REPLAYED_REQUEST` | 这个签名的请求已经收到或已经运行(409次);答案没有说明它是如何结束的. 仔细查查 `provider.getRequest(err.body.requestId, wallet.address)` 别再签了 |
| `REQUEST_LOOKUP_UNAVAILABLE` | `getRequest` 无法询问链( 503 ) : 稍后再试, 不要再签名 |
| `LEDGER_UNAVAILABLE`, (中文(简体) ), `LEDGER_FULL` | 网关 `/dapp/v1` 发送无法记录请求( 503) : 它没有发送, 同样的签名机构可能在稍后再次发送, 没有新的签名 |
| `BASIC_AUTH_UNSUPPORTED` | 这个 `auth` 选项被使用 |
| `NO_CHAIN_IDENTITY` | 网络的链式id或起源散列没有可用;没有它们,便不签名本地转移 |

## 浏览器应用程序

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

## 环境变量

| 变量 | 用于 |
| --- | --- |
| `CX3_CLIENT_ID`, (中文(简体) ), `CX3_CLIENT_SECRET` | 选项省略时的应用程序证书 |
| `CX3_API_KEY` | 遗留钱包 API 密钥 |
| `CX3_NODE_URL` | 网关 URL 用于 `getDefaultProvider()` |

## 类型脚本

类型声明(`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 参考文献](https://cx3script.com/docs?doc=cx3js-sdk)
-   [部署后节点.js](https://cx3script.com/docs?doc=node-after-deploy)
-   [用于浏览器的 CX3 IIFE](https://cx3script.com/docs?doc=cx3iife)
-   [CX3Script 开发站点](https://cx3script.com/)
-   [碳X3 绿色链](https://carbonx3.com/)

## 许可证

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

## 常见问题

### @carbonx3/cx3\.js 是什么？

官方Node\.js SDK \(CX3js\) for CarbonX3 Green 链: OAuth2 应用访问, 本地 sep256k1 签名, ABI 约束合同和信使在 REST \+ JSON 上部署

### 如何安装 @carbonx3/cx3\.js？

在项目目录运行 npm install @carbonx3/cx3\.js，或使用 pnpm add / yarn add / bun add。

### @carbonx3/cx3\.js 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @carbonx3/cx3\.js 支持 ESM 还是 CommonJS？

同时提供 ES Module 与 CommonJS 入口，import 和 require\(\) 都可以使用，打包工具会自动选择合适的版本。

### @carbonx3/cx3\.js 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=20\.19\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @carbonx3/cx3\.js 可以商用吗？

@carbonx3/cx3\.js 使用 UNLICENSED 许可。作者声明为 UNLICENSED，即不授予公开使用许可（与公共领域的 Unlicense 不同）。使用前需获得作者授权。以上为概括，不构成法律意见，请以许可原文为准。

### @carbonx3/cx3\.js 的下载量有多少？

根据 npm 官方下载统计，@carbonx3/cx3\.js 在 2026/10/09 – 2026/11/07 这 30 天内被下载 1,966 次，日均约 66 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @carbonx3/cx3\.js 还在维护吗？

最新版本 0\.3\.8 发布于 2026/11/01（8 天前）；至今共发布 12 个版本，其中过去 12 个月发布了 12 个；首次发布于 2026/09/06。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。