# @across-protocol/contracts 中文文档

规范地址：https://npmcn.com/package/%40across-protocol/contracts/

版本：5\.0\.28
npm 元数据更新时间：2026-11-06T13:30:14.861Z
中文译文更新时间：2026-11-06T13:31:37.498Z
软件包许可：AGPL-3\.0-only

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40across-protocol/contracts
原文对照：https://npmcn.com/package/%40across-protocol/contracts/?lang=original
项目主页：https://github.com/across-protocol/across-smart-contracts-v2#readme
源码仓库：https://github.com/across-protocol/across-smart-contracts-v2

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：8.5 MB，1221 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=22\.18\.0
- 运行依赖：15 个
- peer 依赖：buffer-layout ^1\.2\.2
- 首次发布：2021-12-08T08:04:12.073Z
- 最新版本发布：2026-11-06T13:30:14.581Z
- 近 30 天下载量：20474（2026-10-05 至 2026-11-03，npm 官方下载统计）
- 已发布版本数：154（近 12 个月 86 个）

## 中文简介

![Across-logo](https://raw.githubusercontent.com/across-protocol/across-frontend/65abd7772704a9ec243fd370f9e8e76322f0905b/src/assets/logo.svg)

## 安装

```sh
npm install @across-protocol/contracts
```

也可以使用：`pnpm add @across-protocol/contracts`、`yarn add @across-protocol/contracts`、`bun add @across-protocol/contracts`

## README

![Across-logo](https://raw.githubusercontent.com/across-protocol/across-frontend/65abd7772704a9ec243fd370f9e8e76322f0905b/src/assets/logo.svg)

包含智能合同套件,允许任意两个网络之间的即时令牌传输. 中继器被备份 中央流动资金 `HubPool` 在埃特鲁姆,它也充当了所有合同的跨链管理人 系统. `SpokePool` 合同被部署到任何希望产生象征性存款或成为最终存款的网络 代币转让目的地,它们都受 `HubPool` 在以利他岛.

这些合同一直受到OpenZeppelin的审计,审计报告可以找到 [这里](https://docs.across.to/resources/audits)。 。 。 .

## 理解可升级性

SpokePool的合同是 [UUPS 可升级](https://github.com/OpenZeppelin/openzeppelin-contracts-upgradeable/blob/cbb66aca87521f818d9c1769c69d5dcc1004977a/contracts/proxy/utils/UUPSUpgradeable.sol) 代理合同意味着其地址将永远相同,但其执行代码可以改变.

所有SpokePools可以升级 如果合同的"管理员"呼叫 `upgradeTo`。通过执行 [`_requireAdminSender()` 虚拟函数](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/SpokePool.sol#L1745) 在儿童合同中。 例如这里是 [坐标](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/Arbitrum_SpokePool.sol#L114) 财务报告和审定财务报表 [乐观主义](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/Ovm_SpokePool.sol#L208) 行政检查的执行情况.

所有的 SpokePool 都得到实施,以至于管理员是 HubPool, 因此我们把 SpokePool 描述为拥有"跨链所有权". 湖宝的主人可以打电话 [函数](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/contracts/HubPool.sol#L249) 发送一个跨链执行 `upgradeTo` 在任何 SpokePool 上进行升级.

这个 [脚本](https://github.com/across-protocol/contracts/blob/555475cdee6109afc85065ca415c740d7f97b992/tasks/upgradeSpokePool.ts) 用于创建通过HubPool执行跨链升级的调用数据.

## 已部署的合同版本

最新合同部署情况见 `/broadcast/deployed-addresses.json` (自动生成由 `yarn extract-addresses`) (中文(简体) ).

## 所需资源

这个寄存器假设你有 [节点](https://nodejs.org/en/download/package-manager) 已安装,使用CI版本22.23.4或后期的补丁节点22放出. 取决于你打算怎么处理你可能需要的还款 [铸造](https://book.getfoundry.sh/getting-started/installation) 财务报告和审定财务报表 [锁定](https://www.anchor-lang.com/docs/installation) 也将安装。 如果你有问题,请确保先安装这两个.

如果你还没用过主播 就得跑 `avm use latest` 还有.

## 构建

```shell
yarn
yarn build # Will build all code. Compile solidity & rust (local toolchain), generate ts outputs
yarn build-verified # Will build all code. Compile solidity & rust (verified docker build), generate ts outputs
```

EVM 构建和测试使用 Findry 版本 `.foundry-version`; CI 通过 `foundry-rs/foundry-toolchain`运行 `yarn pin-foundry` 切换本地工具链到它( 当它已经关闭时, 不可打开) 页:1 通过编辑文件跳出针.

## 测试

```shell
yarn test # Run all unit tests without gas analysis, using local toolchain SVM build
yarn test-verified # Run all unit tests (without gas analysis) with verified SVM docker build
yarn test:gas-analytics # Run only tests that count gas costs
yarn test:report-gas # Run unit tests with gas reporting enabled
yarn test-evm # Only test EVM code
yarn test-svm # Only test SVM code (local toolchain build)
yarn test-svm-solana-verify # Only test SVM code (verified docker build)
```

## 林特

```shell
yarn lint
yarn lint-js # Only lint Javascript
yarn lint-rust # Only lint rust
yarn lint-solidity # Only lint solidity
yarn lint-fix
```

## 部署和核查

### EVM( 视频)

#### 创建

```shell
forge build

forge script script/001DeployHubPool.s.sol:DeployHubPool --rpc-url ethereum --broadcast --verify -vvvv

```

#### 创建( ZKSync)

要启用 ZKSync 支持,必须安装铸币局的 Zksync 叉(参见 [这里](https://foundry-book.zksync.io/introduction/installation#using-foundryup-zksync) 说明).

此外 `FOUNDRY_PROFILE` 环境变量必须设定为 `zksync`。 。 。 .

```shell
FOUNDRY_PROFILE=zksync forge script script/016DeployZkSyncSpokePool.s.sol:DeployZkSyncSpokePool --rpc-url zksync --broadcast --verify -vvvv
```

或者 `yarn forge-script-zksync` 命令可用于部署合同.

```shell
yarn forge-script-zksync script/016DeployZkSyncSpokePool.s.sol:DeployZkSyncSpokePool --rpc-url zksync --broadcast --verify -vvvv
```

### 特别志愿人员

在首次部署之前, 确定所有程序 ID 在内 `lib.rs` 财务报告和审定财务报表 `Anchor.toml` 运行时与列表相同 `anchor keys list`如果没有,请更新,以匹配下方的部署密钥 `target/deploy/` 并做出改变.

确保使用可以构建的已验证的嵌入符二进制 :

```shell
unset IS_TEST # Ensures the production build is used (not the test feature)
yarn build-svm-solana-verify # Builds verified SVM binaries
yarn generate-svm-artifacts # Builds IDLs
```

输出所需的环境变量,例如:

```shell
export RPC_URL=https://api.devnet.solana.com
export KEYPAIR=~/.config/solana/dev-wallet.json
export PROGRAM=svm_spoke # Also repeat the deployment process for multicall_handler
export PROGRAM_ID=$(cat target/idl/$PROGRAM.json | jq -r ".address")
export MULTISIG= # Export the Squads vault, not the multisig address!
export SOLANA_VERSION=$(grep -A 2 'name = "solana-program"' Cargo.lock | grep 'version' | head -n 1 | cut -d'"' -f2)
```

初步部署还需要:

```shell
export SVM_CHAIN_ID=$(cast to-dec $(cast shr $(cast shl $(cast keccak solana-devnet) 208) 208))
export HUB_POOL=0x14224e63716afAcE30C9a417E0542281869f7d9e # This is for sepolia, update for mainnet
export DEPOSIT_QUOTE_TIME_BUFFER=3600
export FILL_DEADLINE_BUFFER=21600
export MAX_LEN=$(( 2 * $(stat -c %s target/deploy/$PROGRAM.so) )) # Reserve twice the size of the program for future upgrades
```

#### 初步部署

部署此程序, 并将升级权限设置为多西格 :

```shell
solana program deploy \
  --url $RPC_URL \
  --keypair $KEYPAIR \
  --program-id target/deploy/$PROGRAM-keypair.json \
  --max-len $MAX_LEN \
  --with-compute-unit-price 100000 \
  --max-sign-attempts 100 \
  --use-rpc \
  target/deploy/$PROGRAM.so
solana program set-upgrade-authority \
  --url $RPC_URL \
  --keypair $KEYPAIR \
  --skip-new-upgrade-authority-signer-check \
  $PROGRAM_ID \
  --new-upgrade-authority $MULTISIG
```

更新和承诺 `deployments/legacy-addresses.json` 与已部署的程序标识和部署槽.

上传IDL并设置升级权限到多相:

```shell
anchor idl init \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR \
  --filepath target/idl/$PROGRAM.json \
  $PROGRAM_ID
anchor idl set-authority \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR \
  --program-id $PROGRAM_ID \
  --new-authority $MULTISIG
```

`svm_spoke` 还需要在第一次部署时启动和转让所有权:

```shell
anchor run initialize \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR -- \
  --chainId $SVM_CHAIN_ID \
  --remoteDomain 0 \
  --crossDomainAdmin $HUB_POOL \
  --svmAdmin $MULTISIG \
  --depositQuoteTimeBuffer $DEPOSIT_QUOTE_TIME_BUFFER \
  --fillDeadlineBuffer $FILL_DEADLINE_BUFFER
```

创建接受存款的金库, 例如 :

```shell
export MINT=4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU # This is USDC on devnet, update with address for mainnet
anchor run createVault \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR -- \
  --originToken $MINT
```

`sponsored_cctp_src_periphery` 需要初始化,并为支持的刻录符设定最低押金:

```shell
# Replace --quoteSigner with actual quote signer address
anchor run initializeSponsoredCctpSrc \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR -- \
  --quoteSigner 0x0000000000000000000000000000000000000000
# Below is USDC on devnet, replace --burnToken with mainnet burn token and --amount with required minimum deposit amount (raw value)
anchor run setMinimumDepositSponsoredCctpSrc \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR -- \
  --burnToken 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU \
  --amount 0
```

#### 升级

启动程序升级 :

```shell
solana program write-buffer \
  --url $RPC_URL \
  --keypair $KEYPAIR \
  --with-compute-unit-price 100000 \
  --max-sign-attempts 100 \
  --use-rpc \
  target/deploy/$PROGRAM.so
export BUFFER= # Export the logged buffer address from the command above
solana program set-buffer-authority \
  --url $RPC_URL \
  --keypair $KEYPAIR \
  $BUFFER \
  --new-buffer-authority $MULTISIG
```

将程序ID添加到 Squads multisig () 中`https://devnet.squads.so/` 用于 devnet 和 `https://app.squads.so/` 用于主网),位于开发者/程序段. 然后在缓冲地址中添加升级填充并缓冲退款. 在创建升级后,按要求验证缓冲权限,并着手启动升级. 一旦所有需要的签名者都得到批准,就执行交易部分的升级.

通过写入缓冲器开始IDL升级:

```shell
anchor idl write-buffer \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR \
  --filepath target/idl/$PROGRAM.json \
  $PROGRAM_ID
export IDL_BUFFER= # Export the logged IDL buffer address from the command above
anchor idl set-authority \
  --provider.cluster $RPC_URL \
  --provider.wallet $KEYPAIR \
  --program-id $PROGRAM_ID \
  --new-authority $MULTISIG \
  $IDL_BUFFER
```

构造用于完成IDL升级的多西格交易 。 从以下命令复制已编码的已打印的 Base58 交易, 并将其导入“ 分队多西格” 供批准和执行 :

```shell
anchor run squadsIdlUpgrade -- \
  --programId $PROGRAM_ID \
  --idlBuffer $IDL_BUFFER \
  --multisig $MULTISIG \
  --closeRecipient $(solana address --keypair $KEYPAIR)
```

#### 校验

开始于本地验证已部署的程序是否匹配公共仓库的源代码 :

```shell
solana-verify verify-from-repo \
  --url $RPC_URL \
  --program-id $PROGRAM_ID \
   --library-name $PROGRAM \
   --base-image "solanafoundation/solana-verifiable-build:$SOLANA_VERSION" \
  https://github.com/across-protocol/contracts
```

当被提示时,不要像多西格那样将验证数据上传到区块链上. 继续创建上传交易, 然后导入并签名/ 在 Squads multisig 中执行 :

```shell
solana-verify export-pda-tx \
  --url $RPC_URL \
  --program-id $PROGRAM_ID \
  --library-name $PROGRAM  \
  --base-image "solanafoundation/solana-verifiable-build:$SOLANA_VERSION" \
  --uploader $MULTISIG \
  https://github.com/across-protocol/contracts
```

注意,如果多西格金库没有足够的SOL用于PDA的创建,初始上传交易可能失败. 在这种情况下,在执行上传交易之前,将所需资金转入多西格金库.

最后,将校验结果提交 OtterSec API(只在主网工作):

```shell
solana-verify remote submit-job \
  --url $RPC_URL \
  --program-id $PROGRAM_ID \
  --uploader $MULTISIG
```

## 其他专题

### 斯莱特

[斯莱特](https://github.com/crytic/slither) 是用 Python 3 写的固态静态分析框架 。 它运行着一个 成套脆弱性探测器,打印关于合同细节的可视信息,并提供方便撰写的API 习惯分析。 Slither 使开发者能够发现弱点,增强他们的代码理解,并迅速 原型自定义分析.

已使用 `Slither@0.9.2` 没有找到主要错误。 重新运行分析器,运行:

```sh
slither contracts/SpokePool.sol
\ --solc-remaps @=node_modules/@
\ --solc-args "--optimize --optimize-runs 1000000"
\ --filter-paths "node_modules"
\ --exclude naming-convention
```

您可以替换 `SpokePool.sol` 你要分析的具体合同.

### ZK 同步适配器

ZK EVM通常需要特殊的编译器来将固态转换为可以在ZK VM上运行的代码.

关于汇编和部署合同,有特别指示 `zksync`。汇编命令将创建 `artifacts-zk` 财务报告和审定财务报表 `cache-zk` 目录.

#### 编译

这个步骤要求 [嵌入桌面](https://www.docker.com/products/docker-desktop/) 正在运行,作为 `solc` docker 图像作为先决条件被获取 .

`yarn compile-zksync`

## 许可证

此寄存器中的所有代码均根据BUSL-1.1许可,除非文件中有不同规定. 风险实验室可以对许可证作个别例外规定 软件和设计。 如果你有兴趣在衍生作品中使用代码或设计, 自由接触 [许可@ risklabs. foundation](mailto:licensing@risklabs.foundation)。 。 。 .

## 常见问题

### 如何安装 @across-protocol/contracts？

在项目目录运行 npm install @across-protocol/contracts，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：buffer-layout（^1\.2\.2）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @across-protocol/contracts 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @across-protocol/contracts 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require\(\)；在 ES Module 项目中也可以用 import 引入（Node\.js 会把 module\.exports 作为默认导出）。

### @across-protocol/contracts 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=22\.18\.0。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @across-protocol/contracts 可以商用吗？

@across-protocol/contracts 使用 AGPL-3\.0-only 许可。最严格的 Copyleft：除分发外，通过网络向用户提供基于它的服务也需要开源对应源码。闭源 SaaS 使用前务必评估。以上为概括，不构成法律意见，请以许可原文为准。

### @across-protocol/contracts 的下载量有多少？

根据 npm 官方下载统计，@across-protocol/contracts 在 2026/10/05 – 2026/11/03 这 30 天内被下载 20,474 次，日均约 682 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @across-protocol/contracts 还在维护吗？

最新版本 5\.0\.28 发布于 2026/11/06（1 天前）；至今共发布 154 个版本，其中过去 12 个月发布了 86 个；首次发布于 2021/12/08。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。