Advanced Order Signing

TokenMaster enables creators to enhance user interactions by supporting optional signed advanced orders for buy and sell transactions in addition to spend orders. These advanced orders allow creators to integrate onchain hooks and provide incentives or custom logic.

Features of Advanced Orders:

• Custom Incentives: Creators can reward buyers and sellers through advanced order mechanisms.
• Spend Transactions: Require signed orders but allow hooks to be optional. Offchain monitoring of the SpendOrderFilled event can substitute for hooks.

Advanced Buy Order EIP-712 Primary Message Type:

BuyTokenMasterToken(bytes32 creatorBuyIdentifier,address tokenMasterToken,address tokenMasterOracle,address baseToken,uint256 baseValue,uint256 maxPerWallet,uint256 maxTotal,uint256 expiration,address hook,address cosigner)

Advanced Sell Order EIP-712 Primary Message Type:

SellTokenMasterToken(bytes32 creatorSellIdentifier,address tokenMasterToken,address tokenMasterOracle,address baseToken,uint256 baseValue,uint256 maxPerWallet,uint256 maxTotal,uint256 expiration,address hook,address cosigner)

Spend Order EIP-712 Primary Message Type:

SpendTokenMasterToken(bytes32 creatorSpendIdentifier,address tokenMasterToken,address tokenMasterOracle,address baseToken,uint256 baseValue,uint256 maxPerWallet,uint256 maxTotal,uint256 expiration,address hook,address cosigner)

• creator*Identifier is a value specified by the creator to identify the order during onchain hook execution or for offchain processing.
• tokenMasterOracle must be set to the zero address if not using an oracle to adjust baseValue.
• baseToken is only applicable to orders that are using an oracle to adjust the baseValue.
• baseValue is the amount of token value required to execute the order.
• maxPerWallet is the maximum amount that one wallet can execute against the specific signed order (Note for clarity: a specific signed order encompasses all fields in the message type, not just the creator identifier). For spends this amount is specified in multiples, for buys and sells this amount is specified in tokens.
• maxTotal is the maximum amount that all wallets can execute against the specific signed order (Note for clarity: a specific signed order encompasses all fields in the message type, not just the creator identifier). For spends this amount is specified in multiples, for buys and sells this amount is specified in tokens.
• expiration is the Unix timestamp after which the signed order is invalid.
• hook is the onchain hook to call after the buy/sell/spend is executed. A hook is required for buy and sell advanced orders but optional for spends.
• cosigner is the address of the cosigner for the signed order (see Cosigning).

EIP-712 Signature Requirements:

• Advanced orders must be signed by an authorized account designated on the TokenMaster Router through the setOrderSigner function.
• Domain Separator:
  • Name: TokenMasterRouter
  • Version: 1
  • Chain ID: The chain where the order is executed.
  • Verifying Contract: Address of TokenMaster Router.

Refer to the SignedOrder struct for formatting advanced order parameters and signatures.

Cosigning

Advanced orders can include an optional cosigner to add an extra layer of permissioning. Cosigners enable creators to enforce execution restrictions, such as limiting specific transactions to authorized executors.

Key Features:

• Permissioning: Restrict advanced orders to pre-approved executors.
• EIP-712 Cosignature:
  • Cosignatures include the v, r, and s components of the signed advanced order.
  • These must match the cosigner specified in the Cosignature struct.

Cosignature Format:

Cosignature EIP-712 Primary Message Type:

Cosignature(uint8 v, bytes32 r, bytes32 s, uint256 expiration, address executor)

Developer Notes:

• Cosigner addresses are not permissioned on TokenMaster Router the only requirement is that when a non-zero cosigner address is specified in the Cosignature struct the cosignature's signature recovers to that address.

Example Use Cases:

• Require a transaction is originating from within a creator's application.
• Require a user has completed certain actions prior to executing a transaction.

Permit Transfer

TokenMaster supports PermitC permit transfers for paired tokens when buying TokenMaster tokens. To execute a permit transfer the platform must get a signed permit from the user and ensure the PermitC contract being utilized has sufficient allowance from the user for the token being permitted.

The domain separator for the permit will be the domain separator of the PermitC contract being utilized.

Permit Transfer EIP-712 Primary Message Type:

PermitTransferFromWithAdditionalData(uint256 tokenType,address token,uint256 id,uint256 amount,uint256 nonce,address operator,uint256 expiration,uint256 masterNonce,AdvancedBuyOrder advancedBuyOrder)AdvancedBuyOrder(address tokenMasterToken,uint256 tokensToBuy,uint256 pairedValueIn,bytes32 creatorBuyIdentifier,address hook,uint8 buyOrderSignatureV,bytes32 buyOrderSignatureR,bytes32 buyOrderSignatureS)