-
Notifications
You must be signed in to change notification settings - Fork 726
adds address codec doc to 10.x and next #8662
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
Merged
Merged
Changes from all commits
Commits
Show all changes
9 commits
Select commit
Hold shift + click to select a range
3cdbf3e
adds address codec doc to 10.x and next
Cordtus 113851e
add page frontmatter
Cordtus 3f785ac
remove unnecessary words
Cordtus 453ea05
update version 10.1.x > 10.4.x for clarity
Cordtus 0cb48a7
update codec wiring to align with evmd example
Cordtus 3e1ea4c
correct all filepaths to align with version bump
Cordtus 82bd521
Merge branch 'main' into feat/address-codec
Cordtus 979394a
appease CI
Cordtus 2e264d5
Merge branch 'feat/address-codec' of https://github.com/cordtus/ibc-g…
Cordtus File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
--- | ||
title: Address Codec | ||
sidebar_label: Address Codec | ||
sidebar_position: 7 | ||
slug: /ibc/apps/address-codec | ||
--- | ||
|
||
# Custom Address Codec | ||
|
||
## Overview | ||
|
||
Starting in ibc-go `v10.4.0`, the IBC transfer module uses the application's configured address codec to parse sender and receiver addresses. This enables chains to accept multiple address formats in IBC packets—for example, both standard Cosmos bech32 addresses (`cosmos1...`) and Ethereum hex addresses (`0x...`). | ||
|
||
## Interface | ||
|
||
The Cosmos SDK defines a simple interface for converting between address representations: | ||
|
||
```go | ||
type Codec interface { | ||
StringToBytes(text string) ([]byte, error) | ||
BytesToString(bz []byte) (string, error) | ||
} | ||
``` | ||
|
||
Applications configure a codec implementation on the `AccountKeeper`. The IBC transfer module retrieves this codec via `accountKeeper.AddressCodec()` and uses it throughout packet processing—validating sender addresses when creating packets and parsing receiver addresses when delivering funds. | ||
|
||
**Chain independence:** Each chain applies its own codec independently. The sending chain validates senders with its codec, the receiving chain validates receivers with its codec. This works seamlessly across chains with different codec configurations without any protocol changes. | ||
|
||
## Implementation | ||
|
||
A typical implementation composes the SDK's standard bech32 codec and extends it to parse hex addresses: | ||
|
||
```go | ||
type EvmCodec struct { | ||
bech32Codec address.Codec | ||
} | ||
|
||
func (c *EvmCodec) StringToBytes(text string) ([]byte, error) { | ||
if strings.HasPrefix(text, "0x") { | ||
// Validate and parse hex address using go-ethereum/common | ||
if !common.IsHexAddress(text) { | ||
return nil, errors.New("invalid hex address") | ||
} | ||
addr := common.HexToAddress(text) | ||
return addr.Bytes(), nil | ||
} | ||
// Default to bech32 parsing | ||
return c.bech32Codec.StringToBytes(text) | ||
} | ||
|
||
func (c *EvmCodec) BytesToString(bz []byte) (string, error) { | ||
// Always return bech32 format | ||
return c.bech32Codec.BytesToString(bz) | ||
} | ||
``` | ||
|
||
This pattern accepts both address formats as input while consistently outputting bech32. This makes the codec a drop-in replacement for the standard codec—existing tooling continues to work unchanged while users gain the ability to specify hex addresses where convenient. | ||
|
||
**Note:** A recommended address codec implementation is available in the [cosmos/evm repository](https://github.com/cosmos/evm/blob/main/encoding/address/address_codec.go). | ||
|
||
### Application Wiring | ||
|
||
After initializing your transfer keeper, configure the codec using the `SetAddressCodec` method: | ||
|
||
```go | ||
app.TransferKeeper.SetAddressCodec(evmaddress.NewEvmCodec(sdk.GetConfig().GetBech32AccountAddrPrefix())) | ||
``` | ||
|
||
For a complete example showing the transfer keeper initialization and address codec configuration, see [evmd app.go](https://github.com/cosmos/evm/blob/vlad/erc20-address-codec/evmd/app.go#L483-L494). | ||
|
||
## Usage | ||
|
||
Once configured, the chain accepts IBC transfers with receiver addresses in either format: | ||
|
||
```bash | ||
# Standard bech32 address | ||
gaiad tx ibc-transfer transfer transfer channel-0 \ | ||
cosmos1p9p6h9m8jcn8f7l6h3k2wq9g6yx0l8a9u2n4lr 1000uatom --from sender | ||
|
||
# Ethereum hex address | ||
gaiad tx ibc-transfer transfer transfer channel-0 \ | ||
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb 1000uatom --from sender | ||
``` | ||
|
||
Both formats resolve to the same on-chain account when derived from the same private key. The codec handles conversion to the internal byte representation transparently. | ||
|
||
## Reference Implementation | ||
|
||
The cosmos/evm repository provides a complete implementation in `utils/address_codec.go` with integration examples in the `evmd` reference chain: | ||
|
||
- [**Implementation PR**](https://github.com/cosmos/evm/pull/665) | ||
- [**Example integration**](https://github.com/cosmos/evm/tree/main/evmd) |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
92 changes: 92 additions & 0 deletions
92
docs/versioned_docs/version-v10.4.x/01-ibc/03-apps/07-address-codec.md
Cordtus marked this conversation as resolved.
Show resolved
Hide resolved
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,92 @@ | ||
--- | ||
title: Address Codec | ||
sidebar_label: Address Codec | ||
sidebar_position: 7 | ||
slug: /ibc/apps/address-codec | ||
--- | ||
|
||
# Custom Address Codec | ||
|
||
## Overview | ||
|
||
Starting in ibc-go `v10.4.0`, the IBC transfer module uses the application's configured address codec to parse sender and receiver addresses. This enables chains to accept multiple address formats in IBC packets—for example, both standard Cosmos bech32 addresses (`cosmos1...`) and Ethereum hex addresses (`0x...`). | ||
|
||
## Interface | ||
|
||
The Cosmos SDK defines a simple interface for converting between address representations: | ||
|
||
```go | ||
type Codec interface { | ||
StringToBytes(text string) ([]byte, error) | ||
BytesToString(bz []byte) (string, error) | ||
} | ||
``` | ||
|
||
Applications configure a codec implementation on the `AccountKeeper`. The IBC transfer module retrieves this codec via `accountKeeper.AddressCodec()` and uses it throughout packet processing—validating sender addresses when creating packets and parsing receiver addresses when delivering funds. | ||
|
||
**Chain independence:** Each chain applies its own codec independently. The sending chain validates senders with its codec, the receiving chain validates receivers with its codec. This works seamlessly across chains with different codec configurations without any protocol changes. | ||
|
||
## Implementation | ||
|
||
A typical implementation composes the SDK's standard bech32 codec and extends it to parse hex addresses: | ||
|
||
```go | ||
type EvmCodec struct { | ||
bech32Codec address.Codec | ||
} | ||
|
||
func (c *EvmCodec) StringToBytes(text string) ([]byte, error) { | ||
if strings.HasPrefix(text, "0x") { | ||
// Validate and parse hex address using go-ethereum/common | ||
if !common.IsHexAddress(text) { | ||
return nil, errors.New("invalid hex address") | ||
} | ||
addr := common.HexToAddress(text) | ||
return addr.Bytes(), nil | ||
} | ||
// Default to bech32 parsing | ||
return c.bech32Codec.StringToBytes(text) | ||
} | ||
|
||
func (c *EvmCodec) BytesToString(bz []byte) (string, error) { | ||
// Always return bech32 format | ||
return c.bech32Codec.BytesToString(bz) | ||
} | ||
``` | ||
|
||
This pattern accepts both address formats as input while consistently outputting bech32. This makes the codec a drop-in replacement for the standard codec—existing tooling continues to work unchanged while users gain the ability to specify hex addresses where convenient. | ||
|
||
**Note:** A recommended address codec implementation is available in the [cosmos/evm repository](https://github.com/cosmos/evm/blob/main/encoding/address/address_codec.go). | ||
|
||
### Application Wiring | ||
|
||
After initializing your transfer keeper, configure the codec using the `SetAddressCodec` method: | ||
|
||
```go | ||
app.TransferKeeper.SetAddressCodec(evmaddress.NewEvmCodec(sdk.GetConfig().GetBech32AccountAddrPrefix())) | ||
``` | ||
|
||
For a complete example showing the transfer keeper initialization and address codec configuration, see [evmd app.go](https://github.com/cosmos/evm/blob/vlad/erc20-address-codec/evmd/app.go#L483-L494). | ||
|
||
## Usage | ||
|
||
Once configured, the chain accepts IBC transfers with receiver addresses in either format: | ||
|
||
```bash | ||
# Standard bech32 address | ||
gaiad tx ibc-transfer transfer transfer channel-0 \ | ||
cosmos1p9p6h9m8jcn8f7l6h3k2wq9g6yx0l8a9u2n4lr 1000uatom --from sender | ||
|
||
# Ethereum hex address | ||
gaiad tx ibc-transfer transfer transfer channel-0 \ | ||
0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb 1000uatom --from sender | ||
``` | ||
|
||
Both formats resolve to the same on-chain account when derived from the same private key. The codec handles conversion to the internal byte representation transparently. | ||
|
||
## Reference Implementation | ||
|
||
The cosmos/evm repository provides a complete implementation in `utils/address_codec.go` with integration examples in the `evmd` reference chain: | ||
|
||
- [**Implementation PR**](https://github.com/cosmos/evm/pull/665) | ||
- [**Example integration**](https://github.com/cosmos/evm/tree/main/evmd) |
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes
File renamed without changes.
File renamed without changes
File renamed without changes
File renamed without changes.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,5 +1,5 @@ | ||
[ | ||
"v10.1.x", | ||
"v10.4.x", | ||
"v8.5.x", | ||
"v7.8.x", | ||
"v6.3.x", | ||
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.