usdc.eip_3009

Documentation for eth_defi.usdc.eip_3009 Python module.

EIP-3009 transferWithAuthorization() support for Python.

Internally we use eth_defi.eip_712 module for managing the messages here.

Warning

Polygon bridged tokens’ transferWithAuthorization() is not compatible with EIP-3009. This includes USD Coin (PoS), or USDC on Polygon. See make_eip_3009_transfer() for workarounds.

Functions

construct_eip_3009_authorization_message(...)

Create EIP-712 message for EIP-3009 transfers.

make_eip_3009_transfer(token, from_, to, ...)

Perform an EIP-3009 transferWithAuthorization() and receiveWithAuthorization() transaction.

Classes

EIP3009AuthorizationType

EIP-3009 message types.
class EIP3009AuthorizationType

Bases: enum.Enum

EIP-3009 message types.

  • Note that some contracts e.g. Polygon’s bridged USDC only implement TransferWithAuthorization support. Always check your target token first for supported methods.

  • Use ReceiveWithAuthorization when possible as it is safer due to front running protection

See make_eip_3009_transfer() for more information.

TransferWithAuthorization = 'TransferWithAuthorization'

Used with USDC

ReceiveWithAuthorization = 'ReceiveWithAuthorization'

Used with USDC

Not avaible on Polygon bridged tokens

construct_eip_3009_authorization_message(chain_id, token, from_, to, value, valid_before=0, valid_after=1, duration_seconds=0, authorization_type=EIP3009AuthorizationType.TransferWithAuthorization)

Create EIP-712 message for EIP-3009 transfers.

  • Used to construct the message that then needs to be signed

  • The signature will be verified by receiveWithAuthorization() or transferWithAuthorization function in the token contract

Note

For Polygon USDC transferWithAuthorization() you need to use a different message structure, because Polygon bridged tokens are not EIP-3009 compatible. This function cannot work with Polygon bridged tokens.

Polygon version is:

EIP712Domain: [
  { name: 'name', type: 'string' },
  { name: 'version', type: 'string' },
  { name: 'verifyingContract', type: 'address' },
  { name: 'salt', type: 'bytes32' }
]

More on Polygon incompatibility

Returns

JSON message for EIP-712 signing.

Parameters
Return type

dict

make_eip_3009_transfer(token, from_, to, func, value, valid_before=0, valid_after=1, duration_seconds=0, extra_args=(), authorization_type=EIP3009AuthorizationType.TransferWithAuthorization)

Perform an EIP-3009 transferWithAuthorization() and receiveWithAuthorization() transaction.

  • Constructs the EIP-3009 / EIP-712 payload

  • Signs the message

  • Builds a transaction against receiveWithAuthorization in USDC using Web3.py API, assuming there is a target smart contract function func to be called with this messge

  • The caller can then execute this by building a transaction from the resulting bound function call

Note

This currently supports only LocalAccount because of missing features in web3.py.

Example:

# Deploy some contract that supports
payment_forwarder = deploy_contract(
    web3,
    "VaultUSDCPaymentForwarder.json",
    deployer,
    usdc.address,
    comptroller.address,
)

# Construct bounded ContractFunction instance
# that will transact with MockEIP3009Receiver.deposit()
# smart contract function.
bound_func = make_receive_with_authorization_transfer(
    token=usdc,
    from_=user,
    to=payment_forwarder.address,
    func=payment_forwarder.functions.buySharesOnBehalf,
    value=500 * 10**6,  # 500 USD,
    valid_before=valid_before,
    extra_args=(1,),  # minSharesQuantity
)

# Sign and broadcast the tx
tx_hash = bound_func.transact({"from": user.address})

The receiveAuthorization() signature is:

function receiveWithAuthorization(
    address from,
    address to,
    uint256 value,
    uint256 validAfter,
    uint256 validBefore,
    bytes32 nonce,
    uint8 v,
    bytes32 r,
    bytes32 s)
Parameters

  • token (eth_defi.token.TokenDetails) – USDC token details

  • from – The local account that signs the EIP-3009 transfer.

  • to (eth_typing.evm.HexAddress) – To which contract USDC is transferred.

  • func (web3.contract.contract.ContractFunction) –

    The contract function that is verifying the transfer.

    A smart contract function with the same call signature as receiveAuthorization(). However, the spec does not specify what kind of a signature of a function this is: you can transfer receiveWithAuthorization() payload in any form, with extra parameters, byte packed, etc.

  • value (int) – How many tokens in raw value

  • valid_before (int) – Transfer timeout control

  • valid_after (int) – Transfer timeout control

  • duration_seconds (int) – Automatically set valid_before based on this

  • extra_args – Arguments added after the standard receiveWithAuthorization() prologue.

  • authorization_type – Is this transferWithAuthorization or receiveWithAuthorization style transaction.

  • from_ (eth_account.signers.local.LocalAccount) –

Returns

Bound contract function for transferWithAuthorization

Return type

web3.contract.contract.ContractFunction