@optimex-xyz/market-maker-sdk 0.9.0-staging-adbbc25 → 0.9.1

package/README.md

@@ -1,6 +1,7 @@
 # PMM API Integration Documentation
 
-> **CHANGELOG (v0.8.0)**: 
+> **CHANGELOG (v0.8.0)**:
+>
 > - **Breaking Changes:**
 >   - Update to get router contract from protocol fetcher
 >   - Use consistent trade_id across all protocol
@@ -15,23 +16,85 @@ A comprehensive guide for implementing Private Market Makers (PMMs) in the cross
 
 ## Table of Contents
 
-- [PMM API Integration Documentation](#pmm-api-integration-documentation)  
-  - [1. Overview](#1-overview)    
-  - [2. Quick Start](#2-quick-start)    
+- [PMM API Integration Documentation](#pmm-api-integration-documentation)
+  - [Table of Contents](#table-of-contents)
+  - [Smart Contract Integration](#smart-contract-integration)
+    - [Contract Addresses](#contract-addresses)
+  - [1. Overview](#1-overview)
+    - [1.1. Integration Flow](#11-integration-flow)
+  - [2. Quick Start](#2-quick-start)
+    - [2.1. API Environments](#21-api-environments)
   - [3. PMM Backend APIs](#3-pmm-backend-apis)
-    - [3.1. Endpoint: `/indicative-quote`](#31-endpoint-indicative-quote)      
-    - [3.2. Endpoint: `/commitment-quote`](#32-endpoint-commitment-quote)      
-    - [3.3. Endpoint: `/settlement-signature`](#33-endpoint-settlement-signature)      
-    - [3.4. Endpoint: `/ack-settlement`](#34-endpoint-ack-settlement)      
-    - [3.5. Endpoint: `/signal-payment`](#35-endpoint-signal-payment)      
+    - [3.1. Endpoint: `/indicative-quote`](#31-endpoint-indicative-quote)
+      - [Description](#description)
+      - [Request Parameters](#request-parameters)
+      - [Example Request](#example-request)
+      - [Expected Response](#expected-response)
+    - [3.2. Endpoint: `/commitment-quote`](#32-endpoint-commitment-quote)
+      - [Description](#description-1)
+      - [Request Parameters](#request-parameters-1)
+      - [Example Request](#example-request-1)
+      - [Expected Response](#expected-response-1)
+    - [3.3. Endpoint: `/liquidation-quote`](#33-endpoint-liquidation-quote)
+      - [Description](#description-2)
+      - [Request Parameters](#request-parameters-2)
+      - [Example Request](#example-request-2)
+      - [Expected Response](#expected-response-2)
+    - [3.4. Endpoint: `/settlement-signature`](#34-endpoint-settlement-signature)
+      - [Description](#description-3)
+      - [Request Parameters](#request-parameters-3)
+      - [Example Request](#example-request-3)
+      - [Expected Response](#expected-response-3)
+    - [3.5. Endpoint: `/ack-settlement`](#35-endpoint-ack-settlement)
+      - [Description](#description-4)
+      - [Request Parameters](#request-parameters-4)
+      - [Example Request](#example-request-4)
+      - [Expected Response](#expected-response-4)
+    - [3.6. Endpoint: `/signal-payment`](#36-endpoint-signal-payment)
+      - [Description](#description-5)
+      - [Request Parameters](#request-parameters-5)
+      - [Example Request](#example-request-5)
+      - [Expected Response](#expected-response-5)
   - [4. Solver API Endpoints for PMMs](#4-solver-api-endpoints-for-pmms)
     - [4.1. Endpoint: `/v1/market-maker/tokens`](#41-endpoint-v1market-makertokens)
+      - [Description](#description-6)
+      - [Request Parameters](#request-parameters-6)
+      - [Example Request](#example-request-6)
+      - [Expected Response](#expected-response-6)
     - [4.2. Endpoint: `/v1/market-maker/submit-settlement-tx`](#42-endpoint-v1market-makersubmit-settlement-tx)
+      - [Description](#description-7)
+      - [Request Parameters](#request-parameters-7)
+      - [Example Request](#example-request-7)
+      - [Expected Response](#expected-response-7)
+      - [Notes](#notes)
     - [4.3. Endpoint: `/v1/market-maker/trades/:tradeId`](#43-endpoint-v1market-makertradestradeid)
+      - [Description](#description-8)
+      - [Request Parameters](#request-parameters-8)
+      - [Example Request](#example-request-8)
+      - [Expected Response](#expected-response-8)
   - [5. PMM Making Payment](#5-pmm-making-payment)
     - [5.1. EVM](#51-evm)
     - [5.2. Bitcoin](#52-bitcoin)
 
+## Smart Contract Integration
+
+### Contract Addresses
+
+**Testnet**
+
+| Contract | Address                                      |
+| -------- | -------------------------------------------- |
+| Signer   | `0xA89F5060B810F3b6027D7663880c43ee77A865C7` |
+| Router   | `0x31C88ebd9E430455487b6a5c8971e8eF63e97ED4` |
+| Payment  | `0x7387DcCfE2f1D5F80b4ECDF91eF58541517e90D2` |
+
+**Mainnet**
+
+| Contract | Address                                      |
+| -------- | -------------------------------------------- |
+| Signer   | `0xCF9786F123F1071023dB8049808C223e94c384be` |
+| Router   | `0x1e878cCa765a8aAFEBecCa672c767441b4859634` |
+| Payment  | `0x0A497AC4261E37FA4062762C23Cf3cB642C839b8` |
 
 ## 1. Overview
 
@@ -42,7 +105,6 @@ The PMM integration with Optimex involves bidirectional API communication:
 
 ### 1.1. Integration Flow
 
-
 ```mermaid
 sequenceDiagram
     participant User
@@ -77,22 +139,24 @@ sequenceDiagram
 
 ### 2.1. API Environments
 
-| Environment      | Description                                                          |
-| ---------------- | -------------------------------------------------------------------- |
-| `dev`            | internal environment with test networks and development services     |
-| `staging`        | Staging environment with test networks and staging services      |
-| `prelive` | Pre production environment with mainnet networks for testing before release |
-| `production`     | Production environment with mainnet networks and production services |
+| Environment  | Description                                                                 |
+| ------------ | --------------------------------------------------------------------------- |
+| `dev`        | internal environment with test networks and development services            |
+| `staging`    | Staging environment with test networks and staging services                 |
+| `prelive`    | Pre production environment with mainnet networks for testing before release |
+| `production` | Production environment with mainnet networks and production services        |
 
 <details>
 <summary><strong>Staging Contracts</strong></summary>
 
 **Optimex L2 Testnet**
+
 - **Signer**: [0xA89F5060B810F3b6027D7663880c43ee77A865C7](https://scan-testnet.optimex.xyz/address/0xA89F5060B810F3b6027D7663880c43ee77A865C7)
 - **Router**: [0x31C88ebd9E430455487b6a5c8971e8eF63e97ED4](https://scan-testnet.optimex.xyz/address/0x31C88ebd9E430455487b6a5c8971e8eF63e97ED4)
 - **ProtocolFetcherProxy**: [0x7c07151ca4DFd93F352Ab9B132A95866697c38c2](https://scan-testnet.optimex.xyz/address/0x7c07151ca4DFd93F352Ab9B132A95866697c38c2)
 
 **Ethereum Sepolia**
+
 - **Payment**: [0x7387DcCfE2f1D5F80b4ECDF91eF58541517e90D2](https://sepolia.etherscan.io/address/0x7387DcCfE2f1D5F80b4ECDF91eF58541517e90D2)
 - **ETHVault**: [0x17aD543010fc8E8065b85E203839C0CBEcdfC851](https://sepolia.etherscan.io/address/0x17aD543010fc8E8065b85E203839C0CBEcdfC851)
 - **WETHVault**: [0x673Ac1489457F43F04403940cE425ae19a9D639B](https://sepolia.etherscan.io/address/0x673Ac1489457F43F04403940cE425ae19a9D639B)
@@ -104,13 +168,14 @@ sequenceDiagram
 <details>
 <summary><strong>Production/Prelive Contracts</strong></summary>
 
-
 **Optimex L2 Mainnet**
+
 - **Signer**: [0xCF9786F123F1071023dB8049808C223e94c384be](https://scan.optimex.xyz/address/0xCF9786F123F1071023dB8049808C223e94c384be)
 - **Router**: [0x1e878cCa765a8aAFEBecCa672c767441b4859634](https://scan.optimex.xyz/address/0x1e878cCa765a8aAFEBecCa672c767441b4859634)
 - **ProtocolFetcherProxy**: [0xFDEd4CEf9aE1E03D0BeF161262a266c1c157a32b](https://scan.optimex.xyz/address/0xFDEd4CEf9aE1E03D0BeF161262a266c1c157a32b)
 
 **Ethereum Mainnet**
+
 - **Payment**: [0x0A497AC4261E37FA4062762C23Cf3cB642C839b8](https://etherscan.io/address/0x0A497AC4261E37FA4062762C23Cf3cB642C839b8)
 - **ETHVault**: [0xF7fedF4A250157010807E6eA60258E3B768149Ff](https://etherscan.io/address/0xF7fedF4A250157010807E6eA60258E3B768149Ff)
 - **WETHVault**: [0xaD3f379AaED8Eca895209Af446F2e34f07145dbC](https://etherscan.io/address/0xaD3f379AaED8Eca895209Af446F2e34f07145dbC)
@@ -175,54 +240,101 @@ GET /indicative-quote?from_token_id=ETH&to_token_id=BTC&amount=10000000000000000
 <summary><strong>Example Implementation</strong></summary>
 
 ```js
+import crypto from 'crypto'
+import { tokenService } from '@optimex-xyz/market-maker-sdk'
+
+// In-memory session storage (use Redis in production)
+const sessionStore = new Map()
+
+function generateSessionId() {
+  return crypto.randomBytes(16).toString('hex')
+}
+
+function getPmmAddressByNetworkType(token) {
+  switch (token.networkType.toUpperCase()) {
+    case 'EVM':
+      return process.env.PMM_EVM_ADDRESS
+    case 'BTC':
+    case 'TBTC':
+      return process.env.PMM_BTC_ADDRESS
+    case 'SOLANA':
+      return process.env.PMM_SOLANA_ADDRESS
+    default:
+      throw new Error(`Unsupported network type: ${token.networkType}`)
+  }
+}
+
 async function getIndicativeQuote(req, res) {
   try {
-    const { from_token_id, to_token_id, amount, session_id } = req.query;
+    const { from_token_id, to_token_id, amount, session_id } = req.query
 
     // Generate a session ID if not provided
-    const sessionId = session_id || generateSessionId();
-
-    // Fetch token information from Solver API
-    const tokensResponse = await fetch('https://api.solver.example/v1/market-maker/tokens');
-    const tokensData = await tokensResponse.json();
+    const sessionId = session_id || generateSessionId()
 
-    // Find the from token and to token
-    const fromToken = tokensData.data.tokens.find(token => token.token_id === from_token_id);
-    const toToken = tokensData.data.tokens.find(token => token.token_id === to_token_id);
+    // Fetch token information using SDK tokenService
+    const [fromToken, toToken] = await Promise.all([
+      tokenService.getTokenByTokenId(from_token_id),
+      tokenService.getTokenByTokenId(to_token_id),
+    ])
 
-    if (!fromToken || !toToken) {
+    if (!fromToken) {
+      return res.status(400).json({
+        session_id: sessionId,
+        pmm_receiving_address: '',
+        indicative_quote: '0',
+        error: `From token not found: ${from_token_id}`,
+      })
+    }
+    if (!toToken) {
       return res.status(400).json({
         session_id: sessionId,
         pmm_receiving_address: '',
         indicative_quote: '0',
-        error: 'Token not found'
-      });
+        error: `To token not found: ${to_token_id}`,
+      })
     }
 
+    // Validate amount (implement your own validation logic)
+    const amountBigInt = BigInt(amount)
+    validateIndicativeAmount(amountBigInt, fromToken)
+
     // Calculate the quote (implementation specific to your PMM)
-    // Note: Treat amount as BigInt
-    const amountBigInt = BigInt(amount);
-    const quote = calculateQuote(fromToken, toToken, amountBigInt);
+    const quote = await calculateBestQuote({
+      amountIn: amount,
+      fromTokenId: from_token_id,
+      toTokenId: to_token_id,
+      isCommitment: false,
+    })
+
+    // Get the receiving address based on network type
+    const pmmReceivingAddress = getPmmAddressByNetworkType(fromToken)
 
-    // Get the receiving address for this token pair
-    const pmmReceivingAddress = getPMMReceivingAddress(fromToken.network_id);
+    // Save session data for later use in commitment quote
+    sessionStore.set(sessionId, {
+      fromToken: from_token_id,
+      toToken: to_token_id,
+      amount: amount,
+      pmmReceivingAddress: pmmReceivingAddress,
+      indicativeQuote: quote,
+    })
 
     return res.status(200).json({
       session_id: sessionId,
       pmm_receiving_address: pmmReceivingAddress,
       indicative_quote: quote.toString(),
-      error: ''
-    });
+      error: '',
+    })
   } catch (error) {
     return res.status(500).json({
       session_id: req.query.session_id || '',
       pmm_receiving_address: '',
       indicative_quote: '0',
-      error: error.message
-    });
+      error: error.message,
+    })
   }
 }
 ```
+
 </details>
 
 ### 3.2. Endpoint: `/commitment-quote`
@@ -274,6 +386,11 @@ GET /commitment-quote?session_id=12345&trade_id=0x3bfe2fc4889a98a39b31b348e7b212
 <summary><strong>Example Implementation</strong></summary>
 
 ```js
+import { tokenService } from '@optimex-xyz/market-maker-sdk'
+
+// Session store (use Redis in production)
+const sessionStore = new Map()
+
 async function getCommitmentQuote(req, res) {
   try {
     const {
@@ -287,73 +404,245 @@ async function getCommitmentQuote(req, res) {
       user_deposit_tx,
       user_deposit_vault,
       trade_deadline,
-      script_deadline
-    } = req.query;
+      script_deadline,
+    } = req.query
 
     // Validate the session exists
-    const session = await sessionRepository.findById(session_id);
+    const session = sessionStore.get(session_id)
     if (!session) {
       return res.status(400).json({
         trade_id,
         commitment_quote: '0',
-        error: 'Session not found'
-      });
+        error: 'Session expired during processing',
+      })
     }
 
-    // Fetch token information from Solver API
-    const tokensResponse = await fetch('https://api.solver.example/v1/market-maker/tokens');
-    const tokensData = await tokensResponse.json();
+    // Fetch token information using SDK tokenService
+    const [fromToken, toToken] = await Promise.all([
+      tokenService.getTokenByTokenId(from_token_id),
+      tokenService.getTokenByTokenId(to_token_id),
+    ])
 
-    // Find the from token and to token
-    const fromToken = tokensData.data.tokens.find(token => token.token_id === from_token_id);
-    const toToken = tokensData.data.tokens.find(token => token.token_id === to_token_id);
-
-    if (!fromToken || !toToken) {
+    if (!fromToken) {
       return res.status(400).json({
         trade_id,
         commitment_quote: '0',
-        error: 'Token not found'
-      });
+        error: `From token not found: ${from_token_id}`,
+      })
     }
+    if (!toToken) {
+      return res.status(400).json({
+        trade_id,
+        commitment_quote: '0',
+        error: `To token not found: ${to_token_id}`,
+      })
+    }
+
+    // Validate commitment amount (implement your own validation logic)
+    validateCommitmentAmount(BigInt(amount), fromToken)
+
+    // Delete any existing trade with the same ID (handle retries)
+    await tradeRepository.delete(trade_id)
 
     // Calculate the final quote (implementation specific to your PMM)
-    // Note: Treat numeric values as BigInt
-    const amountBigInt = BigInt(amount);
-    const quote = calculateFinalQuote(fromToken, toToken, amountBigInt, trade_deadline);
+    const quote = await calculateBestQuote({
+      amountIn: amount,
+      fromTokenId: from_token_id,
+      toTokenId: to_token_id,
+      isCommitment: true, // Use commitment pricing
+    })
 
     // Store the trade in the database
     await tradeRepository.create({
       tradeId: trade_id,
-      sessionId: session_id,
       fromTokenId: from_token_id,
       toTokenId: to_token_id,
-      amount: amountBigInt.toString(),
-      fromUserAddress: from_user_address,
-      toUserAddress: to_user_address,
+      fromUser: from_user_address,
+      toUser: to_user_address,
+      amount: amount,
+      fromNetworkId: fromToken.networkId,
+      toNetworkId: toToken.networkId,
       userDepositTx: user_deposit_tx,
       userDepositVault: user_deposit_vault,
       tradeDeadline: trade_deadline,
       scriptDeadline: script_deadline,
-      commitmentQuote: quote.toString()
-    });
+      tradeType: 'SWAP',
+      commitmentQuote: quote.toString(),
+    })
 
     return res.status(200).json({
       trade_id,
       commitment_quote: quote.toString(),
-      error: ''
-    });
+      error: '',
+    })
   } catch (error) {
     return res.status(500).json({
       trade_id: req.query.trade_id || '',
       commitment_quote: '0',
-      error: error.message
-    });
+      error: error.message,
+    })
   }
 }
 ```
+
 </details>
 
-### 3.3. Endpoint: `/settlement-signature`
+### 3.3. Endpoint: `/liquidation-quote`
+
+#### Description
+
+Provides a firm commitment quote for a liquidation trade. This endpoint is called after the user deposits funds and represents a binding commitment to execute the liquidation at the quoted rate.
+
+#### Request Parameters
+
+- **HTTP Method**: `GET`
+- **Query Parameters**:
+  - `session_id` (string): Session identifier from the indicative quote.
+  - `trade_id` (string): Unique trade identifier.
+  - `from_token_id` (string): The ID of the source token.
+  - `to_token_id` (string): The ID of the destination token.
+  - `amount` (string): The amount of the source token to be traded, in base 10. This should be treated as a BigInt in your implementation.
+  - `payment_metadata` (string, optional): Hex string encoded data for smart contract payment method.
+  - `from_user_address` (string): The user's address from which the input token will be sent.
+  - `to_user_address` (string): The user's address to which the output token will be sent.
+  - `user_deposit_tx` (string): Transaction hash of user's deposit.
+  - `user_deposit_vault` (string): Vault containing user's deposit.
+  - `trade_deadline` (string): Expected payment deadline (UNIX timestamp).
+  - `script_deadline` (string): Withdrawal deadline if unpaid (UNIX timestamp).
+
+#### Example Request
+
+```
+GET /liquidation-quote?session_id=12345&trade_id=0x3bfe2fc4889a98a39b31b348e7b212ea3f2bea63fd1ea2e0c8ba326433677328&from_token_id=ETH&to_token_id=BTC&amount=1000000000000000000&from_user_address=0xUserAddress&to_user_address=bc1p68q6hew27ljf4ghvlnwqz0fq32qg7tsgc7jr5levfy8r74p5k52qqphk07&user_deposit_tx=0xDepositTxHash&user_deposit_vault=VaultData&trade_deadline=1696012800&script_deadline=1696016400
+```
+
+#### Expected Response
+
+- **HTTP Status**: `200 OK`
+- **Response Body** (JSON):
+
+```json
+{
+  "trade_id": "0x3bfe2fc4889a98a39b31b348e7b212ea3f2bea63fd1ea2e0c8ba326433677328",
+  "liquidation_quote": "987654321000000000",
+  "error": ""
+}
+```
+
+- `trade_id` (string): The trade ID associated with the request.
+- `liquidation_quote` (string): **Firm committed quote** - PMM must honor this price. Should be treated as a BigInt in your implementation.
+- `error` (string): Error message, if any (empty if no error).
+
+<details>
+<summary><strong>Example Implementation</strong></summary>
+
+```js
+import { tokenService } from '@optimex-xyz/market-maker-sdk'
+
+// Session store (use Redis in production)
+const sessionStore = new Map()
+
+async function getLiquidationQuote(req, res) {
+  try {
+    const {
+      session_id,
+      trade_id,
+      from_token_id,
+      to_token_id,
+      amount,
+      payment_metadata,
+      from_user_address,
+      to_user_address,
+      user_deposit_tx,
+      user_deposit_vault,
+      trade_deadline,
+      script_deadline,
+    } = req.query
+
+    // Validate the session exists
+    const session = sessionStore.get(session_id)
+    if (!session) {
+      return res.status(400).json({
+        trade_id,
+        liquidation_quote: '0',
+        error: 'Session expired during processing',
+      })
+    }
+
+    // Fetch token information using SDK tokenService
+    const [fromToken, toToken] = await Promise.all([
+      tokenService.getTokenByTokenId(from_token_id),
+      tokenService.getTokenByTokenId(to_token_id),
+    ])
+
+    if (!fromToken) {
+      return res.status(400).json({
+        trade_id,
+        liquidation_quote: '0',
+        error: `From token not found: ${from_token_id}`,
+      })
+    }
+    if (!toToken) {
+      return res.status(400).json({
+        trade_id,
+        liquidation_quote: '0',
+        error: `To token not found: ${to_token_id}`,
+      })
+    }
+
+    // Validate commitment amount (implement your own validation logic)
+    validateCommitmentAmount(BigInt(amount), fromToken)
+
+    // Delete any existing trade with the same ID (handle retries)
+    await tradeRepository.delete(trade_id)
+
+    // Calculate the firm liquidation quote (implementation specific to your PMM)
+    const quote = await calculateBestQuote({
+      amountIn: amount,
+      fromTokenId: from_token_id,
+      toTokenId: to_token_id,
+      isCommitment: true, // Use commitment pricing for liquidation
+    })
+
+    // Store the trade in the database with LENDING trade type
+    await tradeRepository.create({
+      tradeId: trade_id,
+      fromTokenId: from_token_id,
+      toTokenId: to_token_id,
+      fromUser: from_user_address,
+      toUser: to_user_address,
+      amount: amount,
+      fromNetworkId: fromToken.networkId,
+      toNetworkId: toToken.networkId,
+      userDepositTx: user_deposit_tx,
+      userDepositVault: user_deposit_vault,
+      tradeDeadline: trade_deadline,
+      scriptDeadline: script_deadline,
+      tradeType: 'LENDING', // Liquidation trades use LENDING type
+      metadata: {
+        paymentMetadata: payment_metadata, // Store payment metadata for liquidation
+      },
+      commitmentQuote: quote.toString(),
+    })
+
+    return res.status(200).json({
+      trade_id,
+      liquidation_quote: quote.toString(),
+      error: '',
+    })
+  } catch (error) {
+    return res.status(500).json({
+      trade_id: req.query.trade_id || '',
+      liquidation_quote: '0',
+      error: error.message,
+    })
+  }
+}
+```
+
+</details>
+
+### 3.4. Endpoint: `/settlement-signature`
 
 #### Description
 
@@ -397,69 +686,151 @@ GET /settlement-signature?trade_id=0x3d09b8eb94466bffa126aeda68c8c0f330633a7d005
 <summary><strong>Example Implementation</strong></summary>
 
 ```js
+import {
+  getCommitInfoHash,
+  getSignature,
+  routerService,
+  SignatureType,
+  signerService,
+  tokenService,
+} from '@optimex-xyz/market-maker-sdk'
+
+import { ethers } from 'ethers'
+
+// Helper function to encode string to hex
+const l2Encode = (info) => {
+  if (/^0x[0-9a-fA-F]*$/.test(info)) {
+    return info
+  }
+  return '0x' + Buffer.from(info, 'utf8').toString('hex')
+}
+
+// Helper function to decode hex to string
+const l2Decode = (hex) => {
+  if (!hex.startsWith('0x')) return hex
+  return Buffer.from(hex.slice(2), 'hex').toString('utf8')
+}
+
 async function getSettlementSignature(req, res) {
   try {
-    const { trade_id, committed_quote, trade_deadline, script_deadline } = req.query;
+    const { trade_id, committed_quote, trade_deadline, script_deadline } = req.query
 
     // Fetch the trade from the database
-    const trade = await tradeRepository.findById(trade_id);
+    const trade = await tradeRepository.findById(trade_id)
     if (!trade) {
       return res.status(400).json({
         trade_id,
         signature: '',
         deadline: 0,
-        error: 'Trade not found'
-      });
+        error: 'Trade not found',
+      })
     }
 
-    // Fetch trade details from Solver API
-    const tradeDetailsResponse = await fetch(`https://api.solver.example/v1/market-maker/trades/${trade_id}`);
-    const tradeDetails = await tradeDetailsResponse.json();
+    // Fetch presigns and trade data from router service
+    const [presigns, tradeData] = await Promise.all([
+      routerService.getSettlementPresigns(trade_id),
+      routerService.getTradeData(trade_id),
+    ])
+
+    const { toChain, fromChain } = tradeData.tradeInfo
+
+    // Get the from token to determine PMM receiving address
+    const fromToken = await tokenService.getToken(l2Decode(fromChain[1]), l2Decode(fromChain[2]))
+    const pmmAddress = getPmmAddressByNetworkType(fromToken) // Your PMM address based on network type
 
     // Calculate a deadline (30 minutes from now)
-    const deadline = Math.floor(Date.now() / 1000) + 1800;
+    const deadline = BigInt(Math.floor(Date.now() / 1000) + 1800)
 
-    // Get PMM data
-    const pmmId = process.env.PMM_ID; // Your PMM ID
+    // Get PMM ID (should be hex encoded)
+    const pmmId = '0x' + Buffer.from(process.env.PMM_ID, 'utf8').toString('hex')
 
-    // Get the presigns and trade data from tradeDetails
-    const { from_token, to_token } = tradeDetails.data;
+    // Find PMM presign and validate receiving address
+    const pmmPresign = presigns.find((t) => t.pmmId === pmmId)
+    if (!pmmPresign) {
+      return res.status(400).json({
+        trade_id,
+        signature: '',
+        deadline: 0,
+        error: 'PMM presign not found',
+      })
+    }
 
-    // Create a commitment info hash
-    // Note: Treat numeric values as BigInt
-    const committedQuoteBigInt = BigInt(committed_quote);
-    const commitInfoHash = createCommitInfoHash(
+    // Validate that the presign receiving address matches expected PMM address
+    if (l2Decode(pmmPresign.pmmRecvAddress).toLowerCase() !== pmmAddress.toLowerCase()) {
+      return res.status(400).json({
+        trade_id,
+        signature: '',
+        deadline: 0,
+        error: 'PMM receiving address mismatch',
+      })
+    }
+
+    const amountOut = BigInt(committed_quote)
+
+    // Create commitment info hash using SDK function
+    const commitInfoHash = getCommitInfoHash(
       pmmId,
-      trade.pmmReceivingAddress,
-      to_token.chain,
-      to_token.address,
-      committedQuoteBigInt,
+      l2Encode(pmmAddress),
+      toChain[1], // destination chain
+      toChain[2], // destination token address
+      amountOut,
       deadline
-    );
+    )
+
+    // Get signer address and domain for EIP-712 signature
+    const signerAddress = await routerService.getSigner()
+    const domain = await signerService.getDomain()
+
+    // Set up provider and wallet
+    const provider = new ethers.JsonRpcProvider(process.env.RPC_URL)
+    const pmmWallet = new ethers.Wallet(process.env.PMM_PRIVATE_KEY, provider)
 
-    // Sign the commitment with your private key
-    const privateKey = process.env.PMM_PRIVATE_KEY;
-    const signature = signMessage(privateKey, trade_id, commitInfoHash);
+    // Generate signature using SDK function
+    const signature = await getSignature(
+      pmmWallet,
+      provider,
+      signerAddress,
+      trade_id,
+      commitInfoHash,
+      SignatureType.VerifyingContract,
+      domain
+    )
 
     return res.status(200).json({
       trade_id,
       signature,
-      deadline,
-      error: ''
-    });
+      deadline: Number(deadline),
+      error: '',
+    })
   } catch (error) {
     return res.status(500).json({
       trade_id: req.query.trade_id || '',
       signature: '',
       deadline: 0,
-      error: error.message
-    });
+      error: error.message,
+    })
+  }
+}
+
+// Helper function to get PMM address based on network type
+function getPmmAddressByNetworkType(token) {
+  switch (token.networkType.toUpperCase()) {
+    case 'EVM':
+      return process.env.PMM_EVM_ADDRESS
+    case 'BTC':
+    case 'TBTC':
+      return process.env.PMM_BTC_ADDRESS
+    case 'SOLANA':
+      return process.env.PMM_SOLANA_ADDRESS
+    default:
+      throw new Error(`Unsupported network type: ${token.networkType}`)
   }
 }
 ```
+
 </details>
 
-### 3.4. Endpoint: `/ack-settlement`
+### 3.5. Endpoint: `/ack-settlement`
 
 #### Description
 
@@ -504,44 +875,56 @@ trade_id=0x024be4dae899989e0c3d9b4459e5811613bcd04016dc56529f16a19d2a7724c0&trad
 <summary><strong>Example Implementation</strong></summary>
 
 ```js
+// Trade status enum
+const TradeStatus = {
+  PENDING: 'PENDING',
+  QUOTE_PROVIDED: 'QUOTE_PROVIDED',
+  COMMITTED: 'COMMITTED',
+  SELECTED: 'SELECTED',
+  SETTLING: 'SETTLING',
+  COMPLETED: 'COMPLETED',
+  FAILED: 'FAILED',
+}
+
 async function ackSettlement(req, res) {
   try {
-    const { trade_id, trade_deadline, script_deadline, chosen } = req.body;
+    const { trade_id, trade_deadline, script_deadline, chosen } = req.body
 
     // Fetch the trade from the database
-    const trade = await tradeRepository.findById(trade_id);
+    const trade = await tradeRepository.findById(trade_id)
     if (!trade) {
       return res.status(400).json({
         trade_id,
         status: 'error',
-        error: 'Trade not found'
-      });
+        error: 'Trade not found',
+      })
     }
 
-    // Update trade status based on whether it was chosen
-    await tradeRepository.update(trade_id, {
-      chosen: chosen === 'true',
-      tradeDeadline: trade_deadline,
-      scriptDeadline: script_deadline
-    });
+    // Update trade status based on whether PMM was chosen
+    const isChosen = chosen === 'true'
+    const newStatus = isChosen ? TradeStatus.SELECTED : TradeStatus.FAILED
+    const failureReason = isChosen ? undefined : 'PMM not chosen for settlement'
+
+    await tradeRepository.updateStatus(trade_id, newStatus, failureReason)
 
     return res.status(200).json({
       trade_id,
       status: 'acknowledged',
-      error: ''
-    });
+      error: '',
+    })
   } catch (error) {
     return res.status(500).json({
       trade_id: req.body.trade_id || '',
       status: 'error',
-      error: error.message
-    });
+      error: error.message,
+    })
   }
 }
 ```
+
 </details>
 
-### 3.5. Endpoint: `/signal-payment`
+### 3.6. Endpoint: `/signal-payment`
 
 #### Description
 
@@ -586,47 +969,90 @@ trade_id=0x3bfe2fc4889a98a39b31b348e7b212ea3f2bea63fd1ea2e0c8ba326433677328&tota
 <summary><strong>Example Implementation</strong></summary>
 
 ```js
+import { tokenService } from '@optimex-xyz/market-maker-sdk'
+
+// Trade status enum
+const TradeStatus = {
+  PENDING: 'PENDING',
+  QUOTE_PROVIDED: 'QUOTE_PROVIDED',
+  COMMITTED: 'COMMITTED',
+  SELECTED: 'SELECTED',
+  SETTLING: 'SETTLING',
+  COMPLETED: 'COMPLETED',
+  FAILED: 'FAILED',
+}
+
+// Queue names for different network types
+const SETTLEMENT_QUEUES = {
+  EVM: 'settlement:evm:transfer',
+  BTC: 'settlement:btc:transfer',
+  SOLANA: 'settlement:solana:transfer',
+}
+
+function getQueueNameByNetworkType(networkType) {
+  switch (networkType.toUpperCase()) {
+    case 'EVM':
+      return SETTLEMENT_QUEUES.EVM
+    case 'BTC':
+    case 'TBTC':
+      return SETTLEMENT_QUEUES.BTC
+    case 'SOLANA':
+      return SETTLEMENT_QUEUES.SOLANA
+    default:
+      throw new Error(`Unsupported network type: ${networkType}`)
+  }
+}
+
 async function signalPayment(req, res) {
   try {
-    const { trade_id, total_fee_amount, trade_deadline, script_deadline } = req.body;
+    const { trade_id, total_fee_amount, trade_deadline, script_deadline } = req.body
 
     // Fetch the trade from the database
-    const trade = await tradeRepository.findById(trade_id);
+    const trade = await tradeRepository.findById(trade_id)
     if (!trade) {
       return res.status(400).json({
         trade_id,
         status: 'error',
-        error: 'Trade not found'
-      });
+        error: 'Trade not found',
+      })
     }
 
-    // Update trade with fee amount
-    await tradeRepository.update(trade_id, {
-      totalFeeAmount: total_fee_amount,
-      tradeDeadline: trade_deadline,
-      scriptDeadline: script_deadline
-    });
+    // Validate trade status - must be SELECTED to proceed
+    if (trade.status !== TradeStatus.SELECTED) {
+      return res.status(400).json({
+        trade_id,
+        status: 'error',
+        error: `Invalid trade status: ${trade.status}`,
+      })
+    }
+
+    // Get the destination token to determine which queue to use
+    const toToken = await tokenService.getTokenByTokenId(trade.toTokenId)
+    const queueName = getQueueNameByNetworkType(toToken.networkType)
 
-    // Queue the payment task
-    await paymentQueue.add({
+    // Queue the payment task to the appropriate network queue
+    await paymentQueue.add(queueName, {
       tradeId: trade_id,
-      totalFeeAmount: total_fee_amount
-    });
+    })
+
+    // Update trade status to SETTLING
+    await tradeRepository.updateStatus(trade_id, TradeStatus.SETTLING)
 
     return res.status(200).json({
       trade_id,
       status: 'acknowledged',
-      error: ''
-    });
+      error: '',
+    })
   } catch (error) {
     return res.status(500).json({
       trade_id: req.body.trade_id || '',
       status: 'error',
-      error: error.message
-    });
+      error: error.message,
+    })
   }
 }
 ```
+
 </details>
 
 ## 4. Solver API Endpoints for PMMs
@@ -661,79 +1087,81 @@ GET /v1/market-maker/tokens
 
 ```json
 {
-    "data": {
-        "supported_networks": [
-            {
-                "network_id": "bitcoin_testnet",
-                "name": "Bitcoin Testnet",
-                "symbol": "tBTC",
-                "type": "BTC",
-                "logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/btc_network.svg"
-            },
-            {
-                "network_id": "ethereum_sepolia",
-                "name": "Ethereum Sepolia",
-                "symbol": "ETH",
-                "type": "EVM",
-                "logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/eth_network.svg"
-            }
-        ],
-        "tokens": [
-            {
-                "id": 2,
-                "network_id": "bitcoin_testnet",
-                "token_id": "tBTC",
-                "network_name": "Bitcoin Testnet",
-                "network_symbol": "tBTC",
-                "network_type": "BTC",
-                "token_name": "Bitcoin Testnet",
-                "token_symbol": "tBTC",
-                "token_address": "native",
-                "token_decimals": 8,
-                "token_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/tbtc.svg",
-                "network_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/btc_network.svg",
-                "active": true,
-                "created_at": "2024-10-28T07:24:33.179Z",
-                "updated_at": "2024-11-07T04:40:46.454Z"
-            },
-            {
-                "id": 11,
-                "network_id": "ethereum_sepolia",
-                "token_id": "ETH",
-                "network_name": "Ethereum Sepolia",
-                "network_symbol": "ETH",
-                "network_type": "EVM",
-                "token_name": "Ethereum Sepolia",
-                "token_symbol": "ETH",
-                "token_address": "native",
-                "token_decimals": 18,
-                "token_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/eth.svg",
-                "network_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/eth_network.svg",
-                "active": true,
-                "created_at": "2024-11-22T08:36:59.175Z",
-                "updated_at": "2024-11-22T08:36:59.175Z"
-            }
-        ],
-        "pairs": [
-            {
-                "from_token_id": "ETH",
-                "to_token_id": "tBTC",
-                "is_active": true
-            },
-            {
-                "from_token_id": "tBTC",
-                "to_token_id": "ETH",
-                "is_active": true
-            }
-        ]
-    }
+  "data": {
+    "supported_networks": [
+      {
+        "network_id": "bitcoin_testnet",
+        "name": "Bitcoin Testnet",
+        "symbol": "tBTC",
+        "type": "BTC",
+        "logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/btc_network.svg"
+      },
+      {
+        "network_id": "ethereum_sepolia",
+        "name": "Ethereum Sepolia",
+        "symbol": "ETH",
+        "type": "EVM",
+        "logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/eth_network.svg"
+      }
+    ],
+    "tokens": [
+      {
+        "id": 2,
+        "network_id": "bitcoin_testnet",
+        "token_id": "tBTC",
+        "network_name": "Bitcoin Testnet",
+        "network_symbol": "tBTC",
+        "network_type": "BTC",
+        "token_name": "Bitcoin Testnet",
+        "token_symbol": "tBTC",
+        "token_address": "native",
+        "token_decimals": 8,
+        "token_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/tbtc.svg",
+        "network_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/btc_network.svg",
+        "active": true,
+        "created_at": "2024-10-28T07:24:33.179Z",
+        "updated_at": "2024-11-07T04:40:46.454Z"
+      },
+      {
+        "id": 11,
+        "network_id": "ethereum_sepolia",
+        "token_id": "ETH",
+        "network_name": "Ethereum Sepolia",
+        "network_symbol": "ETH",
+        "network_type": "EVM",
+        "token_name": "Ethereum Sepolia",
+        "token_symbol": "ETH",
+        "token_address": "native",
+        "token_decimals": 18,
+        "token_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/eth.svg",
+        "network_logo_uri": "https://storage.googleapis.com/Optimex-static-35291d79/images/tokens/eth_network.svg",
+        "active": true,
+        "created_at": "2024-11-22T08:36:59.175Z",
+        "updated_at": "2024-11-22T08:36:59.175Z"
+      }
+    ],
+    "pairs": [
+      {
+        "from_token_id": "ETH",
+        "to_token_id": "tBTC",
+        "is_active": true
+      },
+      {
+        "from_token_id": "tBTC",
+        "to_token_id": "ETH",
+        "is_active": true
+      }
+    ]
+  }
 }
 ```
+
 </details>
 
 ### 4.2. Endpoint: `/v1/market-maker/submit-settlement-tx`
 
 #### Description
+
 Allows the PMM to submit settlement transaction hashes for trades. This endpoint is essential for completing the trade settlement process and must be called after making payments.
 
 #### Request Parameters
@@ -759,17 +1187,18 @@ Allows the PMM to submit settlement transaction hashes for trades. This endpoint
 - `signed_at` (integer): UNIX timestamp (seconds) when you signed this submission.
 - `settlement_tx` (string): Should be hex format with a `0x` prefix
 
-	- **For EVM Chains:**
-		- Use the transaction hash directly without additional encoding
-		- Example: `settlement_tx`: [0x7a87d2c423e13533b5ae0ecc5af900a7b697048103f4f6e32d19edde5e707355](https://etherscan.io/tx/0x7a87d2c423e13533b5ae0ecc5af900a7b697048103f4f6e32d19edde5e707355)
+  - **For EVM Chains:**
 
-	- **For Bitcoin or Solana:**
-		- Must encode raw_tx string using the `l2Encode` function
-		- Example raw_tx string: `3d83c7846d6e5b04279175a9592705a15373f3029b866d5224cc0744489fe403`
-		- After encoding
-		  ```
-		  "settlement_tx": "0x33643833633738343664366535623034323739313735613935393237303561313533373366333032396238363664353232346363303734343438396665343033"
-		  ```
+    - Use the transaction hash directly without additional encoding
+    - Example: `settlement_tx`: [0x7a87d2c423e13533b5ae0ecc5af900a7b697048103f4f6e32d19edde5e707355](https://etherscan.io/tx/0x7a87d2c423e13533b5ae0ecc5af900a7b697048103f4f6e32d19edde5e707355)
+
+  - **For Bitcoin or Solana:**
+    - Must encode raw_tx string using the `l2Encode` function
+    - Example raw_tx string: `3d83c7846d6e5b04279175a9592705a15373f3029b866d5224cc0744489fe403`
+    - After encoding
+      ```
+      "settlement_tx": "0x33643833633738343664366535623034323739313735613935393237303561313533373366333032396238363664353232346363303734343438396665343033"
+      ```
 
 <details>
 <summary><strong>Bitcoin l2Encode</strong></summary>
@@ -789,6 +1218,7 @@ export const l2Encode = (info: string) => {
   return ensureHexPrefix(ethers.hexlify(toUtf8Bytes(info)))
 }
 ```
+
 </details>
 
 #### Example Request
@@ -905,9 +1335,7 @@ GET /v1/market-maker/trades/0xfc24b9bc1299b50896027cb4c85d041c911e062147ffaf7ae9
     "user_deposit_tx": "0x202186375a3b8d55de4d8d1afb7f6a5bec8978cef3b705e6cb379729d03b16c7",
     "deposit_vault": "0xf7fedf4a250157010807e6ea60258e3b768149ff",
     "payment_bundle": {
-      "trade_ids": [
-        "0xfc24b9bc1299b50896027cb4c85d041c911e062147ffaf7ae9c7e51b670086c2"
-      ],
+      "trade_ids": ["0xfc24b9bc1299b50896027cb4c85d041c911e062147ffaf7ae9c7e51b670086c2"],
       "settlement_tx": "3d83c7846d6e5b04279175a9592705a15373f3029b866d5224cc0744489fe403",
       "signature": "0x479a5a89e7a871026b60307351ea650fc667890b25d3d02df7ed2e93f94db90d7c3f8dbd823220896b8ad49b13a90851199236e82a644ffbe99e53503929fe151b",
       "start_index": 0,
@@ -924,6 +1352,7 @@ GET /v1/market-maker/trades/0xfc24b9bc1299b50896027cb4c85d041c911e062147ffaf7ae9
   }
 }
 ```
+
 </details>
 
 ## 5. PMM Making Payment
@@ -933,53 +1362,47 @@ GET /v1/market-maker/trades/0xfc24b9bc1299b50896027cb4c85d041c911e062147ffaf7ae9
 In case the target chain is EVM-based, the transaction should emit the event from the `l1 payment contract` with the correct values for pmmAmountOut and protocolFee.
 
 ```js
-const { ethers } = require('ethers');
+const { ethers } = require('ethers')
 
 async function makeEVMPayment(tradeId, toAddress, amount, token, protocolFeeAmount) {
   try {
     // Get the private key from your secure storage
-    const privateKey = process.env.PMM_EVM_PRIVATE_KEY;
+    const privateKey = process.env.PMM_EVM_PRIVATE_KEY
 
     // Set up the provider and signer
-    const rpcUrl = getRpcUrlForNetwork(token.networkId);
-    const provider = new ethers.JsonRpcProvider(rpcUrl);
-    const signer = new ethers.Wallet(privateKey, provider);
+    const rpcUrl = getRpcUrlForNetwork(token.networkId)
+    const provider = new ethers.JsonRpcProvider(rpcUrl)
+    const signer = new ethers.Wallet(privateKey, provider)
 
     // Get the payment contract address
-    const paymentAddress = getPaymentAddressForNetwork(token.networkId);
+    const paymentAddress = getPaymentAddressForNetwork(token.networkId)
 
     // Create the contract instance
     const paymentAbi = [
       // ABI for the payment contract
-      "function payment(bytes32 tradeId, address token, address recipient, uint256 amount, uint256 feeAmount, uint256 deadline) payable returns (bool)"
-    ];
-    const paymentContract = new ethers.Contract(paymentAddress, paymentAbi, signer);
+      'function payment(bytes32 tradeId, address token, address recipient, uint256 amount, uint256 feeAmount, uint256 deadline) payable returns (bool)',
+    ]
+    const paymentContract = new ethers.Contract(paymentAddress, paymentAbi, signer)
 
     // Calculate the deadline (30 minutes from now)
-    const deadline = Math.floor(Date.now() / 1000) + 30 * 60;
+    const deadline = Math.floor(Date.now() / 1000) + 30 * 60
 
     // If the token is native, we need to set the value
-    const value = token.tokenAddress === 'native' ? amount : 0;
-    const tokenAddress = token.tokenAddress === 'native' ? ethers.ZeroAddress : token.tokenAddress;
+    const value = token.tokenAddress === 'native' ? amount : 0
+    const tokenAddress = token.tokenAddress === 'native' ? ethers.ZeroAddress : token.tokenAddress
 
     // Submit the transaction
-    const tx = await paymentContract.payment(
-      tradeId,
-      tokenAddress,
-      toAddress,
-      amount,
-      protocolFeeAmount,
-      deadline,
-      { value }
-    );
+    const tx = await paymentContract.payment(tradeId, tokenAddress, toAddress, amount, protocolFeeAmount, deadline, {
+      value,
+    })
 
-    console.log(`Transfer transaction sent: ${tx.hash}`);
+    console.log(`Transfer transaction sent: ${tx.hash}`)
 
     // Return the transaction hash with the 0x prefix
-    return `0x${tx.hash.replace(/^0x/, '')}`;
+    return `0x${tx.hash.replace(/^0x/, '')}`
   } catch (error) {
-    console.error('EVM payment error:', error);
-    throw error;
+    console.error('EVM payment error:', error)
+    throw error
   }
 }
 ```
@@ -989,11 +1412,12 @@ async function makeEVMPayment(tradeId, toAddress, amount, token, protocolFeeAmou
 In case the target chain is Bitcoin, the transaction should have at least N + 1 outputs, with the first N outputs being the settlement UTXOs for trades, and one of them being the change UTXO for the user with the correct amount. The output N + 1 is the OP_RETURN output with the hash of tradeIds.
 
 ```js
+import { getTradeIdsHash } from '@optimex-xyz/market-maker-sdk'
+
+import axios from 'axios'
 import * as bitcoin from 'bitcoinjs-lib'
 import { ECPairFactory } from 'ecpair'
 import * as ecc from 'tiny-secp256k1'
-import axios from 'axios'
-import { getTradeIdsHash } from '@optimex-xyz/market-maker-sdk'
 
 async function makeBitcoinPayment(params) {
   const { toAddress, amount, token, tradeId } = params
@@ -1050,9 +1474,7 @@ async function makeBitcoinPayment(params) {
 
   // Check if we have enough balance
   if (totalInput < amount) {
-    throw new Error(
-      `Insufficient balance. Need ${amount} satoshis, but only have ${totalInput} satoshis`
-    )
+    throw new Error(`Insufficient balance. Need ${amount} satoshis, but only have ${totalInput} satoshis`)
   }
 
   // Get fee rate
@@ -1077,10 +1499,7 @@ async function makeBitcoinPayment(params) {
   // Add OP_RETURN output with trade ID hash
   const tradeIdsHash = getTradeIdsHash([tradeId])
   psbt.addOutput({
-    script: bitcoin.script.compile([
-      bitcoin.opcodes.OP_RETURN,
-      Buffer.from(tradeIdsHash.slice(2), 'hex')
-    ]),
+    script: bitcoin.script.compile([bitcoin.opcodes.OP_RETURN, Buffer.from(tradeIdsHash.slice(2), 'hex')]),
     value: 0n,
   })
 
@@ -1107,5 +1526,4 @@ async function makeBitcoinPayment(params) {
 
   return response.data // Transaction ID
 }
-
 ```