Union TypeScript SDK 2 开发实战：Nix 构建、测试、发布与示例运行全流程

本文围绕 Union 仓库中 ts-sdk/README.md 所描述的 TypeScript SDK（npm 包名 @unionlabs/sdk）的完整开发与交付流程展开，覆盖 Nix 构建、本地开发测试、版本发布、EVM ABI 更新与示例脚本运行五大实操环节。读完本文后，你可以独立完成该 SDK 的构建验证、参与本地开发调试，并理解其基于 pnpm workspace + Effect 生态的构建细节，为后续在 Union 零知识跨链协议上集成跨链转账、批次交易（Batch）等功能打好工程基础。

项目定位与模块地图

ts-sdk 是 Union 提供的官方 TypeScript SDK 2（package.json 中 version 当前为 2.0.0-beta.2，description 为 "Union TypeScript SDK 2"），面向 Union 的跨链应用集成。从 src/index.ts 的导出结构看，SDK 对外暴露了一组职责清晰的命名空间模块：

• Ucs03 / Ucs05：分别处理 UCS03（统一跨链调用协议）与 UCS05 标准的交互；
• ZkgmClient / ZkgmClientRequest / ZkgmClientResponse：链无关地提交 ZKGM（零知识网关模块）请求、构造与解析响应；
• TokenOrder / Batch / Call / ZkgmInstruction：UCS03 指令（TokenOrderV2、Batch、Call）的高层构造 API；
• ChainRegistry / ChannelRegistry / TokenRegistry / Token：链、通道与代币的元数据源；
• PriceOracle、Indexer、Staking、Gql、Aptos、Utils、Types、Constants 等辅助模块。

