Frank Kong, 开发者关系工程师, Chainlink Labs

X (Twitter): https://x.com/AlongHudson

Email: frank.kong@smartcontract.com

对于所有符合条件的参与者，将颁发链上完成证书 - 请确保完成每天的作业！

课程大纲

第 1 天

理论讲解

• 传输器（Transporter）,由CCIP提供支持

• 互操作性和Chainlink CCIP简介

  • CCIP：如何使用CCIP进行可编程代币跨链

  • 传统金融（TradFi）中的CCIP 可编程代币跨链

  • 去中心化金融（DeFi）中的CCIP可编程代币跨链

• 如何使用Chainlink CCIP

代码练习

• 练习1：可编程代币跨链

作业

👉 第 1 天作业

第 2 天

理论讲解

• CCIP架构和消息处理

• 调试方法和技巧

• 创建跨链 NFT

代码练习

• 练习2: 创建你首个跨链 NFT

• 练习3: 测试跨链 NFT

作业

👉 第 2 天作业

第 3 天

理论讲解

• Chainlink CCIP 的 5 个跨链安全级别

代码练习

• 练习4: 跨链发送 USDC

作业

👉 第 3 天作业

Chainlink CCIP

Chainlink CCIP 概述

互操作性问题

互操作性 是指在不同系统或网络之间交换信息的能力，即使它们是不兼容的。不同网络上的共享概念确保了各方理解并信任交换的信息。它还考虑了最终性的概念，通过验证信息的准确性和完整性来建立对交换信息的信任。

Web3生态系统已经变得多链化，随着第一层（layer-1）区块链和像应用链（appchains）、子网（subnets）等第二层（layer-2）扩展解决方案的兴起，每个网络都有其自己的可扩展性、安全性和信任度的方法。

然而，区块链是孤立的网络，它们独立运行且不能本地通信。要创建一个真正可互操作的Web3生态系统，数据和价值必须在链之间无缝移动。这就是跨链桥（bridges）的作用所在。

传统的跨链桥（bridges）是当今Web3生态系统中最大的问题之一，因为它们是中心化的。当您使用跨链桥将资金从一条链转移到另一条链时，您实际上是在将您的资金交给某个中心化的实体，并信任他们这些资金将出现在另一侧。令人惊讶的是，到目前为止已经发生了多起跨链桥被黑客攻击的事件。

解决方案——Chainlink CCIP

Chainlink 跨链互操作性协议（CCIP）提供了一个简洁的单一接口，通过这个接口，去中心化应用（dApps）和 Web3 创业者可以安全地满足他们所有的跨链需求，包括代币转账和任意消息传递。

Chainlink CCIP 通过“通道”（lanes）连接区块链网络。“通道”是源区块链到目标区块链路径的唯一组合，例如，从区块链 A 到区块链 C，要使用一个通过。而如果要使用 Chainlink CCIP 反向传输消息，即从区块链 C 到区块链 A，您将需要使用不同的通道，即专属于 C 到 A 路径的通道。

Chainlink CCIP 将始终支持未来添加的每个新链的双向通道。逻辑上的问题是如何让 CCIP 知道通过哪个通道传输 CCIP 跨链消息。实际上这相当简单——每个由 CCIP 支持的区块链都有一个唯一的链选择器。

我们多次提到，通过使用 Chainlink CCIP，您可以 发送跨链消息。但是跨链消息可以包含哪些内容呢？使用 Chainlink CCIP，您可以：

• 转账（支持的）代币

• 发送任何种类的数据

• 同时发送代币和数据

CCIP 的发送者可以是：

• 外部拥有的账户（EOA）

• 任何智能合约

CCIP 的接收者可以是：

• 外部拥有的账户（EOA）

• 任何实现了 CCIPReceiver.sol 的智能合约

注意：如果您向外部拥有的账户（EOA）发送消息和代币，只有代币会到达。

目前，您可以将 CCIP 视为一个“黑盒”组件，并且只需了解路由器合约。我们将在接下来的章节中解释 Chainlink CCIP 的架构。

路由合约（Router） 是 CCIP 用户交互的主要合约。该合约负责启动跨链交互。每个链都有一个路由合约。在转账代币时，调用者必须批准路由合约能够“花费”（转移）调用者的代币。当消息在目标链上接收时，路由器是将代币“交付”到用户账户或将消息传递给接收者（receiver）合约。

Recap概括

Chainlink 跨链互操作性协议提供了一个单一的接口，以安全和去中心化的方式在多个链之间传输代币和数据。

Transporter介绍

Transporter是一个高度安全的接口，可以让您在不同的区块链之间转移代币，而且非常安心。Transporter基于行业领先的跨链协议Chainlink CCIP构建，提供深度防御的安全性。Transporter是一个跨链桥接应用，允许用户在不同的区块链上转移数字资产，并体验每个链所提供的最佳功能。只需几次点击，您就可以在确信Transporter由Chainlink CCIP的五级安全支持的情况下，跨链转移您的代币。Transporter还提供实时交易跟踪，并全天候提供支持服务。

热身练习：让我们桥接一些测试网代币

视频教程：

点击 "Connect wallet " 按钮连接你的钱包

选择你的源网络和目标网络。我将从 Avalanche Fuji 向 Ethereum Sepolia 发送代币。

然后选择你要发送的代币（我们也可以发送消息）。我将使用 USDC。

如果 USDC 无法获取，可以获取 Chainlink 测试代币 CCIP-BnM，用 CCIP-BnM 测试。你可以从下面的链接中获取无限多个 CCIP-BnM 代币。

然后选择您要发送的代币数量。我将选择 1 USDC。

并通过点击“Approve USDC”按钮，授权 Transporter 代表你转移该数量的代币。

下一步是选择您希望用于支付 CCIP 费用的代币。默认情况下，会选择源区块链的本地代币（例如 AVAX），但我将使用 LINK，因为它更便宜。

最后，点击 “Send” 按钮开始转账。

您现在可以坐下来放松会儿，并实时监控您的第一次跨链转账！

请收藏此网址，因为我们在整个训练营期间会经常使用它。

要导航到 Chainlink CCIP 区块浏览器，请单击 “View transaction” 按钮。

一旦源区块链上的交易完成，Chainlink DONs 就可以继续进行跨链转账。最终确定性是区块链技术中一个非常重要的安全概念，因此请确保在本次训练营结束前熟悉它。

最后，我们只需等待目标交易被包含在下一个 Ethereum Sepolia 区块中。

就是这样！传输完成，就这么简单！

当然，您随时可以回到 Chainlink CCIP 区块浏览器查看有关转账的更多详细信息。

Chainlink的 RWA（真实世界资产）代币化训练营为Web3开发者提供了一段激动人心的旅程，通过使用Chainlink 的基础设施，提升您将现实世界资产上链的技能。

在别人之前锁定您的名额。

👉

加入我们为期三天的训练营，您将在链上代币化一个房产。您将学习用不同的数据信息强化资产，安全地在链间转移它，并开发者其超越传统系统的潜力。

您将学到：

• 创建和丰富代币化资产的步骤

• 代币化资产链上开发的关键阶段

• 最大化代币化资产潜力的策略

• 为代币化资产提供统一的黄金记录

请确保在第 1 天之前您已完成以下步骤：

• (获取测试代币，作业练习的时候需要)

• • 如果你通过以上的途径无法获得，

  • 密码: BigMac777

如果你有任何的问题，请在 discord 中询问: ，

或者扫描以下二维码加入微信群：

TradFi 和 DeFi 的交汇点

Chainlink SmartCon 是区块链和金融世界的交汇点，在这里，数字资产的行业先驱、DeFi 的头部项目和区块链开发者汇聚一堂，共同创造全球市场和 Web3 的未来。

👉

活动亮点

Hacker House | 10 月 28-29

与众多开发者一起通过区块链技术开发真实世界的应用，探索如何将区块链技术的应用扩展到全球数十亿用户。

SmartCon 主活动 | 10 月 30-31

从全球金融机构、头部 DeFi 协议和极具创新的初创公司获得前沿的洞见。

往期 SmartCon 的发言嘉宾

Eric Schmidt, 前 CEO, Google

Jonathan Ehrenfeld Solé, 战略主管, SWIFT

Balaji Srinivasan, 天使投资人 & 前 CTO, Coinbase

Laurence Moroney, AI 部门领导, Google

Joseph Chan, 财经事务及库务局, 香港特别行政区

Oliver Roucloux, 业务分析师 & 产品负责人, Euroclear

Rashmi Misra, 人工智能与新兴技术业务发展总经理, Microsoft

我们将要实现的另一个最佳实践称为防御性示例（Defensive Example），这是一种模式，它允许我们在不强制原始交易失败的情况下重新处理失败的消息。让我们解释一下它的工作原理。

接收和处理消息

当目标区块链接收到消息时，CCIP路由器会调用ccipReceive函数。此函数作为合约处理传入CCIP消息的入口点，通过onlyRouter和onlyAllowlisted修饰符实施关键的安全检查。

以下是该过程的逐步分解：

1. 通过ccipReceive进入：

   • ccipReceive函数被调用，传入一个包含待处理消息的Any2EVMMessage结构体。

   • 安全检查确保调用来自授权的路由器、已允许的源链和已允许的发送者。

