How to interact with Althea L1

The goal of this page is to provide a summary of Althea L1 for chain integrators that is concise enough to read in one sitting yet detailed enough to direct the reader to any further information they may need.

Althea L1 runs a modified version of Ethermint which is a system for operating an EVM as a module in CosmosSDK blockchain using the CometBFT delegated proof of stake consensus system.

Sending transactions

Transactions can be sent on either the EVM layer or the CosmosSDK layer using standard tools for each environment.

CosmosSDK transactions

There are a variety of ways to send CosmosSDK transactions due to a history of Legacy RPC formats that have never been fully removed.

We would recommend either using pre-existing tools, or if you are implementing new tools using GRPC endpoints for both querying and sending transactions. They are both more performant and forward looking.

Libraries for CosmosSDK transactions

Rust

DeepSpace - maintained by Althea contributors, pure GRPC
cosmrs - CosmosSDK maintained, pure GRPC

Javascript

altheajs - Maintained by Althea contributors, uses the REST endpoint
cosmjs - CosmosSDK maintained, REST rpc

Since CosmosSDK itself is written in Go simply import some of the client commands.

DeepSpace specifically has ready-made functionality for sending Althea L1 microTX messages from embedded devices.

EVM transactions

EVM transactions can be submitted using the standard Ethereum Json-RPC format. Applications should target the Paris hardfork and avoid using any of the unimplemented EIP listed in the “List of EIP differences” sections. Since the list of differences does not include the signing method or any of the more significant EIPs standard EVM tooling is fully compatible in all cases we have tested so far. Follow your own preference for frontend EVM libraries.

Libraries for Embedded EVM development

Since Althea L1 is focused on iFi applications that generally run on embedded devices, we recommend these the following libraries for embedded use, although any EVM library will do.

Clarity An embedded focused and cross-compile friendly EVM client in Rust maintained by Althea contributors. Should compile to any platform target supported by the Rust language and can be easily modified to work in nostd environments. The associated RPC client library Web30 will compile to any target supporting Linux. Alloy A mainstream highly capable Rust library for EVM chains. Usable on x86 or ARM. Web3.py useful in any environment supporting Python Geth Go language support, usable on x86 or ARM.

Unfortunately there are no credible C or C++ clients for EVM platforms that we know of at this time.

How does the EVM interact with the CosmosSDK

For those not familiar with Ethermint or the CosmosSDK this can be opaque but the behavior is fairly intuitive once some basic behavior is understood.

You can think of a CosmosSDK chain as a modular but not programmable blockchain. Meaning all the potential transaction types, their functions, and how they may execute is decided at development time and baked into the CosmosSDK module code that handles functions like staking, delegating, token balances, token transfers.

This is a very different philosophy than say Ethereum. In Ethereum and ETH based chains the design is so EVM centric that fixed function parts of the chain, like transaction fee handling or sending Ether without calling a contract don’t draw much attention. This is vastly different than the CosmosSDK experience where the ‘bank’ module manages balances of many tokens and has complex functionality like multiple sends, allowing other parties to relay transactions on your behalf, etc.

The EVM in Althea L1 works as a Cosmos SDK module, meaning it’s combined with and does not replace the existing CosmosSDK modules and functions. How this works technically involves turning Geth itself into a module and merging what little native functionality Ethereum based chains have with the CosmosSDK equivalent.

ALTHEA is the native token both inside and outside of the EVM, meaning it’s used to pay fees when sending both Cosmos and EVM transactions. A user’s ALTHEA balance is merged between the EVM and the CosmosSDK bank module. Meaning if you transfer ALTHEA using a native EVM tx it will show up in the user’s balance if you query the bank module. Likewise if you transfer ALTHEA to a user using the bank module it will show in the user’s ALTHEA balance.

There are some quirks of this native balance merging to keep in mind.

If you use a CosmosSDK bank module send transaction to send ALTHEA to another user the funds will show in their EVM account but not generate any transaction id in a block on the EVM side. There will be a CosmosSDK tx to query using Cosmos RPC
If you use the EVM to send a basic transfer of ALTHEA between accounts, that tx can be referenced from both an EVM txid and a CosmosSDK txid.

This holds generally, that every EVM tx has a CosmosSDK txid and an EVM txid, but not every CosmosSDK tx can be queried or accessed from the EVM.

