Skip to main content

Peer-to-Peer Swap (P2PSwap)

Important

This preserved section contains legacy technical specifications.

A full architectural overhaul of this documentation is actively being developed.

P2PSwap is a decentralized exchange protocol service designed to facilitate token swaps within the Mate Metaprotocol ecosystem, eliminating the necessity for a centralized exchange. By leveraging a decentralized architecture, P2PSwap allows users to directly engage in peer-to-peer token exchanges. This approach enhances security and autonomy for users by removing intermediaries typically found in traditional exchange platforms. Within the Mate Metaprotocol, P2PSwap ensures seamless and efficient token interoperability, providing a robust and user-friendly solution for decentralized finance (DeFi) participants.

Overview​

The P2PSwap service protocol is designed to enable users to exchange tokens in diferent market pairs allowing sellers to post orders and buyers to accept them. The service protocol is built on the Mate Metaprotocol and leverages the tokens and markets created within the ecosystem. The P2PSwap service protocol is composed of the following components:

  • makeOrder: This function allows a user to post in a market pair an order to sell a determined amount of tokens. The function locks the amount of tokens to be sold in the service and saves the order id in the service mapping of sell orders inside that market.

  • dispatchOrder: This function allows a user to accept a sell order posted in the service. The function performs the token swap and returns the tokens to the seller and the buyer.

  • cancelOrder: This function allows a user to cancel a sell order posted in the market. The function returns the tokens to the seller.

  • getMarketMetadata: This function allows a user to get the metadata of a specific market.

  • getAllMartetOrders: This function allows a user to get a the full list of orders in a specific market.

  • getMyOrdersInSpecificMarket: This function allows a user to see his orders in a specific market.

  • findMarket: This function allows a user to find a market pair in the service.

  • getAllMarketsMetadata: This function allows a user to get the metadata of all the markets in the service.

  • checkIfANonceP2PSwapIsUsed: This function allows a user to check if a nonce is used in the service.

How market pairs work​

The P2PSwap service protocol is designed to facilitate token swaps in different market pairs. A market pair is a combination of two tokens that can be exchanged in the service. For example, the market pair tokenA and tokenB allows users to exchange tokenA for tokenB but if the user wants to exchange tokenB for tokenA they need to use the market pair tokenB and tokenA. Every market pair is unique so every market pair has its own id to identify it, the id is inside the market struct, so the final user doesn't need to know the id of the market pair to use it.

Examples:

Example 1: If a user wants to sell 10 MATE for 0.1 ETH, the user needs to use the market pair MATE and ETH for this operation. The seller uses the makeOrder to post the order, inside the function identifies the market pair id and posts the order, locking the amount of MATE to be sold in the prosess.

Example 2: If a user wants to sell 0.1 ETH for 10 MATE, the user needs to use the market pair ETH and MATE for this operation. The buyer uses the dispatchOrder to accept the order, inside the function identifies the market pair id and posts the order, locking the amount of MATE to be sold in the prosess.

Example 3: If a user wants to sell 10 MATE for 0.1 NEWTOKEN, the buyer interacts with the dispatchOrder function to accept the order, inside the function check the MATE/NEWTOKEN does not exist, so it creates the market pair with his new id and posts the order, locking the amount of MATE to be sold in the prosess.

Process flow​

After we figure out how the market pairs work, we can see the process flow of the P2PSwap service protocol with this example:

Example 1 - Token Swap:

  1. User A wants to sell 10 MATE for 0.1 ETH, so User A uses the makeOrder function to post the order.
    • The makeOrder checks if the market pair MATE/ETH exists, if not, creates the market pair, if exists, gets the market pair id and posts the order, locking the amount of MATE to be sold in the process.
  2. User B wants to buy this order (10 MATE for 0.1 ETH), so User B uses the dispatchOrder function to accept the order.
    • The dispatchOrder checks if the market pair MATE/ETH exists, if not revert, if exists, gets the market pair id and performs the token swap, returning the tokens to the seller and the buyer.

Example 2 - cancel order:

  1. User A wants to cancel the order of 10 MATE for 0.1 ETH, so User A uses the cancelOrder function to cancel the order.
    • The cancelOrder checks if the market pair MATE/ETH exists, if not revert, if exists, gets the market pair id and returns the MATE to the seller.