2. 处理消息：

   • ccipReceive调用processMessage函数，该函数是外部的，以利用Solidity的try/catch错误处理机制。注意：onlySelf修饰符确保只有合约本身可以调用此函数。

   • 在processMessage内部，使用s_simRevert状态变量检查模拟回滚条件。这个模拟由只有合约所有者可调用的setSimRevert函数来切换。

   • 如果s_simRevert为假，processMessage调用_ccipReceive函数进行进一步的消息处理。

3. _ccipReceive中的消息处理：

   • _ccipReceive从消息中提取并存储各种信息，如messageId、解码后的sender地址、代币数量和数据。

   • 然后发出一个MessageReceived事件，表示消息处理成功。

4. 错误处理：

   • 如果在处理过程中发生错误（或触发了模拟回滚），ccipReceive内的catch块将被执行。

   • 失败消息的messageId被添加到s_failedMessages中，消息内容被存储在s_messageContents中。

   • 发出一个MessageFailed事件，允许以后识别和重处理失败的消息。

失败消息的重新处理

retryFailedMessage函数提供了一种机制，如果CCIP消息处理失败，可以用来恢复资产。它专门设计用来处理消息数据问题导致整个处理无法进行，但允许代币恢复的场景：

1. 初始化：

   • 只有合约所有者可以调用此函数，提供失败消息的messageId和代币恢复用的tokenReceiver地址。

2. 验证：

   • 使用s_failedMessages.get(messageId)检查消息是否已失败。如果没有，就回滚交易。

3. 状态更新：

   • 将消息的错误代码更新为RESOLVED，以防止重复进入和多次重试。

4. 代币恢复：

   • 使用s_messageContents[messageId]检索失败的消息内容。

   • 将与失败消息关联的锁定代币转移到指定的tokenReceiver，作为一个逃生舱口，而无需再次处理整个消息。

5. 事件发出：

   • 发出一个MessageRecovered事件，以信号代币已成功恢复。

这个函数展示了一个优雅的资产恢复解决方案，即使在消息处理遇到问题时也能保护用户的价值。

请在训练营结束前回答这 15 个问题。

通过 此表单 提交您的答案

简单:

1. 什么是 CCIP Lane?

2. 什么是 CCIP Chain Selector? 它与 Chain ID 有何不同？

3. CCIP 消息中的 gasLimit 有什么用途？

4. 如何实时监控 CCIP 消息？

5. Chainlink CCIP 的三大主要功能是什么？请提供利用这些功能的潜在用例示例。

中等:

1. 详细说明在智能合约中验证传入 CCIP 消息完整性的安全最佳做法。在 ccipReceive 函数中应实施哪些特定检查，为什么这些验证对于跨链 dApp 的安全性至关重要？

2. Chainlink CCIP 支持哪些代币转移机制？

3. 描述风险管理网络在 Chainlink CCIP 中的作用，并解释“blessing”和“cursing”的过程。

4. 讨论“最终性”概念在 Chainlink CCIP 中的重要性。源链的最终性如何影响 CCIP 中端到端交易时间？

5. 讨论 CCIP 消息中 gasLimit 设置的最佳做法。开发人员如何准确估算和优化 gas 限制，以确保跨链交易的可靠执行？

困难:

1. 解释 DefensiveExample 模式以及如何优雅地处理 CCIP 消息故障。

2. 列出并解释需要使用 Chainlink CCIP Explorer 手动执行的情景。

3. 解释为什么在 Chainlink CCIP 中将 extraArgs 设置为可变是最佳做法，并描述开发人员如何在他们的智能合约中实现这一点。

4. 什么是 CCIP 速率限制？开发人员在设计应用程序以在这些限制内运行时应考虑哪些因素？

5. 如果你使用 Chainlink CCIP 将任意数据与代币一起发送到一个外部拥有账户（Externally Owned Account），会发生什么？

Chainlink跨链互操作性协议（CCIP）不仅仅是一个简单的代币桥接解决方案。它是一个通用的跨链消息协议，用于在单个跨链交易中传输代币（价值）、消息（数据）或同时传输代币和消息——这被称为可编程代币传输。

实际上，CCIP可编程代币传输使智能合约能够在跨链传输代币的同时，附上关于接收智能合约在目标链上接收到这些代币后应如何处理这些代币的指令。这种将价值和指令结合在一起的革命性概念，就是消息跨链的一种，允许代币化资产在到达目的地后自动和动态地进行交互，基于此可以有很多的创新型应用。

在去中心化金融（DeFi）中，CCIP可编程代币传输使创建跨链原生 dApp 成为可能，例如，一个智能合约可以自动跨链传输代币，并将它们存入收益率最高的借贷市场。在传统金融（TradFi）中，CCIP 可编程代币传输使高级用例成为可能，例如跨链交割对支付（DvP）交易，其中持有稳定币的机构在其私有区块链上可以购买在不同私有或公共链上发行的代币化资产。

重要的是，CCIP 可编程代币传输使机构能够在不需要与该区块链集成或直接与之交互的情况下，与其他区块链网络上的智能合约和代币化资产进行交互。他们所需做的只是向 CCIP 发送指令，说明如何与该链交互，大大减少了他们的开销和与每个区块链网络点对点集成相关的风险。

CCIP支持涉及数据和价值的任何跨链传输

就像TCP/IP是支撑互联网的通用标准一样，Chainlink CCIP是支撑 合约互联网(Internet of Contracts) 的通用标准。为了支持DeFi和TradFi中存在的各种跨链用例，CCIP允许以多种方式跨区块链传输数据和/或价值。

任意消息传递（Arbitrary Messaging）

CCIP对 任意消息传递 的支持使开发人员能够跨区块链网络传输任何任意数据（编码为字节）。开发人员利用CCIP的任意消息传递使他们的智能合约应用成为跨链原生。

有了CCIP，源链上的智能合约可以调用目标链上任何智能合约的任何任意函数来触发任何任意行为（如果需要，还可以在源链上接收回调）。开发人员可以在单个消息中编码多个指令，使他们能够协调复杂的多步骤、多链任务。

代币传输

CCIP代币传输通过高度审计和安全审查的代币池合约启用了链间代币传输。交易可以由外部拥有的账户（EOA）直接发起，例如通过像 Transporter 这样的桥接应用程序从用户钱包，或者由智能合约直接发起。然后，代币可以发送到EOA或智能合约。

为确保最高级别的安全性和卓越的用户体验，代币发行者可以在其代币的智能合约内直接使用CCIP，使其成为跨链原生代币。因此，任何用户或开发人员都可以使用CCIP跨链传输该发行者的代币的官方（规范）版本。各种第一层区块链和第二层扩展解决方案，如Wemix和Metis，通过将 CCIP作为他们的官方跨链基础设施 来集成，构建了这一概念，以推动他们的规范代币桥接。通过CCIP传输到这些区块链网络上的每个代币都是该链上该代币的规范表示。

开发人员可以通过以下三种主要方式集成CCIP进行代币传输：

• 销毁和铸造 (Burn and mint) — 在源链上销毁代币，并在目标链上铸造等量代币。这使得跨链原生代币具有统一的供应量。CCIP 通过销毁和铸造代币传输方法支持Circle的USDC 。

• 锁定和铸造 (Lock and mint) — 代币在它们原本发行的链上被锁定，而在目标链上铸造完全抵押的“包装”（Wrapped）代币。这些包装代币可以通过销毁和铸造在其他非原生目标链上转移，或者被销毁以在原始发行源链上解锁代币。Truflation 的 TRUF 代币利用锁定和铸造进行其在 CCIP 上的代币传输。

• 锁定和解锁 (Lock and unlock) — 代币在源区块链上被锁定，相应数量的代币在目标区块链上被释放。这使得支持没有销毁/铸造功能的代币或如果被包装会带来挑战的代币，例如原生区块链燃气代币。CCIP通过锁定和解锁代币传输方法支持 原生ETH传输 。

可编程代币传输

可编程代币传输将代币传输与任意消息传递结合起来。这使开发人员能够在单个交易中跨链传输代币（价值）和有关如何处理这些代币的指令（数据）。重要的是，可编程代币传输是原生构建到CCIP中的，为用户提供了最佳的安全性、可靠性、用户体验（例如，可组合性）和风险管理。

跨链交易

CCIP 可编程代币转账功能能够实现跨链交换用例，任何代币都可以通过 CCIP 连接到源链和目标链上的流动性池/去中心化交易所（DEX），从而有效进行桥接。

例如，建立在 CCIP 之上的跨链交换应用程序允许用户在 Arbitrum 上持有的 Token A 交换为 Optimism 上的 Token B。操作过程是先将 Arbitrum 上的 Token A 交换为 USDC，然后将 USDC 连同交换数据一起桥接到 Optimism，并自动将 USDC 交换为 Token B，最后发送到用户的钱包。这就是 CCIP 对原生 USDC 支持 的强大之处；它不仅支持通过销毁和铸造方式进行原生 USDC 的跨链转账，而且还支持同时传输有关到达目标链后如何处理 USDC 的数据——这是 CCIP 可编程代币转账的独特功能。

XSwap 是一个跨链交换协议，也是 构建计划（BUILD Project）的参与者，它使用 CCIP 的可编程代币转账功能来实现区块链网络之间的跨链交换。XSwap 使用 USDC 作为流动性代币。自推出以来，XSwap 用户已经发起了超过 1.3 亿美元的 CCIP 可编程代币转账。