Since the EVM only has the concept of a single native token, which ALTHEA fills in this case, all other token balances are not merged between the different environments.

Block Explorer and TX visibility notes

Because the EVM is simply a module on Althea L1 this creates some edge cases around how transactions are visible when querying blocks. You can query any block from the CosmosSDK layer using the Cosmos REST or GRPC API, or from the EVM layer using the ETH JSON-RPC API.

1) All EVM transactions are visible on CosmosSDK block queries as EVM transaction types 2) No CosmosSDK transactions are visible in EVM block queries

Due to the merged balance handling of ALTHEA token this results in one edge case worth mentioning. When a user sends a CosmosSDK bank transfer of ALTHEA to another address the ALTHEA will show up in an EVM account with no transaction in a historical block matching that transfer. Outside of this edge case all EVM activity will show up in the EVM block and event history as expected.

Gas and transaction cost notes

EVM gas and CosmosSDK gas costs are syncronized between environments and currently set to 1*10^-7 ALTHEA per gas unit. Such that a transaction using 200,000 gas would cost 0.02 ALTHEA. This value can be changed by governance and you should not hardcode it. Instead alwyas simulate your transaction. It’s useful to note that while the cost of gas is the same between the EVM and CosmosSDK the way the gas utilized by a given operation is computed is significantly different. A Bank module MsgSend in the CosmosSDK environment uses about 130K CosmosSDK gas, this is almost 5 times more than a basic ALTHEA Send in the EVM which will cost a mere 24K EVM gas. Due to the merged ALTEHA balances this results in an odd corner case where it’s objectively always better for the user to perform EVM sends between compatible accounts.

Other transaction types such as staking, voting, or say an ERC20 transfer within the EVM aren’t directly equivalent in the same way basic a basic ALTEHA transfer can be achived either inside or outside the EVM.

Due to the previously noted TX visibility rules CosmosSDK blocks and EVM blocks may not have the same gas usage as visible via RPC queries. If a block contains all EVM transactions the gas usage of both blocks will be the same. If CosmosSDK transactions are included then the total gas usage will only be visible on the Cosmos RPC side and be equal to the EVM transaction gas used + the Cosmos gas used.

If you are trying to compute fee burn amounts only EVM transactions burn fees. So you only need to query EVM blocks to compute burn and standard Ethereum tools to compute totals will be correct. The ALTHEA spent on CosmosSDK transactions is given the validator as a reward to include it in a block, this helps align incentives as staking, voting, and delegation transactions in the CosmosSDK environment are essential for continued operation of the chain. Unlike EVM transactions which can always be safely excluded in the case that a valdiator has more profitable MicroTX or CosmosSDK transactions available to include.

Linking ERC20 with Cosmos Bank module tokens

For all tokens besides native ALTHEA balances are not merged between the EVM and CosmosSDK environments. In order to convert between CosmosSDK bank module tokens and EVM ERC20 tokens the ‘ERC20’ module is provided. The biggest reason to use this functionality is to allow ERC20 tokens in the Althea L1 evm to be bridged to other chains via CosmosSDK’s integrated bridge stack IBC. Or to create a representation of an IBC token as an ERC20 inside the Althea L1 EVM.

Using the integrated CosmosSDK governance module one of two proposals is submitted a RegisterCoinProposal for a Bank module token -> ERC20 representation in the EVM or a RegisterERC20Proposal for converting an ERC20 deployed in the Althea L1 EVM into a CosmosSDK bank ‘coin’ which can be bridged via IBC to other destinations.

Once governance has passed either of the above proposals MsgConvertCoin or MsgConvertERC20 can be used from the CosmosSDK environment to move governance registered tokens into or out of the EVM permissionlessly.

From within the EVM you can send convertible ERC20 tokens to the address 0x47EeB2eac350E1923b8CBDfA4396A077b36E62a0 (the hash of the string ‘erc20’ as an address) and they will appear in the sender’s equivalent bech32 key Cosmos account.

The Althea L1 EVM

The Althea L1 EVM behaves identically to a standard Ethereum chain on the ‘Paris’ hardfork. With the same JSON-RPC implementation and the same signing style. Existing tooling such as Metamask, Hardhat, Solidity, etc all work out of the box. Transactions that require functionality integrated post ‘Paris’ hardfork will find some incompatibility issues.

List of EIP differences

