From 5536db14e68e900dc1b340b125faab14a204f33c Mon Sep 17 00:00:00 2001 From: Manuel Alessandro Collazo Date: Sun, 8 Mar 2026 09:38:00 +0700 Subject: [PATCH 1/3] docs(evm): clarify Initia ERC20 compatibility for wallet/bridge and registry requirements --- .../registry/introduction.mdx | 7 +++++ .../creating-standard-erc20s.mdx | 28 ++++++++++++++++++- .../evm/update-fee-token.mdx | 4 ++- .../evm/initia-custom-erc20.mdx | 5 ++++ 4 files changed, 42 insertions(+), 2 deletions(-) diff --git a/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx b/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx index 1ba4c540..8ad9ddbf 100644 --- a/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx +++ b/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx @@ -9,6 +9,13 @@ registration is done via a GitHub pull request to the registry repository. The file and directory that need to be updated in the PR vary depending on the type of information being added. + + Registry listing and token contract compatibility solve different problems. A + token may appear in some balance displays (for example, on scan) but still + fail in Wallet or Bridge actions. For full end-user support across Initia + apps, you need both complete registry metadata and compatible token behavior. + + ## Adding Profiles For an application's information including logo, name, description, and more to diff --git a/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx b/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx index aa73ec6b..3fc9fc8f 100644 --- a/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx +++ b/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx @@ -7,7 +7,33 @@ title: Creating Standard ERC20s via ERC20Factory For developers looking to create standard ERC20 tokens on EVM rollups, we recommend using the [ERC20Factory](/resources/developer/contract-references/evm/erc20-factory) -contract. +contract. For most teams, this is the lowest-risk path because it deploys a +token implementation that already includes Initia ERC20 compatibility +extensions. + +## Production Readiness Checklist + +Before treating a token as ready for broad ecosystem support: + +1. Deploy via + [`ERC20Factory`](/resources/developer/contract-references/evm/erc20-factory) + (or implement equivalent Initia extensions in a custom token contract using + [Creating Custom ERC20s](/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-custom-erc20s) + and + [`InitiaCustomERC20`](/resources/developer/contract-references/evm/initia-custom-erc20)). +2. Add token metadata to the relevant `assetlist.json` in + [Initia Registry](/developers/developer-guides/integrating-initia-apps/registry/introduction). +3. Confirm your token supports the Cosmos transfer path (`sudoTransfer`) used in + escrow-style bridge transfer handling by following the compatibility guidance + in + [Creating ERC20s Introduction](/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/introduction) + and + [`InitiaCustomERC20` reference](/resources/developer/contract-references/evm/initia-custom-erc20). + + + Registry listing is required for app-level discovery and metadata display + across Initia products. + ## Project Setup diff --git a/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx b/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx index a17fdc93..f300a399 100644 --- a/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx +++ b/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx @@ -17,7 +17,9 @@ Fee Token as an ERC20 token. Use validator (admin) account to update the chain parameter. - The deployed ERC20 token must inherit the `InitiaERC20` contract. + The fee token ERC20 must include Initia ERC20 compatibility extensions. + Factory-deployed tokens satisfy this automatically. For custom deployments, + inherit `InitiaCustomERC20` (recommended for direct deployment). ```ts diff --git a/resources/developer/contract-references/evm/initia-custom-erc20.mdx b/resources/developer/contract-references/evm/initia-custom-erc20.mdx index 3b2994c7..cbde9d26 100644 --- a/resources/developer/contract-references/evm/initia-custom-erc20.mdx +++ b/resources/developer/contract-references/evm/initia-custom-erc20.mdx @@ -229,6 +229,11 @@ function burn(address from, uint256 amount) external burnable(from) onlyOwner Transfers tokens from one address to another, bypassing the usual access control checks. This function can only be called by the chain signer. + + For Cosmos-side transfer handling in Initia ERC20 flows, `sudoTransfer` is + the key transfer hook used by chain-level logic. + + ```solidity function sudoTransfer(address sender, address recipient, uint256 amount) external onlyChain ``` From c3ca179f80af18ba17b0f6dad66e3ec399cc150e Mon Sep 17 00:00:00 2001 From: Manuel Alessandro Collazo Date: Sun, 8 Mar 2026 22:11:25 +0700 Subject: [PATCH 2/3] fix: prettier formatting --- .../developer/contract-references/evm/initia-custom-erc20.mdx | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/resources/developer/contract-references/evm/initia-custom-erc20.mdx b/resources/developer/contract-references/evm/initia-custom-erc20.mdx index cbde9d26..ecdf327f 100644 --- a/resources/developer/contract-references/evm/initia-custom-erc20.mdx +++ b/resources/developer/contract-references/evm/initia-custom-erc20.mdx @@ -230,8 +230,8 @@ Transfers tokens from one address to another, bypassing the usual access control checks. This function can only be called by the chain signer. - For Cosmos-side transfer handling in Initia ERC20 flows, `sudoTransfer` is - the key transfer hook used by chain-level logic. + For Cosmos-side transfer handling in Initia ERC20 flows, `sudoTransfer` is the + key transfer hook used by chain-level logic. ```solidity From eaea0539ec3fa50b2a2fe470a2e905e18bd74cf4 Mon Sep 17 00:00:00 2001 From: Manuel Alessandro Collazo Date: Mon, 9 Mar 2026 11:09:57 +0700 Subject: [PATCH 3/3] docs: clarify ERC20 compatibility requirements and registry metadata roles --- .../registry/introduction.mdx | 15 ++++++---- .../creating-standard-erc20s.mdx | 29 ++++++++++--------- .../evm/creating-erc20s/introduction.mdx | 14 ++++----- .../evm/update-fee-token.mdx | 7 +++-- .../evm/initia-custom-erc20.mdx | 6 ++-- 5 files changed, 40 insertions(+), 31 deletions(-) diff --git a/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx b/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx index 8ad9ddbf..9a056374 100644 --- a/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx +++ b/developers/developer-guides/integrating-initia-apps/registry/introduction.mdx @@ -9,12 +9,15 @@ registration is done via a GitHub pull request to the registry repository. The file and directory that need to be updated in the PR vary depending on the type of information being added. - - Registry listing and token contract compatibility solve different problems. A - token may appear in some balance displays (for example, on scan) but still - fail in Wallet or Bridge actions. For full end-user support across Initia - apps, you need both complete registry metadata and compatible token behavior. - + + Full token support across Initia apps depends on two separate requirements: + +1. Registry metadata (`assetlist.json`): Controls how the token appears in + product UIs (name, symbol, decimals, logo, and display info in Initia Scan). +2. Token contract behavior: Controls whether token actions actually work (for + example, sending and bridging). For MiniEVM ERC20 tokens, this includes the + `sudoTransfer` hook. + ## Adding Profiles diff --git a/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx b/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx index 3fc9fc8f..1b770ef8 100644 --- a/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx +++ b/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-standard-erc20s.mdx @@ -8,31 +8,34 @@ For developers looking to create standard ERC20 tokens on EVM rollups, we recommend using the [ERC20Factory](/resources/developer/contract-references/evm/erc20-factory) contract. For most teams, this is the lowest-risk path because it deploys a -token implementation that already includes Initia ERC20 compatibility -extensions. +token implementation that already includes the required Initia chain integration +hooks (including `sudoTransfer`). ## Production Readiness Checklist -Before treating a token as ready for broad ecosystem support: +Before treating a factory-deployed token as ready for support across Initia +products (for example, Initia Scan, InterwovenKit, Wallet, and Bridge): 1. Deploy via - [`ERC20Factory`](/resources/developer/contract-references/evm/erc20-factory) - (or implement equivalent Initia extensions in a custom token contract using - [Creating Custom ERC20s](/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-custom-erc20s) - and - [`InitiaCustomERC20`](/resources/developer/contract-references/evm/initia-custom-erc20)). + [`ERC20Factory`](/resources/developer/contract-references/evm/erc20-factory). 2. Add token metadata to the relevant `assetlist.json` in [Initia Registry](/developers/developer-guides/integrating-initia-apps/registry/introduction). -3. Confirm your token supports the Cosmos transfer path (`sudoTransfer`) used in - escrow-style bridge transfer handling by following the compatibility guidance - in +3. Confirm your token is compatible with the required `sudoTransfer` hook used + in sending and bridging flows (included by default for `ERC20Factory` + deployments) by following the compatibility guidance in [Creating ERC20s Introduction](/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/introduction) and [`InitiaCustomERC20` reference](/resources/developer/contract-references/evm/initia-custom-erc20). +If you need custom token logic, deploy a custom ERC20 that inherits +[`InitiaCustomERC20`](/resources/developer/contract-references/evm/initia-custom-erc20) +as the base contract (see +[Creating Custom ERC20s](/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/creating-custom-erc20s)). + - Registry listing is required for app-level discovery and metadata display - across Initia products. + Registry listing is required for tokens to appear correctly in Initia product + UIs with metadata (name, symbol, decimals, logo), and to be selectable in + flows such as balances, transfers, and bridging. ## Project Setup diff --git a/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/introduction.mdx b/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/introduction.mdx index c7d8d177..5d9a2e87 100644 --- a/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/introduction.mdx +++ b/developers/developer-guides/vm-specific-tutorials/evm/creating-erc20s/introduction.mdx @@ -2,18 +2,18 @@ title: Introduction --- -To ensure compatibility with Initia's EVM module and the Cosmos SDK in general, -ERC20 tokens on rollups includes certain extensions beyond the standard ERC20 -template. +For an ERC20 token to work across Initia products (for example, Initia Scan, +InterwovenKit, Wallet, and Bridge), it must include Initia chain integration +hooks in addition to standard ERC20 behavior. Developers looking to create and deploy ERC20s on EVM rollups have two options: -1. Deploy Initia ERC20s using the +1. Deploy using the [ERC20Factory](/resources/developer/contract-references/evm/erc20-factory) - contract. -2. Extend and modify Initia's + contract (recommended when you only need standard token behavior). +2. For custom ERC20 logic, inherit from [InitiaCustomERC20](/resources/developer/contract-references/evm/initia-custom-erc20) - contract. + and extend it. While Initia's `CustomERC20.sol` contains additional logic, it is still fully diff --git a/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx b/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx index f300a399..1f4a53e2 100644 --- a/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx +++ b/developers/developer-guides/vm-specific-tutorials/evm/update-fee-token.mdx @@ -17,9 +17,10 @@ Fee Token as an ERC20 token. Use validator (admin) account to update the chain parameter. - The fee token ERC20 must include Initia ERC20 compatibility extensions. - Factory-deployed tokens satisfy this automatically. For custom deployments, - inherit `InitiaCustomERC20` (recommended for direct deployment). + The fee token ERC20 must implement Initia-compatible chain hooks, especially + `sudoTransfer`, which is used by chain-level transfer handling. Tokens + deployed via `ERC20Factory` satisfy this requirement by default. For custom + ERC20 deployments, the token contract must inherit `InitiaCustomERC20`. ```ts diff --git a/resources/developer/contract-references/evm/initia-custom-erc20.mdx b/resources/developer/contract-references/evm/initia-custom-erc20.mdx index ecdf327f..7067f4fd 100644 --- a/resources/developer/contract-references/evm/initia-custom-erc20.mdx +++ b/resources/developer/contract-references/evm/initia-custom-erc20.mdx @@ -230,8 +230,10 @@ Transfers tokens from one address to another, bypassing the usual access control checks. This function can only be called by the chain signer. - For Cosmos-side transfer handling in Initia ERC20 flows, `sudoTransfer` is the - key transfer hook used by chain-level logic. + For MiniEVM ERC20 tokens, `sudoTransfer` is a required hook in the token + contract. If you deploy through `ERC20Factory` or inherit `InitiaCustomERC20`, + it is included automatically. Without it, sending and bridging may fail even + if the token appears in UIs. ```solidity