> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aultblockchain.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Precompile: Token Registry

## Address

`0x0a01700000000000000000000000000000000004`

The Token Registry precompile exposes the `x/tokenregistry` module's conversion methods,
which move balances between an ERC20 contract and its paired Cosmos coin denom.

Conversions require both module-wide transfers and the specific token pair to be enabled.
Pair registration and enablement are permissioned operations performed by the chain
operators and are not part of this interface.

## Supported Methods

### Conversions

| Signature                                 |
| ----------------------------------------- |
| `transferToCore(address,uint256,address)` |
| `transferToEVM(address,uint256,address)`  |

This precompile is transaction-only; registry state is read through the Cosmos gRPC/REST
query service of `x/tokenregistry`.

### Events

`transferToCore` and `transferToEVM` deliberately emit **no** precompile event — the
post-tx settlement hook emits the standard ERC20 `Transfer` event instead.

## Two-Stage Conversion Model

Conversions do **not** settle inside the precompile call:

1. **Precompile stage** — all preconditions are validated and a pending conversion intent
   is written. The method returns `staged = true`.
2. **Post-tx hook stage** — the mint/burn and ERC20 transfer are executed and the ERC20
   `Transfer` event is emitted.

The model is strictly atomic: any failure in the settlement hook reverts the entire
transaction. A `true` return value therefore means "validated and queued", not
"balance already moved" — do not read balances back within the same call and expect the
conversion to be reflected.

Only one pending conversion intent is allowed per transaction, so a single transaction
cannot chain two conversions.

## Transaction Examples

Set the current testnet EVM JSON-RPC endpoint and precompile address:

> Security note:
> Use a keystore or hardware wallet for real operations.
> Do not pass raw private keys directly in shell commands.

```bash theme={null}
export RPC_URL="https://test-json-rpc.cloud.aultblockchain.xyz"
export TOKENREGISTRY_PRECOMPILE="0x0a01700000000000000000000000000000000004"
```

### Environment Variables

```bash theme={null}
cast wallet import ault-ops --interactive

export CAST_ACCOUNT="ault-ops"
export FROM="$(cast wallet address --account "$CAST_ACCOUNT")"

export ERC20="<0xtoken...>"
export RECIPIENT="<0xrecipient...>"
export AMOUNT="1000000000000000000"
```

### Direct call

Convert ERC20 to the paired Cosmos coin:

```bash theme={null}
cast send "$TOKENREGISTRY_PRECOMPILE" \
  "transferToCore(address,uint256,address)" \
  "$ERC20" \
  "$AMOUNT" \
  "$RECIPIENT" \
  --rpc-url "$RPC_URL" \
  --account "$CAST_ACCOUNT"
```

Convert the Cosmos coin back to ERC20:

```bash theme={null}
cast send "$TOKENREGISTRY_PRECOMPILE" \
  "transferToEVM(address,uint256,address)" \
  "$ERC20" \
  "$AMOUNT" \
  "$RECIPIENT" \
  --rpc-url "$RPC_URL" \
  --account "$CAST_ACCOUNT"
```

## ABI

<a href="/assets/abi/tokenregistry_precompile_abi.json" download>
  Download Token Registry ABI JSON
</a>