Maple Finance 백서

Maple Finance

원문

bitpro가 원문에서 글자만 모은 내용이에요. 표·그림·수식은 빠지거나 깨질 수 있어요. 전체 75쪽 중 2쪽

></td></tr><tr><td>SyrupRouter</td><td><a href="https://sepolia.etherscan.io/address/0x5387ab37f93af968920af6c0faa6dbc52973b020">0x5387ab37f93af968920af6c0faa6dbc52973b020</a></td></tr><tr><td>WithdrawalManagerQueue</td><td><a href="https://sepolia.etherscan.io/address/0x2ff61035de7a1550219be12a6e9d33aa10b844b6">0x2ff61035de7a1550219be12a6e9d33aa10b844b6</a></td></tr></tbody></table> **syrupUSDT** <table><thead><tr><th width="225.046875">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolV2</td><td><a href="https://sepolia.etherscan.io/address/0x7679cbe9ae66298114ac6dac73487b63ac023c0b">0x7679cbe9ae66298114ac6dac73487b63ac023c0b</a></td></tr><tr><td>SyrupRouter</td><td><a href="https://sepolia.etherscan.io/address/0x0b703919cf2d30dbb18bad6febe8f0ea4f191918">0x0b703919cf2d30dbb18bad6febe8f0ea4f191918</a></td></tr><tr><td>WithdrawalManagerQueue</td><td><a href="https://sepolia.etherscan.io/address/0xbbe2bf30b76729a4eb75bf40ced47a58000ae1d3">0xbbe2bf30b76729a4eb75bf40ced47a58000ae1d3</a></td></tr></tbody></table> **syrupUSDG** <table><thead><tr><th width="225.046875">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolV2</td><td><a href="https://sepolia.etherscan.io/address/0x0f40d60293433a64bb8da7e4dfd9d13399ed319e">0x0f40d60293433a64bb8da7e4dfd9d13399ed319e</a></td></tr><tr><td>SyrupRouter</td><td><a href="https://sepolia.etherscan.io/address/0x1d090d34e0b64f9327c0a6b89741a5bd29c886b1">0x1d090d34e0b64f9327c0a6b89741a5bd29c886b1</a></td></tr><tr><td>WithdrawalManagerQueue</td><td><a href="https://sepolia.etherscan.io/address/0x1fd917c8c64070c151a163e16b10d2225781cc43">0x1fd917c8c64070c151a163e16b10d2225781cc43</a></td></tr></tbody></table> {% endtab %} {% endtabs %} Router addresses can also be accessed via the GraphQL API. #### Example query {% code lineNumbers="true" %} ```gql query { poolV2S(where: { syrupRouter_not: null }) { id name asset { symbol decimals } syrupRouter { id } withdrawalManagerQueue { id } poolPermissionManager { id } } } ``` {% endcode %} #### Code example using [**graphql-request**](https://www.npmjs.com/package/graphql-request) {% code overflow="wrap" lineNumbers="true" fullWidth="false" expandable="true" %} ```typescript import { gql, GraphQLClient } from "graphql-request"; interface MaplePoolV2 { id: string; asset: { symbol: string; }; syrupRouter: { id: string; }; withdrawalManagerQueue { id: string; } } interface QueryResponse { poolV2S: MaplePoolV2[]; } const query = gql` query GetMaplePools { poolV2S(where: { syrupRouter_not: null }) { id name asset { symbol } syrupRouter { id } withdrawalManagerQueue { id } } } `; const client = new GraphQLClient(MAPLE_API_URL); const main = async () => { const { poolV2S } = await client.request<QueryResponse>(query); for (const poolV2 of poolV2S) { console.log(`Pool ${poolV2.name}: SyrupRouter: ${poolV2.syrupRouter.id} WithdrawalManagerQueue: ${poolV2.withdrawalManagerQueue.id}`); } }; main(); ``` {% endcode %} ### Listen for Router DepositData events (optional) If you want to correlate deposits off-chain, subscribe to `DepositData(address owner, uint256 amount, bytes32 depositData)` on the `syrupRouter` address returned by GraphQL. Emitters include the caller’s address, raw deposit amount, and a `bytes32` opaque identifier you pass in the `deposit` call. ### Authorization signature verification (auditors) Maple returns an authorization signature (v/r/s) used by `authorizeAndDeposit`. The router verifies a digest constructed from `chainId`, `router address`, `owner`, `owner nonce`, `bitmap`, and `deadline`. For internal reviews, auditors can reproduce the `ecrecover` and confirm the signer is a `permissionAdmin` in `PoolPermissionManager`. It is important to note that the query uses the `syrupRouter_not` filter to return specifically Syrup pools. **Response Fields:** * `poolV2S.id`: The Syrup Pool contract address. * `poolV2S.syrupRouter.id`: The `SyrupRouter` contract address. These addresses can then be used to interact with the `SyrupRouter` contract. ### 2. Determine User Authorization Before depositing, check if a user is already authorized by querying the `Account` entity. This is necessary to perform a deposit. #### Example Query {% code lineNumbers="true" expandable="true" %} ```gql query GetMapleAccount($accountId: ID!) { account(id: $accountId) { isSyrupLender } } ``` {% endcode %} **NOTE**: The account ID must be provided in lowercase. #### Code example using [**graphql-request**](https://www.npmjs.com/package/graphql-request) {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```typescript import { gql, GraphQLClient } from 'graphql-request'; interface MapleAccount { isSyrupLender: boolean; } interface QueryResponse { account: MapleAccount; } const query = gql` query GetMapleAccount($accountId: ID!) { account(id: $accountId) { isSyrupLender } } `; const client = new GraphQLClient(MAPLE_API_URL); const main = async () => { const account = '0x123...'; const { account: mapleAccount } = await client.request<QueryResponse>(query, { accountId: account.toLowerCase(), }); if (mapleAccount) { console.log(`Can user ${account} deposit into Syrup: ${mapleAccount.isSyrupLender}`); } else { console.log('Account not found'); } }; main(); ``` {% endcode %} If `isSyrupLender = true`, the user is already authorized in the `Pool Permission Manager` and can deposit into Syrup pools. Otherwise, the user must perform authorization before their initial deposit. ### 3. Retrieve Authorization Signature **Note:** This step is only required if `isSyrupLender = false` was returned in the previous step. Otherwise, continue to the next step. The Maple Protocol is geared towards institutions and has a permissioning system that requires allowlisting for executing most functions. For pool deposits, in general, lenders need to have their wallet allowlisted in Maple's `Pool Permission Manager`. Aiming to abstract and simplify the process, the `SyrupRouter` integrates directly with the `Pool Permission Manager` to allow for valid users to self-authorize and deposit in a single transaction assuming the user meets eligibility requirements. To retrieve the authorization signature, contact us at <partnerships@maple.finance>. {% hint style="info" %} depositData Parameter * Please send `0:<integrator-name>` with your protocol name (e.g. `0:maple`) as `bytes32` (32-byte hex). * You must send this field with your deposits to enable Maple to correctly attribute them to specific partners and run rewards programs. {% endhint %} ### 4. Execute the Deposit The first time an asset (e.g., `USDC`, `USDT`) is lent to Syrup, it may be necessary to allow the contract to interact with the asset. This is a common transaction on Ethereum. Depositing into a pool requires a transaction. Once the transaction has been processed, `SyrupRouter` will accept the lending tokens and Pool LP (Liquidity Provider) tokens will be received. Each pool contract inherits the [ERC-4626](https://erc4626.info/) standard, also known as the `Tokenized Vault` Standard. This standard informs how the LP Tokens accrue value from borrower repayments of loans. #### `isSyrupLender = true` - User is Already Authorized The `deposit` or `depositWithPermit` method can be called directly on `SyrupRouter`. {% code lineNumbers="true" %} ```solidity function deposit(uint256 assets, bytes32 depositData) ``` {% endcode %} **NOTE**: `depositData` is an optional field that does not need to be provided. ![deposit()](https://github.com/maple-labs/syrup-router/assets/16119563/2e911fe4-cd81-4b58-a290-6809d7bba125) #### Code example using Maple SDK for `USDC` or `USDT`. {% tabs %} {% tab title="USDC" %} {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```typescript import { BigNumber, Contract, providers, utils, Wallet } from 'ethers'; import { addresses, syrupUtils } from '@maplelabs/maple-js'; const main = async () => { const provider = new providers.JsonRpcProvider(RPC_URL); const signer = new Wallet(PRIVATE_KEY, provider); const syrupRouter = syrupUtils.syrupRouter.connect( SYRUP_USDC_ROUTER_ADDRESS, // Explained how to get in previous step signer ); const usdc = new Contract(addresses['mainnet-prod'].USDC, USDC_ABI, signer); const amount = BigNumber.from(1000000); const approveReceipt = await usdc.approve(SYRUP_USDC_ROUTER_ADDRESS, amount); await approveReceipt.wait(); const depositReceipt = await syrupRouter.deposit(amount, utils.formatBytes32String('0:<integrator-name>')); await depositReceipt.wait(); }; main(); ``` {% endcode %} {% endtab %} {% tab title="USDT" %} {% code lineNumbers="true" expandable="true" %} ```typescript import { BigNumber, Contract, providers, utils, Wallet } from 'ethers'; import { addresses, syrupUtils, environmentMocks } from '@maplelabs/maple-js'; const main = async () => { const provider = new providers.JsonRpcProvider(RPC_URL); const signer = new Wallet(PRIVATE_KEY, provider); const syrupRouter = syrupUtils.syrupRouter.connect( SYRUP_USDT_ROUTER_ADDRESS, // Explained how to get in previous step signer ); const usdt = new Contract(addresses['mainnet-prod'].USDT, USDT_ABI, signer); const amount = BigNumber.from(1000000); const approveReceipt = await usdt.approve(SYRUP_USDT_ROUTER_ADDRESS, amount); await approveReceipt.wait(); const depositReceipt = await syrupRouter.deposit(amount, utils.formatBytes32String('0:<integrator-name>')); await depositReceipt.wait(); }; main(); ``` {% endcode %} {% endtab %} {% endtabs %} Deposits into Syrup can also be made with gasless approval using `permit`. For more information, see <https://eips.ethereum.org/EIPS/eip-2612>. {% code lineNumbers="true" expandable="true" %} ```solidity function depositWithPermit( uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s, bytes32 depositData_ ) ``` {% endcode %} **NOTE**: `depositWithPermit` is only available for `Syrup USDC`. ![depositWithPermit()](https://github.com/maple-labs/syrup-router/assets/16119563/db8192f8-c9d3-42d9-9522-9a91df95fb5d) #### Code example using Maple SDK {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```typescript import { BigNumber, Contract, providers, utils, Wallet } from 'ethers'; import { addresses, syrupUtils, erc20 } from '@maplelabs/maple-js'; const main = async () => { const provider = new providers.JsonRpcProvider(RPC_URL); const signer = new Wallet(PRIVATE_KEY, provider); const syrupRouter = syrupUtils.syrupRouter.connect( SYRUP_USDC_ROUTER_ADDRESS, // Explained how to get in previous step signer ); const usdc = new Contract(addresses['mainnet-prod'].USDC, USDC_ABI, signer); const amount = BigNumber.from(1000000); const account = await signer.getAddress(); const deadline = Math.floor(Date.now() / 1000) + 3600; const nonce = await usdc.nonces(account); const network = await provider.getNetwork(); // EIP-712 domain for USDC const domain = { name: await usdc.name(), version: '2', // "1" for Sepolia chainId: network.chainId, verifyingContract: addresses['mainnet-prod'].USDC, }; // EIP-712 types for permit const types = { Permit: [ { name: 'owner', type: 'address' }, { name: 'spender', type: 'address' }, { name: 'value', type: 'uint256' }, { name: 'nonce', type: 'uint256' }, { name: 'deadline', type: 'uint256' }, ], }; const permitMessage = { owner: account, spender: SYRUP_USDC_ROUTER_ADDRESS, value: amount.toString(), nonce: nonce.toString(), deadline: deadline, }; const signature = await signer._signTypedData(domain, types, permitMessage); const sig = utils.splitSignature(signature); const depositWithPermitReceipt = await syrupRouter.depositWithPermit( amount, deadline, sig.v, sig.r, sig.s, utils.formatBytes32String('0:<integrator-name>') ); await depositWithPermitReceipt.wait(); }; main(); ``` {% endcode %} #### `isSyrupLender = false` - User Requires Authorization 1. Retrieve a signature from the Maple API. Follow the instructions received from the team as mentioned in the step above. 2. Use the retrieved signature with the `authorizeAndDeposit` or `authorizeAndDepositWithPermit` method on `SyrupRouter`. {% code lineNumbers="true" expandable="true" %} ```solidity function authorizeAndDeposit( uint256 bitmap, uint256 deadline, uint8 auth_v, bytes32 auth_r, bytes32 auth_s, uint256 amount, bytes32 depositData) ``` {% endcode %} ![authAndDeposit()](https://github.com/maple-labs/syrup-router/assets/16119563/1c59065b-c1cb-4b55-9ab8-1d04ebb9fe83) #### Code example using Maple SDK for `USDC` or `USDT`. {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```typescript import { BigNumber, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... // Exact same steps as regular deposit const { bitmap, deadline, sig } = authorize(); // Contact the Syrup team for authorization information const authorizeAndDepositReceipt = await syrupRouter.authorizeAndDeposit( bitmap, deadline, sig.v, sig.r, sig.s, amount, utils.formatBytes32String('0:<integrator-name>') ); await authorizeAndDepositReceipt.wait(); }; main(); ``` {% endcode %} Deposits into Syrup can also be made with gasless approval using `permit`. For more information, see <https://eips.ethereum.org/EIPS/eip-2612>. {% code lineNumbers="true" expandable="true" %} ```solidity function authorizeAndDepositWithPermit( uint256 bitmap, uint256 auth_deadline, uint8 auth_v, bytes32 auth_r, bytes32 auth_s, uint256 amount, bytes32 depositData, uint256 permit_deadline, uint8 permit_v, bytes32 permit_r, bytes32 permit_s ) ``` {% endcode %} **NOTE**: `authorizeAndDepositWithPermit` is only available for `Syrup USDC`. ![authAndDepositWithPermit()](https://github.com/maple-labs/syrup-router/assets/16119563/c0e4d64f-e092-46b0-9b7f-00def236ace7) #### Code example using Maple SDK {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```typescript import { BigNumber, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () { ... // Exact same steps as regular depositWithPermit const { bitmap, authDeadline, authSig } = authorize(); // Contact the Syrup team for authorization information const authorizeAndDepositWithPermitReceipt = await syrupRouter.authorizeAndDepositWithPermit( bitmap, authDeadline, authSig.v, authSig.r, authSig.s, amount, utils.formatBytes32String('0:<integrator-name>'), deadline, sig.v, sig.r, sig.s ); await authorizeAndDepositWithPermitReceipt.wait(); } main(); ``` {% endcode %} ## Withdraw ### 1. Retrieve Pool Position Query the Maple API for the user's pool position data using the `PoolV2Position` field in the `Account` query: #### Data model {% code lineNumbers="true" %} ```gql PoolPositionV2 { availableBalance // The pool position in the pool asset. availableShares // The underlying shares representing that position. redeemRequested // A boolean indicating if a redeem request is active. } ``` {% endcode %} #### Example query {% code lineNumbers="true" %} ```gql query GetMapleAccount($accountId: ID!, $poolId: String!) { account(id: $accountId) { id poolV2Positions(where: { pool: $poolId }) { id // "$lender_address-$pool_address" availableBalance // Position in pool asset availableShares // Underlying shares redeemRequested // Boolean flag pool { name } } } } ``` {% endcode %} #### Code example using [**graphql-request**](https://www.npmjs.com/package/graphql-request) {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```typescript import { gql, GraphQLClient } from 'graphql-request'; interface MaplePoolPosition { id: string; availableBalance: string; availableShares: string; redeemRequested: boolean; pool: { name: string; }; } interface MapleAccount { id: string; poolV2Positions: MaplePoolPosition[]; } interface QueryResponse { account: MapleAccount; } const query = gql` query GetMapleAccount($accountId: ID!, $poolId: String!) { account(id: $accountId) { id poolV2Positions(where: { pool: $poolId }) { id availableBalance availableShares redeemRequested pool { name } } } } `; const client = new GraphQLClient(MAPLE_API_URL); const main = async () => { const account = '0x123...'; const { account: mapleAccount } = await client.request<QueryResponse>(query, { accountId: account.toLowerCase(), poolId: SYRUP_USDC, }); if (mapleAccount) { for (const poolV2Position of mapleAccount.poolV2Positions) { console.log(`Pool ${poolV2Position.pool.name} position for ${account}`); console.log(`Available balance: ${poolV2Position.availableBalance}`); console.log(`Available shares: ${poolV2Position.availableShares}`); } } else { console.log('Account not found'); } }; main(); ``` {% endcode %} ### 2. Calculate Shares to Redeem * Withdrawal requests must be expressed in shares. Although the Maple API provides both `availableShares` and `availableBalance`, losses or impairments on the pool may affect the value of assets relative to shares. * To ensure accuracy, convert the desired asset amount to "exit shares" using the pool contract's conversion method. * These transactions leverage the `ERC-4626` tokenized vault standard. For more information, see <https://ethereum.org/en/developers/docs/standards/tokens/erc-4626/>. #### Function signature {% code overflow="wrap" lineNumbers="true" %} ```solidity function convertToExitShares(uint256 assets_) external view returns (uint256 shares_); ``` {% endcode %} #### Code example using Maple SDK {% code lineNumbers="true" expandable="true" %} ```typescript import { BigNumber, providers } from 'ethers'; import { poolV2 } from '@maplelabs/maple-js'; const main = async () => { const provider = new providers.JsonRpcProvider(RPC_URL); const syrupPool = poolV2.core.connect(SYRUP_USDC, provider); const amount = BigNumber.from(10 ** 8); const sharesToRedeem = await syrupPool.convertToExitShares(amount); console.log(`${amount.toString()} is equal to ${sharesToRedeem.toString()}`); }; main(); ``` {% endcode %} ### 3. Execute the Withdrawal After calculating `sharesToRedeem` or fetching `availableShares`, call the `requestRedeem` method on the Pool contract to initiate the withdrawal. #### Function signature {% code lineNumbers="true" %} ```solidity function requestRedeem( uint256 shares, // Shares to redeem (from Step 1 or Step 2) address receiver // Address to receive the assets ) ``` {% endcode %} #### Code example using Maple SDK {% code lineNumbers="true" expandable="true" %} ```typescript import { BigNumber, providers, Wallet } from 'ethers'; import { poolV2 } from '@maplelabs/maple-js'; const main = async () => { const provider = new providers.JsonRpcProvider(RPC_URL); const signer = new Wallet(PRIVATE_KEY, provider); const syrupPool = poolV2.core.connect(SYRUP_USDC_POOL, signer); const account = await signer.getAddress(); const requestRedeemReceipt = await syrupPool.requestRedeem(sharesToRedeem, account); await requestRedeemReceipt.wait(); }; main(); ``` {% endcode %} ### 4. Await Withdrawal Completion Withdrawals are processed automatically by Maple. If there is sufficient liquidity in the pool, the withdrawal will be processed within a few minutes. Expected processing time is typically less than 2 days, but it can take up to 30 days depending on available liquidity. The current status of the withdrawal queue can be retrieved either directly from the `WithdrawalManagerQueue` contract or through the Maple GraphQL API: #### Example query {% code lineNumbers="true" %} ```gql query GetPoolV2Queue($id: ID!) { poolV2(id: $id) { withdrawalManagerQueue { totalShares nextRequest { id shares status } } } } ``` {% endcode %} #### Code example using [**grap
프로젝트로 돌아가기