- Add support for the TRANSFER function
- Add support for decoding the "revert on fail" flag and prepare for encoding on UR functions that support it.
- Add support for encoding the
execute()
function without deadline
- Fix issue #35 - fails to decode input data when there is too many commands
- Add support for SWEEP and PAY_PORTION
- Fix decoding issues
- Remove useless parameter
payer_is_sender
fromv*_swap_exact_in_from_balance()
methods - Update Router ABI
- Add uint48 and uint160 in ABI builder
The object of this library is to decode & encode the transaction input sent to the Uniswap universal router (UR)
(address 0x3fC91A3afd70395Cd496C647d5a6CC9D4B2b7FAD
on Ethereum Mainnet). It is based on, and is intended to be used with web3.py
⚠ This library has not been audited, so use at your own risk !
⚠ This project is a work in progress so not all commands are decoded yet. Below the list of the already implemented ones.
Command Id | Function Name | Decode | Encode |
---|---|---|---|
0x00 | V3_SWAP_EXACT_IN | ✅ | ✅ |
0x01 | V3_SWAP_EXACT_OUT | ✅ | ✅ |
0x02 - 0x03 | ❌ | ❌ | |
0x04 | SWEEP | ✅ | ✅ |
0x05 | TRANSFER | ✅ | ✅ |
0x06 | PAY_PORTION | ✅ | ✅ |
0x07 | placeholder | N/A | N/A |
0x08 | V2_SWAP_EXACT_IN | ✅ | ✅ |
0x09 | V2_SWAP_EXACT_OUT | ✅ | ✅ |
0x0a | PERMIT2_PERMIT | ✅ | ✅ |
0x0b | WRAP_ETH | ✅ | ✅ |
0x0c | UNWRAP_WETH | ✅ | ✅ |
0x0d | PERMIT2_TRANSFER_FROM_BATCH | ❌ | ❌ |
0x0e - 0x0f | placeholders | N/A | N/A |
0x10 - 0x1d | ❌ | ❌ | |
0x1e - 0x3f | placeholders | N/A | N/A |
A good practice is to use Python virtual environments, here is a tutorial.
The library can be pip installed from pypi.org as usual:
# update pip to latest version if needed
pip install -U pip
# install the decoder from pypi.org
pip install uniswap-universal-router-decoder
The library exposes a class, RouterCodec
with several public methods that can be used to decode or encode UR data.
To decode a transaction input, use the decode.function_input()
method as follows:
from uniswap_universal_router_decoder import RouterCodec
trx_input = "0x3593564c000000000000000000 ... 90095b5c4e9f5845bba" # the trx input to decode
codec = RouterCodec()
decoded_trx_input = codec.decode.function_input(trx_input)
Example of decoded input returned by decode.function_input()
:
(
<Function execute(bytes,bytes[],uint256)>, # the UR function that executes all commands
{
'commands': b'\x0b\x00', # the list of commands sent to the UR
'inputs': [ # the inputs used for each command
(
<Function WRAP_ETH(address,uint256)>, # the function corresponding to the first command
{ # and its parameters
'recipient': '0x0000000000000000000000000000000000000002', # code indicating the recipient of this command is the router
'amountMin': 4500000000000000000 # the amount in WEI to wrap
},
{
'revert_on_fail': True # flag indicating if the transaction must revert when this command fails
},
),
(
<Function V3_SWAP_EXACT_IN(address,uint256,uint256,bytes,bool)>, # the function corresponding to the second command
{ # and its parameters
'recipient': '0x0000000000000000000000000000000000000001', # code indicating the sender will receive the output of this command
'amountIn': 4500000000000000000, # the exact amount sent
'amountOutMin': 6291988002, # the min amount expected of the bought token for the swap to be executed
'path': b"\xc0*\xaa9\xb2#\xfe\x8d\n\x0e\\O'\xea\xd9\x08<ul\xc2" # the V3 path (tokens + pool fees)
b'\x00\x01\xf4\xa0\xb8i\x91\xc6!\x8b6\xc1\xd1\x9dJ.' # can be decoded with the method decode.v3_path()
b'\x9e\xb0\xce6\x06\xebH',
'payerIsSender': False # a bool indicating if the input tokens come from the sender or are already in the UR
},
{
'revert_on_fail': True # flag indicating if the transaction must revert when this command fails
},
)
],
'deadline': 1678441619 # The deadline after which the transaction is not valid any more.
}
)
It's also possible to decode the whole transaction, given its hash
and providing the codec has been built with either a valid Web3
instance or the link to a rpc endpoint:
# Using a web3 instance
from web3 import Web3
from uniswap_universal_router_decoder import RouterCodec
w3 = Web3(...) # your web3 instance
codec = RouterCodec(w3=w3)
# Using a rpc endpoint
from web3 import Web3
from uniswap_universal_router_decoder import RouterCodec
rpc_link = "https://..." # your rpc endpoint
codec = RouterCodec(rpc_endpoint=rpc_link)
And then the decoder will get the transaction from the blockchain and decode it, along with its input data:
trx_hash = "0x52e63b7 ... 11b979dd9"
decoded_transaction = codec.decode.transaction(trx_hash)
The RouterCodec
class exposes also the method decode.v3_path()
which can be used to decode a given Uniswap V3 path.
from uniswap_universal_router_decoder import RouterCodec
uniswap_v3_path = b"\xc0*\xaa9\xb2#\xfe\x8d\n\x0e ... \xd7\x89" # bytes or str hex
fn_name = "V3_SWAP_EXACT_IN" # Or V3_SWAP_EXACT_OUT
codec = RouterCodec()
decoded_path = codec.decode.v3_path(fn_name, uniswap_v3_path)
The result is a tuple, starting with the "in-token" and ending with the "out-token", with the pool fees between each pair.
The Universal Router allows the chaining of several functions in the same transaction. This codec supports it (at least for supported functions) and exposes public methods that can be chained.
The chaining starts with the encode.chain()
method and ends with the build()
one which returns the full encoded data to be included in the transaction.
Below some examples of encoded data for one function and one example for 2 functions.
Default values for deadlines and expirations can be computed with the static methods get_default_deadline()
and get_default_expiration()
respectively.
from uniswap_universal_router_decoder import RouterCodec
default_deadline = RouterCodec.get_default_deadline()
default_expiration = RouterCodec.get_default_expiration()
These 2 functions accept a custom duration in seconds as argument.
This function can be used to convert eth to weth using the UR.
from uniswap_universal_router_decoder import FunctionRecipient, RouterCodec
codec = RouterCodec()
encoded_data = codec.encode.chain().wrap_eth(FunctionRecipient.SENDER, amount_in_wei).build(1676825611) # to convert amount_in_wei eth to weth, and send them to the transaction sender.
# then in your transaction dict:
transaction["data"] = encoded_data
# you can now sign and send the transaction to the UR
This function can be used to swap tokens on a V2 pool. Correct allowances must have been set before sending such transaction.
from uniswap_universal_router_decoder import FunctionRecipient, RouterCodec
codec = RouterCodec()
encoded_data = codec.encode.chain().v2_swap_exact_in(
FunctionRecipient.SENDER, # the output tokens are sent to the transaction sender
amount_in, # in Wei
min_amount_out, # in Wei
[
in_token_address, # checksum address of the token sent to the UR
out_token_address, # checksum address of the received token
],
).build(timestamp) # unix timestamp after which the trx will not be valid any more
# then in your transaction dict:
transaction["data"] = encoded_data
# you can now sign and send the transaction to the UR
For more details, see this tutorial
This function can be used to swap tokens on a V2 pool. Correct allowances must have been set before sending such transaction.
from uniswap_universal_router_decoder import FunctionRecipient, RouterCodec
codec = RouterCodec()
encoded_data = codec.encode.chain().v2_swap_exact_out(
FunctionRecipient.SENDER,
amount_out, # in Wei
max_amount_in, # in Wei
[
in_token_address,
out_token_address,
],
).build(timestamp) # unix timestamp after which the trx will not be valid any more
# then in your transaction dict:
transaction["data"] = encoded_data
# you can now sign and send the transaction to the UR
This function can be used to swap tokens on a V3 pool. Correct allowances must have been set before using sending such transaction.
from uniswap_universal_router_decoder import FunctionRecipient, RouterCodec
codec = RouterCodec()
encoded_data = codec.encode.chain().v3_swap_exact_in(
FunctionRecipient.SENDER,
amount_in, # in Wei
min_amount_out, # in Wei
[
in_token_address,
pool_fee,
out_token_address,
],
).build(timestamp) # unix timestamp after which the trx will not be valid any more
# then in your transaction dict:
transaction["data"] = encoded_data
# you can now sign and send the transaction to the UR
This function can be used to swap tokens on a V3 pool. Correct allowances must have been set before sending such transaction.
from uniswap_universal_router_decoder import FunctionRecipient, RouterCodec
codec = RouterCodec()
encoded_data = codec.encode.chain().v3_swap_exact_out(
FunctionRecipient.SENDER,
amount_out, # in Wei
max_amount_in, # in Wei
[
in_token_address,
pool_fee,
out_token_address,
],
).build(timestamp) # unix timestamp after which the trx will not be valid any more
# then in your transaction dict:
transaction["data"] = encoded_data
# you can now sign and send the transaction to the UR
This function is used to give an allowance to the universal router thanks to the Permit2 contract (0x000000000022D473030F116dDEE9F6B43aC78BA3
).
It is also necessary to approve the Permit2 contract using the token approve function.
See this tutorial
from uniswap_universal_router_decoder import RouterCodec
codec = RouterCodec()
data, signable_message = codec.create_permit2_signable_message(
token_address,
amount, # max = 2**160 - 1
expiration,
nonce, # Permit2 nonce
spender, # The UR checksum address
deadline,
1, # chain id
)
# Then you need to sign the message:
signed_message = acc.sign_message(signable_message) # where acc is your LocalAccount
# And now you can encode the data:
encoded_data = codec.encode.chain().permit2_permit(data, signed_message).build(deadline)
# Then in your transaction dict:
transaction["data"] = encoded_data
# you can now sign and send the transaction to the UR
After that, you can swap tokens using the Uniswap universal router.
Don't forget to give a token allowance to the Permit2 contract as well.
from uniswap_universal_router_decoder import FunctionRecipient, RouterCodec
codec = RouterCodec()
# Permit signature
data, signable_message = codec.create_permit2_signable_message(
token_address,
amount, # max = 2**160 - 1
expiration,
nonce, # Permit2 nonce
spender, # The UR checksum address
deadline,
1, # chain id
)
# Then you need to sign the message:
signed_message = acc.sign_message(signable_message) # where acc is your LocalAccount
# Permit + v2 swap encoding
path = [token_in_address, token_out_address]
encoded_data = (
codec
.encode
.chain()
.permit2_permit(data, signed_message)
.v2_swap_exact_in(FunctionRecipient.SENDER, Wei(10**18), Wei(0), path)
.build(deadline)
)
# Then in your transaction dict:
transaction["data"] = encoded_data
# you can now sign and send the transaction to the UR
(See integration tests for full examples)
Example where a recipient is paid 1% of the USDC amount:
.pay_portion(FunctionRecipient.CUSTOM, usdc_address, 100, recipient_address)
Example where the sender gets back all remaining USDC:
.sweep(FunctionRecipient.SENDER, usdc_address, 0)
Example where an USDC amount is sent to a recipient:
.transfer(FunctionRecipient.CUSTOM, usdc_address, usdc_amount, recipient_address)
See the SDK Wiki.
See the Discussions and 𝕏