其他使用CCIP可编程代币转账的用户包括 Transporter、ChainSwap、WEMIX PLAY、Amino Rewards等。

跨链质押和再质押

CCIP 可编程代币转账为跨链质押和再质押解锁了创新。最终用户可以直接从二层网络进行质押/再质押，其中 CCIP 用于将原生资产转回第一层区块链，并附带指示（再）质押资产到指定的（再）质押协议的指令。这降低了用户的 gas 成本，并为他们提供了从任何链上进行（再）质押的便利。

例如，EigenPie 正在集成 Chainlink CCIP，以使其用户能够直接将ETH存入他们的二层合约中，以接收相应的LRT（egETH），而无需离开链。一旦用户将ETH存入二层合约，CCIP的可编程代币转账将把代币桥接到以太坊，并附带指示将它们再质押到 Eigenlayer 的指令。然后，CCIP 被用来锁定在以太坊上铸造的egETH，并将其桥接回 L2，在那里进行铸造并发送到最终用户的钱包地址。

你可以在博客上阅读更多关于Chainlink对质押和再质押的支持：Chainlink 平台如何解锁 DeFi 中的 LST 和 LRT 采用。了解如何在 CCIP大师课：跨链质押版中实现Chainlink CCIP可编程代币转账，以获得更深入的技术洞察。

CCIP可编程代币转账对于实现跨链 货银兑付（DvP）交易 至关重要。在传统金融中，DvP指的是资产交付（例如，证券）和这些资产的支付必须同时发生（即，原子结算）。DvP 是一个重要的特性，可以避免交易双方，一方履行交易义务，但是另一方却没有履行的情况。

澳大利亚和新西兰银行集团有限公司（ANZ）展示了 CCIP 可编程代币转账如何实现跨境、跨链、跨货币的DvP 交易。在一次单一的跨链交易中，一种由本地货币支持的稳定币（NZ$DC）被转换为另一种不同国家货币的稳定币（A$DC），从买方的源链转移到卖方的目标链，并附带购买代币化资产（例如，珊瑚信用）的指令，随后这些资产被发送回客户在源链上的钱包。

想要了解更多信息，请查看与ANZ合作编写的案例研究 使用CCIP进行代币化资产的跨链结算，以及Chainlink联合创始人Sergey Nazarov和ANZ银行服务负责人Nigel Dobson在 Sibos小组讨论 中的对话。

CCIP 最简架构

总结一下，通过 Chainlink CCIP，可以：

• 转移（支持的）代币

• 发送任何类型的数据

• 发送代币和数据

CCIP 接收者可以是：

• EOA（外部拥有的账户）

• 任何实现了 CCIPReceiver.sol 的智能合约

注意：如果您向 EOA 发送消息和代币，只有代币会到达。

目前，您可以将 CCIP 视为一个“黑盒”组件，并且只需关注 Router 合约。我们将在后续章节中解释 Chainlink CCIP 的架构。

开始入门

您可以使用任何区块链开发框架来使用 Chainlink CCIP。对于本次大师班，我们准备了 Hardhat、Foundry 和 Remix IDE 的步骤。

让我们创建一个新项目。

node -v

npm -v

mkdir ccip-masterclass

cd ccip-masterclass

npx hardhat@2.14.1 init

forge --version

mkdir ccip-masterclass

cd ccip-masterclass

forge init

或者，您可以克隆以下项目：

• CCIP 入门套件 (Hardhat 版本)

• CCIP 入门套件 (Foundry 版本)

@chainlink/contracts-ccip NPM 包

要使用 Chainlink CCIP，你需要与 @chainlink/contracts-ccip NPM 包中的 Chainlink CCIP 专用合约进行交互。

要安装它，请按照针对您将用于本次大师班的开发环境的特定步骤进行操作。

npm i @chainlink/contracts-ccip --save-dev

# Node modules
node_modules/

npm i @chainlink/contracts-ccip --save-dev

libs = ['node_modules', 'lib']
remappings = [
    '@chainlink/contracts-ccip/=node_modules/@chainlink/contracts-ccip'
]

forge install smartcontractkit/ccip@ccip-develop

# foundry.toml
remappings = [
    '@chainlink/contracts-ccip/=lib/ccip/contracts/'
]

// SPDX-License-Identifier: MIT
pragma solidity 0.8.19;

import {Client} from "@chainlink/contracts-ccip/src/v0.8/ccip/libraries/Client.sol";

contract Empty {}

基础接口

尽管如前所述，CCIP 的发送者和接收者可以是 EOA（外部拥有的账户）和智能合约，并且所有组合都是可能的，我们将要介绍最复杂的情况，即 CCIP 的发送者和接收者都是位于不同区块链上的智能合约。

源区块链

要发送 CCIP 消息，源区块链上的智能合约必须调用 ccipSend()函数，该函数定义在IRouterClient.sol接口中。

// SOURCE BLOCKCHAIN 

interface IRouterClient {
    /// @notice 请求发送 CCIP 消息到目标链
    /// @param destinationChainSelector 目标链选择器
    /// @param message 包含数据和/或代币的跨链 CCIP 消息
    /// @return messageId 消息 ID
    function ccipSend(
        uint64 destinationChainSelector,
        Client.EVM2AnyMessage calldata message
    ) external payable returns(bytes32 messageId);
}

正在发送的CCIP消息是来自Client库中的EVM2AnyMessage Solidity 结构体。

// SOURCE BLOCKCHAIN

library Client {
    struct EVM2AnyMessage {
        bytes receiver; // 目标 EVM 链上的接收者地址，使用 abi.encode(receiver address)
        bytes data; // 数据负载
        EVMTokenAmount[] tokenAmounts; // 转移的代币地址和数量
        address feeToken; // 费用代币地址；address(0) 表示你发送 msg.value
        bytes extraArgs; // 使用 _argsToBytes(EVMExtraArgsV1) 填充此字段
    }
    
    struct EVMTokenAmount {
        address token; // 本地区块链上的代币地址
        uint256 amount;
    }
    
    struct EVMExtraArgsV1 {
        uint256 gasLimit;
        bool strict;
    }
}

现在让我们理解一下我们正在发送的EVM2AnyMessage结构体的每个属性代表什么以及如何使用它。

receiver (接收者)

接收者合约的地址。它可以是智能合约或外部拥有的账户（EOA）。使用abi.encode(receiver)将地址编码为 Solidity 的字节数据类型。

data (数据)

通过 CCIP 消息发送的数据。这正是我们所说的 CCIP 消息可以携带的“任意类型的数据”。这些数据可以简单到像是“Hello, world!”这样的文本，也可以复杂到 Solidity 编写的结构体或者函数的签名。

tokenAmount (代币数量)

源链上表示的代币及其数量。这里我们指定了我们正在发送的代币（出自支持的代币）以及数量。这是一个EVMTokenAmount结构体数组，它只包含两个属性：

• token(代币)- 我们在本地（源）区块链上发送的代币的地址

• amount(数量) 我们正在发送的代币数量。发送者必须批准CCIP路由器代表发送者花费这个数量，否则对ccipSend函数的调用将会回滚。

目前，单一 CCIP 发送交易中可以发送的代币数量最多为5个。

feeToken (费用代币)

feeToken 是费用代币的地址。CCIP 支持使用 LINK 以及包括原生区块链原生代币（能支付gas fee的代币）和它们的 ERC20 包装版本在内的替代资产来支付费用。对开发者而言，这意味着你可以在源链上轻松支付费用，而 CCIP 将负责在目标链上执行操作。若要使用原生代币支付，例如在以太坊上的 ETH 或者在 Polygon 上的 MATIC，可以将 feeToken 设置为address(0)。即便使用原生资产支付费用，Chainlink 去中心化预言机网络（DON）中的节点只会得到 LINK 作为奖励

extraArgs (额外参数)

用户填写EVMExtraArgsV1结构体，然后使用_argsToBytes函数将其编码为字节。该结构体由两个属性组成：

• gasLimit - CCIP 在目标区块链上的合约执行ccipReceive()可以消耗的最大 gas 数量。未用完的 gas 不会退还。这意味着，例如，如果你将代币发送到 EOA，你应该把gasLimit值设为0，因为EOA 无法实现ccipReceive()（或任何其他）函数。为了估计目标合约的准确 gas limit（要使用的 gas 数量），请考虑利用 Ethereum 客户端 RPC 通过在receiver.ccipReceive()函数上应用eth_estimateGas，或者使用 Hardhat插件进行gas测试 ，或者进行 Foundry gas测试 。

• strict - 用于严格排序。你应该将其设置为false。CCIP将始终按发送顺序处理来自特定发送者到特定目标区块链的消息。如果你在消息的extraArgs部分设置strict: true，并且如果ccipReceive失败（回滚），它将阻止来自同一发送者的任何后续消息被处理，直到当前消息成功执行。使用此功能时应该非常小心，以避免无意中停止发送者的消息被处理。严格排序功能目前是实验性的，未来不保证其维护或进一步开发。

如果未指定 extraArgs，即设置为 extraArgs: ""，默认情况下将应用 200_000 的 gasLimit 并且不启用严格顺序。在生产环境中部署时，请确保 extraArgs 是可更改的。这允许您在链下构建此参数，并在需要时通过函数调用传递或存储在可更新的变量中。这样的设计使得 extraArgs 能够适应未来对CCIP的任何升级。

