Asset Burning

Immutable X now supports asset burning :fire:

Burning describes the process of permanently removing tokens from circulation, and on mainnet Ethereum this is often achieved by transferring the asset to a designated burn address (e.g. the zero account). A burn address is not owned by any user and no one can feasibly guess its private key, so any assets owned by a burn address are considered lost forever.

On L2, we have a burn address (zero address - 0x00...0) paired with a non-zero stark key (0x00...01) as the designated burn address for Immutable X. The stark key must be non-zero because a zero stark key does not lie on the Stark elliptic curve and would therefore be invalid, so we chose the next closest key possible. As with the L1 burn account, finding the stark private key for this specific public key is practically impossible, so assets owned by this stark key will remain locked in the Stark smart contract forever and cannot be transferred or withdrawn.

To burn an asset, you need to transfer the asset to the burn address. We have added burn functions in the SDK for clarity, and these are just wrappers for standard transfer functions to this burn address. Using the transfer functions with the burn address as a recipient will also work just the same.

BurnEthAddress = 0x0000000000000000000000000000000000000000
BurnStarkKey   = 0x0000000000000000000000000000000000000000000000000000000000000001

ImmutableXClient

Explicit burn functions in the SDK (wrappers for transfer functions):

// import { ImmutableXClient } from '@imtbl/imx-sdk';
// client = ImmutableXClient.build({...})

await client.burn({
    sender: "<wallet-address>",
    token: {
        type: ERC721TokenType.ERC721,
        data:{
            tokenId: "123",
            tokenAddress: "0xacb3c6a43d15b907e8433077b6d38ae40936fe2c"
        }
    },
    quantity: 1,
});
// import { ImmutableXClient } from '@imtbl/imx-sdk';
// client = ImmutableXClient.build({...})

const getBurnResult = await client.getBurns();
// import { ImmutableXClient } from '@imtbl/imx-sdk';
// client = ImmutableXClient.build({...})

const getBurnsResult = await client.getBurn({ id: 123 }); // same as transfer id

Or using standard transfer function:

// import { ImmutableXClient } from '@imtbl/imx-sdk';
// client = ImmutableXClient.build({...})

await client.transfer({
    sender: "<wallet-address>",
    token: {
        type: ERC721TokenType.ERC721,
        data:{
            tokenId: "123",
            tokenAddress: "0xacb3c6a43d15b907e8433077b6d38ae40936fe2c"
        }
    },
    receiver: "0x0000000000000000000000000000000000000000",
    quantity: 1,
});

Burned assets will still show up in the response of getAssets (/assets API) with their status as 'burned'. This is a filterable field, so you can find all burned assets by querying the assets API:

// import { ImmutableXClient, ImmutableAssetStatus } from '@imtbl/imx-sdk';
// client = ImmutableXClient.build({...})

const burnedAssets = await client.getAssets({
    status: ImmutableAssetStatus.burned, // 'burned'
});

Link

To implement a burn feature for users on your frontend, you should use the link.transfer function with the recipient set as the burn address. Learn more.

// import { Link } from '@imtbl/imx-sdk';
// link = new Link(<link-url>)

const transferResponsePayload:TransferV2ResultsCodec = await link.transfer([
  {
    type: ERC721TokenType.ERC721,
    tokenId: "123",
    tokenAddress: "0xacb3c6a43d15b907e8433077b6d38ae40936fe2c",
    toAddress: '0x0000000000000000000000000000000000000000',
  },
]);

Multi-burns

When burning multiple assets in one go, you will be using the multi-transfer functionality in link.transfer. Keep in mind that this submits separate transfer transactions to the API. Although rare, it is possible to have some transfers fail while others succeed, so multi-burns (just like multi-transfers) are not an entirely atomic operation. We will be looking into adding support for atomic 'multi' transactions across all features in the future.

For use cases such as 'burn x NFTs to receive a new NFT', it is currently recommended to keep track of all successful and failed burns (provided in the link.transfer response), and implement a retry mechanism for users to complete their full burn before triggering the next step in the process.


Did this page help you?