package.json 还揭示了它跨多链的技术栈：依赖中同时包含 @cosmjs/*（Cosmos 生态）、@aptos-labs/ts-sdk（Aptos）、@mysten/sui（Sui），并以 viem 作为 EVM 链的 peer dependency；GraphQL 查询则通过 gql.tada 生成类型安全代码。SDK 直接以 TypeScript 源码作为入口（exports 中 "." 指向 ./src/index.ts），并在 src/index.ts 顶部明确标注：SDK 自 v2.0.0 起处于稳定化阶段，在 v3.0.0 之前可能存在破坏性变更——这是使用该版本时的首要适用前提。

用 Nix 构建：nix build .#ts-sdk -L

README 中给出的构建命令是：

nix build .#ts-sdk -L

其背后是 ts-sdk.nix 中定义的 ts-sdk 包，采用 buildPnpmPackage 派生并锁定 lockfile 哈希。关键构建参数可以从源码中逐一确认：

• doCheck = true，且 checkPhase 实际执行：

pnpm --filter=@unionlabs/sdk check   # 即 tsc -b tsconfig.json 类型检查
pnpm --filter=@unionlabs/sdk test    # 即 vitest run 单元测试

这意味着 nix build 不只是编译，还会把类型检查和 test/ 目录下全部测试（如 Batch.test.ts、ZkgmClientRequest.test.ts、Ucs03.test.ts 等）作为质量门禁跑一遍，任何一步失败构建即失败。

• buildPhase 执行 pnpm --filter=@unionlabs/sdk build，对应 package.json 中的多阶段构建管线：

pnpm build-esm        # tsc -b tsconfig.build.json，产出 ESM
pnpm build-annotate   # babel 注入 pure-call 注解（tree-shaking 友好）
pnpm build-cjs        # babel 转 CommonJS，兼容 CJS 消费方
build-utils pack-v3   # Effect build-utils 打包 v3

即最终产物同时提供 ESM 与 CJS 两套模块格式。

• installPhase 将 ts-sdk/dist/* 拷入 $out，也就是发布到 npm 的内容形态。

此外还有配套包 ts-sdk-docs，构建时运行 pnpm --filter=@unionlabs/sdk docgen（配置见 docgen.json），用 Effect 生态的 @effect/docgen 生成 API 文档，并显式排除了 src/aptos/**、src/cosmos/**、src/evm/**、src/generated/**、src/internal/** 等内部目录，只对外部模块生成文档。

本地开发：nix develop + 测试监听

README 给出的开发流程为：

nix develop
cd ts-sdk/
npm install
npm run test-watch

结合仓库实际内容补充两点说明：

1. 该仓库整体是 pnpm workspace（根目录有 pnpm-workspace.yaml，且 package.json 中 peerDependencies 使用 pnpm 的 catalog: 协议引用版本）。nix develop 会提供 Node、pnpm 等完整工具链；安装依赖时若遇到 catalog: 协议解析问题，按仓库构建方式应优先使用 pnpm install 对齐 workspace 语义。
2. 测试由 Vitest 驱动：vitest.config.ts 仅将本地配置与仓库级 vitest.shared.ts 合并，说明测试共享全仓库统一的 Vitest 基座（环境、覆盖率、Setup 等）；package.json 中 test 与 test:watch 分别对应 vitest run 与 vitest，README 里的 npm run test-watch 即持续监听模式。

类型检查方面，tsconfig.json 采用项目引用（references tsconfig.src.json 与 tsconfig.test.json），并注册了 gql.tada/ts-plugin 语言服务插件，其 schema 指向 src/generated/schema.graphql——这解释了下一节"更新 schema"操作存在的必要性：GraphQL 查询的端到端类型依赖这两个生成文件。

发布流程：先 bump 版本，再 nix run .#publish-ts-sdk -L

README 描述的发布流程：

# 1. 先修改 package.json 中的 version
# 2. 然后执行：
nix run .#publish-ts-sdk -L

对应的 nix app 定义在 ts-sdk.nix 中，其 program 实质是：

cd <ts-sdk 构建产物>/   # 即 self'.packages.ts-sdk 的输出目录
pnpm publish --access='public'

从源码结构看，这个 app 是在 ts-sdk 包的构建输出目录（即 dist 内容）内执行 pnpm publish。配合 package.json 的 publishConfig：

"publishConfig": {
  "access": "public",
  "provenance": true,
  "directory": "dist",
  "linkDirectory": false
}

provenance: true 表示走 npm 的构建溯源（Provenance）机制——npm 会根据 Git commit 与 CI 构建记录为发布包签发来源证明，这正是"先构建（nix build .#ts-sdk）、后从构建产物发布"这一流程的意义所在。因此发布时的标准动作是：修改 version → 触发可溯源的构建 → 由 nix app 完成 pnpm publish，全程不手工 npm pack。

更新 EVM ABI：nix build .#hubble-abis -L

README 还给出了 ABI 同步流程：

nix build .#hubble-abis -L
# 将 result/ 下的内容拷贝到 src/evm/abi/

即 EVM 链相关合约的 ABI 由独立的 hubble-abis 构建产物统一产出，开发者构建后把 result/ 目录中的 ABI 文件复制到 ts-sdk/src/evm/abi/ 目录完成同步。这一步保证 SDK 内 EVM 交互所使用的合约 ABI 与链上部署版本保持一致，属于跨合约工程的例行维护操作。

运行示例脚本

README 给出的示例运行方式：

nix develop
cd ts-sdk/
npm install
bun run ./examples/create-batch.ts

examples/ 目录当前包含大量按场景组织的真实示例，可直接替换上面命令中的脚本路径运行，例如：

• UCS03 跨链转账：ucs03-send-holesky-to-stargaze.ts、ucs03-send-bob-to-babylon.ts、ucs03-send-sui-to-union-testnet-10.ts 等十余条链间链路示例；
• 带授权（approval）的 EVM → Cosmos 转账：ucs03-send-holesky-to-stargaze-with-approvals.ts；
• 批次与编码：ucs03-encode-instruction.ts、ucs03-encode-packet.ts、ucs03-create-fungible-asset-order.ts；
• 目录化的场景示例：examples/EVM/、examples/Cosmos/、examples/UCS03/ 子目录，以及根部的 Cosmos 合约交互示例 cosmos-execute-contract.ts、cosmos-to-evm-transfer.ts 和 Aptos 系列读/写示例。

示例的 TypeScript 编译由独立的 tsconfig.examples.json 负责（对应 check:examples 脚本），示例内可直接按包名导入 @unionlabs/sdk。

附录：GraphQL Schema 代码生成

ts-sdk.nix 中还定义了一个未出现在 README 中的辅助 app ts-sdk-fetch-schema，值得开发者知晓：

cd ts-sdk/
pnpm dlx gql.tada generate-schema --tsconfig ./tsconfig.json \
  --output "./src/generated/schema.graphql" \
  "https://graphql.union.build/v1/graphql"
pnpm dlx gql.tada generate-output --disable-preprocessing \
  --tsconfig ./tsconfig.json --output ./src/generated/graphql-env.d.ts

它从 Union 官方 GraphQL 网关拉取最新 schema 并重新生成 graphql-env.d.ts 类型文件，与 src/generated/schema.graphql 配套。当 Union 后端 API 变更导致 SDK 内 GraphQL 查询类型报错时，这是标准的刷新手段。

小结与版本注意事项

综合 ts-sdk/README.md 与仓库源码，@unionlabs/sdk 的工程主线可以概括为：

环节	命令	依据
构建 + 类型检查 + 测试	nix build .#ts-sdk -L	ts-sdk.nix
本地开发	nix develop + 安装依赖 + npm run test-watch	vitest.config.ts
发布	bump version 后 nix run .#publish-ts-sdk -L	ts-sdk.nix
更新 EVM ABI	nix build .#hubble-abis -L，拷贝 result/ 至 src/evm/abi/	ts-sdk/README.md
运行示例	bun run ./examples/<script>.ts	examples/

需要注意的适用前提：当前版本为 2.0.0-beta.2，处于 v3.0.0 前的稳定化窗口，API 可能仍有破坏性变更；构建与发布强依赖 Nix flake 环境；依赖版本大量使用 pnpm catalog: 协议，脱离 pnpm workspace 环境直接安装可能失败。所有验证依据均可在 ts-sdk/ 目录下的 README.md、package.json、ts-sdk.nix、docgen.json 与 src/index.ts 中直接核对。