目标区块链

目标区块链上的智能合约要接收 CCIP 消息，必须实现IAny2EVMMessageReceiver接口。@chainlink/contracts-ccip NPM 包提供了正确实现此接口的合约，称为 CCIPReceiver.sol，但在接下来的章节中我们会更多地讨论它。现在，让我们理解在一般场景下必须实现的IAny2EVMMessageReceiver接口的哪些函数。

// DESTINATION BLOCKCHAIN

/// @notice 打算从路由器接收消息的应用合约应实现此接口。
interface IAny2EVMMessageReceiver {
    /// @notice 路由器调用此函数以传递消息
    /// @param message CCIP 消息
    /// @dev 注意确保你检查 `msg.sender` 是路由器
    function ccipReceive(Client.Any2EVMMessage calldata message) external;
}

如您所见，IAny2EVMMessageReceiver接口中的ccipReceive()函数接受来自 Client 库的Any2EVMMessage结构体对象。这个结构体是接收到的CCIP消息在Solidity中的表现形式。请注意，这个Any2EVMMessage结构体与我们在源区块链上用于发送的结构体——EVM2AnyMessage——是不同的。它们并不相同。

// DESTINATION BLOCKCHAIN

library Client {
    struct Any2EVMMessage {
        bytes32 messageId; // 源链上的 `ccipSend` 对应的消息 ID
        uint64 sourceChainSelector; // 源链选择器
        bytes sender; // 如果来自 EVM 链，使用 `abi.decode(sender)`
        bytes data; // 在原始消息中发送的负载
        EVMTokenAmount[] tokenAmounts; // 在目标链上的代币及其数量
    }
    
    struct EVMTokenAmount {
        address token; // 本地区块链上的代币地址
        uint256 amount;
    }
}

现在让我们理解一下我们接收到的Any2EVMMessage结构体的每个属性代表什么以及如何使用它：

• messageId - CCIP消息ID，在源链生成。

• sourceChainSelector - 源链选择器。

• sender - 发送者地址。如果源链是EVM链，使用abi.decode(sender, (address))进行解码。

• data - CCIP消息中发送的有效载荷。例如，"Hello, world!"。

• tokenAmounts - 接收到的代币及其在目标链上的表示形式的金额。

回顾一下，下面是所需的最小架构图，用于发送和接收Chainlink CCIP消息：

您可能已经注意到，由于存在一些额外的摩擦点——例如设置钱包、获取测试网代币、等待跨链交易完成等，直接在测试网络上使用 CCIP 构建并不理想。这是因为测试网络用于测试，而本地环境（如 Foundry、Hardhat 或 Remix IDE）用于构建和单元测试。

介绍 Chainlink Local

为了解决这个问题，我们创建了 。在本章中，您将学习如何在本地模拟跨链交易，并以比在测试网络上工作快 2000 倍的速度使用 Chainlink CCIP 构建项目！

Chainlink Local 是一个可安装的依赖项，例如 OpenZeppelin。它提供了一个工具（Chainlink Local 模拟器），开发人员可以将其导入到他们的 Foundry、Hardhat 或 Remix IDE 项目中。这个工具在本地运行 ，这意味着开发人员可以在本地环境中快速探索、设计原型和迭代 CCIP dApps，只有在准备好在实际环境中测试时再将项目移动至测试网。

最重要的是，用 Chainlink Local 测试的智能合约可以在不做任何修改的情况下部署到测试网络（假设通过构造函数传入了网络特定的合约地址，如 Router 合约和 LINK 代币地址）。

要查看更详细的文档和更多示例，请访问 和 。

本地模式 vs 分叉模式

模拟器支持两种模式：

• 本地模式：使用在本地运行的开发区块链节点上的模拟合约，运行在 localhost 上。

• 分叉模式：使用已部署的 Chainlink CCIP 合约，通过多个进行工作。

本地模式

在本地模拟模式下工作时，模拟器会将一组智能合约预部署到一个空白的 Hardhat/Anvil 网络的EVM 状态，并通过调用 configuration() 函数公开它们的详细信息。尽管应该存在两个 Router 合约（sourceRouter 和 destinationRouter），开发人员通过这两个不同的 Router 路由跨链消息，但在本地模式中它们都是在本地区块链节点上运行的同一个合约。

分叉模式

代码时间: 为我们的XNFT.sol合约编写单元测试

创建一个新的Foundry工程

运行以下命令创建一个新的Foundry工程：

安装必要的依赖项

接下来，我们需要安装以下依赖项。如果您不想在每次安装后提交更改，请在运行以下每个命令后附加--no-commit 标志。

@chainlink/contracts

@chainlink/contracts-ccip

@openzeppelin/contracts

@chainlink/local

然后在您的 foundry.toml 或 remappings.txt 文件中设置以下 remappings：

删除 src/Counter.sol、test/Counter.t.sol 和 script/Counter.s.sol 文件。在 src 文件夹中创建一个新的 XNFT.sol 文件，并粘贴上一页/练习中的 XNFT 智能合约内容。运行 forge build 来编译该合约。如果您正确安装了依赖项会编译成功。

配置Ethereum Sepolia和Arbitrum Sepolia的RPC URLs

然后在您的 foundry.toml 文件中添加 rpc_endpoints 部分。其最终版如下所示：

使用Chainlink Local来编写您第一个测试文件

在上一个练习中，我们在两个不同的测试网络上执行了 7 个步骤：从部署、铸造、转移 XNFT 到另一个账户。使用 Chainlink Local，您可以编写一个测试文件在本地环境中执行相同的操作。测试中使用与测试网络上完全相同的 CCIP 合约，并且速度更快。

创建一个新的 test/XNFT.t.sol 文件。粘贴以下内容：

如果您尝试编译此合约，可能会遇到错误，因为缺少上一个练习中的 EncodeExtraArgs.sol 辅助智能合约。通过创建一个新文件 test/utils/EncodeExtraArgs.sol 并粘贴以下代码来修复此问题。

让我们分析一下目前的代码。我们从 @chainlink/local 包中导入了 CCIPLocalSimulatorFork，这意味着我们使用的是分叉模式。我们创建了一个新的 CCIPLocalSimulatorFork 实例，并在所有不同的分叉之间使其保持持久性，使它能正常工作。

在作业中，您需要从 @chainlink/local 包中导入 CCIPLocalSimulator。

我们还创建了两个分叉网络（即最新区块的区块链网络副本——最好固定这个区块号，而不是总是使用最新的区块号）Ethereum Sepolia 和 Arbitrum Sepolia 测试网络。现在我们可以使用 Foundry 在多个分叉网络之间切换，但我们选择 Ethereum Sepolia 作为开始的源区块链。

Foundry 使用分叉 ID 管理同一测试中不同的分叉网络，通常是 1、2、3 等这样的数字。分叉 ID 与 block.chainid 并不相同——后者是可以从Solidity 中获取的区块链网络的实际 Chain ID，例如，Ethereum Sepolia 的 Chain ID 是 11155111。

Foundry 中的 CCIPLocalSimulatorFork 提供了Register 辅助合约，其中包含 NetworkDetails 结构，如下所示：

在该结构体中已预先设置了一些测试网络的详细信息，并且其中特意不包含主网络。因此最好的做法是始终验证这些信息——否则模拟将无法工作：

我们将在 setup() 函数中直接执行前一个练习的步骤 1）和 2），如下所示：

在一个新的test函数中直接执行前一个练习的其余步骤，如下所示：

最终的完整代码：

接下来，我们将通过几个步骤来看一下 CCIP 消息的工作流程。

步骤1：准备工作

1. 发送方准备一条 CCIP 消息 (EVM2AnyMessage)，用于其到目标区块链（chainSelector）的跨链交易。一条CCIP 消息包括以下信息：

• 接收方

• 数据载荷

• 代币地址和金额

• 费用代币

• 其他参数（gasLimit，strict）

1. 发送方调用 Router.getFee() 获得支付给 CCIP 的总费用（包括 gas 和溢价），并授权这部分费用金额。

2. 发送方调用 Router.ccipSend()，提供他们想要发送的 CCIP 消息及其期望的目标链chainSelector。考虑到要进行代币的转移，这部分金额必须被授权给 Router。

步骤2：发送

Router 验证接收到的消息（例如，支持的目标链IDchainId和支持的目标链上的代币）。

Router 接收手续费并将其转给 OnRamp。

Router 接收代币并将其转到对应的代币池。如果发送方未将此代币授权给 Router，此操作将失败。

Router 将消息转发给正确的 OnRamp（基于目标链选择器chainSelector）进行处理：

• 验证消息（代币数量、gasLimit、数据长度等）。

• [对于代币转移] 确保转移的金额不超过该通道的总速率限制。

• 使用序列号sequence number对消息进行排序。

• 对于消息中包含的每种代币：通知代币池锁定/销毁代币。这也将验证该通道的代币池速率限制。

• OnRamp 抛出包含已排序消息的事件。这会触发 DONs 处理消息。

• 生成一个 messageId 并返回给发送方。

步骤3: Committing DON

1. Commiting DON中的节点监听已准备好发送的消息事件。

2. 考虑到消息的安全性，为了防止重组攻击，消息必须处于finalized状态。

