HyperCore <> HyperEVM transfers

Introduction

Spot assets can be sent between HyperCore and the HyperEVM. In the context of these transfers, spot assets on HyperCore are called Core spot while ones on the EVM are called EVM spot. The spot deployer can link their Core spot asset to any ERC20 contract deployed to the EVM. The Core spot asset and ERC20 token can be deployed in either order.

As the native token on HyperCore, HYPE also links to the native HyperEVM balance rather than an ERC20 contract.

System Addresses

Every token has a system address on the Core, which is the address with first byte 0x20 and the remaining bytes all zeros, except for the token index encoded in big-endian format. For example, for token index 200, the system address would be 0x20000000000000000000000000000000000000c8 .

The exception is HYPE, which has a system address of 0x2222222222222222222222222222222222222222 .

Transferring HYPE

HYPE is a special case as the native gas token on the HyperEVM. HYPE is received on the EVM side of a transfer as the native gas token instead of an ERC20 token. To transfer back to HyperCore, HYPE can be sent as a transaction value. The EVM transfer address 0x222..2 is a system contract that emits event Received(address indexed user, uint256 amount) as its payable receive() function. Here user is msg.sender, so this implementation enables both smart contracts and EOAs to transfer HYPE back to HyperCore. Note that there is a small gas cost to emitting this log on the EVM side.

Transferring between Core and EVM

Only once a token is linked, it can be converted between HyperCore and HyperEVM spot using a spotSend action (or via the frontend) and on the EVM by using an ERC20 transfer.

Transferring tokens from HyperCore to HyperEVM can be done using a spotSend action (or via the frontend) with the corresponding system address as the destination. The tokens are credited by a system transaction that calls transfer(recipient, amount) on the linked contract as the system address, where recipient is the sender of the spotSend action.

Transferring tokens from HyperEVM to HyperCore can be done using an ERC20 transfer with the corresponding system address as the destination. The tokens are credited to the Core based on the emitted Transfer(address from, address to, uint256 value) from the linked contract.

Do not blindly assume accurate fungibility between Core and EVM spot. See Caveats for more details.

Linking Core and EVM Spot Assets

In order for transfers between Core spot and EVM spot to work the token's system address must have the total non-system balance on the other side. For example, to deploy an ERC20 contract for an existing Core spot asset, the system contract should have the entirety of the EVM spot supply equal to the max Core spot supply. Once this is done the spot deployer needs to send a spot deploy action to link the token to the EVM:

/**
 * @param token - The token index to link
 * @param address - The address of the ERC20 contract on the evm.
 * @param evmExtraWeiDecimals - The difference in Wei decimals between Core and EVM spot. E.g. Core PURR has 5 weiDecimals but EVM PURR has 18, so this would be 13. evmExtraWeiDecimals should be in the range [-2, 18] inclusive
 */
interface RequestEvmContract {
  type: “requestEvmContract”;
  token: number;
  Address: address;
  evmExtraWeiDecimals: number;
}

After sending this action, HyperCore will store the pending EVM address to be linked. The deployer of the EVM contract must then verify their intention to link to the HyperCore token in one of two ways:

1. If the EVM contract was deployed from an EOA, the EVM user can send an action using the nonce that was used to deploy the EVM contract.

2. If the EVM contract was deployed by another contract (e.g. create2 via a multisig), the contract's first storage slot must store the HyperCore deployer's address. This can be done at initialization by defining the first state variable in solidity.

To finalize the link, a finalizer sends the following action (note that this not nested in a spot deploy action). In the "create" case, the EVM deployer sends the action, and in the "firstStorageSlot" case, the Core token deployer sends the action.

/**
 * @param input - One of the two EVM deployer options above
 */
interface FinalizeEvmContract {
  type: “finalizeEvmContract”;
  token: number;
  input: {"create": {"nonce": number}} | "firstStorageSlot"};
}

Caveats

There are currently no checks that the system address has sufficient supply or that the contract is a valid ERC20, so be careful when sending funds.

In particular, the linked contract may have arbitrary bytecode, so it's prudent to verify that its implementation is correct. There are no guarantees about what the transfer call does on the EVM, so make sure to verify the source code and total balance of the linked EVM contract.

If the EVM contract has extra Wei decimals, then if the relevant log emitted has a value that is not round (does not end in extraEvmWeiDecimals zeros), the non-round amount is burned (guaranteed to be <1 Wei). This is true for both HYPE and any other spot tokens.

Mainnet PURR

Mainnet PURR is deployed as an ERC20 contract at 0x9b498C3c8A0b8CD8BA1D9851d40D186F1872b44E with the following code. It will be linked to PURR on HyperCore once linking is enabled on mainnet.

// SPDX-License-Identifier: MIT
pragma solidity 0.8.28;

import "@openzeppelin/contracts/token/ERC20/extensions/ERC20Permit.sol";

contract Purr is ERC20Permit {
    constructor() ERC20("Purr", "PURR") ERC20Permit("Purr") {
        address initialHolder = 0x2000000000000000000000000000000000000001;
        uint256 initialBalance = 600000000;

        _mint(initialHolder, initialBalance * 10 ** decimals());
    }
}

Final Notes

Attached is a sample script for deploying an ERC20 token to the EVM and linking it to a Core spot token.

39KB

evm_erc20.py