Skip to content

Fix typos #263

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open
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
6 changes: 3 additions & 3 deletions docs/adr/adr-001.md
Original file line number Diff line number Diff line change
Expand Up @@ -35,7 +35,7 @@ a. how to update the commitments in the host(i.e. handler) after updating LC sta
b. how to determine the ethereum ABI format from the proto definition
c. how to know the function definition of the LC contract to which the message is sent

To resolve `a`, we added `updateClientCommitments` function to the handler which allows relayers to update the commitments corresponding to the LC state. Since the anyone can call directly `updateClient` in LC contract without the handler, it is required to call this function to set the commitment in the handler after the state is updated. However, in an established channel, there is almost no need to update the commitments every time per `updateClient`. An example implementation of yui-relayer, which does not update client commitments after a connection is established, can be found in the Appendix.
To resolve `a`, we added `updateClientCommitments` function to the handler which allows relayers to update the commitments corresponding to the LC state. Since anyone can call directly `updateClient` in LC contract without the handler, it is required to call this function to set the commitment in the handler after the state is updated. However, in an established channel, there is almost no need to update the commitments every time per `updateClient`. An example implementation of yui-relayer, which does not update client commitments after a connection is established, can be found in the Appendix.

To resolve `b` and `c`, we added a new helper function `routeUpdateClient` to `ILightClient`. The function decodes the given proto-encoded message, converts it to eth-ABI message and returns it with the call information of the `updateClient` function. The function could be implemented off-chain, such as in a relayer, but considering the backwards compatibility with existing proto-encoded `updateClient` messages, we decide that it should be provided in LC contract. Note that a relayer does not need to use `routeUpdateClient`, assuming it knows the ABI of LC's UpdateClient function.

Expand Down Expand Up @@ -111,7 +111,7 @@ In the above implementation, the `routeUpdateClient` function returns the select

### Constructing Tx using `routeUpdateClient`

If a relayer connects to an untrusted blockchain node and constructs a transaction using the tampered returned value of `routeUpdateClient`, an arbitrary contract call attack can be happened. Therefore, the relayer needs to register a LC contract address and function selectors in the allowed list and ensure that the returned value of `routeUpdateClient` matches them. However, if the LC contract provides a relayer-trust update function, such a function should not be included within the allowed list. In that case, the relayer should be given the UpdateClient ABI and the relayer should construct an UpdateClient tx instead of using `routeUpdateClient`.
If a relayer connects to an untrusted blockchain node and constructs a transaction using the tampered returned value of `routeUpdateClient`, an arbitrary contract call attack can happen. Therefore, the relayer needs to register a LC contract address and function selectors in the allowed list and ensure that the returned value of `routeUpdateClient` matches them. However, if the LC contract provides a relayer-trust update function, such a function should not be included within the allowed list. In that case, the relayer should be given the UpdateClient ABI and the relayer should construct an UpdateClient tx instead of using `routeUpdateClient`.

## Backward Compatibility