3. 当 OnRamp 中的消息队列达到一定数量或时间时，将触发Committing DON 创建一个包含所有发送消息的带有承诺的Report（以批次形式）。此承诺以 Merkle Root的形式表示。

4. 在Committing DON 达成共识后，包含 Merkle Root的Report被传送给目标链上的 CommitStore 合约。

5. 风险管理网络（Risk Managemendt Network）通过CommitStore合约中“批准”该Merkle Root，以确保它可以正确代表 OnRamp 中经过排序的消息。

Merkle Root与Merkle Proof

1. Merkle Root：Merkle Tree的根哈希值。它是对树中所有叶子节点（消息 M1-M4）的承诺。树中的每个节点都是其下方节点的哈希值。

2. Merkle Proof：为了证明消息 M1 被包含在 Merkle Root（承诺）中，证明者向仅持有Merkle Root的Verifier提供以下元素作为证明：

• M1

• H(M2)

• H(H(M3),H(M4))

使用这个Merkle Proof，Verifier可以轻松地验证M1确实包含在其拥有的承诺（Merkle Root）中。

步骤4: Executing DON

1. 执行 DON 中的节点监听准备发送的消息事件，该过程类似于Committing DON。

2. 考虑到消息的安全性，为了防止重组攻击，消息必须处于finalized状态。

3. 除了监控时间或OnRamp中消息队列中的消息数量外，Executing DON还监控CommitStore合约，以确保消息已准备好在目标链上执行，即消息是否包含在被批准的链上承诺中。

4. 如果条件满足，Executing DON将创建一个包含所有准备发送的消息的Report（以批次形式）。它在批处理逻辑中说明每条消息的 gasLimit。它还为每条消息计算相关的Merkle Proof，以证明该消息包含在Committing DON向CommitStore合约提交的Merkle Root中。注意，Executing DON 的批次可以是Committing DON批次的任何子集。

5. 达成共识后，Report将被传送到目标链上的OffRamp合约。

步骤5: 执行

1. 对于接收到的批次中的每条消息，OffRamp 合约使用提供的Merkle Proof验证该交易是否包含在CommitStore合约中被批准的承诺中。

2. 如果交易中包含代币，OffRamp合约将验证通道的总速率限制并去匹配对应的代币池。

3. OffRamp 调用代币池的unlock/mint函数。这将验证代币池的速率限制，并解锁或铸造代币并将其转移给指定的接收方。

4. 如果接收方是一个合约地址并且实现了正确的接口，OffRamp使用Router来调用接收方的 ccipReceive()函数。

5. 接收方处理消息，并被告知此消息的来源（区块链 + 发送方）、转移的代币和数据载荷（含相关指令）。

6. 根据数据载荷，接收方可能将代币转移给最终接收者（终端用户）。

CCIP就像国际航班

那么，你是否需要了解 CCIP消息处理的具体过程呢？完全不需要。你只需通过与Router合约交互来发送跨链消息，Chainlink CCIP会将其投递出去。这就像寄包裹一样——你只需将包裹交给邮局，标明收件人并支付费用即可。

就像国际航班中涉及各种检查站和相应程序确保从一个国家到另一个国家的旅程安全一样，Chainlink CCIP确保了不同区块链网络之间在被验证状态下的安全通信。

起飞前的 JFK 机场：提交阶段

在任何飞机起飞之前，都需要进行一系列严格的检查——类似于CCIP 的初始化阶段。这里，Router充当了我们的值机柜台，用户在这里提交他们的跨链请求，就像乘客确认他们的航班细节一样。

旅行者检查他们的行李，然后由机场工作人员处理。就像长途航班上的任何行李一样，跨链消息也要遵循安全协议。同样在CCIP中，OnRamp合约检查目标区块链地址的有效性、消息大小、gas 限制和序列号，确保“行李”（或数据载荷）已为其旅程做好准备。

护照和签证的验证非常像 Commit Store 智能合约，它存储finalized状态消息的Merkle Root，并确保这些消息在目标链上执行之前会通过风险管理网络的“批准”来保证其真实性和安全性。

飞行中：跨链传输

在飞行过程中，乘客和行李处于运输状态，类似于跨链消息在网络之间传播。Executing DON类似于幕后工作的机组人员，确保跨链交互的顺利进行。

正如我们所知，飞行的持续时间可能会有所不同——向东飞行可能会追逐太阳，缩短我们感受到的白天，而向西飞行则会延长它。同样，跨链消息的交付时间取决于源区块链的最终确定性。我们从 CCIP大师班 #1 中了解到，最终确定性是指区块链上交易的不可逆性和永久记录状态。

抵达香港机场：执行阶段

到达时，OffRamp合约通过验证已提交和批准的Merkle Root来确保消息的真实性。

就像风险管理网络在幕后进行的最终检查（乘客看不到）一样，行李或我们的跨链消息也要经过各种安全检查，确保其符合目标区块链的规则及规范。

最后，目标链上的Router扮演边境管制的角色，将消息数据和/或代币传递到接收方地址，就像旅客拿到盖了章的护照进入新国家一样。

尽管整个过程很复杂，但对于终端用户来说大多是不可见的，他们仅仅体验到数字资产从一个区块链到另一个区块链的无缝转移。从值机到取回行李的喜悦，通过CCIP进行跨链消息传递的整个过程可谓是现代密码学的奇迹，它确保我们收到的东西就是之前我们交付给网络的。

通过以下表单提交包含您的练习的公共 GitHub 仓库

使用 chainlink-local 为项目 https://github.com/smartcontractkit/ccip-cross-chain-name-service 编写测试。您可以参考 https://cll-devrel.gitbook.io/chainlink-local-documentation 获取帮助。

在测试中，您必须：

• 创建 一个CCIPLocalSimulator.sol 智能合约的实例

• 调用 configuration() 函数获取 Router 合约地址

• 创建 CrossChainNameServiceRegister、CrossChainNameServiceReceiver 和 CrossChainNameServiceLookup 智能合约的实例，并在需要时调用 enableChain() 函数

• 调用 register() 函数，并提供 “alice.ccns” 和 Alice 的 EOA 地址作为函数参数

• 调用 lookup() 函数，并提供 “alice.ccns” 作为函数参数。断言判断返回的地址就是 Alice 的 EOA 地址

• 发送指向公共 GitHub 仓库的 URL

通过此表单提交您的公共GitHub仓库以完成以下练习

按照 https://docs.chain.link/ccip/tutorials/ccipreceive-gaslimit 指南，测量 ccipReceive 函数的燃气消耗。一旦得到该数值，将其增加10%，并将其作为 transferUsdc 函数的 gasLimit 参数，而不是当前硬编码的500,000。

使用此Gitbook作为指导

转移代币与数据 - 防御性示例

本教程扩展了可编程代币传输的示例。它使用 Chainlink CCIP 在不同区块链上的智能合约之间传输代币和任意数据，专注于接收合约中的防御性编码。如果在 CCIP 消息接收期间发生指定错误，合约将锁定代币。锁定代币允许所有者根据需要恢复和重定向它们。防御性编码至关重要，因为它使得恢复锁定的代币成为可能，并确保了用户资产的保护。

开始之前

1. 您应该了解如何编写、编译、部署和资助智能合约。如果您需要复习基础知识，请阅读本教程，它将指导您使用 Solidity 编程语言，在 MetaMask 钱包中交互以及在 Remix 开发环境中工作。

2. 您的账户必须在 Avalanche Fuji 上有一些 AVAX 和 LINK 代币，在以太坊 Sepolia 上有一些 ETH 代币。了解如何 获取测试网 LINK。

3. 查看支持的网络页面，确认您要传输的代币是否支持您的通道。在这个例子中，您将从 Avalanche Fuji 传输代币到以太坊 Sepolia，所以请在这里检查支持的代币列表。

4. 了解如何 获取 CCIP 测试代币。按照本指南操作后，您应该拥有 CCIP-BnM 代币，并且 CCIP-BnM 应该出现在 MetaMask 中您的代币列表中。

5. 了解如何 资助您的合约。本指南展示了如何使用 LINK 资助您的合约，但您可以使用相同的指南为合约资助任何 ERC20 代币，只要它们出现在 MetaMask 的代币列表中。

6. 按照前一个教程：使用 数据传输代币 来学习如何使用 CCIP 进行可编程代币传输。

编码时间！

在这个练习中，我们将从 Avalanche Fuji 上的智能合约启动交易，向 以太坊 Sepolia 上的另一个智能合约发送字符串文本和 CCIP-BnM 代币，使用 CCIP。然而，在到达接收合约时，处理逻辑将故意失败。本教程将展示一种优雅的错误处理方法，允许合约所有者恢复被锁定的代币。

正确估计您的 gas 限制

彻底测试所有场景以准确估计所需的 gas 限制至关重要，包括失败场景。请注意，用于执行失败场景的错误处理逻辑的 gas 可能高于成功场景。

// SPDX-License-Identifier: MIT
pragma solidity 0.8.19;

