Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Doc updates. #271

Merged
merged 4 commits into from
Oct 30, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,23 @@
<div style="text-align:center" align="center">
<a href="https://chain.link" target="_blank">
<img src="https://raw.githubusercontent.com/smartcontractkit/chainlink/develop/docs/logo-chainlink-blue.svg" width="225" alt="Chainlink logo">
</a>

[![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)
</div>

# 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

Expand Down Expand Up @@ -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
77 changes: 75 additions & 2 deletions docs/ccip_protocol.md
Original file line number Diff line number Diff line change
@@ -1,3 +1,76 @@
# 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 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
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 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

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) 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
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](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).

### 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 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
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
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
[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
Empty file removed docs/execution_order.md
Empty file.
Empty file removed docs/token_data.md
Empty file.
Loading