Adds readme docs for all precompiles

precompiles/bank/README.md

@@ -0,0 +1,108 @@
+# Bank Precompile
+
+## Address
+
+`0x0000000000000000000000000000000000000804`
+
+## Description
+
+The Bank precompile provides read-only access to the Cosmos SDK `x/bank` module state through an EVM-compatible interface.
+This enables smart contracts to query native token balances and supply information
+for accounts and tokens registered with corresponding ERC-20 representations.
+
+## Interface
+
+### Methods
+
+#### balances
+
+```solidity
+function balances(address account) external view returns (Balance[] memory)
+```
+
+Retrieves all native token balances for the specified account.
+Each balance includes the ERC-20 contract address and amount in the token's original precision.
+
+**Parameters:**
+
+- `account`: The account address to query
+
+**Returns:**
+
+- Array of `Balance` structs containing:
+    - `contractAddress`: ERC-20 contract address representing the native token
+    - `amount`: Token balance in smallest denomination
+
+**Gas Cost:** 2,851 + (2,851 × (n-1)) where n = number of tokens returned
+
+#### totalSupply
+
+```solidity
+function totalSupply() external view returns (Balance[] memory)
+```
+
+Retrieves the total supply of all native tokens in the system.
+
+**Parameters:** None
+
+**Returns:**
+
+- Array of `Balance` structs containing:
+    - `contractAddress`: ERC-20 contract address representing the native token
+    - `amount`: Total supply in smallest denomination
+
+**Gas Cost:** 2,477 + (2,477 × (n-1)) where n = number of tokens returned
+
+#### supplyOf
+
+```solidity
+function supplyOf(address erc20Address) external view returns (uint256)
+```
+
+Retrieves the total supply of a specific token by its ERC-20 contract address.
+
+**Parameters:**
+
+- `erc20Address`: The ERC-20 contract address of the token
+
+**Returns:**
+
+- Total supply as `uint256`. Returns 0 if the token is not registered.
+
+**Gas Cost:** 2,477
+
+### Data Structures
+
+```solidity
+struct Balance {
+    address contractAddress;  // ERC-20 contract address
+    uint256 amount;          // Amount in smallest denomination
+}
+```
+
+## Implementation Details
+
+### Token Resolution
+
+The precompile resolves native Cosmos SDK denominations to their corresponding ERC-20
+contract addresses through the `x/erc20` module's token pair registry.
+Only tokens with registered token pairs are returned in query results.
+
+### Decimal Precision
+
+All amounts returned preserve the original decimal precision stored in the `x/bank` module.
+No decimal conversion is performed by the precompile.
+
+### Gas Metering
+
+The precompile implements efficient gas metering by:
+
+- Charging base gas for the first result
+- Incrementally charging for each additional result in batch queries
+- Consuming gas before returning results to prevent DoS vectors
+
+### Error Handling
+
+- Invalid token addresses in `supplyOf` return 0 rather than reverting
+- Queries for accounts with no balances return empty arrays
+- All methods are read-only and cannot modify state

precompiles/bech32/README.md