import {IRouterClient} from "@chainlink/contracts-ccip/src/v0.8/ccip/interfaces/IRouterClient.sol";
import {OwnerIsCreator} from "@chainlink/contracts-ccip/src/v0.8/shared/access/OwnerIsCreator.sol";
import {Client} from "@chainlink/contracts-ccip/src/v0.8/ccip/libraries/Client.sol";
import {CCIPReceiver} from "@chainlink/contracts-ccip/src/v0.8/ccip/applications/CCIPReceiver.sol";
import {IERC20} from "@chainlink/contracts-ccip/src/v0.8/vendor/openzeppelin-solidity/v4.8.3/contracts/token/ERC20/IERC20.sol";
import {SafeERC20} from "@chainlink/contracts-ccip/src/v0.8/vendor/openzeppelin-solidity/v4.8.3/contracts/token/ERC20/utils/SafeERC20.sol";
import {EnumerableMap} from "@chainlink/contracts-ccip/src/v0.8/vendor/openzeppelin-solidity/v4.8.3/contracts/utils/structs/EnumerableMap.sol";

/**
 * 这是一个使用硬编码值来增加清晰度的示例合约。
 * 这是一个使用未经审计代码的示例合约。
 * 不要在生产环境中使用这段代码。
 */

/// @title - 一个简单的跨链传输/接收代币和数据的信使合约。
/// @dev - 这个示例展示了如何在撤销的情况下恢复代币
contract ProgrammableDefensiveTokenTransfers is CCIPReceiver, OwnerIsCreator {
    using EnumerableMap for EnumerableMap.Bytes32ToUintMap;
    using SafeERC20 for IERC20;

    // 自定义错误，提供更具描述性的撤销消息。
    error NotEnoughBalance(uint256 currentBalance, uint256 calculatedFees); // 用于确保合约有足够的余额来支付费用。
    error NothingToWithdraw(); // 当尝试提取以太币但没有可提取的以太币时使用。
    error FailedToWithdrawEth(address owner, address target, uint256 value); // 当提取以太币失败时使用。
    error DestinationChainNotAllowlisted(uint64 destinationChainSelector); // 当目标链没有被合约所有者列入允许名单时使用。
    error SourceChainNotAllowed(uint64 sourceChainSelector); // 当源链没有被列入允许名单时使用。
    error SenderNotAllowed(address sender); // 当发件人没有被合约所有者列入允许名单时使用。
    error InvalidReceiverAddress(); // 当接收地址为0时使用。
    error OnlySelf(); // 当函数在合约外部被调用时使用。
    error ErrorCase(); // 当模拟消息处理过程中的撤销时使用。
    error MessageNotFailed(bytes32 messageId);

    // 示例错误代码，可以有许多不同的错误代码。
    enum ErrorCode {
        // 首先是RESOLVED，以便默认值是已解决的。
        RESOLVED,
        // 此处可以有任意数量的错误代码。
        FAILED
    }

    struct FailedMessage {
        bytes32 messageId;
        ErrorCode errorCode;
    }

    // 当消息发送到另一个链时发出的事件。
    event MessageSent(
        bytes32 indexed messageId, // CCIP消息的唯一ID。
        uint64 indexed destinationChainSelector, // 目的链的链选择器。
        address receiver, // 目的链上的接收地址。
        string text, // 被发送的文本。
        address token, // 被转移的代币地址。
        uint256 tokenAmount, // 被转移的代币数量。
        address feeToken, // 用于支付CCIP费用的代币地址。
        uint256 fees // 为发送消息支付的费用。
    );

    // 当从另一个链收到消息时发出的事件。
    event MessageReceived(
        bytes32 indexed messageId, // CCIP消息的唯一ID。
        uint64 indexed sourceChainSelector, // 来源链的链选择器。
        address sender, // 来自源链的发件人地址。
        string text, // 收到的文本。
        address token, // 被转移的代币地址。
        uint256 tokenAmount // 被转移的代币数量。
    );

    event MessageFailed(bytes32 indexed messageId, bytes reason);
    event MessageRecovered(bytes32 indexed messageId);

    bytes32 private s_lastReceivedMessageId; // 存储最后接收的消息ID。
    address private s_lastReceivedTokenAddress; // 存储最后接收的代币地址。
    uint256 private s_lastReceivedTokenAmount; // 存储最后接收的数量。
    string private s_lastReceivedText; // 存储最后接收的文本。

    // 映射，用于跟踪允许的目标链。
    mapping(uint64 => bool) public allowlistedDestinationChains;

    // 映射，用于跟踪允许的源链。
    mapping(uint64 => bool) public allowlistedSourceChains;

    // 映射，用于跟踪允许的发件人。
    mapping(address => bool) public allowlistedSenders;

    IERC20 private s_linkToken;

    // 存储失败消息的内容。
    mapping(bytes32 messageId => Client.Any2EVMMessage contents)
        public s_messageContents;

    // 包含失败消息及其状态。
    EnumerableMap.Bytes32ToUintMap internal s_failedMessages;

    // 用于模拟消息处理函数中的撤销。
    bool internal s_simRevert = false;

    /// @notice 构造函数，用于使用路由器地址初始化合约。
    /// @param _router 路由器合约的地址。
    /// @param _link LINK合约的地址。
    constructor(address _router, address _link) CCIPReceiver(_router) {
        s_linkToken = IERC20(_link);
    }

    /// @dev 修饰符，用于检查给定目标链选择器的链是否被列入允许名单。
    /// @param _destinationChainSelector 目的链的选择器。
    modifier onlyAllowlistedDestinationChain(uint64 _destinationChainSelector) {
        if (!allowlistedDestinationChains[_destinationChainSelector])
            revert DestinationChainNotAllowlisted(_destinationChainSelector);
        _;
    }

    /// @dev 修饰符，用于检查源链选择器的链和发件人是否被允许。
    /// @param _sourceChainSelector 目的链的选择器。
    /// @param _sender 发件人的地址。
    modifier onlyAllowlisted(uint64 _sourceChainSelector, address _sender) {
        if (!allowlistedSourceChains[_sourceChainSelector])
            revert SourceChainNotAllowed(_sourceChainSelector);
        if (!allowlistedSenders[_sender]) revert SenderNotAllowed(_sender);
        _;
    }

    /// @dev 修饰符，检查接收地址不为0。
    /// @param _receiver 接收地址。
    modifier validateReceiver(address _receiver) {
        if (_receiver == address(0)) revert InvalidReceiverAddress();
        _;
    }

    /// @dev 修饰符，仅允许合同本身执行功能。
    /// 如果由任何帐户调用，则抛出异常，而不是合同本身。
    modifier onlySelf() {
        if (msg.sender != address(this)) revert OnlySelf();
        _;
    }

    /// @dev 更新目标链的交易允许状态。
    /// @notice 只能由所有者调用此功能。
    /// @param _destinationChainSelector 要更新的目的链选择器。
    /// @param allowed 设置目的链的允许状态。
    function allowlistDestinationChain(
        uint64 _destinationChainSelector,
        bool allowed
    ) external onlyOwner {
        allowlistedDestinationChains[_destinationChainSelector] = allowed;
    }

    /// @dev 更新源链的允许状态
    /// @notice 只能由所有者调用此功能。
    /// @param _sourceChainSelector 要更新的源链选择器。
    /// @param allowed 设置源链的允许状态。
    function allowlistSourceChain(
        uint64 _sourceChainSelector,
        bool allowed
    ) external onlyOwner {
        allowlistedSourceChains[_sourceChainSelector] = allowed;
    }

    /// @dev 更新发件人的交易允许状态。
    /// @notice 只能由所有者调用此功能。
    /// @param _sender 要更新的发件人地址。
    /// @param allowed 设置发件人的允许状态。
    function allowlistSender(address _sender, bool allowed) external onlyOwner {
        allowlistedSenders[_sender] = allowed;
    }

    /// @notice 向目标链上的接收者发送数据和转移代币。
    /// @notice 使用 LINK 支付费用。
    /// @dev 假设你的合约有足够的LINK来支付 CCIP 费用。
    /// @param _destinationChainSelector 目标区块链的标识符（即选择器）。
    /// @param _receiver 目标区块链上的接收者地址。
    /// @param _text 要发送的字符串数据。
    /// @param _token 代币地址。
    /// @param _amount 代币数量。
    /// @return messageId 发送的 CCIP 消息的 ID。
    function sendMessagePayLINK(
        uint64 _destinationChainSelector,
        address _receiver,
        string calldata _text,
        address _token,
        uint256 _amount
    )
        external
        onlyOwner
        onlyAllowlistedDestinationChain(_destinationChainSelector)
        validateReceiver(_receiver)
        returns (bytes32 messageId)
    {
        // 在内存中创建一个 EVM2AnyMessage 结构，其中包含发送跨链消息所需的信息
        // address(linkToken) 表示费用以 LINK 支付
        Client.EVM2AnyMessage memory evm2AnyMessage = _buildCCIPMessage(
            _receiver,
            _text,
            _token,
            _amount,
            address(s_linkToken)
        );

        // 初始化一个路由器客户端实例，以与跨链路由器交互
        IRouterClient router = IRouterClient(this.getRouter());

        // 获取发送 CCIP 消息所需的费用
        uint256 fees = router.getFee(_destinationChainSelector, evm2AnyMessage);

        if (fees > s_linkToken.balanceOf(address(this)))
            revert NotEnoughBalance(s_linkToken.balanceOf(address(this)), fees);

        // 批准路由器代表合约转移 LINK 代币。它将花费费用中的 LINK
        s_linkToken.approve(address(router), fees);

        // 批准路由器代表合约花费给定数量的代币。它将花费给定数量的代币
        IERC20(_token).approve(address(router), _amount);

        // 通过路由器发送消息，并存储返回的消息 ID
        messageId = router.ccipSend(_destinationChainSelector, evm2AnyMessage);

        // 发出一个事件，其中包含消息详细信息
        emit MessageSent(
            messageId,
            _destinationChainSelector,
            _receiver,
            _text,
            _token,
            _amount,
            address(s_linkToken),
            fees
        );

        // 返回消息 ID
        return messageId;
    }

    /// @notice 向目标链上的接收者发送数据和转移代币。
    /// @notice 使用原生gas支付费用。
    /// @dev 假设你的合约有足够的原生gas，如以太坊上的ETH或Polygon上的MATIC。
    /// @param _destinationChainSelector 目标区块链的标识符（即选择器）。
    /// @param _receiver 目标区块链上的接收者地址。
    /// @param _text 要发送的字符串数据。
    /// @param _token 代币地址。
    /// @param _amount 代币数量。
    /// @return messageId 发送的CCIP消息的ID。
    function sendMessagePayNative(
        uint64 _destinationChainSelector,
        address _receiver,
        string calldata _text,
        address _token,
        uint256 _amount
    )
        external
        onlyOwner
        onlyAllowlistedDestinationChain(_destinationChainSelector)
        validateReceiver(_receiver)
        returns (bytes32 messageId)
    {
        // 在内存中创建一个 EVM2AnyMessage 结构，其中包含发送跨链消息所需的信息
        // address(0) 表示费用以原生气体支付
        Client.EVM2AnyMessage memory evm2AnyMessage = _buildCCIPMessage(
            _receiver,
            _text,
            _token,
            _amount,
            address(0)
        );

        // 初始化一个路由器客户端实例，以与跨链路由器交互
        IRouterClient router = IRouterClient(this.getRouter());

        // 获取发送 CCIP 消息所需的费用
        uint256 fees = router.getFee(_destinationChainSelector, evm2AnyMessage);

        if (fees > address(this).balance)
            revert NotEnoughBalance(address(this).balance, fees);

        // 批准路由器代表合约花费给定数量的代币。它将花费给定数量的代币
        IERC20(_token).approve(address(router), _amount);

        // 通过路由器发送消息，并存储返回的消息 ID
        messageId = router.ccipSend{value: fees}(
            _destinationChainSelector,
            evm2AnyMessage
        );

        // 发出一个事件，其中包含消息详细信息
        emit MessageSent(
            messageId,
            _destinationChainSelector,
            _receiver,
            _text,
            _token,
            _amount,
            address(0),
            fees
        );

        // 返回消息 ID
        return messageId;
    }
    
    /**
     * @notice 返回最后接收到的CCIP消息的详细信息。
     * @dev 此函数检索最后接收到的CCIP消息的ID、文本、代币地址和代币数量。
     * @return messageId 最后接收到的CCIP消息的ID。
     * @return text 最后接收到的CCIP消息的文本。
     * @return tokenAddress 最后接收到的CCIP消息中的代币地址。
     * @return tokenAmount 最后接收到的CCIP消息中的代币数量。
     */
    function getLastReceivedMessageDetails()
        public
        view
        returns (
            bytes32 messageId,
            string memory text,
            address tokenAddress,
            uint256 tokenAmount
        )
    {
        return (
            s_lastReceivedMessageId,
            s_lastReceivedText,
            s_lastReceivedTokenAddress,
            s_lastReceivedTokenAmount
        );
    }

    /**
     * @notice 检索失败消息的分页列表。
     * @dev 此功能返回由 `offset` 和 `limit` 参数定义的失败消息的子集。它确保分页参数在可用数据集的范围内。
     * @param offset 要返回的第一个失败消息的索引，通过从数据集的开头跳过指定数量的消息来实现分页。
     * @param limit 要返回的失败消息的最大数量，限制返回数组的大小。
     * @return failedMessages `FailedMessage` 结构的数组，每个结构包含一个 `messageId` 和一个 `errorCode`（解决或失败），表示请求的失败消息的子集。返回数组的长度由 `limit` 和失败消息的总数决定。
     */
    function getFailedMessages(
        uint256 offset,
        uint256 limit
    ) external view returns (FailedMessage[] memory) {
        uint256 length = s_failedMessages.length();

        // 计算实际返回的项目数量（不能超过总长度或请求的限制）
        uint256 returnLength = (offset + limit > length)
            ? length - offset
            : limit;
        FailedMessage[] memory failedMessages = new FailedMessage[](
            returnLength
        );

        // 调整循环以尊重分页（从 offset 开始，结束于 offset + limit 或总长度）
        for (uint256 i = 0; i < returnLength; i++) {
            (bytes32 messageId, uint256 errorCode) = s_failedMessages.at(
                offset + i
            );
            failedMessages[i] = FailedMessage(messageId, ErrorCode(errorCode));
        }
        return failedMessages;
    }

    /// @notice CCIP 路由器调用的入口点。此功能不应撤销，所有错误应在合约内部处理。
    /// @param any2EvmMessage 要处理的消息。
    /// @dev 非常重要的是确保只有路由器调用此功能。
    function ccipReceive(
        Client.Any2EVMMessage calldata any2EvmMessage
    )
        external
        override
        onlyRouter
        onlyAllowlisted(
            any2EvmMessage.sourceChainSelector,
            abi.decode(any2EvmMessage.sender, (address))
        ) // 确保源链和发件人被列入允许名单
    {
        /* solhint-disable no-empty-blocks */
        try this.processMessage(any2EvmMessage) {
            // 本示例中故意为空；如果 processMessage 成功，则无需采取任何行动
        } catch (bytes memory err) {
            // 可以根据捕获的错误设置不同的错误代码。每个都可以有不同的处理方式。
            s_failedMessages.set(
                any2EvmMessage.messageId,
                uint256(ErrorCode.FAILED)
            );
            s_messageContents[any2EvmMessage.messageId] = any2EvmMessage;
            // 不要撤销，以免 CCIP 撤销。改为发出事件。
            // 可以稍后重试该消息，而无需手动执行 CCIP。
            emit MessageFailed(any2EvmMessage.messageId, err);
            return;
        }
    }

    /// @notice 为此合约处理传入消息的入口点。
    /// @param any2EvmMessage 接收到的 CCIP 消息。
    /// @dev 将指定数量的代币转移到此合约的所有者。此功能必须是外部的，因为利用 Solidity 的 try/catch 错误处理机制。
    /// 它使用 `onlySelf`：只能由合约调用。
    function processMessage(
        Client.Any2EVMMessage calldata any2EvmMessage
    )
        external
        onlySelf
        onlyAllowlisted(
            any2EvmMessage.sourceChainSelector,
            abi.decode(any2EvmMessage.sender, (address))
        ) // 确保源链和发件人被列入允许名单
    {
        // 为测试目的模拟撤销
        if (s_simRevert) revert ErrorCase();

        _ccipReceive(any2EvmMessage); // 处理消息 - 可能会撤销
    }

    /// @notice 允许所有者重试失败的消息，以解锁相关的代币。
    /// @param messageId 失败消息的唯一标识符。
    /// @param tokenReceiver 将代币发送到的地址。
    /// @dev 该功能只能由合约所有者调用。它更改消息的状态从 'failed(失败)' 到 'resolved(已解决)'，以防止重复条目和多次重试相同的消息
    function retryFailedMessage(
        bytes32 messageId,
        address tokenReceiver
    ) external onlyOwner {
        // 检查消息是否失败；如果没有，则撤销交易。
        if (s_failedMessages.get(messageId) != uint256(ErrorCode.FAILED))
            revert MessageNotFailed(messageId);

        // 将错误代码设置为 RESOLVED，以禁止重新进入和多次重试同一失败消息。
        s_failedMessages.set(messageId, uint256(ErrorCode.RESOLVED));

        // 检索失败消息的内容。
        Client.Any2EVMMessage memory message = s_messageContents[messageId];

        // 本示例期望一次发送一枚代币，但你可以处理多个代币。
        // 将关联的代币转移到指定的接收者作为紧急逃生方式。
        IERC20(message.destTokenAmounts[0].token).safeTransfer(
            tokenReceiver,
            message.destTokenAmounts[0].amount
        );

        // 发出事件，表明消息已被恢复。
        emit MessageRecovered(messageId);
    }

    /// @notice 允许所有者切换模拟撤销的测试。
    /// @param simRevert 如果为 `true`，模拟撤销条件；如果为 `false`，禁用模拟。
    /// @dev 该功能只能由合约所有者调用。
    function setSimRevert(bool simRevert) external onlyOwner {
        s_simRevert = simRevert;
    }

    function _ccipReceive(
        Client.Any2EVMMessage memory any2EvmMessage
    ) internal override {
        s_lastReceivedMessageId = any2EvmMessage.messageId; // 获取消息ID
        s_lastReceivedText = abi.decode(any2EvmMessage.data, (string)); // 解码发送的文本
        // 预期一次转移一个代币，但可以转移多个代币。
        s_lastReceivedTokenAddress = any2EvmMessage.destTokenAmounts[0].token;
        s_lastReceivedTokenAmount = any2EvmMessage.destTokenAmounts[0].amount;
        emit MessageReceived(
            any2EvmMessage.messageId,
            any2EvmMessage.sourceChainSelector, // 获取源链标识符（即选择器）
            abi.decode(any2EvmMessage.sender, (address)), // 解码发送者地址，
            abi.decode(any2EvmMessage.data, (string)),
            any2EvmMessage.destTokenAmounts[0].token,
            any2EvmMessage.destTokenAmounts[0].amount
        );
    }
    
    /// @notice 构建CCIP消息。
    /// @dev 此函数将创建一个EVM2AnyMessage结构体，包含所有必要的信息以实现可编程的代币转移。
    /// @param _receiver 接收者的地址。
    /// @param _text 要发送的字符串数据。
    /// @param _token 要转移的代币。
    /// @param _amount 要转移的代币数量。
    /// @param _feeTokenAddress 用于费用的代币地址。将address(0)设置为使用原生gas。
    /// @return Client.EVM2AnyMessage 返回一个EVM2AnyMessage结构体，其中包含发送CCIP消息所需的信息。
    function _buildCCIPMessage(
        address _receiver,
        string calldata _text,
        address _token,
        uint256 _amount,
        address _feeTokenAddress
    ) private pure returns (Client.EVM2AnyMessage memory) {
        // 设置代币数量
        Client.EVMTokenAmount[]
            memory tokenAmounts = new Client.EVMTokenAmount[](1);
        Client.EVMTokenAmount memory tokenAmount = Client.EVMTokenAmount({
            token: _token,
            amount: _amount
        });
        tokenAmounts[0] = tokenAmount;
        // 在内存中创建一个 EVM2AnyMessage 结构，包含发送跨链消息所需的信息
        Client.EVM2AnyMessage memory evm2AnyMessage = Client.EVM2AnyMessage({
            receiver: abi.encode(_receiver), // ABI 编码的接收地址
            data: abi.encode(_text), // ABI 编码的字符串
            tokenAmounts: tokenAmounts, // 被转移的代币数量和类型
            extraArgs: Client._argsToBytes(
                // 额外参数，设置 gas 限制
                Client.EVMExtraArgsV1({gasLimit: 400_000})
            ),
            // 设置 feeToken 为 feeTokenAddress，表示将使用特定资产支付费用
            feeToken: _feeTokenAddress
        });
        return evm2AnyMessage;
    }

    /// @notice 该合约接收以太的默认函数。
    /// @dev 该函数没有函数体，使其成为接收以太的默认函数。
    /// 当向合约发送以太时而没有任何数据时，会自动调用此函数。
    receive() external payable {}

    /// @notice 允许合约所有者从合约中提取全部以太余额。
    /// @dev 如果没有资金可提取或转账失败，该函数将撤销。
    /// 只能由合约所有者调用。
    /// @param _beneficiary 将以太发送到的地址。
    function withdraw(address _beneficiary) public onlyOwner {
        // 检索此合约的余额
        uint256 amount = address(this).balance;

        // 如果没有可提取的内容，撤销
        if (amount == 0) revert NothingToWithdraw();

        // 尝试发送资金，捕获成功状态并丢弃任何返回数据
        (bool sent, ) = _beneficiary.call{value: amount}("");

        // 如果发送失败，带有尝试转账信息的撤销
        if (!sent) revert FailedToWithdrawEth(msg.sender, _beneficiary, amount);
    }

    /// @notice 允许合约所有者提取特定ERC20代币的所有代币。
    /// @dev 如果没有代币可提取，则此函数将回滚并显示'NothingToWithdraw'错误。
    /// @param _beneficiary 应将代币发送到的地址。
    /// @param _token 要提取的ERC20代币的合约地址。
    function withdrawToken(
        address _beneficiary,
        address _token
    ) public onlyOwner {
        // 检索此合约的代币余额
        uint256 amount = IERC20(_token).balanceOf(address(this));

        // 如果没有可提取的代币，撤销
        if (amount == 0) revert NothingToWithdraw();

        // 安全地将代币转移到指定受益人
        IERC20(_token).safeTransfer(_beneficiary, amount);
    }
}

