# EVM

BitBadges runs the cosmos/evm module, so Solidity contracts deploy and run on the chain. This section is for developers who want to reach the token standard, liquidity pools, or native coins from a contract.

```text
Solidity contract -> precompile (Go) -> Cosmos SDK module keeper -> chain state
```

A precompile is a fixed contract address that runs native Go instead of EVM bytecode. Calling it gives a contract direct access to a Cosmos SDK module, with type conversion, validation, and error handling done on the Go side.

## The Three BitBadges Precompiles

| Precompile | Address | Module | Use it for |
| --- | --- | --- | --- |
| [Tokenization](https://docs.bitbadges.io/chain/evm/tokenization-precompile) | `0x0000000000000000000000000000000000001001` | `x/tokenization` | Collections, transfers, approvals, dynamic stores, address lists, votes |
| [GAMM](https://docs.bitbadges.io/chain/evm/gamm-precompile) | `0x0000000000000000000000000000000000001002` | `x/gamm` | Join and exit liquidity pools, single and multi-hop swaps, swap with IBC transfer, pool queries |
| [Send manager](https://docs.bitbadges.io/chain/evm/send-manager-precompile) | `0x0000000000000000000000000000000000001003` | `x/sendmanager` | Send native coins (including alias denoms such as `badgeslp:...`) from a contract without ERC20 wrapping |

All three take one `string calldata msgJson` argument per method. The JSON matches the protobuf JSON of the underlying Cosmos message. The caller (`msg.sender`) is set as the `creator` or `sender` on the Go side and cannot be spoofed. Addresses are the same on both sides: a `0x` address and its `bb1` bech32 form are the same 20 bytes.

The chain also ships the upstream [Cosmos SDK Precompiles](https://docs.bitbadges.io/chain/evm/cosmos-precompiles) (staking, distribution, bank, governance, IBC, bech32, P256) at `0x0000000000000000000000000000000000000100` through `0x0000000000000000000000000000000000000807`.

## Pages

| Page | Read it when |
| --- | --- |
| [Solidity Quickstart](https://docs.bitbadges.io/chain/evm/solidity-quickstart) | You want a working contract in five minutes. Constants, addresses, patterns, errors. |
| [Setup](https://docs.bitbadges.io/chain/evm/setup) | You need chain IDs, RPC ports, MetaMask, a deploy script, and a frontend hook. |
| [Developer Guide](https://docs.bitbadges.io/chain/evm/developer-guide) | You need the rules: who can sign what, address conversion, `msg.sender` in precompiles, 9 vs 18 decimals. |
| [Architecture](https://docs.bitbadges.io/chain/evm/architecture) | You want the call path and the Go package layout. |
| [Tokenization Precompile](https://docs.bitbadges.io/chain/evm/tokenization-precompile) | Overview, then [API](https://docs.bitbadges.io/chain/evm/tokenization-precompile/api), [Gas](https://docs.bitbadges.io/chain/evm/tokenization-precompile/gas), [Errors](https://docs.bitbadges.io/chain/evm/tokenization-precompile/errors), [Security](https://docs.bitbadges.io/chain/evm/tokenization-precompile/security). |
| [GAMM Precompile](https://docs.bitbadges.io/chain/evm/gamm-precompile) | Overview, then [API](https://docs.bitbadges.io/chain/evm/gamm-precompile/api) and [gotchas](https://docs.bitbadges.io/chain/evm/gamm-precompile/gotchas). |
| [Send Manager Precompile](https://docs.bitbadges.io/chain/evm/send-manager-precompile) | The `send` method. |
| [Cosmos SDK Precompiles](https://docs.bitbadges.io/chain/evm/cosmos-precompiles) | Staking, distribution, governance, IBC, bank, bech32, P256, slashing, ICS02. |
| [EVM RPC Endpoints](https://docs.bitbadges.io/chain/evm/rpc-endpoints) | Public JSON-RPC URLs, Hardhat and Foundry config, running your own JSON-RPC node. |

## Minimal Example

```solidity
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.0;

import "./interfaces/ITokenizationPrecompile.sol";
import "./libraries/TokenizationJSONHelpers.sol";

contract Example {
    ITokenizationPrecompile constant TOKENIZATION =
        ITokenizationPrecompile(0x0000000000000000000000000000000000001001);

    function balanceOf(uint256 collectionId, address user) external view returns (uint256) {
        string memory json = TokenizationJSONHelpers.getBalanceAmountJSON(
            collectionId, user, 1, block.timestamp * 1000
        );
        return TOKENIZATION.getBalanceAmount(json);
    }
}
```

The Solidity interfaces, helper libraries, and example contracts live in the chain repo under [`contracts/`](https://github.com/BitBadges/bitbadgeschain/tree/master/contracts). The [counter-dapp](https://github.com/BitBadges/bitbadgeschain/tree/master/counter-dapp) is an end-to-end example with a deploy script and a Next.js frontend.

## Related

- [Token Standard](https://docs.bitbadges.io/token-standard)
- [Network endpoints](https://docs.bitbadges.io/chain)
- [EVM Query Challenges](https://docs.bitbadges.io/token-standard/approval-criteria/evm-query-challenges)
- [Cosmos EVM documentation](https://docs.cosmos.network/evm/v0.5.0/documentation/overview)