From 718a2a1e426d1b1bfe27c96d87d4daa00f27f4b7 Mon Sep 17 00:00:00 2001 From: Will Winder Date: Fri, 25 Oct 2024 09:51:06 -0400 Subject: [PATCH 1/3] Doc updates. --- README.md | 17 +++++++-- docs/ccip_protocol.md | 76 +++++++++++++++++++++++++++++++++++++++-- docs/execution_order.md | 0 docs/token_data.md | 0 4 files changed, 89 insertions(+), 4 deletions(-) delete mode 100644 docs/execution_order.md delete mode 100644 docs/token_data.md diff --git a/README.md b/README.md index e202ea482..ed5732f7a 100644 --- a/README.md +++ b/README.md @@ -1,12 +1,23 @@ +
+ + Chainlink logo + + +[![License](https://img.shields.io/static/v1?label=license&message=BUSL%201.1&color=green)](https://github.com/smartcontractkit/chainlink-ccip/blob/master/LICENSE) +[![Code Documentation](https://img.shields.io/static/v1?label=code-docs&message=latest&color=blue)](docs/ccip_protocol.md) +[![API Documentation](https://img.shields.io/static/v1?label=api-docs&message=latest&color=blue)](https://docs.chain.link/ccip) +
+ # chainlink-ccip -This is the repo that implements the OCR3 CCIP plugins. This includes the commit and execution plugins. +This repo contains [OCR3 plugins][ocr3] for CCIP. See the [documentation](docs/ccip_protocol.md) for more. ## Getting Started ### Go Version -This repo uses Go 1.22. You can install Go from their [installation page](https://go.dev/doc/install). +The version of go is specified in the project's [go.mod](go.mod) file. +You can install Go from their [installation page](https://go.dev/doc/install). ### Running the Linter @@ -50,3 +61,5 @@ the `ccip-develop` branch of chainlink-ccip. You can do this by: 5. Go back to your chainlink-ccip PR and re-run the integration test workflow. 6. Once the integration test passes, merge your chainlink-ccip PR into `ccip-develop`, however do not delete the branch on the remote. 7. Create a new PR in ccip that points to the newly merged commit in the `ccip-develop` tree and merge that. + +[ocr3]: https://github.com/smartcontractkit/libocr/blob/master/offchainreporting2plus/ocr3types/plugin.go#L108 diff --git a/docs/ccip_protocol.md b/docs/ccip_protocol.md index 3c20dc8d6..3a58efd73 100644 --- a/docs/ccip_protocol.md +++ b/docs/ccip_protocol.md @@ -1,3 +1,75 @@ -# CCIP Protocol +# Cross-Chain Interoperability Protocol (CCIP) -TODO: information about the CCIP protocol with links to feature details. +A protocol designed to transfer data and value across blockchains in a trust +minimized fashion. This is done using a combination of checks on the source +chain(s), destination chains, and offchain security. This document describes +the most important security considerations along with the messaging protocol +at the data and event processing level. As this repository is for the off-chain +portion of CCIP, we'll focus on off-chain components and the on-chain +integration points. + +The user interface is not described here. It is largely unchanged compared to +the earlier architecture and the [public docoumentation][public-docs] provides +an excellent guide for how to use CCIP. + +## OffChain Reporting (OCR) + +The [libOCR][ocr-repo] framework provides security to the system with a +Distributed Oracle Network (DON) utilizing a [byzantine fault tolerant][bft] +protocol. Security is assumed given the [Reporting Plugin][ocr-interface] built +within this framework ensures observation thresholds on the data used by the +system. See the [Consensus and Sub-consensus](consensus.md) page for more +information about how the CCIP plugins use and extend this the typical OCR +framework. + +## Plugins + +The protocol is implemented in two phases, each with a corresponding libOCR +plugin: commit and execute. + +### Commit + +In the commit phase, user created messages are collected from every source +chain, a merkle root is generated for messages from each source, and the roots +are put into a [Commit Report][commit-report-src]. The report is sent to the +on-chain code for final processing where a commit report log is written to the +blockchain. + +An independant Risk Management Network (RMN) is used as a second layer of +security to ensure the merkle roots are valid. RMN can be thought of as a +validation network with veto power. In the previous version of CCIP RMN was +an independent component which provided a blessing or curse after the commit +report was written to the network. With this architecture the plugin queries +the RMN network directly so that the RMN signatures can be included in the +initial report. + +The report includes additional gas and token price data required by the billing +algorithm. Strictly speaking, it is not part of the protocol and could be +implemented separately. For convenience it is included in the commit plugin. + +More detail about the implementation can be found in the [README](commit#readme). + +### Execute + +In the execute phase, the plugin searches for commit reports with pending +executions. All messages for these commit reports are gathered and a +[special merkle proof][merklemulti] is computed for all messsages ready for +execution. These proofs are put into the [Execute Plugin Report][exec-report-src]. + +Due to the [Role DON](consensus.md#role-don) architecture, this +process has to be done across several rounds of consensus: + +1. Destination readers look for commit reports. +2. Based on the commit reports, source readers fetch the messages. +3. Based on the messages, the destination reader determines execution order. + +The commit report is sent to the on-chain code for final processing. This +includes all token transfers, data handling and user contract interaction. + +[public-docs]: https://docs.chain.link/ccip +[ocr-repo]: https://github.com/smartcontractkit/libocr/tree/master +[bft]: https://en.wikipedia.org/wiki/Byzantine_fault +[ocr-interface]: https://github.com/smartcontractkit/libocr/blob/adbe57025f12b9958907bb203acba14360bf8ed2/offchainreporting2plus/ocr3types/plugin.go#L165 +[commit-report-src]: https://github.com/smartcontractkit/chainlink-ccip/blob/0f6dce5d1fdb67b3127332ac729191f2c1c790ff/pkg/types/ccipocr3/plugin_commit_types.go#L19 +[merklemulti]: https://github.com/smartcontractkit/chainlink-common/tree/main/pkg/merklemulti +[exec-report-src]: https://github.com/smartcontractkit/chainlink-common/tree/main/pkg/merklemulti diff --git a/docs/execution_order.md b/docs/execution_order.md deleted file mode 100644 index e69de29bb..000000000 diff --git a/docs/token_data.md b/docs/token_data.md deleted file mode 100644 index e69de29bb..000000000 From 4c6cc2dc8c2511e1449989843640a253384315a4 Mon Sep 17 00:00:00 2001 From: Will Winder Date: Fri, 25 Oct 2024 10:20:02 -0400 Subject: [PATCH 2/3] Minor cleanup --- docs/ccip_protocol.md | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/ccip_protocol.md b/docs/ccip_protocol.md index 3a58efd73..0f5ed4f58 100644 --- a/docs/ccip_protocol.md +++ b/docs/ccip_protocol.md @@ -1,25 +1,25 @@ # Cross-Chain Interoperability Protocol (CCIP) -A protocol designed to transfer data and value across blockchains in a trust -minimized fashion. This is done using a combination of checks on the source -chain(s), destination chains, and offchain security. This document describes -the most important security considerations along with the messaging protocol -at the data and event processing level. As this repository is for the off-chain +A protocol designed to transfer data and value across blockchains in a +trust-minimized manner. This is done using a combination of checks on the source +chain(s), destination chains, and off-chain security. This document outlines +key security considerations and details the messaging protocol at the data and +event processing levels. As this repository is for the off-chain portion of CCIP, we'll focus on off-chain components and the on-chain integration points. The user interface is not described here. It is largely unchanged compared to the earlier architecture and the [public docoumentation][public-docs] provides -an excellent guide for how to use CCIP. +a comprehensive guide to using CCIP. ## OffChain Reporting (OCR) The [libOCR][ocr-repo] framework provides security to the system with a Distributed Oracle Network (DON) utilizing a [byzantine fault tolerant][bft] -protocol. Security is assumed given the [Reporting Plugin][ocr-interface] built -within this framework ensures observation thresholds on the data used by the -system. See the [Consensus and Sub-consensus](consensus.md) page for more -information about how the CCIP plugins use and extend this the typical OCR +protocol. Security is enhanced by the [Reporting Plugin][ocr-interface] when +the plugins ensure observation thresholds on data used by the system. +See the [Consensus and Sub-consensus](consensus.md) page for more +information about how the CCIP plugins use and extend the typical OCR framework. ## Plugins @@ -35,8 +35,8 @@ are put into a [Commit Report][commit-report-src]. The report is sent to the on-chain code for final processing where a commit report log is written to the blockchain. -An independant Risk Management Network (RMN) is used as a second layer of -security to ensure the merkle roots are valid. RMN can be thought of as a +An independant Risk Management Network (RMN) serves as an additional security +layer to validate merkle roots. RMN can be thought of as a validation network with veto power. In the previous version of CCIP RMN was an independent component which provided a blessing or curse after the commit report was written to the network. With this architecture the plugin queries @@ -52,8 +52,8 @@ More detail about the implementation can be found in the [README](commit#readme) ### Execute In the execute phase, the plugin searches for commit reports with pending -executions. All messages for these commit reports are gathered and a -[special merkle proof][merklemulti] is computed for all messsages ready for +executions. All messages for these commit reports are gathered, and a +[special merkle proof][merklemulti] is computed for all messages ready for execution. These proofs are put into the [Execute Plugin Report][exec-report-src]. Due to the [Role DON](consensus.md#role-don) architecture, this @@ -64,7 +64,7 @@ process has to be done across several rounds of consensus: 3. Based on the messages, the destination reader determines execution order. The commit report is sent to the on-chain code for final processing. This -includes all token transfers, data handling and user contract interaction. +step includes token transfers, data handling and user contract interaction. [public-docs]: https://docs.chain.link/ccip [ocr-repo]: https://github.com/smartcontractkit/libocr/tree/master From b2925bdccbbc92385edef991dedf87db74a0ab7c Mon Sep 17 00:00:00 2001 From: Will Winder Date: Fri, 25 Oct 2024 10:25:30 -0400 Subject: [PATCH 3/3] cross link the billing page. --- docs/ccip_protocol.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/ccip_protocol.md b/docs/ccip_protocol.md index 0f5ed4f58..62f6d438d 100644 --- a/docs/ccip_protocol.md +++ b/docs/ccip_protocol.md @@ -43,9 +43,10 @@ report was written to the network. With this architecture the plugin queries the RMN network directly so that the RMN signatures can be included in the initial report. -The report includes additional gas and token price data required by the billing -algorithm. Strictly speaking, it is not part of the protocol and could be -implemented separately. For convenience it is included in the commit plugin. +The report includes additional gas and token price data required by the +[billing algorithm](billing.md). Strictly speaking, it is not part of the +protocol and could be implemented separately. For convenience it is included in +the commit plugin. More detail about the implementation can be found in the [README](commit#readme).