• Stars
    star
    119
  • Rank 297,871 (Top 6 %)
  • Language
    TypeScript
  • License
    Other
  • Created almost 4 years ago
  • Updated 24 days ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

🔮 OPTimistic Interchain Communication

Optics

OPTimistic Interchain Communication

Overview

Optics is a cross-chain communication system. It handles passing raw buffers between blockchains cheaply, and with minimal fuss. Like IBC and other cross-chain communication systems, Optics creates channels between chains, and then passes its messages over the channel. Once a channel is established, any application on the chain can use it to send messages to any other chain.

Compared to IBC and PoS light client based cross-chain communication, Optics has weaker security guarantees, and a longer latency period. However, Optics may be implemented on any smart contract chain, with no bespoke light client engineering. Because it does not run a light client, Optics does not spend extra gas verifying remote chain block headers.

In other words, Optics is designed to prioritize:

  • Cost: No header verification or state management.
  • Speed of implementation: Requires only simple smart contracts, no complex cryptography.
  • Ease of use: Simple interface for maintaining xApp connections.

You can read more about Optics' architecture at Celo's main documentation site or within the docs folder of this repository.

Integrating with Optics

Optics establishes communication channels with other chains, but it's up to xApp (pronounced "zap", and short for "cross-chain applications") developers to use those. This repo provides a standard pattern for integrating Optics channels, and ensuring that communication is safe and secure.

Integrations require a few key components:

  • A Home and any number of Replica contracts deployed on the chain already. These contracts manage Optics communication channels. and will be used by the xApp to send and receive messages.

  • A XAppConnectionManager (in solidity/optics-core/contracts). This contract connects the xApp to Optics by allowing the xApp admin to enroll new Home and Replica contracts. Enrolling and unenrolling channels is the primary way to ensure that your xApp handles messages correctly. xApps may deploy their own connection manager, or share one with other xApps.

  • A Message library. Optics sends raw byte arrays between chains. The xApp must define a message specification that can be serialized for sending, and deserialized for handling on the remote chain

  • A Router contract. The router translates between the Optics cross-chain message format, and the local chain's call contract. It also implements the business logic of the xApp. It exposes the user-facing interface, handles messages coming in from other chains, and dispatches messages being sent to other chains.

Solidity developers interested in implementing their own Message library and Router contract should check out the optics-xapps package. It contains several example xApps.

You can find current testnet deploy configurations in the rust/config/ directory. These deployments happen frequently and are unstable. Please feel free to try out integrations using the deployed contracts in the LATEST config.

It is Strongly Recommended that xApp admins run a watcher daemon to maintain their XAppConnectionManager and guard from fraud. Please see the documentation in the rust/ directory and the Optics architecture documentation for more details.

Working on Optics

Commit signature verification

Commits (and tags) for this repo require signature verification. If you'd like to contribute to Optics, make sure that your commits are signed locally.

Pre-commit hooks

Set up your pre-commit hook:

echo "./pre-commit.sh" > .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Note: In the event you need to bypass the pre-commit hooks, pass the --no-verify flag to your git commit command

Solidity

  1. Install dependencies

    cd solidity/optics-core
    npm i
    cd ../optics-xapps
    npm i
  2. Setup your .env files

    cd typescript/optics-deploy
    touch .env && cat .env.example > .env
    cd ../../solidity/optics-core
    touch .env && cat .env.example > .env
    cd ../optics-xapps
    touch .env && cat .env.example > .env

    Then, add values to the keys in the newly created .env files.

  3. Install jq

    brew install jq

      OR  

    sudo apt-get install jq
  4. Install solhint

    npm install -g solhint
    // to check it is installed:
    solhint --version

Rust

  • install rustup
  • see rust/README.md

Building Agent Images

There exists a docker build for the agent binaries. These docker images are used for deploying the agents in a production environment.

cd rust
./build.sh <image_tag>
./release.sh <image_tag>

What is Optics?

We present Optics — a system for sending messages between consensus systems without paying header validation costs by creating the illusion of cross-chain communication. Similar to an atomic swap, Optics uses non-global protocol validation to simulate cross-chain communication. Optics can carry arbitrary messages (raw byte vectors), uses a single-producer multi-consumer model, and has protocol overhead sublinear in the number of messages being sent.

Key Points

System sketch:

  1. A "home" chain commits messages in a merkle tree
  2. A bonded "updater" attests to the commitment
  3. The home chain ensures the attestation is accurate, and slashes if not
  4. Attested updates are replayed on any number of "replica" chains, after a time delay

As a result, one of the following is always true:

  1. All replicas have a valid commitment to messages from the home chain
  2. Failure was published before processing, and the updater can be slashed on the home chain

This guarantee, although weaker than header-chain validation, is still likely acceptable for most applications.

Summary

