Haw

@choptop/haw 是一个面向 Internet Computer（ICP）项目的 TypeScript 工具库，提供常用的数据转换、Principal 与 Account 处理、Candid 数据结构解析、管理罐调用，以及 Cloudflare Workers 响应和参数校验工具。

安装

npm install @choptop/haw @icp-sdk/core@^5 @icp-sdk/canisters@^3

运行环境要求：

• Node.js >= 20.19.0
• ESM 项目（"type": "module"）
• @icp-sdk/core >= 5.2.1 < 6
• @icp-sdk/canisters >= 3.5.2 < 4

快速开始

数据转换

import { array2hex, formatDateTime, hex2array, shrinkPrincipal, unwrapOption, wrapOption } from '@choptop/haw';

hex2array('00ff'); // [0, 255]
array2hex(new Uint8Array([0, 255])); // '00ff'

wrapOption('value'); // ['value']
unwrapOption<string>(['value']); // 'value'

formatDateTime(); // UTC ISO 时间，例如 2026-07-12T03:00:00.000Z
shrinkPrincipal('ryjl3-tyaaa-aaaaa-aaaba-cai'); // ryjl3...cai

hex2array 会严格校验输入；非法字符或奇数长度的十六进制文本会抛出异常。

Principal 与 Account

import { isPrincipalText, principal2account, string2principal } from '@choptop/haw';

const principal = '2vxsx-fae';

isPrincipalText(principal); // true
string2principal(principal); // Principal
principal2account(principal); // ICP Account Identifier

EXT Token Identifier

import { parse_token_identifier, parse_token_index, parse_token_index_with_checking } from '@choptop/haw';

const collection = 'ryjl3-tyaaa-aaaaa-aaaba-cai';
const tokenIdentifier = parse_token_identifier(collection, 42);

parse_token_index(tokenIdentifier); // 42
parse_token_index_with_checking(collection, tokenIdentifier); // 42

Token index 必须是 0 到 2^32 - 1 之间的整数。

ICP 身份与罐管理

import { canister_status, getIdentityBySecretKey } from '@choptop/haw';

const identity = await getIdentityBySecretKey(process.env.IC_SECRET_KEY!);

const status = await canister_status({
    identity,
    canister_id: process.env.CANISTER_ID!,
});

console.log(status.status, status.cycles, status.memory_size);

库中还提供以下管理操作：

• create_canister、deploy_canister
• start_canister、stop_canister、delete_canister
• install_code、upgrade_code、reinstall_code、uninstall_code
• update_settings、canister_status
• canister_status_info、canister_candid

调用管理罐的身份必须拥有对应罐的控制权限。不要在源码或版本库中保存私钥。

Cloudflare Workers

Cloudflare 专用工具从独立入口导入：

import { check_integer, handle_error, success } from '@choptop/haw/dist/cloudflare/index.js';

type Env = {
    API_NAME: string;
};

export default {
    fetch: handle_error<Env>(async (request, env) => {
        const url = new URL(request.url);
        const result = check_integer(url.searchParams.get('id') ?? undefined);

        if (result.err) return result.err;

        return success({
            id: result.id,
            service: env.API_NAME,
        });
    }),
};

Cloudflare 模块包括：

• JSON 成功和失败响应：success、failed
• 参数校验：check_integer、check_bigint、check_hex
• ICP 校验：check_principal、check_canister_id、check_account_hex
• 统一异常处理：handle_error

如果 Worker 使用依赖 Node.js 内置 API 的功能，请在 Wrangler 配置中启用 nodejs_compat。

主要模块

| 模块 | 功能 | | ------------ | ------------------------------------------------------- | | common | 消息、JSON、URL、邮件、深度比较和通知工具 | | data | Hex、BigInt、日期、数字、Option、Result 和 Variant 转换 | | ic | ICP 身份、Account、管理罐、罐状态和 EXT 工具 | | types | Candid Option、Result、Variant 和身份相关类型 | | cloudflare | Worker 响应、输入校验和错误处理 |

根入口会导出 common、data、ic 和 types。Cloudflare 工具需要使用上面的独立入口。

本地开发

npm ci
npm run build
npm test
npm run lint

测试流程还会验证编译后的 Node.js ESM 入口与 Cloudflare 入口是否能够正常加载。

License

Apache-2.0