The ISC Magic Contract

EVM and ISC are inherently very different platforms. Some EVM-specific actions (e.g., manipulating Ethereum tokens) are disabled, and EVM contracts can access ISC-specific functionality through the ISC Magic Contract.

The Magic contract is an EVM contract deployed by default on every ISC chain, in the EVM genesis block, at address 0x1074000000000000000000000000000000000000. The implementation of the Magic contract is baked-in in the evm core contract); i.e. it is not a pure-Solidity contract.

The Magic contract has several methods, which are categorized into specialized interfaces: ISCSandbox, ISCAccounts, ISCUtil and so on. You can access these interfaces from any Solidity contract by importing the ISC library.

The Magic contract also provides proxy ERC20 contracts to manipulate ISC base tokens and native tokens on L2.

Examples

Calling getEntropy()

pragma solidity >=0.8.5;

import "@iscmagic/ISC.sol";

contract MyEVMContract {
    event EntropyEvent(bytes32 entropy);

    // this will emit a "random" value taken from the ISC entropy value
    function emitEntropy() public {
        bytes32 e = ISC.sandbox.getEntropy();
        emit EntropyEvent(e);
    }
}

In the example above, ISC.sandbox.getEntropy() calls the getEntropy method of the ISCSandbox interface, which, in turn, calls ISC Sandbox's GetEntropy.

Calling a native contract

You can call native contracts using ISC.sandbox.call:

pragma solidity >=0.8.5;

import "@iscmagic/ISC.sol";

contract MyEVMContract {
    event EntropyEvent(bytes32 entropy);

    function callInccounter() public {
        ISCDict memory params = ISCDict(new ISCDictItem[](1));
        bytes memory int64Encoded42 = hex"2A00000000000000";
        params.items[0] = ISCDictItem("counter", int64Encoded42);
        ISCAssets memory allowance;
        ISC.sandbox.call(ISC.util.hn("inccounter"), ISC.util.hn("incCounter"), params, allowance);
    }
}

ISC.util.hn is used to get the hname of the incounter countract and the incCounter entry point. You can also call view entry points using ISC.sandbox.callView.

API Reference

• Common type definitions
• ISC library
• ISCSandbox interface, available at ISC.sandbox
• ISCAccounts interface, available at ISC.accounts
• ISCUtil interface, available at ISC.util
• ERC20BaseTokens contract, available at ISC.baseTokens (address 0x1074010000000000000000000000000000000000)
• ERC20NativeTokens contract, available at ISC.nativeTokens(foundrySN) after being registered by the foundry owner by calling registerERC20NativeToken (address 0x107402xxxxxxxx00000000000000000000000000 where xxxxxxxx is the little-endian encoding of the foundry serial number)
• ERC20ExternalNativeTokens contract, available at a dynamically assigned address after being registered by the foundry owner by calling registerERC20NativeTokenOnRemoteChain on the chain that controls the foundry.
• ERC721NFTs contract, available at ISC.nfts (address 0x1074030000000000000000000000000000000000)
• ERC721NFTCollection contract, available at ISC.erc721NFTCollection(collectionID), after being registered by calling registerERC721NFTCollection.

There are some usage examples in the ISCTest.sol contract (used internally in unit tests).