BrilliantHash JavaScript SDK

JavaScript/TypeScript SDK for BrilliantHash blockchain。支持构建与签名交易、RPC 调用、浏览器数据订阅以及示例合约的只读调用。

功能概览

• 钱包：生成地址、公钥、私钥；签名消息哈希；Keystore 导入/导出
• 交易：交易构建与签名（后端生成消息哈希），RPC 发送交易
• 网络：HTTP 传输（自动 BigInt→number 序列化），事件订阅（Node 环境自动采用 eventsource polyfill 或轮询回退）
• 查询：最新区块高度、按高度/哈希查询区块、账户信息、Explorer 统计与分页
• 合约：部署合约（读取仓库中的 Wasm 文件）、只读调用合约（calldata 为 4 字节选择器 + bincode 参数）

环境要求

• Node.js ≥ 18、npm
• TypeScript ≥ 5（项目已内置）

安装与构建

• 安装依赖

npm install

• 构建

npm run build

快速开始

• 通过 SDK 创建钱包并打印地址、公钥、私钥（示例参考 examples/smoke.ts）：

import { Wallet } from "./src/index.js";

const wallet = await Wallet.create();
console.log("address:", wallet.addressHex());
console.log("publicKey:", wallet.publicKeyHex());
console.log("privateKey:", wallet.privateKeyHex()); // 请勿在生产日志输出

• 进行简单 RPC 调用（示例参考 examples/rpc-smoke.ts）：

import { HttpTransport, Client } from "./src/index.js";

const transport = new HttpTransport(["http://127.0.0.1:1111"]);
const client = new Client(transport);
const height = await client.getLatestBlockHeight();
console.log("Latest height:", height);

示例与运行脚本

本仓库已提供多个示例（位于 js-sdk/examples），编译后可通过 npm 脚本运行：

• 构建

npm run build

• 基本钱包/加解密/Keystore 冒烟

npm run smoke

• RPC 冒烟（Explorer 统计、最新高度等）

npm run rpc-smoke

• 转账冒烟

npm run transfer-smoke

• 部署合约（读取仓库根的 target/wasm32-unknown-unknown/release/output_example.wasm）

npm run deploy-smoke

• 只读调用合约（调用 who_am_i()）

npm run call-smoke

只读调用合约（who_am_i）

• 运行前需设置环境变量 CONTRACT_ADDRESS（合约部署成功后得到的地址）。注意 PowerShell 与 cmd 的写法不同：

PowerShell：

$env:CONTRACT_ADDRESS="0xb051a819b9888637ebb6278a21e031e864b0558fce39d6148feccfa2a3087e88"

然后运行：

npm run call-smoke

cmd（命令提示符）：

set CONTRACT_ADDRESS=0xb051a819b9888637ebb6278a21e031e864b0558fce39d6148feccfa2a3087e88

然后运行：

npm run call-smoke

• 可选：指定私钥（默认使用仓库中的创世私钥） PowerShell：

$env:PRIVATE_KEY_HEX="0xc31a2f259866b056c34e1243b4e99bb941bce6216e14198cb0960626f316eab5"

cmd：

set PRIVATE_KEY_HEX=0xc31a2f259866b056c34e1243b4e99bb941bce6216e14198cb0960626f316eab5

• 返回值说明：call_contract 返回 Wasm 执行结果的原始字节，封装为十六进制字符串（0x...）。对 who_am_i()，返回的是 (Address, Address) 的 bincode 编码，所以你会看到两段“长度前缀 u64 LE（32字节） + 32字节地址”。示例已附带解码函数，将打印调用者地址与合约自身地址。

事务发送与结构约定

• Client.sendTransaction(tx: RpcTransaction) 会自动完成与后端的结构对齐：
  • publicKey、signature：自动移除 0x 前缀
  • nonce、fee、所有金额类字段：自动从 BigInt 转换为 number（由 HTTP 传输层统一处理）
  • deployContract.code 与 callContract.data：自动移除 0x 前缀，符合后端的 String 入参解码策略
• 你可以直接构建 RpcTransaction 并调用 client.sendTransaction(tx)；或使用 TransactionBuilder 请求后端生成消息哈希并本地签名：

import { HttpTransport, Client, TransactionBuilder, Wallet } from "./src/index.js";

const transport = new HttpTransport(["http://127.0.0.1:1111"]);
const client = new Client(transport);
const wallet = await Wallet.create();

const builder = new TransactionBuilder()
  .setData({ type: "transfer", to: "0x<recipient>", amount: 1000n })
  .setNonce(1n)
  .setFee(5000n);

const tx = await builder.signAndBuild(
  transport,
  wallet.publicKeyHex(),
  (msgHex) => wallet.signMessageHash(msgHex)
);

await client.sendTransaction(tx);

合约部署与只读调用

• 部署示例 deploy-contract.ts 会读取 ../target/wasm32-unknown-unknown/release/output_example.wasm 并发送 deployContract 交易；请确保你已用 Rust 环境构建出该 Wasm。
• 只读调用示例 contract-call-smoke.ts 使用极简 ABI 编码器生成 4 字节选择器（与以太风格一致），参数采用 bincode 编码，最终拼装为 calldata；示例包含 who_am_i() 的解码逻辑。

Explorer 事件订阅（SSE）

• 浏览器环境：使用原生 EventSource
• Node 环境：
  • 优先动态加载 eventsource polyfill（已在 dependencies 中）
  • 加载失败时自动回退为每秒轮询 /explorer/stats，并以统一事件格式回调
• 该机制内置于 HttpTransport.subscribeSse(path, onMessage)。示例文件 examples/explorer-stream.ts 展示了使用方式。

安全注意事项

• 切勿在生产日志打印私钥或敏感数据（示例仅用于本地验证）
• 示例使用默认创世账户私钥，实际生产请自行管理密钥并进行权限控制

已知约束

• 只读调用返回的是原始字节的十六进制字符串；具体含义需依据合约的返回类型进行 bincode 解码（示例已提供 who_am_i() 的解码）。
• AddressHex、交易字段约定均使用小写十六进制，地址为 32 字节（0x 前缀）。