Functions​

The P2PSwap service protocol is composed of the following functions:

makeOrder​

This function allows a user to post in a market pair an order to sell a determined amount of tokens. The function locks the amount of tokens to be sold in the service and saves the order id in the service mapping of sell orders inside that market.

This function has the following parameters:

  • user (address): The address of the user that wants to post the order.
  • nonce (uint256): The nonce of the user in the P2PSwap service.
  • tokenA (address): The address of the token A.
  • tokenB (address): The address of the token B.
  • amountA (uint256): The amount of token A to be sold.
  • amountB (uint256): The amount of token B to be bought.
  • signature (bytes): The signature of the user for executing the function.
  • _priorityFee_Evvm (uint256): The priority fee to be paid to the fisher, as a optional tip in the EVVM.
  • _nonce_Evvm (uint256): The nonce (sync/asyn) of the user who wants to execute the token transfer in the EVVM.
  • _priority_Evvm (bool): The priority of the user in the EVVM.
  • _signature_Evvm (bytes): The signature of the user who sends the payment in the EVVM.

Important note: The nonce inside the P2PSwap service is different from the nonce inside the EVVM, the nonce inside the P2PSwap service is a asynchronous nonce, meanwhile the nonce inside the EVVM can be a synchronous or asynchronous nonce.

makeOrder Process​

The process of the makeOrder has two flows, the first flow is using a fishing spot and the second flow is a permissionless flow.

Fishing Spot Flow​

makeOrder Fishing Spot Flow

  1. A user signs the parameters of the makeOrder P2PSwap function and the pay EVVM function.
  2. The user sends the payment to the fishing spot.
  3. A fisher "catches" the paylods and verifies if the signatures and values are correct, if not the fisher "drops" the payload.
  4. The fisher sends the payment to the P2PSwap service.
  5. The P2PSwap service verifies the p2p signature and the p2p nonce, if fails the service reverts.
  6. The P2PSwap service invokes the makePay function who performs the token transfer in the EVVM, the EVVM verifies the EVVM signature and the EVVM nonce, the amount of tokens to be transferred, the priority fee and if the executor is the P2PSwap service, if fails the EVVM reverts and so the P2PSwap service, if the EVVM succeeds the tokens are locked in the P2PSwap service.
  7. The EVMV gives the reward and the priority fee to the service to be dispatched later.
  8. The P2PSwap check if the market pair exists, if not creates the market pair, if exists gets the market pair id to be executed later.
  9. The P2PSwap makes the order with the market pair id with the corresponding post id.
  10. If the fisher has sMate tokens, the fisher can claim the reward in MATE tokens and if the transaction has a priority fee, the fisher can claim the priority fee in the token of the user post the order.
  11. The nonce of the user is updated.
Permissionless Flow​

makeOrder Permissionless Flow

  1. A user signs the parameters of the makeOrder P2PSwap function.
  2. The user sends the transaction to the P2PSwap service.
  3. The P2PSwap service verifies the p2p signature and the p2p nonce, if fails the service reverts.
  4. The P2PSwap service invokes the makePay function who performs the token transfer in the EVVM, the EVVM verifies the EVVM signature and the EVVM nonce, the amount of tokens to be transferred, the priority fee and if the executor is the P2PSwap service, if fails the EVVM reverts and so the P2PSwap service, if the EVVM succeeds the tokens are locked in the P2PSwap service.
  5. The EVMV gives the reward and the priority fee to the service to be dispatched later.
  6. The P2PSwap check if the market pair exists, if not creates the market pair, if exists gets the market pair id to be executed later.
  7. The P2PSwap makes the order with the market pair id with the corresponding post id.
  8. If the user has sMate tokens, the user can claim the reward in MATE tokens and if the user adds a priority fee, the user can reclaim the priority fee in the token of the user post the order.
  9. The nonce of the user is updated.

makeOrder signature structure​

The signature of the makeOrder function is a string signed using ERC-191. The signature is a string that has the following structure:

string.concat(
    "63b8896c",
    ",",
    Strings.toString(_nonce),
    ",",
    addressToString(_tokenA),
    ",",
    addressToString(_tokenB),
    ",",
    Strings.toString(_amountA),
    ",",
    Strings.toString(_amountB)
);