部署您的合约

要使用此合约：

1. 在 Remix 中打开合约。

2. 编译您的合约。

3. 部署并在 Avalanche Fuji 上资助您的发送者合约，并启用向以太坊 Sepolia 发送消息的功能：

   1. 打开 MetaMask 并选择网络 Avalanche Fuji。

   2. 在 Remix IDE 中，点击 Deploy & Run Transactions，从环境列表中选择 Injected Provider - MetaMask。然后 Remix 将与您的 MetaMask 钱包交互，以与 Avalanche Fuji 通信。

   3. 填写您的区块链路由器和 LINK 合约地址。可以在 支持的网络页面 上找到路由器地址，在 LINK 代币合约页面 上找到 LINK 合约地址。对于 Avalanche Fuji，路由器地址是 0xF694E193200268f9a4868e4Aa017A0118C9a8177，LINK 合约地址是 0x0b9d5D9136855f6FEc3c0993feE6E9CE8a297846。

   4. 点击 transact 按钮。确认交易后，合约地址将出现在 已部署合约 列表中。记下您的合约地址。

   5. 打开 MetaMask 并用 CCIP-BnM 代币为您的合约注资。您可以向您的合约转账 0.002 CCIP-BnM。

   6. 启用您的合约以向 以太坊 Sepolia 发送 CCIP 消息：

      1. 在 Remix IDE 中，转到 Deploy & Run Transactions，在您部署在 Avalanche Fuji 上的智能合约的函数列表中。

      2. 调用 allowlistDestinationChain，传入 16015286601757825753 作为目标链选择器，以及 true 设置为允许。每个链选择器都可以在 支持的网络页面 上找到。

