Skip to content
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
2 changes: 1 addition & 1 deletion docs/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ make check-docs-link
This command will run `lychee` (if you don't have it, see the [install docs](https://lychee.cli.rs/installation/)) and check all links in `./docs/docs` (i.e. it will not check versioned docs).

Since a lot of our links are to github, this command easily gets rate limited, so it has been set up with a long retry sequence for links. You may need to run it multiple times to check all links.
The results (except rate limit responses) are cached for 1 week, so once you have run it, it will not keep checking the same links twice (this is primarly to help with rate limiting).
The results (except rate limit responses) are cached for 1 week, so once you have run it, it will not keep checking the same links twice (this is primarily to help with rate limiting).

## Updating the Documentation

Expand Down
2 changes: 1 addition & 1 deletion docs/dev/go-style-guide.md
Original file line number Diff line number Diff line change
Expand Up @@ -142,7 +142,7 @@ func (chain *TestChain) NextBlock() {
```go
// good
func (c *TestChain) NextBlock() {
// Ommitted
// Omitted
```

---
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/00-intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ The Inter-Blockchain Communication Protocol (IBC) is a protocol that allows bloc
The protocol realizes this interoperability by specifying a set of data structures, abstractions, and semantics that can be implemented by any distributed ledger that satisfies a small set of requirements.

:::note Notice
Since ibc-go v10, there are two versions of the protocol in the same release: IBC classic and IBC v2. The protocols are seperate - a connection uses either IBC classic or IBC v2
Since ibc-go v10, there are two versions of the protocol in the same release: IBC classic and IBC v2. The protocols are separate - a connection uses either IBC classic or IBC v2
:::

## High-level overview of IBC v2

For a high level overview of IBC v2, please refer to [this blog post.](https://ibcprotocol.dev/blog/ibc-v2-announcement) For a more detailed understanding of the IBC v2 protocol, please refer to the [IBC v2 protocol specification.](https://github.com/cosmos/ibc/tree/main/spec/IBC_V2)

If you are interested in using the cannonical deployment of IBC v2, connecting Cosmos chains and Ethereum, take a look at the [IBC Eureka](https://docs.skip.build/go/eureka/eureka-overview) documentation to get started.
If you are interested in using the canonical deployment of IBC v2, connecting Cosmos chains and Ethereum, take a look at the [IBC Eureka](https://docs.skip.build/go/eureka/eureka-overview) documentation to get started.

## High-level overview of IBC Classic

Expand Down
2 changes: 1 addition & 1 deletion docs/docs/01-ibc/03-apps/00-ibcv2apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ Modules may return to the IBC handler an acknowledgement which implements the `A
The IBC handler will then commit this acknowledgement of the packet so that a relayer may relay the
acknowledgement back to the sender module.

The state changes that occurr during this callback could be:
The state changes that occur during this callback could be:

- the packet processing was successful as indicated by the `PacketStatus_Success` and an `Acknowledgement()` will be written
- if the packet processing was unsuccessful as indicated by the `PacketStatus_Failure` and an `ackErr` will be written
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/01-ibc/03-apps/01-apps.md
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ slug: /ibc/apps/apps
# IBC Applications

:::warning
This page is relevant for IBC Classic, naviagate to the IBC v2 applications page for information on v2 apps
This page is relevant for IBC Classic, navigate to the IBC v2 applications page for information on v2 apps
:::

Learn how to configure your application to use IBC and send data packets to other chains.
Expand All @@ -18,7 +18,7 @@ Communication Protocol (IBC) applications for custom use cases.

Due to the modular design of the IBC protocol, IBC
application developers do not need to concern themselves with the low-level details of clients,
connections, and proof verification, however a brief explaination is given. Then the document goes into detail on the abstraction layer most relevant for application
connections, and proof verification, however a brief explanation is given. Then the document goes into detail on the abstraction layer most relevant for application
developers (channels and ports), and describes how to define your own custom packets, and
`IBCModule` callbacks.

Expand Down
8 changes: 4 additions & 4 deletions docs/docs/01-ibc/04-middleware/02-developIBCv2.md
Original file line number Diff line number Diff line change
Expand Up @@ -77,11 +77,11 @@ The middleware must have access to the underlying application, and be called bef

> Middleware **may** choose not to call the underlying application's callback at all. Though these should generally be limited to error cases.

The `IBCModule` interface consists of the packet callbacks where cutom logic is performed.
The `IBCModule` interface consists of the packet callbacks where custom logic is performed.

### Packet callbacks

The packet callbacks are where the middleware performs most of its custom logic. The middleware may read the packet flow data and perform some additional packet handling, or it may modify the incoming data before it reaches the underlying application. This enables a wide degree of usecases, as a simple base application like token-transfer can be transformed for a variety of usecases by combining it with custom middleware, for example acting as a filter for which tokens can be sent and recieved.
The packet callbacks are where the middleware performs most of its custom logic. The middleware may read the packet flow data and perform some additional packet handling, or it may modify the incoming data before it reaches the underlying application. This enables a wide degree of usecases, as a simple base application like token-transfer can be transformed for a variety of usecases by combining it with custom middleware, for example acting as a filter for which tokens can be sent and received.

#### `OnRecvPacket`

Expand Down Expand Up @@ -255,6 +255,6 @@ The middleware follows a decorator pattern that wraps an underlying application'

The least intrusive middleware is stateless. They simply read the ICS26 callback arguments before calling the underlying app's callback and error if the arguments are not acceptable (e.g. whitelisting packets). Stateful middleware that are used solely for erroring are also very simple to build, an example of this would be a rate-limiting middleware that prevents transfer outflows from getting too high within a certain time frame.

Middleware that directly interfere with the payload or acknowledgement before passing control to the underlying app are way more intrusive to the underyling app processing. This makes such middleware more error-prone when implementing as incorrect handling can cause the underlying app to break or worse execute unexpected behavior. Moreover, such middleware typically needs to be built for a specific underlying app rather than being generic. An example of this is the packet-forwarding middleware which modifies the payload and is specifically built for transfer.
Middleware that directly interfere with the payload or acknowledgement before passing control to the underlying app are way more intrusive to the underlying app processing. This makes such middleware more error-prone when implementing as incorrect handling can cause the underlying app to break or worse execute unexpected behavior. Moreover, such middleware typically needs to be built for a specific underlying app rather than being generic. An example of this is the packet-forwarding middleware which modifies the payload and is specifically built for transfer.

Middleware that modifies the payload or acknowledgement such that it is no longer readable by the underlying application is the most complicated middleware. Since it is not readable by the underlying apps, if these middleware write additional state into payloads and acknowledgements that get committed to IBC core provable state, there MUST be an equivalent counterparty middleware that is able to parse and intepret this additional state while also converting the payload and acknowledgment back to a readable form for the underlying application on its side. Thus, such middleware requires deployment on both sides of an IBC connection or the packet processing will break. This is the hardest type of middleware to implement, integrate and deploy. Thus, it is not recommended unless absolutely necessary to fulfill the given use case.
Middleware that modifies the payload or acknowledgement such that it is no longer readable by the underlying application is the most complicated middleware. Since it is not readable by the underlying apps, if these middleware write additional state into payloads and acknowledgements that get committed to IBC core provable state, there MUST be an equivalent counterparty middleware that is able to parse and interpret this additional state while also converting the payload and acknowledgment back to a readable form for the underlying application on its side. Thus, such middleware requires deployment on both sides of an IBC connection or the packet processing will break. This is the hardest type of middleware to implement, integrate and deploy. Thus, it is not recommended unless absolutely necessary to fulfill the given use case.
12 changes: 6 additions & 6 deletions docs/docs/02-apps/01-transfer/10-IBCv2-transfer.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,12 +7,12 @@ slug: /apps/transfer/ics20-v1/ibcv2transfer

# IBC v2 Transfer

Much of the core business logic of sending and recieving tokens between chains is unchanged between IBC Classic and IBC v2. Some of the key differences to pay attention to are detailed below.
Much of the core business logic of sending and receiving tokens between chains is unchanged between IBC Classic and IBC v2. Some of the key differences to pay attention to are detailed below.

## No Channel Handshakes, New Packet Format and Encoding Support

- IBC v2 does not establish connection between applications with a channel handshake. Channel identifiers represent Client IDs and are included in the `Payload`
- The source and destination port must be `"transfer"`
- The source and destination port must be "transfer"
- The channel IDs [must be valid client IDs](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/v2/ibc_module.go#L46-L47) of the format `{clientID}-{sequence}`, e.g. 08-wasm-007
- The [`Payload`](https://github.com/cosmos/ibc-go/blob/main/modules/core/04-channel/v2/types/packet.pb.go#L146-L158) contains the [`FungibleTokenPacketData`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/types/packet.pb.go#L28-L39) for a token transfer.

Expand All @@ -23,7 +23,7 @@ The code snippet shows the `Payload` struct.
type Payload struct {
// specifies the source port of the packet, e.g. transfer
SourcePort string `protobuf:"bytes,1,opt,name=source_port,json=sourcePort,proto3" json:"source_port,omitempty"`
// specifies the destination port of the packet, e.g. trasnfer
// specifies the destination port of the packet, e.g. transfer
DestinationPort string `protobuf:"bytes,2,opt,name=destination_port,json=destinationPort,proto3" json:"destination_port,omitempty"`
// version of the specified application
Version string `protobuf:"bytes,3,opt,name=version,proto3" json:"version,omitempty"`
Expand Down Expand Up @@ -56,9 +56,9 @@ type FungibleTokenPacketData struct {

## Base Denoms cannot contain slashes

With the new [`Denom`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/types/token.pb.go#L81-L87) struct, the base denom, i.e. uatom, is seperated from the trace - the path the token has travelled. The trace is presented as an array of [`Hop`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/types/token.pb.go#L136-L140)s.
With the new [`Denom`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/types/token.pb.go#L81-L87) struct, the base denom, i.e. uatom, is separated from the trace - the path the token has travelled. The trace is presented as an array of [`Hop`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/transfer/types/token.pb.go#L136-L140)s.

Because IBC v2 no longer uses channels, it is no longer possible to rely on a fixed format for an identifier so using a base denom that contains a "/" is dissallowed.
Because IBC v2 no longer uses channels, it is no longer possible to rely on a fixed format for an identifier so using a base denom that contains a "/" is disallowed.

## Changes to the application module interface

Expand All @@ -77,7 +77,7 @@ Thus, `MsgTransfer` has an additional `UseAliasing` boolean field to indicate th
```go
MsgTransfer{
SourcePort: "transfer",
SourceChannel: "channel-4", //note: we are using an existing v1 channel identiifer
SourceChannel: "channel-4", //note: we are using an existing v1 channel identifier
Token: "uatom",
Sender: {senderAddr},
Receiver: {receiverAddr},
Expand Down
4 changes: 2 additions & 2 deletions docs/docs/04-middleware/01-callbacks/07-callbacks-IBCv2.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,14 +15,14 @@ Some of the interface differences are:

- The callbacks middleware for IBC v2 requires the [`Underlying Application`](../01-callbacks/01-overview.md) to implement the new [`CallbacksCompatibleModuleV2`](https://github.com/cosmos/ibc-go/blob/main/modules/apps/callbacks/types/callbacks.go#L53-L58) interface.
- `channeltypesv2.Payload` is now used instead of `channeltypes.Packet`
- With IBC classic, the `OnRecvPacket` callback returns the `ack`, whereas v2 returns the `recvResult` which is the [status of the packet](https://github.com/cosmos/ibc-go/blob/main/modules/core/04-channel/v2/types/packet.pb.go#L26-L38): unspecified, success, failue or asynchronous
- With IBC classic, the `OnRecvPacket` callback returns the `ack`, whereas v2 returns the `recvResult` which is the [status of the packet](https://github.com/cosmos/ibc-go/blob/main/modules/core/04-channel/v2/types/packet.pb.go#L26-L38): unspecified, success, failure or asynchronous
- `api.WriteAcknowledgementWrapper` is used instead of `ICS4Wrapper.WriteAcknowledgement`. It is only needed if the lower level application is going to write an asynchronous acknowledgement.

## Contract Developers

The wasmd contract keeper enables cosmwasm developers to use the callbacks middleware. The [cosmwasm documentation](https://cosmwasm.cosmos.network/ibc/extensions/callbacks) provides information for contract developers. The IBC v2 callbacks implementation uses a `Payload` but reconstructs an IBC classic `Packet` to preserve the cosmwasm contract keeper interface. Additionally contracts must now handle the IBC v2 `ErrorAcknowledgement` sentinel value in the case of a failure.

The callbacks middleware can be used for transfer + action workflows, for example a transfer and swap on recieve. These workflows require knowledge of the ibc denom that has been recieved. To assist with parsing the ics20 packet, [helper functions](https://github.com/cosmos/solidity-ibc-eureka/blob/a8870b023e58622fb7b3f733572c684851f8e5ee/packages/cosmwasm/ibc-callbacks-helpers/src/ics20.rs#L7-L41) can be found in the solidity-ibc-eureka repository.
The callbacks middleware can be used for transfer + action workflows, for example a transfer and swap on receive. These workflows require knowledge of the ibc denom that has been received. To assist with parsing the ics20 packet, [helper functions](https://github.com/cosmos/solidity-ibc-eureka/blob/a8870b023e58622fb7b3f733572c684851f8e5ee/packages/cosmwasm/ibc-callbacks-helpers/src/ics20.rs#L7-L41) can be found in the solidity-ibc-eureka repository.

## Integration

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Packet Forward Middleware enables multi-hop token transfers by forwarding IBC pa
The middleware can be configured to retry forwarding in the case that there was a timeout.
- **Forwarding across multiple chains with nested memos:**
Instructions on which route to take to forward a packet across more than one chain can be set within a nested JSON with the memo field
- **Configurable Fee Deduction on Recieve:**
- **Configurable Fee Deduction on Receive:**
Integrators of PFM can choose to deduct a percentage of tokens forwarded through their chain and distribute these tokens to the community pool.

## How it works?
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,14 +14,14 @@ Learn about rate limit middleware, a middleware that can be used in combination
The rate limit middleware enforces rate limits on IBC token transfers coming into and out of a chain. It supports:

- **Risk Mitigation:** In case of a bug exploit, attack or economic failure of a connected chain, it limits the impact to the in/outflow specified for a given time period.
- **Token Filtering:** Through the use of a blacklist, the middleware can completely block tokens entering or leaving a domain, relevant for complicance or giving asset issuers greater control over the domains token can be sent to.
- **Uninterupted Packet Flow:** When desired, rate limits can be bypassed by using the whitelist, to avoid any restriction on asset in or outflows.
- **Token Filtering:** Through the use of a blacklist, the middleware can completely block tokens entering or leaving a domain, relevant for compliance or giving asset issuers greater control over the domains token can be sent to.
- **Uninterrupted Packet Flow:** When desired, rate limits can be bypassed by using the whitelist, to avoid any restriction on asset in or outflows.

## How it works

The rate limiting middleware determines whether tokens can flow into or out of a chain. The middleware does this by:

1. Check transfer limits for an asset (Quota): When tokens are recieved or sent, the middleware determines whether the amount of tokens flowing in or out have exceeded the limit.
1. Check transfer limits for an asset (Quota): When tokens are received or sent, the middleware determines whether the amount of tokens flowing in or out have exceeded the limit.

2. Track in or outflow: When tokens enter or leave the chain, the amount transferred is tracked in state

Expand Down
4 changes: 2 additions & 2 deletions docs/versioned_docs/version-v10.1.x/00-intro.md
Original file line number Diff line number Diff line change
Expand Up @@ -12,14 +12,14 @@ The Inter-Blockchain Communication Protocol (IBC) is a protocol that allows bloc
The protocol realizes this interoperability by specifying a set of data structures, abstractions, and semantics that can be implemented by any distributed ledger that satisfies a small set of requirements.

:::note Notice
Since ibc-go v10, there are two versions of the protocol in the same release: IBC classic and IBC v2. The protocols are seperate - a connection uses either IBC classic or IBC v2
Since ibc-go v10, there are two versions of the protocol in the same release: IBC classic and IBC v2. The protocols are separate - a connection uses either IBC classic or IBC v2
:::

## High-level overview of IBC v2

For a high level overview of IBC v2, please refer to [this blog post.](https://ibcprotocol.dev/blog/ibc-v2-announcement) For a more detailed understanding of the IBC v2 protocol, please refer to the [IBC v2 protocol specification.](https://github.com/cosmos/ibc/tree/main/spec/IBC_V2)

If you are interested in using the cannonical deployment of IBC v2, connecting Cosmos chains and Ethereum, take a look at the [IBC Eureka](https://docs.skip.build/go/eureka/eureka-overview) documentation to get started.
If you are interested in using the canonical deployment of IBC v2, connecting Cosmos chains and Ethereum, take a look at the [IBC Eureka](https://docs.skip.build/go/eureka/eureka-overview) documentation to get started.

## High-level overview of IBC Classic

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ Modules may return to the IBC handler an acknowledgement which implements the `A
The IBC handler will then commit this acknowledgement of the packet so that a relayer may relay the
acknowledgement back to the sender module.

The state changes that occurr during this callback could be:
The state changes that occur during this callback could be:

- the packet processing was successful as indicated by the `PacketStatus_Success` and an `Acknowledgement()` will be written
- if the packet processing was unsuccessful as indicated by the `PacketStatus_Failure` and an `ackErr` will be written
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Communication Protocol (IBC) applications for custom use cases.

Due to the modular design of the IBC protocol, IBC
application developers do not need to concern themselves with the low-level details of clients,
connections, and proof verification, however a brief explaination is given. Then the document goes into detail on the abstraction layer most relevant for application
connections, and proof verification, however a brief explanation is given. Then the document goes into detail on the abstraction layer most relevant for application
developers (channels and ports), and describes how to define your own custom packets, and
`IBCModule` callbacks.

Expand Down
Loading