blockworks-foundation
/
pyth-crosschain
mirror of https://github.com/blockworks-foundation/pyth-crosschain.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Message publishing and fees design doc 

Change-Id: I0cb70e5bbad5e65950c7b60ae25979de6fcd10f9
This commit is contained in:
Hendrik Hofstadt 2021-05-11 18:47:54 +02:00
parent 05ea24faf7
commit 6beb1dfca7
2 changed files with 282 additions and 69 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

136
design/0001_generic_message_passing.md
View File

@ -4,19 +4,33 @@
## Objective
To refactor Wormhole into a fully generic cross chain messaging protocol and remove any application-specific functionality from the core protocol.
To refactor Wormhole into a fully generic cross chain messaging protocol and remove any application-specific
functionality from the core protocol.
## Background
Wormhole was originally designed to support a very specific kind of cross-chain message passing - token wrapping/swaps between Solana and Ethereum. Read more about the original design and its goals in the [announcement blog post](https://medium.com/certus-one/introducing-the-wormhole-bridge-24911b7335f7) and the [protocol documentation](https://github.com/certusone/wormhole/blob/48b3c0a3f8b35818952f61c38d89850eb8924b55/docs/protocol.md).
Wormhole was originally designed to support a very specific kind of cross-chain message passing - token wrapping/swaps
between Solana and Ethereum. Read more about the original design and its goals in
the [announcement blog post](https://medium.com/certus-one/introducing-the-wormhole-bridge-24911b7335f7) and
the [protocol documentation](https://github.com/certusone/wormhole/blob/48b3c0a3f8b35818952f61c38d89850eb8924b55/docs/protocol.md)
Since then, it has become clear that there is strong demand for using Wormhole's simple cross-chain state attestation model for applications beyond its original design. This includes third-party projects wanting to transfer tokens other than ERC20 (like NFTs), transfers guaranteed by insurance pools, "slow path/fast path" designs, as well as entirely different use cases like oracles broadcasting arbitrary data to multiple chains.
Since then, it has become clear that there is strong demand for using Wormhole's simple cross-chain state attestation
model for applications beyond its original design. This includes third-party projects wanting to transfer tokens other
than ERC20 (like NFTs), transfers guaranteed by insurance pools, "slow path/fast path" designs, as well as entirely
different use cases like oracles broadcasting arbitrary data to multiple chains.
Enabling these use cases requires extending Wormhole to provide a generic set of APIs and design patterns, decoupling it from the application logic.
Enabling these use cases requires extending Wormhole to provide a generic set of APIs and design patterns, decoupling it
from the application logic.
The core problem that both the current and future Wormhole design is solving is that of **enabling contracts on one chain to verify messages from a different chain**. Smart contract engines on chains are often insufficiently powerful to independently verify expensive state proofs from other chains due to the amount of storage and compute required. They therefore need to rely on off-chain oracles to observe and verify messages and then re-sign them such that they *can* be verified on any of the connected chains, by trusting the oracle network as an intermediary rather than trusting the remote chain.
The core problem that both the current and future Wormhole design is solving is that of **enabling contracts on one
chain to verify messages from a different chain**. Smart contract engines on chains are often insufficiently powerful to
independently verify expensive state proofs from other chains due to the amount of storage and compute required. They
therefore need to rely on off-chain oracles to observe and verify messages and then re-sign them such that they *can* be
verified on any of the connected chains, by trusting the oracle network as an intermediary rather than trusting the
remote chain.
We previously designed a similar protocol extension for the current Wormhole design, called EE-VAAs, which is the precursor to this fully generic design:
We previously designed a similar protocol extension for the current Wormhole design, called EE-VAAs, which is the
precursor to this fully generic design:
- [External Entity VAAs](https://github.com/certusone/wormhole/issues/147)
- [External Entity: Account State Attestation](https://github.com/certusone/wormhole/issues/149)
@ -26,29 +40,42 @@ This design doc assumes basic familiarity with the current design of Wormhole.
## Goals
We want to enable a wider range of both 1:1 and 1:n messaging applications to be built on Wormhole without requiring changes to the core protocol for each new use case. Some examples of such applications that third parties could build:
We want to enable a wider range of both 1:1 and 1:n messaging applications to be built on Wormhole without requiring
changes to the core protocol for each new use case. Some examples of such applications that third parties could build:
- Unicast messaging between two specific contracts on different chains (example: token or NFT swaps).
- Multicast from a single chain to a specific set of connected chains (example: relaying data published by price oracles like Pyth or Chainlink).
- Multicast from a single chain to a specific set of connected chains (example: relaying data published by price oracles
like Pyth or Chainlink).
The goal is to **redesign the protocol such that it is fully decoupled from the application logic**. This means that Wormhole will no longer hold assets in custody or interact with any tokens other than providing the low-level protocol which protocols interacting with tokens could be built on top of. This includes message delivery - Wormhole's current design directly delivered messages to a target contract for some chains. With a generic protocol, the delivery mechanism can wildly differ between different use cases.
The goal is to **redesign the protocol such that it is fully decoupled from the application logic**. This means that
Wormhole will no longer hold assets in custody or interact with any tokens other than providing the low-level protocol
which protocols interacting with tokens could be built on top of. This includes message delivery - Wormhole's current
design directly delivered messages to a target contract for some chains. With a generic protocol, the delivery mechanism
can wildly differ between different use cases.
## Non-Goals
This design document focuses only on the mechanics of the message passing protocol and does not attempt to solve the following problems, leaving them for future design iterations:
This design document focuses only on the mechanics of the message passing protocol and does not attempt to solve the
following problems, leaving them for future design iterations:
- The specifics of implementing applications, other than ensuring we provide the right APIs.
- Data availability on chains other than Solana. Delivering the signed message to the target chain is up to the individual application. Possible implementations include client-side message retrieval and submission, like the current Wormhole implementation does for delivering transfer messages on Ethereum, or message relays.
- Data availability on chains other than Solana. Delivering the signed message to the target chain is up to the
individual application. Possible implementations include client-side message retrieval and submission, like the
current Wormhole implementation does for delivering transfer messages on Ethereum, or message relays.
- The mechanics of economically incentivizing nodes to maintain uptime and not to censor or forge messages.
- Governance and criteria for inclusion in the guardian set. We only specify the governance API without defining its implementation, which could be a smart contract on one of the connected chains.
- Governance and criteria for inclusion in the guardian set. We only specify the governance API without defining its
implementation, which could be a smart contract on one of the connected chains.
## Overview
We simplify the design of Wormhole to only provide generic **signed attestations of finalized chain state**. Attestations can be requested by any contract by publishing a message, which is then picked up and signed by the Wormhole guardian set. The signed attestation will be published on the Wormhole P2P network and - if requested by the message publisher - be persisted, but not executed, on Solana for data availability.
We simplify the design of Wormhole to only provide generic **signed attestations of finalized chain state**.
Attestations can be requested by any contract by publishing a message, which is then picked up and signed by the
Wormhole guardian set. The signed attestation will be published on the Wormhole P2P network and - if requested by the
message publisher - be persisted, but not executed, on Solana for data availability.
Delivering the message to a contract on the target chain is shifted to the higher-layer protocol.
@ -89,6 +116,13 @@ VAA struct {
// the guardian node according to protocol metadata.
EmitterAddress Address // <-- NEW
// Sequence number of the message. Automatically set and
// and incremented by the core contract when called by
// an emitter contract.
//
// Tracked per (EmitterChain, EmitterAddress) tuple.
Sequence uint64 // <-- NEW
// Payload of the message.
Payload []byte // <-- NEW
@ -120,44 +154,86 @@ Signature struct {
}
```
The previous `Payload` method and `BodyTransfer`/`BodyGuardianSetUpdate`/`BodyContractUpgrade` structs with fields like `TargetChain`, `TargetAddress`, `Asset`and `Amount` will be removed and replaced by top-level `EmitterChain` and `EmitterAddress` fields and an unstructured `Payload` blob.
The previous `Payload` method and `BodyTransfer`/`BodyGuardianSetUpdate`/`BodyContractUpgrade` structs with fields
like `TargetChain`, `TargetAddress`, `Asset`and `Amount` will be removed and replaced by top-level `EmitterChain`
and `EmitterAddress` fields and an unstructured `Payload` blob. To allow for ordering on the receiving end, `Sequence`
was added which is a message counter tracked per emitter.
Notably, we remove target chain semantics, leaving it as an implementation detail for a higher-level relayer protocol.
Guardian set updates and contract upgrades will still be handled and special-cased at the Wormhole contract layer. Instead of specifying a VAA payload type like we previously did, Wormhole contracts will instead be initialized with a specific well-known `EmitterChain` and `EmitterAddress` tuple which is authorized to execute governance operations. Governance operations are executed by calling a dedicated governance method on the contracts.
Guardian set updates and contract upgrades will still be handled and special-cased at the Wormhole contract layer.
Instead of specifying a VAA payload type like we previously did, Wormhole contracts will instead be initialized with a
specific well-known `EmitterChain` and `EmitterAddress` tuple which is authorized to execute governance operations.
Governance operations are executed by calling a dedicated governance method on the contracts.
All contracts will be expected to support online upgrades. This implies changes to the Ethereum and Terra contracts to make them upgradeable.
All contracts will be expected to support online upgrades. This implies changes to the Ethereum and Terra contracts to
make them upgradeable.
## Related Technologies
In this section, Wormhole is compared to related technologies on the market. We have carefully evaluated all existing solutions to ensure that we have selected a unique set of trade-offs and are not reinventing any wheels.
In this section, Wormhole is compared to related technologies on the market. We have carefully evaluated all existing
solutions to ensure that we have selected a unique set of trade-offs and are not reinventing any wheels.
### Cosmos Hub and IBC
The [IBC protocol](https://ibcprotocol.org/documentation), famously implemented by the Cosmos SDK, occupies a similar problem space as Wormhole - cross-chain message passing. It is orthogonal to Wormhole and solves a larger and differently shaped problem, leading to a different design.
The [IBC protocol](https://ibcprotocol.org/documentation), famously implemented by the Cosmos SDK, occupies a similar
problem space as Wormhole - cross-chain message passing. It is orthogonal to Wormhole and solves a larger and
differently shaped problem, leading to a different design.
IBC specifies a cross-chain communication protocol with high-level semantics like channels, ports, acknowledgements, ordering and timeouts. It is a stream abstraction on top of a packet/datagram transport, vaguely similar to the TCP/IP protocol. IBC is part of the Cosmos Internet of Blockchain vision scalability vision, with hundreds or even thousands of sovereign IBC-compatible chains (called "zones") communicating via IBC using a hub-and-spoke topology. Data availability is provided by permissionless relayers.
IBC specifies a cross-chain communication protocol with high-level semantics like channels, ports, acknowledgements,
ordering and timeouts. It is a stream abstraction on top of a packet/datagram transport, vaguely similar to the TCP/IP
protocol. IBC is part of the Cosmos Internet of Blockchain vision scalability vision, with hundreds or even thousands of
sovereign IBC-compatible chains (called "zones") communicating via IBC using a hub-and-spoke topology. Data availability
is provided by permissionless relayers.
With IBC, for two chains to communicate directly with each other, they would have to be able to prove state mutually. This usually means implementing light clients for the other chain. In modern pBFT chains like those based on [Tendermint](https://v1.cosmos.network/resources/whitepaper) consensus, verifying light client proofs is [very cheap](https://blog.cosmos.network/light-clients-in-tendermint-consensus-1237cfbda104) - all that is needed is to follow validator set changes, instead of a full header chain. However, chains talking to each other directly would get unmanageable with many chains - and this is where central hubs like Cosmos Hub come in. Instead of every individual chain discovering and validating proofs of every other chain, instead, it can choose trust a single chain - the Hub - which then runs light clients for every chain it is connected to. This requires the hub to have a very high degree of security, which is why the Cosmos Hub has its own token - $ATOM - which now has a billion-dollar market cap.
With IBC, for two chains to communicate directly with each other, they would have to be able to prove state mutually.
This usually means implementing light clients for the other chain. In modern pBFT chains like those based
on [Tendermint](https://v1.cosmos.network/resources/whitepaper) consensus, verifying light client proofs
is [very cheap](https://blog.cosmos.network/light-clients-in-tendermint-consensus-1237cfbda104) - all that is needed is
to follow validator set changes, instead of a full header chain. However, chains talking to each other directly would
get unmanageable with many chains - and this is where central hubs like Cosmos Hub come in. Instead of every individual
chain discovering and validating proofs of every other chain, instead, it can choose trust a single chain - the Hub -
which then runs light clients for every chain it is connected to. This requires the hub to have a very high degree of
security, which is why the Cosmos Hub has its own token - $ATOM - which now has a billion-dollar market cap.
IBC works best when connecting modern pBFT chains that implement the IBC protocol and whose light client proofs are cheap to verify.
IBC works best when connecting modern pBFT chains that implement the IBC protocol and whose light client proofs are
cheap to verify.
This is not the case for chains like Ethereum or Solana. Ethereum requires a lot of state - the full header chain - to verify inclusion proofs. This is too expensive to do on the Hub, or any individual Cosmos chain, so a proxy chain (called a "peg zone") instead verifies the proofs, similarly to Wormhole. The peg zone would have its own security and validator set just like any other zone, and vouches for the Ethereum state.
This is not the case for chains like Ethereum or Solana. Ethereum requires a lot of state - the full header chain - to
verify inclusion proofs. This is too expensive to do on the Hub, or any individual Cosmos chain, so a proxy chain (
called a "peg zone") instead verifies the proofs, similarly to Wormhole. The peg zone would have its own security and
validator set just like any other zone, and vouches for the Ethereum state.
See [Gravity](https://github.com/cosmos/gravity-bridge) for how an Ethereum peg zone would look like. It's possible to verify Cosmos light client proofs on Ethereum, but not vice versa - the peg zone validators are trusted just like Wormhole nodes, and use a multisig mechanism similar to Wormhole for messages sent to Ethereum.
See [Gravity](https://github.com/cosmos/gravity-bridge) for how an Ethereum peg zone would look like. It's possible to
verify Cosmos light client proofs on Ethereum, but not vice versa - the peg zone validators are trusted just like
Wormhole nodes, and use a multisig mechanism similar to Wormhole for messages sent to Ethereum.
Solana does not currently provide a light client implementation, but like Ethereum, any Solana light client would also need a [large amount of state](https://docs.solana.com/proposals/simple-payment-and-state-verification) to verify inclusion proofs due to the complexity of the Solana consensus.
Solana does not currently provide a light client implementation, but like Ethereum, any Solana light client would also
need a [large amount of state](https://docs.solana.com/proposals/simple-payment-and-state-verification) to verify
inclusion proofs due to the complexity of the Solana consensus.
Instead of connecting hundreds of IBC-compatible chains with a few non-IBC outliers with peg zones, Wormhole is designed to **connect a low number of high-value DeFi chains**, most of which do not support IBC, which results in a different design.
Instead of connecting hundreds of IBC-compatible chains with a few non-IBC outliers with peg zones, Wormhole is designed
to **connect a low number of high-value DeFi chains**, most of which do not support IBC, which results in a different
design.
A peg zone is the closest analogy to Wormhole in the IBC model, with some important differences:
- Wormhole is a lower-level building block than IBC and specifies no high-level semantics like connections or target chains, leaving this to higher-layer protocols (think "Ethernet", not "TCP/IP"). This is more flexible and less complex to implement and audit, and moves the complexity to the upper layer and libraries only where it is needed.
- Wormhole is a lower-level building block than IBC and specifies no high-level semantics like connections or target
chains, leaving this to higher-layer protocols (think "Ethernet", not "TCP/IP"). This is more flexible and less
complex to implement and audit, and moves the complexity to the upper layer and libraries only where it is needed.
- Instead of operating our own Layer 1 proof-of-stake chain, we rely on finality of the connected chains. A staking mechanism for Wormhole guardian nodes would be managed by a smart contract on one of those chains and inherit its security properties. Nodes cannot initiate consensus on their own.
- Instead of operating our own Layer 1 proof-of-stake chain, we rely on finality of the connected chains. A staking
mechanism for Wormhole guardian nodes would be managed by a smart contract on one of those chains and inherit its
security properties. Nodes cannot initiate consensus on their own.
- By only reacting to finalized state on chains, each with strong finality guarantees, the Wormhole protocol does not need complex consensus, finality or leader election. It signs *observations* of finalized state, which all nodes do synchronously, and broadcasts them to a peer-to-peer network. There's no possibility of equivocation or eclipse attacks leading to disagreements.
- By only reacting to finalized state on chains, each with strong finality guarantees, the Wormhole protocol does not
need complex consensus, finality or leader election. It signs *observations* of finalized state, which all nodes do
synchronously, and broadcasts them to a peer-to-peer network. There's no possibility of equivocation or eclipse
attacks leading to disagreements.
- Long-range attacks and other PoS attacks are prevented by guardian set update finality on the connected chains. After a brief convergence window, the old guardian set becomes invalid and no alternative histories can be built.
- Long-range attacks and other PoS attacks are prevented by guardian set update finality on the connected chains. After
a brief convergence window, the old guardian set becomes invalid and no alternative histories can be built.
- Instead of relying on inclusion proofs, we use a multisig scheme which is easier to understand and audit and cheaper to verify on all connected chains. The extra guarantees offered by an inclusion proof are not needed in the Wormhole network, since it merely shuttles data between chains, each of which have provable and immutable history.
- Instead of relying on inclusion proofs, we use a multisig scheme which is easier to understand and audit and cheaper
to verify on all connected chains. The extra guarantees offered by an inclusion proof are not needed in the Wormhole
network, since it merely shuttles data between chains, each of which have provable and immutable history.

137
design/0004_message_publishing.md Normal file
View File

@ -0,0 +1,137 @@
# Message Publishing and Persistence
## Objective
To specify the mechanics and interfaces for publishing messages over Wormhole and how they are persisted.
## Background
The original Generic Message Passing design doc describes the format of Wormhole messages, however, the way messages are
published needs to be defined clearly for chain endpoints to be built.
## Goals
* Specify an interface for posting messages.
* Define the concept of persisted and non-persisted messages.
* Specify a fee model for message posting.
## Non-Goals
* Dynamic spam protection.
* Distribution of fees.
## Overview
The core Wormhole contracts on every chain will have a method for posting messages to Wormhole, which will emit an event
that needs to be observable by guardians running a full node on a given chain.
The method will allow to specify whether the produced VAA shall be persisted onto Solana or just be circulated on the
P2P network. Persisting messages will incur an increased fee vs. non-persisted attestations.
The fees will be payable in the respective chain's native currency. Fees can be
claimed by the protocol and collected in a fee pool on Solana where they can be distributed according to protocol rules.
## Detailed Design
Wormhole core contracts have a `postMessage` method which can be used by EOAs (externally owned accounts) or SCs (smart
contracts)
to publish a message via Wormhole.
This method has to perform verification on the payload for the maximum size limitation of **750 bytes**. The message
should be emitted such that it can be picked up by guardians in a way that allows offline nodes to replay missed blocks.
The Wormhole contract will also need to make the emitter of the published message available to the guardians. The
emitter is either a parameter to the postMessage method if the chain allows proving that the caller controls or is
authorized by said address (i.e. Solana PDAs), or it is the sender of the transaction.
Additionally, the Wormhole contract will keep track of a sequence number per emitter that is incremented for each
message submitted.
The timestamp is derived by the guardian software using the finalized timestamp of the block the message was published
in.
**Persistence:**
In case an emitter chooses to persist a message, the guardian software will publish it to the Solana blockchain where
the full VAA including all signatures will be stored with rent exemption (i.e. forever). This is meant to allow a user
to pick up a signed VAA from a browser with an unreliable connection, instead of having to listen to the P2P network or
building a separate data availability layer.
The Solana Wormhole program will have a `postVAA` method which will verify and persist a VAA.
If no persistence is chosen, the signatures and VAA will only be constructable by nodes listening to the P2P network.
This is meant for high-throughput data feeds where reliability is less important than cost-effectiveness, or use cases
where a sophisticated setup on the receiving/consumer end takes care of data availability.
**Fees:**
In order to incentivize guardians and prevent spamming of the Wormhole network, publishing a message will require a fee
payment.
This fee is supposed to be paid in any of the chain's native fee currencies when publishing a message. This assumes that
anyone sending a transaction is already required to hold such assets in order to make the transaction publishing the
message, and that the fee will therefore not negatively affect usability of the bridge.
The fee is defined by governance using the `SetMessageFee` VAA. The fees set are denominated in the respective chains
native currency. Each chain's Wormhole program is supposed to use an on-chain price oracle (e.g. a uniswap pool TWAP or
Pyth price feed)
Fees are set per chain to allow the protocol to take into consideration the effort required to keep the chain's nodes
online and account for spam attacks.
Fees will be collected in a wallet that is controlled by the Wormhole contract, governance or a more automated mechanism
to be implemented in a later design doc will be able to produce a `TransferFees` which will allow to move the collected
fee tokens to a specified address. In case there is a widely accepted token bridge, this mechanism might be extended to
bridge tokens back to the chain where the governance and staking contracts are located for them to be distributed there.
### API / database schema
Proposed bridge interface:
`postMessage(bytes payload, bool persist)` - Publish a message to be attested by Wormhole.
`postVAA(VAA signed_vaa)` - Persist a VAA on chain (Solana only)
`setFees(VAA fee_payload)` - Update the fees using a `SetMessageFee` VAA
`transferFees(VAA transfer_payload)` - Transfer fees using a `TransderFees` VAA
---
**Payloads**:
The payloads follow the governance message format.
SetMessageFee:
```
// Core Wormhole Module
Module [32]byte = "Core"
// Action index (3 for Fee Update)
Action uint16 = 3
Chain uint16
// Message fee in the native token
Fee uint64
```
TransferFees:
```
// Core Wormhole Module
Module [32]byte = "Core"
// Action index (4 for Fee Transfer)
Action uint16 = 4
Chain uint16
// Amount being transferred (big-endian uint256)
Amount [32]uint8
// Address of the recipient. Left-zero-padded if shorter than 32 bytes
To [32]uint8
```
## Caveats
A governance decision is required for the collection of fees. This means a lot of manual intervention in the
distribution of fees to stakers and guardians. The lack of a token bridge makes it hard to automate this in the early
days of the protocol. Also, a transfer primitive is unlikely to support token bridges (which may require smart contract
calls), so a contract will be required.
## Security Considerations