TWAMM streams

Available on Go-Gateway and Cloud API

• About TWAMM

• How does it work?

• Capturing arbitrage

• The TWAMM bloXroute service

• TWAMM Data Streams Details

  • Virtual Pool Stream

  • Order Stream

  • Order Pool Stream

About TWAMM

Time-weighted automated market makers aka TWAMMs (pronounced "tee-wham") are a special class of AMMs that execute orders over multiple blocks, a concept introduced by researchers at Paradigm together with the inventor of Uniswap.

TWAMMs aim to help traders on Ethereum execute large orders with minimal slippage and low gas fees without negatively affecting the price. The first, and currently only, TWAMM by Cron Finance.

How does it work?

Each TWAMM instance facilitates trading between a particular pair of assets, for example, ETH and USDC. The TWAMM contains an embedded AMM, a standard constant-product market maker for those two assets. Traders can submit long-term orders to the TWAMM, which are orders to buy or sell a fixed amount of one of the assets over a fixed number of blocks.

Capturing arbitrage

The execution of long-term orders pushes the embedded AMM's price away from prices on other markets over time. When this happens, searchers can trade against the embedded AMM's price to bring it back in line, ensuring good execution for long-term orders.

Users of bloXroute TWAMM services are entitled to a discounted fee (see details below). The discounted fee provides arbitrage opportunities earlier than arbitrage from the mempool without TWAMM discounted fee.

The TWAMM bloXroute service

bloXroute provides several new data streams to enable users to see and act fast when opportunities come up. Additional details about the various streams can be found below.

Sending TWAMM orders incurs a fee paid to Cron Finance in accordance with their fee schedule here.

Using the TWAMM bloXroute service will give you access not only to the fastest data stream but also to a 50% TWAMM transaction fee discount.

To get the discount please contact [e-mail]

Payment for the service is 10% of MEV profit to be paid to bloXroute as part of the arbitrage transaction.

• When capturing the arbitrage a searcher should include an internal transaction that is paying 10% of the MEV profit to the bloXroute wallet.

• To ensure faster execution, no check is being done prior to the execution of the transaction. However, searchers that will not comply with the program will be removed from it and will not receive the discount.

• Payment should be paid to the following address: 0x965df5ff6116c395187e288e5c87fb96cfb8141c

TWAMM Data Streams Details

Virtual Pool Stream

This endpoint provides the actual status of each TWAMM instance (also referred to as “pool”).

Response Event

Field	Type	Description
blockHeight	uint64	Current Ethereum block height.
virtualPool	virtualPool	See virtualPool below for details.

virtualPool

Field	Type	Description
poolID	string	The index id of the pool.
token0Symbol	string	The symbol of one token in the pool.
token0Address	string	The address of one token in the pool.
virtualToken0Reserve	unit64	The expected reserve amount of one token in the pool, considering the virtual TWAMM events.
token1Symbol	string	The symbol of another token in the pool.
token1Address	string	The address of another token in the pool.
virtualToken1Reserve	unit64	The expected reserve amount of the another token in the pool, considering the virtual TWAMM events.
salesRateToken0	unit64	The amount of token 0 being sold this block.
salesRateToken1	unit64	The amount of token 1 being sold this block.
orders	orders	See orders below for detail.

orders

Field	Type	Description
orderID	uint64	Unique ID for the order.
sender	string	The initiator address of the transaction.
tokenIn	string	Swap in token symbol.
tokenOut	string	Swap out token symbol.
startBlock	unit64	The block height where this TWAMM swap started.
endBlock	uint64	The block height where this TWAMM swap is expected to be finished.

Event Example

{
    "blockHeight:16799598",
    "pool": {
        "poolID": "0x69269Fe1945e018727Dd301790a465E357a9063B",
        "token0Symbol":"USDC",
        "token0Address":"0x07865c6E87B9F70255377e024ace6630C1Eaa37F",
        "virtualToken0Reserve":85093566, 
        "token1Symbol":"WETH",
        "token1Address":"0xB4FBF271143F4FBf7B91A5ded31805e42b2208d6",
        "virtualToken1Reserve":18446744073579229056, 
        "salesRateToken0":"18557",
        "orders": [{
            "sender":"0xFD59D945c10C6884eB88787E27f3083C6336aB7A" 
            "tokenIn":"USDC" 
            "tokenOut":"WETH" 
            "originalInAmount":10000000 
            "virtualInAmount":10000000 
            "startBlock":16799597 
            "endBlock":16800368
        }]
    }
}

Order Stream

This endpoint returns any transaction interacting with a TWAMM instance. Including creating new orders, canceling orders, etc.

Response Event

Field	Type	Description
blockHeight	uint64	Current Ethereum block height.
order	order	See order below for details.

orders