Expand Down Expand Up @@ -142,7 +142,7 @@ function updateClient(MsgUpdateClient calldata msg_) external override {

Shows an implementation example in the ethereum module of yui-relayer https://github.com/datachainlab/ethereum-ibc-relay-chain. Note that yui-relayer relays between a "path" consisting of a single connection and channel.

In the function `SendMsgs`, which sends a transaction to ethereum, it can be determined that the commitment update can be skipped if the connection state is confirmed to be `OPEN` by `QueryConnection`.
In the function `SendMsgs`, which sends a transaction to ethereum, it can be determined that the commitment update can be skipped if the connection state is confirmed to be `OPEN` by `QueryConnection`.

```go
func (c *Chain) SendMsgs(msgs []sdk.Msg) ([]core.MsgID, error) {
Expand Down
4 changes: 2 additions & 2 deletions docs/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -134,11 +134,11 @@ The packet sending flow using the `EchoApp` is the following:
1. src chain: send a packet containing "hello" as data qith `sendMessage` of the `EchoApp`.
2. dst chain:
- The relayer submits the packet from 1 with `recvPacket` of the `IBCHandler`.
- The `IBCHandler` ensure that the packet commitment is valid and calls `onRecvPacket` of the `EchoApp`.
- The `IBCHandler` ensures that the packet commitment is valid and calls `onRecvPacket` of the `EchoApp`.
- `onRecvPacket` returns the received packet data as acknowledgement data
3. src chain:
- The relayer submits the 1. packet and 2. acknowledgement
- The `IBCHandler` ensure that the acknowledgement commitment is valid and calls `onAcknowledgementPacket` of the `EchoApp`.
- The `IBCHandler` ensures that the acknowledgement commitment is valid and calls `onAcknowledgementPacket` of the `EchoApp`.
- In `onAcknowledgementPacket`, ensure that acknowledgement data matches the send message("hello")

Also, an App can define callback functions for state transitions in the channel handshake. See [IIBCModule interface](../contracts/core/26-router/IIBCModule.sol) for more details.
Expand Down
14 changes: 7 additions & 7 deletions docs/ibft2-light-client.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ This document describes a light client that validates Hyperledger Besu using IBF

The light client is a client software that connects to full nodes to interact with the blockchain.[2][3]

In general, full nodes needs to validate every block and every transaction, which requires a lot of resources. light client can be used as intermediaries with minimal trust in full nodes, enabling blockchain validation with relatively small resources. Examples of such light client are those of bitcoin, ethereum 2.0, and tendermint. Among them, tendermint's work on light client has greatly influenced us to design the IBFT 2.0 Light Client protocol.
In general, full nodes need to validate every block and every transaction, which requires a lot of resources. Light clients can be used as intermediaries with minimal trust in full nodes, enabling blockchain validation with relatively small resources. Examples of such light clients are those of bitcoin, ethereum 2.0, and tendermint. Among them, tendermint's work on light client has greatly influenced us to design the IBFT 2.0 Light Client protocol.

This document will first give an overview of the IBFT 2.0 protocol and then describe the IBFT 2.0 Light Client protocol.

Expand All @@ -16,7 +16,7 @@ IBFT 2.0 is Proof-of-Authority (PoA) Byzantine-Fault-Tolerant (BFT) blockchain c

In IBFT 2.0 protocol, the total number of nodes, `n`, and the maximum number of byzantine nodes(`f(n)`) can be expressed as `f(n) = (n-1) / 3`

There is a voting mechanism that allows nodes to add or remove validators from the valudator set. Up to one vote can be added per Block and will be applied if 1/2+ votes of the validator set are included in the block within the epoch. For more details on how voting works, please refer to [5].
There is a voting mechanism that allows nodes to add or remove validators from the validator set. Up to one vote can be added per Block and will be applied if 1/2+ votes of the validator set are included in the block within the epoch. For more details on how voting works, please refer to [5].

An overview of the consensus state transitions in IBFT 2.0 is shown below:

Expand All @@ -36,7 +36,7 @@ When using IBFT 2.0 in Besu, a result of consensus is stored in the extra data f

The second element of the list is a list of each address in a validator set of this block, and the fifth is commit seals to this block by the validator set.

Each blockchain node verifies the commit seals to validates the block according to Algorithm 1[1].
Each blockchain node verifies the commit seals to validate the block according to Algorithm 1[1].

## Light Client protocol

Expand All @@ -48,13 +48,13 @@ The light client is assumed to be initialized based on a trusted source. In the

### Trusting period

In the IBFT 2.0 protocol, it is implicitly assumed that the nodes can trust the valiadtor set of each finalized block height.
In the IBFT 2.0 protocol, it is implicitly assumed that the nodes can trust the validator set of each finalized block height.

Therefore, asynchronous nodes somehow receive blocks from trusted nodes, validate them according to Algorithm.1 in [1], and add them to their own ledgers.

In this paper, there is an implicit assumption that the validator set for each block is always trusted. However, we thought this assumption may be difficult to satisfy in some environments. e.g. an environment where changes to the validator set occur relatively frequently.

For this purpose, the light client verification follows the IBFT 2.0 failure model with an additional assumption about a period of the validator set of height can be trusted. The assumption is follows:
For this purpose, the light client verification follows the IBFT 2.0 failure model with an additional assumption about a period of the validator set of height can be trusted. The assumption is as follows:

- The new block must be verified by the validator set of a block generated within time duration `T` before the current time.

Expand All @@ -75,7 +75,7 @@ Let the height of the trusted block be `n`, the height of the untrusted block be
2. `B n+m` has 1/3 signatures of `V n`
3. `B n+m` has 2/3+ signatures of `V n+m`

1 has already been explained in [Trusting period]. Next, let's consider 2: under the assumption that the maximum byzantine number can be expressed as `f(n) = (n-1)/3`, ensure that there is at least one honest validator. Finally, in 3 it ensure that the finalized block of height `n+m` is valid.
1 has already been explained in [Trusting period]. Next, let's consider 2: under the assumption that the maximum byzantine number can be expressed as `f(n) = (n-1)/3`, ensure that there is at least one honest validator. Finally, in 3 it ensures that the finalized block of height `n+m` is valid.

### Liveness analysis

Expand All @@ -93,7 +93,7 @@ If this equation holds, there will always be a block height with a validator set

If the failure model of IBFT 2.0 is violated and there are more than `(n-1) / 3` failed nodes, multiple valid confirmed blocks may be generated.

The light client may be able to detect such failures or attacks. This works will be done in the future.
The light client may be able to detect such failures or attacks. This work will be done in the future.

## References

Expand Down