@caict-bif/bif-typescript-sdk

直连 BIF 底层链节点的 TypeScript SDK（CommonJS）。

接口范围以链对外公开的 HTTP/WebSocket 接口为准，仅包含本 SDK 实际提供的方法。

项目结构

src/
├── bif-core/            # 传输层：HTTP 客户端（BifHttpClient）、WebSocket 订阅客户端、订阅协议
├── bif-sdk/             # SDK 层
│   ├── provider.ts      # BifProvider 入口：聚合五个域服务
│   └── interface/
│       ├── signer.ts    # BifSigner（账户 + 交易签名）
│       ├── service/     # 域服务：chain / account / ledger / transaction / contract
│       └── builder/     # 离线交易构造：buildPayCoin / buildTransaction / ...
├── abi/                 # Solidity ABI 工具（ethers 封装）
└── proto/               # 链 protobuf wire 编解码

安装

npm install @caict-bif/bif-typescript-sdk

快速开始

import { BifProvider, BifSigner, generateKeyPair } from "@caict-bif/bif-typescript-sdk";

const provider = new BifProvider({
  baseUrl: "https://your-bif-node.example", // 替换为你的 BIF 节点地址
  allowInsecureTls: true, // 测试网 TLS 证书链不完整时使用；生产环境不要开启
});

(async () => {
  // 链信息
  console.log(await provider.chain.hello());

  // 账户查询
  const account = await provider.account.getAccountBase("did:bid:ef...");
  console.log(account);

  // 区块查询
  console.log(await provider.ledger.getLedger({ seq: 1 }));
})();

签名器（Signer）

签名器可通过 connect(provider) 绑定后直接获得在线能力。

import { BifProvider, BifSigner, generateKeyPair } from "@caict-bif/bif-typescript-sdk";

const provider = new BifProvider({ baseUrl: "https://your-bif-node.example" });
const pair = generateKeyPair();
const signer = new BifSigner(pair.privateKey).connect(provider);

// 离线能力
const sig = signer.sign("aabb...");                        // 交易 blob → hex 签名
const ok = signer.verify("aabb...", "sighex");             // 验签

// 在线能力（connect 后）
await signer.getAccount();          // 查自己账户
await signer.getAccountBalance();   // 查自己余额
await signer.getLedgerNumber();     // 最新区块高度
await signer.estimateGas({ operations, gasPrice });  // 费用评估

// 绑定后的签名者可直接用于交易
await provider.transaction.sendTransaction({ signer, tx: {...} });

交易

交易支持两种流程，均与底层链 chain.proto 对齐：

1. 本地构造 + 签名 + 提交（推荐，零额外步骤）

import { BifProvider, OperationType, buildPayCoin, buildSetMetadata } from "@caict-bif/bif-typescript-sdk";

const provider = new BifProvider({ baseUrl: "https://your-bif-node.example" });
const signer = new BifSigner("你的编码私钥");

const result = await provider.transaction.sendTransaction({
  signer,
  tx: {
    sourceAddress: signer.address,
    nonce: 1, // INCREASE_NONCE 模式填账户当前 nonce；RANDOM_NONCE 模式填任意
    feeLimit: 10_000_000,
    gasPrice: 1000,
    operations: [
      buildPayCoin({ destAddress: "did:bid:ef...", amount: 1000, input: "" }),
      buildSetMetadata({ key: "k", value: "v" }),
    ],
  },
});
console.log(result); // { hash, error_code, error_desc }

本地序列化使用 SDK 自带的手写 protobuf wire 编码器，hash = SHA256(序列化字节)，与链端 HashWrapper::Crypto（hash_type=0 时）一致。

2. 链端生成 blob（getTransactionBlob）

const tx = buildTransaction({ sourceAddress: signer.address, nonce: 1, operations: [...] });
const blob = await provider.transaction.getTransactionBlob(tx); // { transactionBlob, hash }
const signature = signer.signTransaction(blob.transactionBlob);
const results = await provider.transaction.submitTransaction([{ transaction_blob: blob.transactionBlob, signatures: [signature] }]);

离线交易构造接口

离线 operation 构造器（可与 sendTransaction / buildTransaction 组合）：

