hyperlane-monorepo/docs/xapps/developing.md

# Developing Cross-Chain Applications 

## Summary

Optics sends messages from one chain to another in the form of raw bytes. A cross-chain application that wishes to *use* Optics will need to define the rules for sending and receiving messages for its use case. 

Each cross-chain application must implement its own messaging protocol. By convention, we call the contracts that implement this protocol the application's **Router contracts.** These Router contracts must: 

- ***maintain a permissioned set*** of the contract(s) on remote chains from which it will accept messages via Optics — this could be a single owner of the application on one chain; it could be a registry of other applications implementing the same rules on various chains
- ***encode messages in a standardized format***, so they can be decoded by the Router contract on the destination chain
- ***handle messages*** from remote Router contracts
- ***dispatch messages*** to remote Router contracts

By implementing these pieces of functionality within a Router contract and deploying it across multiple chains, we create a working cross-chain application using a common language and set of rules. Applications of this kind may use Optics as the cross-chain courier for sending and receiving messages to each other. 

## Example Code 

This repository has several examples one can use to build understanding around Cross-Chain Applications. 

### xApp Template

[This is a template](https://github.com/celo-org/optics-monorepo/tree/main/solidity/optics-xapps/contracts/xapp-template) provided by the Optics team that shows the high-level components of an xApp, ready for one to fill in their own application logic and utilize an Optics channel for cross-chain communication. 

To implement a xApp, define the actions you would like to execute across chains.
For each type of action,
- in the [xApp Router](https://github.com/celo-org/optics-monorepo/blob/main/solidity/optics-xapps/contracts/xapp-template/RouterTemplate.sol) 
    - implement a function like doTypeA to initiate the action from one domain to another (add your own parameters and logic)
    - implement a corresponding _handle function to receive, parse, and execute this type of message on the remote domain
    - add logic to the handle function to route incoming messages to the appropriate _handle function
- in the [Message library](https://github.com/celo-org/optics-monorepo/blob/main/solidity/optics-xapps/contracts/xapp-template/MessageTemplate.sol),
    - implement functions to *format* the message to send to the other chain (encodes all necessary information for the action)
    - implement functions to *parse* the message once it is received on the other chain (decode all necessary information for the action)

### Ping Pong xApp 

[The PingPong xApp](https://github.com/celo-org/optics-monorepo/tree/main/solidity/optics-xapps/contracts/ping-pong) is capable of initiating PingPong "matches" between two chains. A match consists of "volleys" sent back-and-forth between the two chains via Optics.

The first volley in a match is always a Ping volley.
- When a Router receives a Ping volley, it returns a Pong.
- When a Router receives a Pong volley, it returns a Ping.

The Routers keep track of the number of volleys in a given match, and emit events for each Sent and Received volley so that spectators can watch.

### Token Bridge xApp 

See the full-length [Token Bridge Documentation](#TODO) for in-depth details on Token Bridge operation and construction. 

[Link to Contracts](https://github.com/celo-org/optics-monorepo/tree/main/solidity/optics-xapps/contracts/bridge)

### Cross-Chain Governance xApp

See the full-length [Optics Governance Documentation](#TODO) for in-depth details on Governance xApp operation and construction. 

[Link to Contracts](https://github.com/celo-org/optics-monorepo/tree/main/solidity/optics-core/contracts/governance)

## Useful Links 

- [xApp Developers Workshop @ EthCC 2021 by Anna Carroll](https://www.youtube.com/watch?v=E_zhTRsxWtw)

## Glossary of Terms

- **Local vs Remote**: in the context of discussing a particular contract, it is deployed on a particular chain. Contracts and assets on that chain are "local." Contracts and assets on another chain are "remote"
    - e.g. Uniswap is deployed on Ethereum. Ethereum is the local chain. Celo is a remote chain
    - e.g. there is a token deployed on Celo. There is a local `Home` contract (on Celo), and a local `Replica` contract (on Celo) receiving messages from Ethereum. There is a remote `Home` (on Ethereum) sending messages. There is a remote `Replica` (on Ethereum) receiving messages from Celo. There is a remote `Router` (on Ethereum) communicating with the local `Router` on Celo.
- **"Locally originating" vs "Remotely Originating" -** in the context of a token or asset in a specific contract, these terms denote whether the original canonical contract is deployed on the local chain, or on a remote chain
    - e.g. cUSD originates on Celo. in the context of the Celo blockchain, cUSD is "of local origin" or "locally originating"; in the context of the Ethereum blockchain, cUSD is "of remote origin"
    - e.g. Ether and WETH originate on Ethereum. When used in a Celo contract, they are "remotely originating" or "of remote origin"
    - e.g. a `Router` receives a Transfer message for a remotely-originating asset. It finds the local contract that represents that asset. When it receives a message for a locally originating asset, it knows that it can find the original asset contract locally
- **Router Contract**: a contract that implements a cross-chain application by specifying the:
    - **message format** - the bytes-encoded format of messages for the application
    - **registry of remote Router contracts** that implement the same application on remote chains
    - **rules & behavior for handling messages** sent via Optics by a registered Router contract on a remote chain
    - **rules & behavior for dispatching messages** via Optics to a registered Router contract on a remote chain
- **Message**: bytes transferred via Optics that encode some application-specific instructions via a standardized set of rules
- **Instructions**: set of application-specific actions (e.g. "send 5 token X to 0x123...456 on chain Z" in the case of a Token Bridge); calls to functions on the Router contract
- **Handling Messages from Optics Channels**:
    - receive bytes-encoded message from Optics (sent from a remote chain)
    - enact or dispatch the instructions on the local chain
    - local handler decodes the message into application-specific instructions
- **Dispatching Message to Optics Channels:**
    - receive instructions on the local chain (via local users and contracts calling functions on the contract)
    - encode the instructions into bytes using standardized message format
    - dispatch the bytes-encoded message to Optics (to be sent to a remote chain)