This is a list of all known EIP differences between current mainnet Ethereum and Althea L1’s EVM. Since Althea L1 is on the ‘Paris’ hardfork this is essentially a shortlist of changes made since that time. EIP for configuration options or non-EVM functionality are not included here. Keep in mind that Althea L1 may move forward to another Ethereum hardfork target in the future, adding support for some EIP’s in the process. Only implemented EIP are listed here, not proposed.

Note that consensus related EIP are generally marked with “Not relevant for CometBFT”. While we won’t completely rule out implementing some of these EIP in a way that maps to CometBFT validators it’s not probable.

Similarly for blob related EIP Althea L1 as a CometBFT fast finality chain has very different options for scaling that are discussed in the whitepaper. As such it’s improbable blobs in general will be implemented.

EIP-7702 - Not yet implemented
EIP-2537 - Not yet implemented
EIP-7623 - Not yet implemented
EIP-2935 - Not yet implemented
EIP-1153 - Not yet implemented
EIP-5656 - Not yet implemented
EIP-6780 - Not yet implemented
EIP-3651 - Not yet implemented
EIP-3855 - Not yet implemented
EIP-3860 - Not yet implemented
EIP-7251 - Not relevant for CometBFT consensus
EIP-7002 - Not relevant for CometBFT consensus
EIP-6110 - Not relevant for CometBFT consensus
EIP-7549 - Not relevant for CometBFT consensus
EIP-7002 - Not relevant for CometBFT consensus
EIP-4788 - Not relevant for CometBFT consensus
EIP-4895 - Not relevant for CometBFT consensus
EIP-7516 - Blob related, not implemented
EIP-4844 - Blob related, not implemented
EIP-4844 - Blob related, not implemented
EIP-7691 - Blob related, not implemented

Addresses, address formats, signature formats, and key derivation paths

Althea L1 uses both Bech32 format addresses with the prefix ‘althea’ as well as EIP-55 formatted Ethereum addresses. The command althea debug addr can be used to translate between a bech32 address and its equivalent EIP-55 address.

Native ALTHEA balances are merged between the EVM and CosmosSDK bank module and therefore sending ALTHEA token to either address is interchangeable.

Not all keys are EVM compatible

Althea L1 supports three key types tm-ed25519, secp256k1, and eth-secp256k1. The first is only allowed for consensus and the last is the only one compatible with EVM accounts and the only account type where it’s possible to use the bech32 address or EIP-55 address interchangeably.

secp256k1 accounts (default cosmos key types) can’t be used in the EVM as they would not produce EVM compatible signatures. They can be used for all other actions on Althea L1.

If you perform a bech32 to EIP-55 account conversion and send ALTHEA token to that converted EIP-55 address, funds will be lost. There is no way to recover those funds

By default all generated keys are eth-secp256k1 keys, so with few exceptions most users should never encounter these issues. As a general recommendation we advise avoiding performing address type conversion unless you own the key yourself.

Note Althea L1 may add new key types in the future.

Key derivation paths

Cosmos Key Path m/44'/118'/0'/0/0 Ethereum Key Path m/44'/60'/0'/0/0

These two key derivation paths are in use on Althea L1. Once again the default matches Ethereum and means that seed phrases should produce the same address when imported in the althea CLI and when imported into a standard EVM wallet such as Metamask.

Bridges on Althea L1

This section covers both current bridges and bridging in general on Althea L1.

IBC

Currently IBC is the only bridge protocol operating on Althea L1 with the following available destinations.

Gravity Bridge Noble

Gravity Bridge

Gravity Bridge is a decentralized Ethereum mainnet <-> IBC bridge that connects any chain that supports IBC to Ethereum mainnet permissionlessly. While any token from Ethereum can be brought to Althea L1 permissionlessly it requires a RegisterCoinProposal to be submitted and pass governance before it can be wrapped into an ERC20 in the Althea EVM.

For Bridge providers

EVM bridges can be deployed in the Althea L1 EVM environment permissionlessly and will function as they would on any other EVM based chain with only one quirk. When ALTHEA is transferred on the CosmosSDK side it will appear in a client’s account with a transaction that is not queryable from the EVM. Using ERC20 tokens rather than the native token will avoid this issue.

Thanks to CometBFT consensus Althea L1 has instant irrevocable finality on any block. So it is safe to unlock funds on other chains after a single block confirmation on Althea L1