构造器	底层 Operation
`buildPayCoin({destAddress, amount, input?})`	PAY_COIN
`buildContractInvoke({contractAddress, amount?, input?})`	PAY_COIN → 合约
`buildSetMetadata({key, value, version?, deleteFlag?})`	SET_METADATA
`buildCreateAccount({destAddress, initBalance?, contract?, priv?, ...})`	CREATE_ACCOUNT
`buildActivateAccount(destAddress, initBalance?)`	CREATE_ACCOUNT + 默认权限
`buildSetPrivilege({masterWeight?, signers?, txThreshold?, typeThresholds?})`	SET_PRIVILEGE
`buildBatchGasSend(items[])`	批量 PAY_COIN
`buildBatchContractInvoke(items[])`	批量合约调用

多签离线签名（无需网络）：

const { transactionBlob, hash, signatures } = provider.transaction.buildSignedBlob(
  { sourceAddress, nonce: 1, operations: [...] },
  [signerA, signerB],        // 多签者
  { dissPubkey: false },
);
// signatures[].sign_data / .public_key 可直接提交 provider.transaction.submitTransaction

对外接口清单

chain（链信息）

方法	对应链接口	说明
`provider.chain.hello()`	GET /hello	链基础信息
`provider.chain.getNetworkId()` / `getChainVersion()`	GET /hello	网络 ID / 节点版本

account（账户）

方法	对应链接口	说明
`provider.account.getAccount(address, opts?)`	GET /getAccount	账户信息
`provider.account.getAccountBase(address)`	GET /getAccountBase	账户基础信息
`provider.account.getAccountMetaData(address, key?)`	GET /getAccountMetaData	账户 metadata
`provider.account.getAccountNonce(address)`	GET /getAccountBase	账户 nonce
`provider.account.getAccountBalance(address)`	GET /getAccountBase	账户余额
`provider.account.getAccountPriv(address)`	GET /getAccountBase	账户权限

ledger（账本）

方法	对应链接口	说明
`provider.ledger.getLedgerNumber()`	GET /getLedger	最新区块高度
`provider.ledger.getLedger(opts?)`	GET /getLedger	区块信息（seq/withFee/withValidator/withConsvalue/withLeader）
`provider.ledger.getLedgerTransactions(seq)`	GET /getLedger	区块内交易列表

transaction（交易）

方法	对应链接口	说明
`provider.transaction.getTxCacheSize()`	GET /getTxCacheSize	交易池条数
`provider.transaction.getTransactionCache(opts?)`	GET /getTransactionCache	交易池缓存
`provider.transaction.getTransactionHistory(opts?)`	GET /getTransactionHistory	链上交易
`provider.transaction.getTransactionBlob(tx)`	POST /getTransactionBlob	交易转 blob
`provider.transaction.submitTransaction(items)`	POST /submitTransaction	提交交易
`provider.transaction.testTransaction(item)`	POST /testTransaction	节点内测试交易（不上链）
`provider.transaction.sendTransaction({tx, signer})`	本地构造+签名+提交	一键交易
`provider.transaction.buildBlob(params)` / `buildSignedBlob(...)`	本地	离线构造 / 多签离线签名

contract（合约）

方法	对应链接口	说明
`provider.contract.callContract(params)`	POST /callContract	合约只读调用
`provider.contract.getContractInfo(address)`	GET /getAccountBase	合约账户信息
`provider.contract.getContractAddress(hash)`	GET /getTransactionHistory	合约创建交易 hash → 合约地址列表

WebSocket 订阅

import { BifWsClient, MessageType, chainTxStatusCodec, ledgerHeaderCodec } from "@caict-bif/bif-typescript-sdk";

const ws = new BifWsClient({ url: "wss://your-bif-node.example/ws", });

MessageType.CHAIN_LEDGER_HEADER(16) 订阅区块头 → ledgerHeaderCodec
MessageType.CHAIN_LEDGER_TXS(18) 订阅完整区块
MessageType.CHAIN_CONTRACT_LOG(17) 订阅合约 TLOG → tlogSubscribeResponseCodec
MessageType.CHAIN_SUBSCRIBE_TX(19) 订阅指定地址交易
MessageType.SUBSCIBE_TXS(21) 订阅交易丢弃状态 → txSubscribeResponseCodec
MessageType.CHAIN_TX_STATUS(11) 交易执行状态推送 → chainTxStatusCodec
MessageType.CHAIN_HELLO(10) 连接握手，链端默认开启区块/区块头/交易状态推送

Solidity ABI 工具（EVM 合约，基于 ethers v6）

提供 Solidity 合约的 ABI 编解码能力，仅服务 EVM 合约（原生 JS 合约 input 为 JSON 字符串，不走本工具）。

import { encodeFunctionInput, decodeFunctionOutput, getEventTopic, getFunctionSelector, encodeAbiTypes } from "@caict-bif/bif-typescript-sdk";

