mcpField
A
axelar-gmp

axelar-gmp

github.com/hedera-dev开发28474 次安装8 周前更新
代码仓库

关于 axelar-gmp

axelar-gmp 是面向 Hedera 智能合约开发者的 Axelar GMP 实现指南，涵盖跨链消息发送、接收与授权校验。它强调将桥接传输与业务逻辑分离，并说明如何与 HSS 编排配合。

主要功能

  1. 01Axelar GMP 发送与接收流程
  2. 02先支付原生 Gas 再调用 Gateway
  3. 03源链与合约地址白名单校验
  4. 04传输层与业务处理层分离
  5. 05与 Hedera HSS 调度配合

适用场景

  1. 01实现 Hedera 合约间的跨链消息传递
  2. 02为接收端设置来源链和地址校验
  3. 03设计通过 HSS 周期触发的跨链任务

安装

复制下面的命令，在终端中运行。

$npx skills add https://github.com/hedera-dev/hedera-skills --skill axelar-gmp

安装后在 Claude Code 中输入/axelar-gmp确认已加载。

附带文件references/examples.mdreferences/hedera-axelar.md

详细介绍

Axelar GMP（Hedera）

**GMP 模式：**在源链上编码载荷，以原生代币支付 Axelar Gas，调用 Gateway，然后在目标链上验证来源是否在允许列表中，再解码并执行操作。

Source app → BridgeSender (pay gas + gateway.callContract)
                 → Axelar relayers
                      → AxelarExecutable._execute → Handler

在 Hedera 上，编排通常会将 GMP 与 HSS（0x16b）搭配使用，使合约能够自行重新调度并在每个周期执行派发。桥接传输应封装在精简的发送方接口之后，让编排器保持与桥接无关。

快速参考

组件作用
IAxelarGatewaycallContract(destChain, destAddress, payload)
IAxelarGasService在调用 Gateway 前调用 payNativeGasForContractCall{value}
AxelarExecutable目标链基类；重写 _execute(...)
链名称Axelar 字符串 ID，例如 "hedera"、"ethereum-sepolia"（不是数字链 ID）
地址对端合约的 EVM 字符串形式（校验和格式的 0x…）

有关链名称惯例和 SDK 导入，请参阅 references/hedera-axelar.md。有关发送方／接收方示例，请参阅 references/examples.md。

关键：先支付 Gas，再调用 Gateway

务必在调用 callContract 之前支付 Gas。中继费用使用 msg.value > 0；退款地址应为已注资的编排器（或计划所有者），而不是随机的 EOA。

gasService.payNativeGasForContractCall{ value: msg.value }(
    address(this),       // sender contract
    destinationChain,    // Axelar name string
    destinationAddress,  // receiver 0x… as string
    payload,
    refundAddress        // usually authorizedCaller / orchestrator
);
gateway.callContract(destinationChain, destinationAddress, payload);

关键：授权并设置允许列表

端限制
源链发送方只有 authorizedCaller（编排器）可以调用 send
目标链接收方处理消息前，验证 srcChain + srcAddress（不区分大小写）
目标链处理器只有接收方可以调用业务逻辑（authorizedCaller）

使用统一的小写哈希比较 Axelar 链名称和地址字符串，因为 Axelar 的大小写可能不同。

require(
    keccak256(bytes(_toLower(srcChain))) == keccak256(bytes(_toLower(expectedSourceChain))),
    "invalid source chain"
);
require(
    keccak256(bytes(_toLower(srcAddress))) == keccak256(bytes(_toLower(expectedSourceAddress))),
    "invalid source address"
);

架构：将传输与业务逻辑分离

Source chain                    Destination chain
─────────────────────────────   ─────────────────────────────
Orchestrator ──send──►          MessageReceiver (_execute)
     │ BridgeSender iface              │ Handler iface
BridgeSender                    Handler (swap / settle / …)
  1. 先部署 处理器（不涉及桥接）。
  2. 部署 接收方，并配置 gateway、预期来源和处理器。
  3. 部署 发送方，并配置 gateway、gas service、目标链和目标地址。
  4. 部署 编排器，并配置发送方地址；在发送方上授权编排器。
  5. 双方部署完成后进行 连接配置：在发送方上设置目标地址；在接收方上设置预期来源。
  6. 为编排器注资（用于 Axelar Gas 的原生代币），并为处理器注资（用于目标链工作的代币／资金）。

载荷约定

双方应统一使用一套 ABI 编码／解码方式。若要扩展字段，请为载荷保留版本兼容能力；解码不匹配会导致路由失效。

bytes memory payload = abi.encode(/* agreed fields… */);
// receiver:
(/* fields… */) = abi.decode(payload, (/* matching types… */));

Hedera 编排钩子（HSS）

当源应用通过 HSS（0x16b）调度自身时，每个周期都应：

  1. 确保间隔有效且计划处于活动状态
  2. 使用原生代币调用桥接发送方，以支付 Axelar Gas
  3. 使用 hasScheduleCapacity + scheduleCall 重新调度下一次到期时间（SUCCESS = 22）

如果调度失败，请设置恢复标记，并向计划所有者提供手动重新调度功能。

检查清单

  • 在调用 callContract 前使用原生代币支付 Gas
  • 目标链名称与 Axelar 的 ID 匹配（字符串，而非数字链 ID）
  • 两个合约都部署后再设置对端地址（连接配置步骤）
  • 两端都设置源链允许列表和授权调用方
  • 载荷编码／解码保持一致
  • 为编排器注资以支付中继 Gas；为目标链处理器注资以执行工作
  • 区分演示与生产环境：明确由谁拥有目标链收益

参考资料

评论

支持 Markdown