Account Mapping Contracts

TinyGo WASM smart contracts that bridge account-based blockchains (EVM and ERC-20 compatible) to the VSC/Magi network.

Companion to vsc-eco/utxo-mapping, which covers UTXO-based chains (BTC, LTC, DASH, DOGE, BCH).

Supported Chains

Contract	Chain(s)	Asset
evm-mapping-contract	Ethereum + any EVM L2 (Arbitrum, Optimism, Base, …)	ETH + ERC-20

Chain selection is compile-time via the NetworkMode ldflag and runtime via setChainId.

How It Works

The contract verifies on-chain deposit proofs (receipt-trie inclusion against a stored block header) and credits the depositor's VSC account with a wrapped token balance. Withdrawals (unmapping) construct and TSS-sign an EVM transaction, returning funds to the user's external address.

Contract Actions

Deposit & transfer:

• map — process an incoming deposit with a receipt-trie proof
• transfer / transferFrom / approve / increaseAllowance / decreaseAllowance — ERC-20-style balance operations on mapped tokens
• confirmSpend — finalize a pending unmap after its tx confirms on-chain

Withdrawal:

• unmapETH — withdraw native ETH to an external address
• unmapERC20 — withdraw a registered ERC-20 token
• unmapFrom — withdraw on behalf of a third party via allowance
• replaceWithdrawal — replace a stuck withdrawal tx (e.g. for fee bump)
• clearNonce — reset the contract's EVM nonce tracker after an on-chain rollback

Chain relay:

• addBlocks — oracle appends new EVM block headers
• replaceBlock — replace the tip header after a reorg

Admin / owner:

• registerPublicKey — register TSS primary + backup keys
• registerRouter — register the DEX router contract
• registerToken — whitelist an ERC-20 contract
• setVault — set the 20-byte EVM vault address holding mapped funds
• setChainId — set the EIP-155 chain ID
• setGasReserve — set the gas buffer retained for withdrawal txs
• adminMint — emergency mint (owner-only)

Repo Layout

evm-mapping-contract/
├── Makefile                 # TinyGo build targets (dev/testnet/mainnet/…)
├── go.mod, go.sum
├── contract/                # on-chain logic
│   ├── main.go              # wasmexport entry points
│   ├── blocklist/           # EVM block header relay + reorg
│   ├── mapping/             # deposit/withdrawal flow
│   ├── crypto/              # keccak, RLP, receipt decoding
│   ├── constants/
│   └── contracterrors/
├── monitor/                 # off-chain helpers (scanner, receipt encoding)
├── sdk/                     # VSC WASM runtime bindings
└── runtime/                 # TinyGo GC shim (leaking allocator)

Build

cd evm-mapping-contract
USE_DOCKER=1 make testnet   # -> bin/testnet.wasm
USE_DOCKER=1 make mainnet   # -> bin/mainnet.wasm
USE_DOCKER=1 make dev       # -> bin/dev.wasm (regtest)
make test                   # Go tests (no TinyGo)

Docker is recommended because TinyGo 0.39 requires Go 1.19–1.25 and most dev boxes run newer Go.

License

See upstream at vsc-eco/utxo-mapping — same license applies.