const abi = [
  "function transfer(address to, uint256 amount) returns (bool)",
  "function balanceOf(address account) view returns (uint256)",
  "event Transfer(address indexed from, address indexed to, uint256 value)",
];

const input = encodeFunctionInput({ abi, name: "transfer", args: [to, 1000n] }); // 0x + selector + 参数，可直接作 contractInvoke 的 input
const returns = decodeFunctionOutput({ abi, name: "balanceOf", data: rawResult }); // [42n]
const topic = getEventTopic({ abi, name: "Transfer" }); // 事件 topicHash
const selector = getFunctionSelector("transfer(address,uint256)"); // 0xa9059cbb

扩展能力

方法	说明
`provider.transaction.parseBlob(blobHex)`	本地反序列化交易 blob → `{transaction, hash}`，无需网络
`provider.contract.getContractAddress(hash)`	合约创建交易 hash → 合约地址列表（解析交易 `error_desc`）
`provider.transaction.evaluateFee({sourceAddress, operations, nonceType?, feeLimit?, gasPrice?, remarks?})`	费用评估：nonceType=0 自动取账户 nonce+1；=1 本地随机 nonce + maxLedgerSeq，底层走 `/testTransaction`

const fee = await provider.transaction.evaluateFee({
  sourceAddress: "did:bid:ef...",
  operations: [buildContractInvoke({ contractAddress: "did:bid:efContract", input: "{}" })],
  gasPrice: 1000,
});

Sample

仓库提供 sample/ 目录，覆盖基础查询、交易构造/提交、签名器、ABI/合约与 WebSocket 订阅场景。提交到 git 的示例只包含占位连接地址和占位账户，不包含真实节点、私钥或 API Key。

npm run build
node sample/run-all.js --list

需要跑联网或写交易场景时，在本地复制配置文件并填写真实值：

cp sample/config.example.js sample/config.local.js

sample/config.local.js 已被 .gitignore 忽略，用来填写本地敏感信息：

baseUrl：HTTP 节点地址（查询、费用评估、testTransaction 使用）
wsUrl：WebSocket 订阅地址
readerAddress：只读查询账户地址
contractAddress / contractDeployHash：合约在线示例需要时填写
writerPrivateKey：写交易账户编码私钥，仅保存在本地
enableWriteRuns：写交易总开关，必须显式设为 true 才会发送交易

也可以用环境变量临时覆盖：BIF_BASE_URL、BIF_WS_URL、BIF_READER_ADDRESS、BIF_WRITER_PRIVATE_KEY。

npm run sample -- --list
npm run sample
npm run sample -- --only=tx-offline-builders

默认占位配置下，离线场景会运行；联网、WebSocket 和写交易场景会跳过并提示需要填写的本地配置。

开发

npm install
npm test          # tsc 编译 + mocha（33 个用例：wire/编解码/签名/交易构造/ABI/扩展能力）
npm run build

说明

allowInsecureTls: true 仅用于测试网联调（节点 TLS 证书链不完整）。
int64 字段内部用 BigInt 处理，响应解码时安全范围内的值返回 number。
交易 JSON（getTransactionBlob）中 bytes 字段以 hex 字符串表示（与链端 Json2Proto 一致）。

Name		Name	Last commit message	Last commit date
sample		sample
scripts		scripts
src		src
.gitignore		.gitignore
.npmignore		.npmignore
LICENSE		LICENSE
README.md		README.md
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

Navigation Menu

Repository files navigation

@caict-bif/bif-typescript-sdk

项目结构

安装

快速开始

签名器（Signer）

交易

1. 本地构造 + 签名 + 提交（推荐，零额外步骤）

2. 链端生成 blob（getTransactionBlob）

离线交易构造接口

对外接口清单

chain（链信息）

account（账户）

ledger（账本）

transaction（交易）

contract（合约）

WebSocket 订阅

Solidity ABI 工具（EVM 合约，基于 ethers v6）

扩展能力

Sample

开发

说明

About

Releases

Packages

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

@caict-bif/bif-typescript-sdk

项目结构

安装

快速开始

签名器（Signer）

交易

1. 本地构造 + 签名 + 提交（推荐，零额外步骤）

2. 链端生成 blob（getTransactionBlob）

离线交易构造接口

对外接口清单

chain（链信息）

account（账户）

ledger（账本）

transaction（交易）

contract（合约）

WebSocket 订阅

Solidity ABI 工具（EVM 合约，基于 ethers v6）

扩展能力

Sample

开发

说明

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages