Skip to main content

Mapped tokens mechanism

[Token Shield] Mapped tokens mechanisms


This is a note on composable security mechanisms for bridging tokens between two systems based on the ability to observe non-bridge token transfers by the other system.



  • Give conversion guarantees to bridged tokens even when the layer 1 bridge creation mechanism is broken. :::


The problem we are discussing is how to make a bridge between two systems fail with as little collateral damage as possible.

Minting or releasing tokens at layer 1 is required when moving tokens from layer 2 to layer 1.

This can happen using various techniques (optimistic, n of m signatures, state proof etc) which have various upsides and downsides.

In this discussion we assume there is a mechanism for minting tokens, and we look at what happens when this mechanism fail.

We can generalize to the case where a smart contract at layer 1 holds tokens and releases them. We will also refer to this as "minting" tokens in this discussion.

The mapping mechanism

The mapping mechanism consists of attaching properties to tokens to track whether they are covered by collateral in the other system. We call tokens that are correctly minted as mapped, and those that are incorrectly minted as unmapped.

In a properly working bridge, all tokens are mapped, but when

We define a failure of the minting mechanism to occur whenever a token is minted that does not

In this case, the bridge is

The assumed setup is a pair of contracts, one contract at layer 1 and one contract at layer 2.

The contract at layer 2 is equipped to observe everything happening at layer 1.

We assume that there are some tokens that exist at layer 2 and some that exist at layer 1. By moving tokens between the layers, the total number of tokens in the layers must be adjusted so the total is kept constant.

We have two classes of tokens at layer 1: fixed supply and variable supply.

Overall framework

For the ERC20 CWEB with fixed supply, tokens which are not circulating at L1 must be held in escrow. L1 smart contracts (L1SC) implement this behavior

The mechanism

We describe the mechanism as simply as possible, excluding multi-pool and L2 collateral requirements.

The protocol defines a Holding behavior which is a way

A type of SCL1 that holds tokens and behaves in a certain way is given the power to smart contract that holds

The smart contract controlling the pool at layer 1 (SCL1) is registered at layer 2 (SCL2) to be monitored.

In the case of the initial unwrapping of ERC20 CWEB tokens, the SCL1 must be

At layer 1, a contract can receive token


Handling fraudulent layer 1 minting

Minting tokens at layer 1 requires a trusted party or mechanism. The mechanism can be a trusted positive capability to mint, where the trusted party or mechanism can directly mint tokens, or it can be a trusted negative capability to deny minting, where the trusted party or mechanism can deny others from minting tokens. This is the most fragile part of handling transfers of tokens between the layers.

Layer 2 can detect fraudulent layer 1 minting, but it cannot do anything about it.

Flow rate control

One method that can be used to limit the possible amount of fraud layer 1 token holders can be exposed to, is to limit the flow of tokens in the layer 2 -> layer 1 direction.

This can be coded into the layer 1 contract so that a maximum amount of tokens can be minted per unit time.

Using a leaky bucket setup, small transfers can be done immediately, while only large transfers need to ways for some period of time to be completed.

Setting the flow rate can be done as a control theory based setup (PID controller, kalman filter) where the system adjusts to accepting the normal flow, as long as this flow is regular.

When fraudulent issuance of tokens are detected at layer 1, holders will have the option of immediately transferring their layer 1 tokens into layer 2 at an exchange rate that is just slightly lower than 1:1.

If the layer 1 minter has a bond that has a size similar to the flow for some unit of time, then lossless conversion can be guaranteed as long as participants detect the fraudulent issuance within the time period.

Treating fraudulently minted tokens as a separate token

If fraudulently minted tokens are allowed to increase the token supply at layer 1, then token holders will not be able to redeem layer 1 tokens for layer 2 tokens at the 1:1 rate, but will be subject to a worse exchange rate.

A coinweb light client, or the Coinweb API will be able to indicate whether layer 1 contains fraudulent tokens or not.

To incentivise users for the ERC-20 token to check whether to accept a transfer or not, it might be beneficial to let the recipients of invalid ERC-20 tokens take the burden of a lower exchange rate for their token, while shielding existing holders of the ERC-20 token.

This can be implemented by, at layer 2, consider fraudulently minted layer 1 tokens as a separate token, a token that is not exchangeable.

In such a model, layer 2 has two token amounts associated with each layer 1 address in an ERC-20 contract: valid tokens, and invalid tokens.

When a transfer is made at the ERC-20 layer, blended tokens which contain a fraction of valid tokens, and a fraction of invalid tokens, are transferred.

By doing it like this, old accounts would be able to move their layer 1 tokens with no penalty into layer 2 tokens, while only addresses that have accepted invalid tokens would be unable to convert their tokens.

Given that exchanges are typical recipients of tokens to be blended, it would be in their interest to check whether layer 1 is in sync with layer 2 before debiting the exchange account when receiving an ERC-20 deposit from a mirrored token like this. They would check this by querying Coinweb layer 2.

The effect of such a design would be that any liquidity pools would be the target of transfers, as they do not have protection against this. Thus the token value on Uniswap would plummet, while exchanges should simply stop accepting the token.

Token holders, on the other hand, would be able to convert their token into layer 2 tokens.

Circuit breakers

When layer 2 detects minting of invalid tokens at layer 1, a circuit breaker can be invoked. This process would consist of one or more external parties that run a system of surveillance of the layer 1 contract. When layer 2 indicates that layer 1 is not in sync or has issued invalid tokens, then the circuit breaker pause() can be invoked to stop all ERC-20 transfers.

If an attack is detected, stop() can be invoked, and state transferred to another contract.

A circuit breaker for minting new tokens, pause_minting() could also exist separately from other circuit breakers.

In order for the circuit breaker to be able to come into effect in time, an nn-block quarantine could be put on any address that has received newly minted tokens.

Self-minting of layer 1 tokens

If a user, in a single transaction, could mint layer 1 tokens and at the same time burn layer 2 tokens, that could be quite useful.

Using the circuit breaker approach from the previous section, as well as the nn-block quarantine, this should be possible. If, in addition, the minter would have to mint into their own address, where an existing amount were present, then the contents of the address could be used as a bond for the minting. In cases where a circuit breaker was pulled, the bond would be forfeited.

One operational advantage of self-minting is that the deployment is less exposed to fraud. An attacker who takes control of the circuit breaker can only deny minting of tokens, and when wrestling control of the contract back from the attacker, those wrongly denied their minted tokens can be made good, potentially.

This is a corner-case worth ensuring works. Wrongly denied minted tokens should stay around at layer 2 so minting ca

This does not preclude batching transactions though. An ERC-20 contract that can accept a batch of signed transfers in one go could be executed more cheaply.