Optics is a new strategy for simulating cross-chain communication without validating headers. The goal is to create a single short piece of state (a 32-byte hash) that can be updated regularly. This hash represents a merkle tree containing a set of cross-chain messages being sent by a single chain (the "home" chain for the Optics system). Contracts on the home chain can submit messages, which are put into a merkle tree (the "message tree"). The message tree's root may be transferred to any number of "replica" chains.

Rather than proving validity of the commitment, we put a delay on message receipt, and ensure that failures are publicly visible. This ensures that participants in the protocol have a chance to react to failures before the failure can harm them. Which is to say, rather than preventing the inclusion of bad messages, Optics guarantees that message recipients are aware of the inclusion, and have a chance to refuse to process them.

To produce this effect, the home chain designates a single "updater." The updater places a bond ensuring her good behavior. She is responsible for producing signed attestations of the new message tree root. The home chain accepts and validates these attestations. It ensures that they extend a previous attestation, and contain a valid new root of the message set. These attestations are then sent to each replica.

The replica accepts an update attestation signed by the updater, and puts it in a pending state. After a timeout, it accepts the update from that attestation and stores a new local root. Because this root contains a commitment of all messages sent by the home chain, these messages can be proven (using the replica's root) and then dispatched to contracts on the replica chain.

The timeout on new updates to the replica serves two purposes:

  1. It ensures that any misbehavior by the updater is published in advance of message processing. This guarantees that data necessary for home chain slashing is available for all faults.
  2. It gives message recipients a chance to opt-out of message processing for the update. If an incorrect update is published, recipients always have the information necessary to take defensive measures before any messages can be processed.

Deploy Procedure

The contract addresses of each deploy can be found in rust/config. The latest deploy will be at rust/config/[latest timestamp] with bridge contracts within that same folder under /bridge/[latest timestamp].

The agents are setup to point at 2 environments at a time: deployment and staging.

When agents are deployed to point at a new environment, they cease to point at the old ones. We do not continue to operate off-chain agents on old contract deploys. Contracts not supported by the agents will cease to function (i.e. messages will not be relayed between chains).

Off-chain agents are not automatically re-deployed when new contract deploys are merged. Auto-redeploys will be implemented at some future date.

The Optics team will maintain a document here that will specify the contracts supported by the rust agents.

More Repositories

1

celo-monorepo

Official repository for core projects comprising the Celo platform
Solidity
696
star
2

celo-blockchain

Official repository for the golang Celo Blockchain
Go
502
star
3

gitcoin

A place to track gitcoin related issues, bounties and quests.
159
star
4

celo-composer

celo-composer is a starter project with all code needed to build, deploy, and upgrade a dapps on Celo.
TypeScript
121
star
5

celo-bls-snark-rs

Implements SNARK-friendly BLS signatures
Rust
84
star
6

celo-proposals

Celo Improvement Proposals
61
star
7

celo-threshold-bls-rs

Threshold BLS Signatures and DKG
Rust
59
star
8

react-celo

Connect your react dApp to Celo
TypeScript
59
star
9

docs

TypeScript
58
star
10

governance

Governance Repository for Celo
JavaScript
46
star
11

make-crypto-mobile-hackathon

Build the next generation of Defi accessibility with Celo mobile-first blockchain! Create new solutions on top of the Celo Ledger - DeFi, NFTs, Smart Contracts, Developer tooling and more.
37
star
12

shrubs

JavaScript
27
star
13

build-with-celo-hackathon

21
star
14

rosetta

go server implementation of the Rosetta API spec
Go
20
star
15

savings-circle-demo

TypeScript
17
star
16

SocialConnect

Protocol mapping social identifiers to blockchain addresses
17
star
17

website

OLD Repo for OLD Celo.org Website
TypeScript
15
star
18

celo-bls-go

Go module for https://github.com/celo-org/bls-zexe/
Go
14
star
19

celo-oracle

TypeScript
14
star
20

faucet

Alfajores Faucet
TypeScript
14
star
21

plumo-prover

Prover for the Plumo light client system https://docs.zkproof.org/pages/standards/accepted-workshop3/proposal-plumo_celolightclient.pdf
Rust
14
star
22

no-yolo-signatures

TypeScript
13
star
23

rainbowkit-celo

TypeScript
12
star
24

bls-embedded

Rust
11
star
25

snark-setup-operator

Rust
11
star
26

staked-celo-web-app

TypeScript
10
star
27

bls12377js

TypeScript implementation of BLS12-377-based Proofs of Possession.
TypeScript
10
star
28

developer-tooling

🛠️ SDKs and CLI for interacting with Celo
TypeScript
10
star
29

celo-mondo

Staking and Governance Tools for Celo
TypeScript
9
star
30

staked-celo

TypeScript
8
star
31

DevRel

All things DevRel!
JavaScript
7
star
32

blind-threshold-bls-wasm

WASM Bindings for blind bls threshold signature generation and verification
JavaScript
7
star
33

celo-camp

7
star
34

dappkit-web-starter

TypeScript
7
star
35

stackshift

The Celo Stackshift program
7
star
36

social-connect

Protocol mapping social identifiers to blockchain addresses
TypeScript
7
star
37

hello-celo-contractkit

An introduction to using Celo ContractKit
JavaScript
6
star
38

kliento

Client library for celo (golang)
Go
6
star
39

snark-setup-coordinator

TypeScript
6
star
40

celostats-frontend

TypeScript
6
star
41

reserve-site

Celo Reserve Website
TypeScript
5
star
42

celostats-server

Celo network status dashboard
TypeScript
5
star
43

compliance

TypeScript
5
star
44

celo-ledger-web-app

JavaScript
5
star
45

mento2-model

Jupyter Notebook
5
star
46

awesome-celo

A curated list of awesome Celo resources, libraries, tools and more
5
star
47

eksportisto

Metric Exporter for celo-node
Go
4
star
48

interview_challenge

HTML
4
star
49

komenci

Komenci (Start in esperanto) is the onboarding service that provides Valora with fee-less mobile attestations.
TypeScript
4
star
50

celo-forkmon

Fork Monitor for POA/POS networks, customized for Celo
HTML
4
star
51

plumo-ceremony-attestations

Python
4
star
52

nexus

MiniPay project for external partners
TypeScript
4
star
53

charts

cLabs managed applications for Kubernetes using Helm
Smarty
4
star
54

qa-interview-assignment

Takehome assignment for the cLabs QA Engineer interview process
TypeScript
4
star
55

payments

TypeScript
4
star
56

celo-lms

Celo LMS is a learning management system that allows users to create and manage courses using Markdown.
TypeScript
3
star
57

celo-exchange-bot

TypeScript
3
star
58

OpenSSL-headers

C
3
star
59

dappkit-base

Expo DAppKit Base
JavaScript
3
star
60

celo-token-list

Celo's default token list
TypeScript
3
star
61

typechain-target-web3-v1-celo

TypeScript
3
star
62

geth_exporter

Go
3
star
63

minipay-minidapps

MiniDApps for MiniPay
TypeScript
3
star
64

celo-academy

Source code for Celo Academy.
TypeScript
3
star
65

plumo-verifier

Node.js module for verifying Plumo proofs and reading states based on it
JavaScript
3
star
66

celo-ledger-spender-app-w-docker-build-tools

The Celo spender ledger app used for signing transactions
Dockerfile
3
star
67

SocialConnect-Twitter

SocialConnect Twitter example
TypeScript
3
star
68

SocialConnect-Twitter-Server-Side

SocialConnect Twitter Server Side example
TypeScript
2
star
69

celo-bls-go-android

Go
2
star
70

celo-status

Dashboard to display blockchain node logs publicly
HTML
2
star
71

rosetta-cusd

Module implementation of Coinbase's Rosetta spec for cUSD, to be used in conjunction with the `rosetta` repository.
Go
2
star
72

celo-ledger-token-data

TypeScript
2
star
73

celo-bls-go-ios

Go
2
star
74

celo-bls-go-other

Go
2
star
75

minimal-docker

A minimal docker image with unix utilities
Dockerfile
2
star
76

gcloud-kubectl-docker

A simple docker image containing gcloud and kubectl
Dockerfile
2
star
77

celo-bls-go-linux

Go
2
star
78

blind-threshold-bls-neon

Neon bindings to the Celo threshold BLS library
Rust
2
star
79

celocli

TypeScript
2
star
80

brand

Celo Brand Assets
2
star
81

hardfork-testing

Hardfork Testing Tools & Scripts
Solidity
2
star
82

celo-bls-go-macos

Go
2
star
83

cel2-ethereum-compatibility

🛠️ CEL2 Ethereum-compatibility evaluation
TypeScript
2
star
84

snark

Rust
2
star
85

stokado

Secure off-chain data storage
TypeScript
2
star
86

economics-scripts

TypeScript
2
star
87

celo-poprf-rs

Rust
2
star
88

simple-address-statistics

Basic transaction monitoring for supplied Celo addresses
TypeScript
2
star
89

celo-validator-signer-app

C
2
star
90

ethglobal-brussels

ETHGlobal Brussels
TypeScript
2
star
91

bls12377js-blind

TypeScript
2
star
92

celo-ccip-workshop

This is expample code for Celo Alfajores <> Ethereum Sepolia CCIP.
TypeScript
2
star
93

crypto-pm

1
star
94

terraform-azure

terraform configs for azure
1
star
95

minipay-template

TypeScript
1
star
96

sbi

simple build image: build docker containers, push to registry, interpolate and apply kubernetes manifests
Shell
1
star
97

release-celo-deployments-28

1
star
98

cooperate-demo

Cooperate Demo
TypeScript
1
star
99

health-checker-docker

https://github.com/gruntwork-io/health-checker in a Docker image
Dockerfile
1
star
100

celo-bls-go-windows

Go
1
star