跳到主要内容

TypeScript 接入

环境与依赖​

使用支持 ES modules、bigint 和顶层 await 的环境。安装兼容的 @invisi-labs/sdk、@invisi-labs/prover 与 ethers;管理库存时再加入 @invisi-labs/session。安装包版本与本文 API 必须相符,具体选择见兼容性。

下面代码分别是完整离线脚本和供宿主应用调用的函数。调用函数时需要传入真实测试环境的服务、资产及钱包能力;不要把演示地址用于入金。

离线构造 Note 输出​

此脚本只构造输出意图,不连接服务、不移动资金。地址是公开测试收款材料,两个 0x111… / 0x222… 地址仅用于离线绑定,10n 是十个最小单位。保存为 .ts 后可用项目已配置的 TypeScript 运行器执行。

import { NoteOutput } from "@invisi-labs/sdk";

const output = await NoteOutput.create({
chainId: 31337n,
protocolAddress: "0x1111111111111111111111111111111111111111",
tokenAddress: "0x2222222222222222222222222222222222222222",
amount: 10n,
recipient: { type: "invisi", address: "0i0e0525SFRf53yh2aljmm3sn9JQ5nJk7LqWt0G2ajnRY2pe698y550QXhp9uELXpcCZMf5Y608rRDJ68jJgfEWy5j7U5e5eVNPVz8vW2W2kmyw4p9lVLwW3z3WeFHQs5KdfR980CX" },
});
console.log(output.commitment);

每次创建使用随机化材料,因此 commitment 不应作为固定值断言。拿到 commitment 不表示链上已存在该 Note,也不代表收款已经成功。

连接协议环境​

以下函数的 chainRpcUrl 是通用链节点;protocolRpcUrl 是 Protocol RPC 的 /v1 服务入口。chainId 与 coreAddress 必须来自你的受信部署配置,而不是直接照抄不可信服务响应。bbBin 与 coreCatalog 是本机匹配的 BB 可执行文件和经过认证的 Core 证明资源目录。

import { JsonRpcProvider } from "ethers";
import { Invisi, Protocol, ProtocolRpcClient } from "@invisi-labs/sdk";
import { NativeProver } from "@invisi-labs/prover/native";

export async function connectProtocol(options: {
chainRpcUrl: string; protocolRpcUrl: string;
chainId: bigint; coreAddress: string;
bbBin: string; coreCatalog: string;
}) {
const provider = new JsonRpcProvider(options.chainRpcUrl);
try {
const protocolRpc = new ProtocolRpcClient(options.protocolRpcUrl);
const protocol = await Protocol.fromRpc(protocolRpc, provider);
if (protocol.context.chainId !== options.chainId ||
protocol.context.protocolAddress.toLowerCase() !== options.coreAddress.toLowerCase()) {
throw new Error("Unexpected network or Core instance");
}
const prover = new NativeProver({
bbBin: options.bbBin,
resources: { directory: options.coreCatalog, offline: true },
});
const invisi = new Invisi({ provider, protocolRpc, prover });
return { provider, protocolRpc, protocol, invisi };
} catch (error) {
provider.destroy();
throw error;
}
}

成功返回后由调用方在应用退出时执行 provider.destroy()。资源校验失败应停止接入,不自动切换到未知镜像或其他证明版本。

准备第一笔公开入金​

下面导出可复用函数;传入已连接的 invisi、protocol、完整付款钱包 payer、token 地址、完整 0i 收款地址和最小单位 amount。它只返回待提交交易,不签名、approve 或发送。

import { Invisi, NoteOutput, Protocol, Wallet } from "@invisi-labs/sdk";

export async function prepareDeposit(
invisi: Invisi, protocol: Protocol, payer: Wallet,
tokenAddress: `0x${string}`, recipientAddress: `0i${string}`, amount: bigint,
) {
if (amount <= 0n) throw new Error("Amount must be positive base units");
const output = await NoteOutput.create({
...protocol.context, tokenAddress, amount,
recipient: { type: "invisi", address: recipientAddress },
});
const prepared = await invisi.prepareShield({
wallet: payer, protocol, tokenAddress, outputs: [output],
funding: { payer: payer.ownerAddress, amount, authorization: "caller" },
});
const ready = await prepared.ready();
return ready.exportTransaction();
}

公开入金走 ready(),不需要 ZK prove()。最终 EVM 提交者必须满足 caller funding 的 payer 要求,且具有 ERC-20 余额、对 Core 的 allowance 及 gas。应用先审阅导出的目标、金额与 calldata,再通过自己的交易签名器提交。

提交后按事件及确认核对结果。不要因提交超时而重新创建输出;保留原操作及哈希,查询或恢复原交易。

下一步:用 WalletSession 同步并支付。

下载完整离线示例