The string.concat function is a function that concatenates all the parameters.

All parameters are concatenated using a comma , as a separator. The string begins with the function identifier 63b8896c and the nonce of the user _nonce, the address of the token A _tokenA, the address of the token B _tokenB, the amount of token A to be sold _amountA and the amount of token B to be bought _amountB. The Strings.toString function is a function that converts a number to a string and the addressToString function is a function that converts an address to a string and set all the characters to lowercase.

cancelOrder​

This function allows a user to cancel a order posted in the market. The function returns the tokens to the seller.

This function has the following parameters:

  • user (address): The address of the user that wants to cancel the order.
  • nonce (uint256): The nonce of the user in the P2PSwap service.
  • tokenA (address): The address of the token A.
  • tokenB (address): The address of the token B.
  • orderId (uint256): The id of the order to be canceled.
  • signature (bytes): The signature of the user for executing the function.
  • _priorityFee_Evvm (uint256): The priority fee to be paid to the fisher, as a optional tip in the EVVM.
  • _nonce_Evvm (uint256): The nonce (sync/asyn) of the user who wants to execute the token transfer in the EVVM.
  • _priority_Evvm (bool): The priority of the user in the EVVM.
  • _signature_Evvm (bytes): The signature of the user who sends the payment in the EVVM.

Important note: The nonce inside the P2PSwap service is different from the nonce inside the EVVM, the nonce inside the P2PSwap service is a asynchronous nonce, meanwhile the nonce inside the EVVM can be a synchronous or asynchronous nonce.

cancelOrder Process​

The process of the cancelOrder has two flows, the first flow is using a fishing spot and the second flow is a permissionless flow.

Fishing Spot Flow​

cancelOrder Fishing Spot Flow

  1. A user signs the parameters of the cancelOrder P2PSwap function and the pay EVVM function.
  2. The user sends the payment to the fishing spot.
  3. A fisher "catches" the paylods and verifies if the signatures and values are correct, if not the fisher "drops" the payload.
  4. The fisher sends the payment to the P2PSwap service.
  5. The P2PSwap service verifies the p2p signature and the p2p nonce, the market exist, the user is the owner of the order and the order is not dispatched, if fails the service reverts.
  6. If there a priority fee, the service invokes the makePay function who performs the token transfer in the EVVM, the EVVM verifies the EVVM signature and the EVVM nonce, the amount of tokens to be transferred, the priority fee and if the executor is the P2PSwap service, if fails the EVVM reverts and so the P2PSwap service, if the EVVM succeeds the tokens are returned to the seller.
  7. The EVMV gives the reward and the priority fee to the service to be dispatched later if there is a priority fee.
  8. The P2PSwap service cancels the order and the tokens are returned to the seller.
  9. If the fisher has sMate tokens, the fisher can claim the reward in MATE tokens and if the transaction has a priority fee, the fisher can claim the priority fee in the token of the user post the order.
  10. The nonce of the user is updated.
Permissionless Flow​

cancelOrder Permissionless Flow

  1. A user signs the parameters of the cancelOrder P2PSwap function.
  2. The user sends the transaction to the P2PSwap service.
  3. The P2PSwap service verifies the p2p signature and the p2p nonce, the market exist, the user is the owner of the order and the order is not dispatched, if fails the service reverts.
  4. If there a priority fee, the service invokes the makePay function who performs the token transfer in the EVVM, the EVVM verifies the EVVM signature and the EVVM nonce, the amount of tokens to be transferred, the priority fee and if the executor is the P2PSwap service, if fails the EVVM reverts and so the P2PSwap service, if the EVVM succeeds the tokens are returned to the seller.
  5. The EVMV gives the reward and the priority fee to the service to be dispatched later if there is a priority fee.
  6. The P2PSwap service cancels the order and the tokens are returned to the seller.
  7. If the user has sMate tokens, the user can claim the reward in MATE tokens and if the user adds a priority fee, the user can reclaim the priority fee in the token of the user post the order.
  8. The nonce of the user is updated.

cancelOrder signature structure​

The signature of the cancelOrder function is a string signed using ERC-191. The signature is a string that has the following structure:

string.concat(
    "215497c1",
    ",",
    Strings.toString(_nonce),
    ",",
    addressToString(_tokenA),
    ",",
    addressToString(_tokenB),
    ",",
    Strings.toString(_orderId)
);

The string.concat function is a function that concatenates all the parameters.

All parameters are concatenated using a comma , as a separator. The string begins with the function identifier 215497c1 and the nonce of the user _nonce, the address of the token A _tokenA, the address of the token B _tokenB and the id of the order to be canceled _orderId. The Strings.toString function is a function that converts a number to a string and the addressToString function is a function that converts an address to a string and set all the characters to lowercase.

dispatchOrder​

This function allows a user to accept a order posted in the service. The function performs the token swap and returns the tokens to the seller and the buyer.

This function has the following parameters:

  • user (address): The address of the user that wants to accept the order.
  • nonce (uint256): The nonce of the user in the P2PSwap service.
  • tokenA (address): The address of the token A.
  • tokenB (address): The address of the token B.
  • orderId (uint256): The id of the order to be accepted.
  • signature (bytes): The signature of the user for executing the function.
  • _priorityFee_Evvm (uint256): The priority fee to be paid to the fisher, as a optional tip in the EVVM.
  • _nonce_Evvm (uint256): The nonce (sync/asyn) of the user who wants to execute the token transfer in the EVVM.
  • _priority_Evvm (bool): The priority of the user in the EVVM.
  • _signature_Evvm (bytes): The signature of the user who sends the payment in the EVVM.

Important note: The nonce inside the P2PSwap service is different from the nonce inside the EVVM, the nonce inside the P2PSwap service is a asynchronous nonce, meanwhile the nonce inside the EVVM can be a synchronous or asynchronous nonce.

dispatchOrder Process​

The process of the dispatchOrder has two flows, the first flow is using a fishing spot and the second flow is a permissionless flow.

Fishing Spot Flow​

dispatchOrder Fishing Spot Flow

  1. A user signs the parameters of the dispatchOrder P2PSwap function and the pay EVVM function.
  2. The user sends the payload to the fishing spot.
  3. A fisher "catches" the paylods and verifies if the signatures and values are correct, if not the fisher "drops" the payload.
  4. The fisher sends the payment to the P2PSwap service.
  5. The P2PSwap service verifies the p2p signature and the p2p nonce, the market exist and the order is not dispatched, if fails the service reverts.
  6. If there a priority fee, the service invokes the makePay function who performs the token transfer in the EVVM, the EVVM verifies the EVVM signature and the EVVM nonce, the amount of tokens to be transferred, the priority fee and if the executor is the P2PSwap service, if fails the EVVM reverts and so the P2PSwap service, if the EVVM succeeds the tokens are locked in the P2PSwap service.
  7. The EVMV gives the reward and the priority fee to the service to be dispatched later if there is a priority fee.
  8. The P2PSwap service dispatches the order and the tokens are returned to the seller and the buyer.
  9. If the fisher has sMate tokens, the fisher can claim the reward in MATE tokens and if the transaction has a priority fee, the fisher can claim the priority fee in the token of the user post the order.
  10. The nonce of the user is updated.
Permissionless Flow​

dispatchOrder Permissionless Flow

  1. A user signs the parameters of the dispatchOrder P2PSwap function.
  2. The user sends the transaction to the P2PSwap service.
  3. The P2PSwap service verifies the p2p signature and the p2p nonce, the market exist and the order is not dispatched, if fails the service reverts.
  4. If there a priority fee, the service invokes the makePay function who performs the token transfer in the EVVM, the EVVM verifies the EVVM signature and the EVVM nonce, the amount of tokens to be transferred, the priority fee and if the executor is the P2PSwap service, if fails the EVVM reverts and so the P2PSwap service, if the EVVM succeeds the tokens are locked in the P2PSwap service.
  5. The EVMV gives the reward and the priority fee to the service to be dispatched later if there is a priority fee.
  6. The P2PSwap service dispatches the order and the tokens are returned to the seller and the buyer.
  7. If the user has sMate tokens, the user can claim the reward in MATE tokens and if the user adds a priority fee, the user can reclaim the priority fee in the token of the user post the order.
  8. The nonce of the user is updated.