@@ -0,0 +1,93 @@
+# Bech32 Precompile
+
+## Address
+
+`0x0000000000000000000000000000000000000400`
+
+## Description
+
+The Bech32 precompile provides address format conversion between Ethereum hex addresses and Cosmos bech32 addresses.
+This enables smart contracts to interact with Cosmos SDK modules that require bech32-formatted addresses.
+
+## Interface
+
+### Methods
+
+#### hexToBech32
+
+```solidity
+function hexToBech32(address addr, string memory prefix) external returns (string memory bech32Address)
+```
+
+Converts an Ethereum hex address to bech32 format with the specified human-readable prefix (HRP).
+
+**Parameters:**
+
+- `addr`: The Ethereum address to convert
+- `prefix`: The bech32 human-readable prefix (e.g., "cosmos", "evmos")
+
+**Returns:**
+
+- Bech32-formatted address string
+
+**Validation:**
+
+- Prefix must be non-empty and properly formatted
+- Address must be a valid 20-byte Ethereum address
+- Reverts if bech32 encoding fails
+
+#### bech32ToHex
+
+```solidity
+function bech32ToHex(string memory bech32Address) external returns (address addr)
+```
+
+Converts a bech32-formatted address to Ethereum hex format.
+
+**Parameters:**
+
+- `bech32Address`: The bech32 address string to convert
+
+**Returns:**
+
+- Ethereum address in hex format
+
+**Validation:**
+
+- Input must be a valid bech32 address with proper formatting
+- Address must contain the separator character "1"
+- The decoded address must be 20 bytes
+- Reverts if bech32 decoding fails
+
+## Implementation Details
+
+### Gas Usage
+
+The precompile uses a configurable base gas amount for all operations.
+The gas cost is fixed regardless of string length *within reasonable bounds*.
+
+### Address Validation
+
+Both methods perform validation on the address format:
+
+- Hex addresses must be exactly 20 bytes
+- Bech32 addresses must conform to the bech32 specification
+- Invalid addresses result in execution reversion
+
+### Prefix Handling
+
+For `hexToBech32`:
+
+- The prefix parameter determines the human-readable part of the bech32 address
+- Common prefixes include account addresses, validator addresses, and consensus addresses
+- Empty or whitespace-only prefixes are rejected
+
+For `bech32ToHex`:
+
+- The prefix is automatically extracted from the bech32 address
+- No prefix parameter is required as it's embedded in the address
+
+### State Mutability
+
+Both methods are marked as `nonpayable` in the ABI but function as read-only operations.
+They do not modify blockchain state and could technically be seen as `view` functions.

precompiles/callbacks/README.md

@@ -0,0 +1,86 @@
+# Callbacks Interface
+
+## Description
+
+The Callbacks interface defines a standard for smart contracts to receive notifications about IBC packet lifecycle events.
+This is not a precompile with a fixed address, but rather an interface specification
+that contracts must implement to receive callbacks from the IBC module.
+
+## Interface
+
+### Methods
+
+#### onPacketAcknowledgement
+
+```solidity
+function onPacketAcknowledgement(
+    string memory channelId,
+    string memory portId,
+    uint64 sequence,
+    bytes memory data,
+    bytes memory acknowledgement
+) external
+```
+
+Called when an IBC packet sent by the implementing contract receives an acknowledgement from the destination chain.
+
+**Parameters:**
+
+- `channelId`: The IBC channel identifier
+- `portId`: The IBC port identifier
+- `sequence`: The packet sequence number
+- `data`: The original packet data
+- `acknowledgement`: The acknowledgement data from the destination chain
+
+**Invocation:**
+
+- Only called by the IBC module
+- Only invoked for packets sent by the implementing contract
+- Called after successful packet delivery and acknowledgement
+
+#### onPacketTimeout
+
+```solidity
+function onPacketTimeout(
+    string memory channelId,
+    string memory portId,
+    uint64 sequence,
+    bytes memory data
+) external
+```
+
+Called when an IBC packet sent by the implementing contract times out without being processed by the destination chain.
+
+**Parameters:**
+
+- `channelId`: The IBC channel identifier
+- `portId`: The IBC port identifier
+- `sequence`: The packet sequence number
+- `data`: The original packet data
+
+**Invocation:**
+
+- Only called by the IBC module
+- Only invoked for packets sent by the implementing contract
+- Called when packet timeout conditions are met
+
+## Implementation Requirements
+
+### Access Control
+
+Implementing contracts must ensure that only the IBC module can invoke these callback methods.
+This prevents unauthorized contracts from triggering callback logic.
+
+### State Management
+
+Contracts should maintain appropriate state to correlate callbacks with their original packet sends,
+typically using the sequence number as a unique identifier.
+
+### Error Handling
+
+Callback implementations should handle errors gracefully as failures in callback execution may affect the IBC packet lifecycle.
+
+### Gas Considerations
+
+Callback execution consumes gas on the source chain.
+Implementations should be gas-efficient to avoid transaction failures due to out-of-gas errors.