4. 在 以太坊 Sepolia 上部署您的接收者合约，并启用从您的发送者合约接收消息：

   1. 打开 MetaMask 并选择网络 以太坊 Sepolia。

   2. 在 Remix IDE 中，转到 Deploy & Run Transactions，确保环境仍然是 Injected Provider - MetaMask。

   3. 填写您的区块链路由器和 LINK 合约地址。可以在 支持的网络页面 上找到路由器地址，在 LINK 代币合约页面 上找到 LINK 合约地址。对于以太坊 Sepolia，路由器地址是 0x0BF3dE8c5D3e8A2B34D2BEeB17ABfCeBaf363A59，LINK 合约地址是 0x779877A7B0D9E8603169DdbD7836e478b4624789。

   4. 点击 transact 按钮。确认交易后，合约地址将出现在 已部署合约列表 中。记下您的合约地址。

   5. 启用您的合约以接收来自 Avalanche Fuji 的 CCIP 消息：:

      1. 在 Remix IDE 中，转到 Deploy & Run Transactions，打开您部署在 以太坊 Sepolia 上的智能合约的函数列表。

      2. 调用 allowlistSourceChain，传入 14767482510784806043 作为源链选择器，以及 true 设置为允许。每个链选择器都可以在 支持的网络页面 上找到。

   6. 启用您的合约以接收来自您部署在 Avalanche Fuji 上的合约的 CCIP 消息：

      1. 在 Remix IDE 中，转到 Deploy & Run Transactions，打开您部署在 以太坊 Sepolia 上的智能合约的函数列表。

      2. 调用 allowlistSender，传入您部署在 Avalanche Fuji 上的合约地址，并设置为 true。

   7. 调用 setSimRevert 函数，传入 true 作为参数，然后等待交易确认。将 s_simRevert 设置为 true 会在处理接收到的消息时模拟失败。更多详情请参阅解释部分。

此时，您在 Avalanche Fuji 上有一个发送者合约，在 以太坊 Sepolia 上有一个接收者合约。作为安全措施，您已启用发送者合约向 以太坊 Sepolia 发送 CCIP 消息，以及接收者合约接收来自 Avalanche Fuji 上发送者的 CCIP 消息。接收者合约无法处理消息，因此，它不会抛出异常，而是会锁定接收到的代币，使所有者能够恢复它们。

注意：另一项安全措施强制只有路由器可以调用 _ccipReceive 函数。更多详情请参阅解释部分。

恢复被锁定的代币

转移 0.001 CCIP-BnM 和一些文本。使用 CCIP 的 CCIP 费用将以 LINK 支付。

1. 打开 MetaMask 并连接到 Avalanche Fuji。用 LINK 代币为您的合约注资。您可以向您的合约转账 0.5 LINK。在此示例中，LINK 用于支付 CCIP 费用。

2. 从 Avalanche Fuji 发送带有代币的字符串数据：:

   1. 打开 MetaMask 并选择网络 Avalanche Fuji.

   2. 在 Remix IDE 中，转到 Deploy & Run Transactions，打开您部署在 Avalanche Fuji 上的智能合约的函数列表。

   3. 填写 sendMessagePayLINK 函数的参数:
   4. 点击 transact 并在 MetaMask 上确认交易。

   5. 交易成功后，请记录交易哈希。以下是在Avalanche Fuji上进行交易的一个示例。

注意

在gas价格飙升期间，您的交易可能会失败，需要超过 0.5 LINK 的gas费才能继续。如果您的交易失败，请向您的合约中注入更多的 LINK 代币，并尝试重新提交交易。

1. 打开CCIP浏览器，通过交易哈希搜索你的跨链交易。

1. CCIP交易在状态被标记为“Success”时完成。在这个例子中，CCIP消息ID是0x120367995ef71f83d64a05bd7793862afda9d04049da4cb32851934490d03ae4。