Field	Type	Description
confirmationLevel	string	The confirmation level of the order transaction. The value could be CL_UNKNOWN, CL_NEW, CL_PENDING, CL_BLOCK.
orderType	string	The type of the order. The value could be OT_UNKNOWN, OT_NEW, OT_CANCEL.
swapTyep	string	The type of the swap. The value could be ST_LONG_TERM, ST_PARTNER_SWAP, ST_UNKNOWN.
poolID	string	The index id of the pool.
sender	string	The initiator address of the transaction.
tokenIn	string	Swap in token symbol.
tokenOut	string	Swap out token symbol.
amount	unit64	Amount of the swap in token.
adjustedAmount	double	Amount of the swap in token, converted to human readable with decimals.
intervals	uint64	Numbers of the intervals for this order.
blockCount	uint64	Number of blocks (derived from intervals)

Event Example

{
    "blockHeight":"8819399",
    "order":{
        "confirmationLevel":"CL_PENDING",
        "orderType":"OT_NEW",
        "swapType":"ST_LONG_TERM",
        "poolID":"0x69269Fe1945e018727Dd301790a465E357a9063B",
        "sender":"0x4836668594Ad7a6bae5ed39Eec1A0eB9e1e01dB6",
        "tokenIn":"0x07865c6E87B9F70255377e024ace6630C1Eaa37F",
        "tokenOut":"0xB4FBF271143F4FBf7B91A5ded31805e42b2208d6",
        "amount":"1000000",
        "adjustedAmount":1000000,
        "intervals":"3",
        "blockCount":"771",
        "txHash":"0xe2…96d7"
    }
}

How to Run Streams Through Cloud API

As of 7/20/2023, there is support for mainnet ethereum and goerli ethereum chains. To connect to these streams, you need to connect to cloud api. To do this, see here: https://docs.bloxroute.com/introduction/cloud-api-ips

In order to run the streams, you are going to need an authorization header that works with cloud API. Then, follow these instructions:

wscat -c wss://cloud-api-ip/ws -H "Authorization:Auth-header" --no-check

If the IP address and authorization header work, you should see a successful connection response.

Connected (press CTRL+C to quit)
> 

Here are some sample commands to use the TWAMM streams (for each stream):

virtualPoolStream

{"id": 1, "method": "subscribe", "params": ["virtualPool", {"include": []}]}

To connect to this stream with specific pool address, use this command:

{"id": 1, "method": "subscribe", "params": ["virtualPool", {"include": [],"filter":["PoolID"=="xxxxx"]}]}

orderStream

"id": 1, "method": "subscribe", "params": ["orderStream"]}

As of 7/20/2023, here are useful launched pools

wstETH/rETH (mainnet):

https://etherscan.io/address/0x6910C4e32D425a834Fb61e983C8083a84b0EBd01

0x6910C4e32D425a834Fb61e983C8083a84b0EBd01

USDC/WETH (mainnet): https://etherscan.io/address/0x0018C32D85D8AebEA2eFbE0b0F4a4Eb9e4F1C8C9

0x0018C32D85D8AebEA2eFbE0b0F4a4Eb9e4F1C8C9

USDC/WETH (goerli testnet): https://goerli.etherscan.io/address/0x28d56210D3682F89dD3AF3542F7a05259358bb22#internaltx

0x28d56210D3682F89dD3AF3542F7a05259358bb22

How to Submit an Arbitrage ("Partner") Swap

In order to submit swaps that execute instantly on the TWAMM pool, one must be an affiliated partner with the TWAMM pool smart contract. bloxRoute has a partnership with TWAMM, that gives us discounted fees and also allows this swap to be executed. For more information about partner swaps and their affiliated contract, see here: https://docs.cronfi.com/twamm/fundamentals/admin-privileges (towards the bottom of the page).

The parter address that is bloxRoute's partner address is:

0xa3bf741ea039C1A6Da55CE91958fceF2bBC1930d

The Arbitrage Partner Contract can be found here. https://etherscan.io/address/0x01Ce5b536e6629F3ABC664f7EF530108BcBb6A9B. This contract controls who can be added to a "partner" list, but for all intents and purposes you should use the bloxRoute partner address above for the lower fee tier.

For actually submitting the swap, you need to construct a "short term swap" write call on the balancer contract (https://etherscan.io/address/0xBA12222222228d8Ba445958a75a0704d566BF2C8). We have some code samples below that can help you do this.

Golang: https://github.com/bloXroute-Labs/eth-trader-api/blob/develop/cmd/scripts/twamm_generator_mainnet/main.go

Python: https://github.com/bloXroute-Labs/twamm-trader-bot/blob/develop/src/bloxroute_dex.py#L388

For any additional help, you can reach out on the bloxRoute discord!

Here are some examples of an arbitrage transaction on TWAMM's low volume wstETH-rETH pool (they are making ~$15USD every transaction!): https://etherscan.io/tx/0xb7838c2b9d4993affae61d66101f32cd51361005bfe23781944aafcb06011552