Maple Finance 백서

Maple Finance

원문

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

hql-request**](https://www.npmjs.com/package/graphql-request) {% code overflow="wrap" lineNumbers="true" expandable="true" %} ```typescript import { gql, GraphQLClient } from 'graphql-request'; interface MapleWithdrawalManagerQueue { totalShares: string; nextRequest: { id: string; shares: string; status: string; }; } interface MaplePool { withdrawalManagerQueue: MapleWithdrawalManagerQueue; } interface QueryResponse { poolV2: MaplePool; } const query = gql` query GetPoolV2Queue($poolId: ID!) { poolV2(id: $poolId) { withdrawalManagerQueue { totalShares nextRequest { id shares status } } } } `; const client = new GraphQLClient(MAPLE_API_URL); const main = async () => { const { poolV2 } = await client.request<QueryResponse>(query, { poolId: SYRUP_USDC, }); if (poolV2) { const { withdrawalManagerQueue } = poolV2; console.log(`Total shares in the queue ${withdrawalManagerQueue.totalShares}`); console.log( `Next request ${withdrawalManagerQueue.nextRequest.id}: ${withdrawalManagerQueue.nextRequest.shares} shares. ${withdrawalManagerQueue.nextRequest.status}` ); } }; main(); ``` {% endcode %} ## Edge Cases <details> <summary>User Not Authorized</summary> When attempting to use `deposit` or `depositWithPermit` and receiving the error `SR:D:NOT_AUTHORIZED`, it indicates that the account being used for deposit is not authorized in Syrup USD. To authorize the account, use `authorizeAndDeposit` or `authorizeAndDepositWithPermit`. **Problem:** ```typescript import { BigNumber, Contract, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... const depositReceipt = await syrupRouter.deposit( amount, utils.formatBytes32String('0:<integrator-name>') ); await depositReceipt.wait(); }; main(); ``` **Solution:** ```typescript import { BigNumber, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... 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(); ``` </details> <details> <summary>Insufficient Approval</summary> When attempting to use `deposit` or `depositWithPermit` and receiving the error `SR:D:TRANSFER_FROM_FAIL`, it indicates that `SyrupRouter` could not transfer lending tokens. Ensure that the deposit amount matches the current approval for `SyrupRouter`. If it does not, increase the approval. **Problem:** ```typescript import { BigNumber, Contract, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... const depositReceipt = await syrupRouter.deposit( amount, utils.formatBytes32String('0:<integrator-name>') ); await depositReceipt.wait(); }; main(); ``` **Solution:** ```typescript import { BigNumber, Contract, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... const account = await signer.getAddress(); const allowance = await usdc.allowance(account, SYRUP_USDC_ROUTER_ADDRESS); if (allowance.lt(amount)) { 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(); ``` </details> <details> <summary>Invalid Signature</summary> When attempting to use `depositWithPermit` and receiving the error `ERC20:P:INVALID_SIGNATURE`, it indicates that the recovered address from the signature does not match the address attempting to deposit. Ensure that the signature is signed by the account executing the transaction. </details> <details> <summary>Expired Signature</summary> When attempting to use `depositWithPermit` and receiving the error `ERC20:P:EXPIRED`, it indicates that the permit signature has expired. Ensure that the deadline set on the signature provides sufficient time to execute the transaction. </details> <details> <summary>Insufficient Gas</summary> When transactions fail due to insufficient gas, increase the gas limit in the transaction parameters. Syrup operations require more gas than simple token transfers due to the complex authorization and routing logic. **Problem:** ```typescript import { BigNumber, Contract, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... const depositReceipt = await syrupRouter.deposit( amount, utils.formatBytes32String('0:<integrator-name>') ); await depositReceipt.wait(); }; main(); ``` **Solution:** ```typescript import { BigNumber, Contract, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... // Estimate gas and add 20% const gasEstimate = await syrupRouter.estimateGas.deposit( amount, utils.formatBytes32String('0:<integrator-name>') ); const gasLimit = gasEstimate.mul(120).div(100); const depositReceipt = await syrupRouter.deposit( amount, utils.formatBytes32String('0:<integrator-name>'), { gasLimit } ); await depositReceipt.wait(); }; main(); ``` </details> <details> <summary>Pool Deposit Limit Exceeded</summary> When encountering error `P:DEPOSIT_GT_LIQ_CAP`, it means the deposit amount exceeds the pool's deposit limit. Check the pool's current capacity before attempting large deposits. **Problem:** ```typescript import { BigNumber, Contract, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... const depositReceipt = await syrupRouter.deposit( amount, utils.formatBytes32String('0:<integrator-name>') ); await depositReceipt.wait(); }; main(); ``` **Solution:** ```typescript import { BigNumber, Contract, providers, utils, Wallet } from "ethers"; import { addresses, syrupUtils } from "@maplelabs/maple-js"; const main = async () => { ... const account = await signer.getAddress(); const syrupPool = poolV2.core.connect( SYRUP_POOL, signer, ); const maxDeposit = await syrupPool.maxDeposit(account); if (maxDeposit.lt(amount)) { amount = maxDeposit } const depositReceipt = await syrupRouter.deposit( amount, utils.formatBytes32String('0:<integrator-name>') ); await depositReceipt.wait(); }; main(); ``` To perform a deposit larger than the limit, contact the Syrup team via [Telegram](https://t.me/syrupfi). </details> ## FAQ <details> <summary>What is the difference between Syrup and Maple?</summary> Syrup is the protocol - the smart contracts that power onchain lending. Maple encompasses the entities that conduct institutional lending services using this infrastructure. **For developers:** You'll be integrating with Syrup (the protocol), while Maple handles the institutional lending operations. </details> <details> <summary>What is the authorize and deposit function with permit?</summary> The `authorizeAndDepositWithPermit` function combines three operations into a single transaction: 1. **Authorization**: Grants permission to deposit into Syrup pools (required for first-time users) 2. **Permit**: Provides gasless token approval using [EIP-2612](https://eips.ethereum.org/EIPS/eip-2612) standard 3. **Deposit**: Transfers tokens and mints pool shares This function is ideal for first-time users who want to deposit USDC without requiring separate authorization and approval transactions. It saves gas and improves user experience by reducing the number of required transactions from three to one. **NOTE**: Only available for USDC deposits, not USDT. </details> <details> <summary>What are the permit signature parameters?</summary> There are 5 parameters required for permit signature: * **`owner`**: The wallet address that owns the tokens and is granting permission (typically the user's address) * **`spender`**: The contract address receiving approval (the `SyrupRouter` contract address) * **`value`**: The token amount in smallest units (for USDC: 6 decimals, e.g., 1000000 = 1 USDC) that the spender is allowed to spend * **`nonce`**: A unique number preventing replay attacks (obtained by calling `nonces(address)` on the token contract). It increments with each permit signature used * **`deadline`**: Unix timestamp when the permit expires **Example** ```typescript const permitMessage = { owner: account, spender: SYRUP_USDC_ROUTER_ADDRESS, value: '1000000', // 1 USDC nonce: await usdc.nonces(account), deadline: Math.floor(Date.now() / 1000) + 3600, // 1 hour from now }; ``` </details> <details> <summary>Do I need authorization for smart contract integration?</summary> Yes, authorization is required for all Syrup deposits. Syrup protocol is built by Maple, which uses a permissioning system for institutional-grade security. **Authorization Process** 1. Contact us at <partnerships@maple.finance> for eligibility verification 2. Receive authorization signature parameters 3. Use `authorizeAndDeposit` or `authorizeAndDepositWithPermit` for first deposit 4. Subsequent deposits only need `deposit` or `depositWithPermit` Once authorized, the permission persists across all Syrup pools and future deposits. </details> <details> <summary>How do withdrawals work?</summary> Withdrawals follow a queue-based system: 1. **Request**: Call `requestRedeem()` to enter the withdrawal queue 2. **Queue Position**: Withdrawals are processed first-in, first-out (FIFO) 3. **Processing**: When pool liquidity is available, withdrawals are automatically processed 4. **Completion**: Assets are sent directly to the wallet (no additional transaction required) **Timeline** * Expected processing time is typically less than 2 days * During low liquidity periods, it may take up to 30 days * No penalties for withdrawing, but yield stops accumulating once withdrawal is requested </details> <details> <summary>How long do withdrawals take?</summary> syrupUSDC & syrupUSDT normally have instant liquidity, but in rare cases withdrawals can take around 24h with the maximum possible time being 30 days. You can see the available funds to withdraw in the Liquidity section of the [Details page](https://app.maple.finance/earn/details). </details> <details> <summary>How can I get the APY data for syrupUSDC or syrupUSDT?</summary> Querying the GraphQL API is the simplest way to get APY data for syrupUSDC or syrupUSDT into your app. **Example request** ``` { poolV2(id: "0x80ac24aa929eaf5013f6436cda2a7ba190f5cc0b") { name weeklyApy monthlyApy } syrupGlobals { dripsYieldBoost } } ``` **This returns** ``` { "data": { "poolV2": { "name": "Syrup USDC", "weeklyApy": "69937809610000000000000000000", "monthlyApy": "67212806350000000000000000000" }, "syrupGlobals": { "apy": "69731920498003078965054825961", "dripsYieldBoost": "0" } } } ``` You can get the APY % by using the fomula: `APY % = rawValue / 1e28` In the example above, the monthly base APY is 6.72%. Drips have been discontinued after Q4 2025 in favour of rewards distributed via Merkl for using partner products. You can discard `dripsYieldBoost` going forward. Read more: [Drips Rewards](/syrupusdc-usdt-usdg-for-lenders/drips-rewards) </details> <details> <summary>How can I get the price received on redemption for syrupUSDC or syrupUSDT?</summary> syrupUSDC and syrupUSDT are redeemed at the smart contract exchange rate at the point of processing the withdrawal, incurring no slippage. You can get the spot exchange rate for syrupUSDC to USDC or syrupUSDT to USDT by querying the GraphQL API. **Example request** ``` { account(id: "0xyourwallet") { poolV2Positions { pool { asset { symbol decimals } id name } lendingBalance totalShares } } } ``` **This returns** ``` { "data": { "account": { "poolV2Positions": [ { "pool": { "asset": { "symbol": "USDC", "decimals": 6 }, "id": "0x80ac24aa929eaf5013f6436cda2a7ba190f5cc0b", "name": "Syrup USDC" }, "lendingBalance": "3102053352414", "totalShares": "2742550894631" } ] } } } ``` The ratio of `lendingBalance` / `totalShares` is the spot exchange rate. </details> # Smart Contract Integration Integrate syrupUSDC, syrupUSDT & syrupUSDG via smart contracts on Ethereum mainnet. Your contracts must deposit through SyrupRouter with authorization handled PoolPermissionManager. {% hint style="info" %} **Step-by-step** **Deposit:** 1. [**Determine lender authorization**](#id-1.-determine-lender-authorization-onchain) (onchain via PoolPermissionManager) 2. [**Retrieve authorization signature**](#id-2.-retrieve-authorization-signature) (from Maple) 3. [**Execute the deposit**](#id-3.-execute-the-deposit) (authorize-and-deposit or deposit) **Withdraw:** 1. [**Retrieve lender balance**](#id-1.-retrieve-lenders-balance) (shares) 2. [**Calculate shares to redeem**](#id-2.-calculate-shares-to-redeem) (full balance or convertToExitShares for partial) 3. [**Execute the withdrawal**](#id-3.-execute-the-withdrawal) (requestRedeem) {% endhint %} ## Overview ### 1. Syrup Protocol Overview Smart contracts integrating with syrupUSDC & syrupUSDT act as lenders and must interact via `SyrupRouter`. Authorization is enforced by `PoolPermissionManager`. First-time deposits require an authorization signature; subsequent deposits can call `deposit` directly once authorized. ### 2. SyrupRouter Interface Below are the primary functions exposed by `SyrupRouter` for integrators. These mirror the onchain interface and are stable entry points for deposits: {% code overflow="wrap" expandable="true" %} ```solidity // Events event DepositData(address indexed owner, uint256 amount, bytes32 depositData); // Views function asset() external view returns (address); function pool() external view returns (address); function poolManager() external view returns (address); function poolPermissionManager() external view returns (address); function nonces(address owner) external view returns (uint256); // First-time (with authorization signature) function authorizeAndDeposit( uint256 bitmap, uint256 deadline, uint8 v, bytes32 r, bytes32 s, uint256 amount, bytes32 depositData ) external returns (uint256 shares); // First-time with ERC-2612 token permit function authorizeAndDepositWithPermit( uint256 bitmap, uint256 authDeadline, uint8 authV, bytes32 authR, bytes32 authS, uint256 amount, bytes32 depositData, uint256 permitDeadline, uint8 permitV, bytes32 permitR, bytes32 permitS ) external returns (uint256 shares); // Subsequent deposits (already authorized) function deposit(uint256 amount, bytes32 depositData) external returns (uint256 shares); function depositWithPermit( uint256 amount, uint256 deadline, uint8 v, bytes32 r, bytes32 s, bytes32 depositData ) external returns (uint256 shares); ``` {% endcode %} Notes for implementers: * Authorization signature: For first-time deposits, Maple (a permission admin) provides an ECDSA signature authorizing the lender’s bitmap permissions. The signature digest includes `chainId`, the `SyrupRouter` address, the `owner` (msg.sender), a `nonce`, the `bitmap`, and `deadline`. Your smart contract should pass this signature through to `authorizeAndDeposit`/`authorizeAndDepositWithPermit`. * Permissions: The router enforces `PoolPermissionManager.hasPermission(poolManager, owner, "P:deposit")`. Your address must be permissioned (via allowlist or bitmaps) before deposits succeed. * Deposit metadata: `depositData` is a `bytes32` field emitted via `DepositData` for off-chain correlation (e.g., internal IDs). Use a pre-hashed value if longer than 32 bytes. * Gas optimization: Prefer `depositWithPermit` where the asset supports EIP‑2612 to avoid a separate approval step. ### 3. Syrup Addresses All ABIs are available on GitHub: [Maple JS (ABIs)](https://github.com/maple-labs/maple-js/tree/main/src/abis) {% tabs %} {% tab title="Mainnet" %} **syrupUSDC** <table><thead><tr><th width="224.77734375">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolV2</td><td><a href="https://etherscan.io/address/0x80ac24aA929eaF5013f6436cdA2a7ba190f5Cc0b">0x80ac24aA929eaF5013f6436cdA2a7ba190f5Cc0b</a></td></tr><tr><td>SyrupRouter</td><td><a href="https://etherscan.io/address/0x134cCaaA4F1e4552eC8aEcb9E4A2360dDcF8df76">0x134cCaaA4F1e4552eC8aEcb9E4A2360dDcF8df76</a></td></tr><tr><td>WithdrawalManagerQueue</td><td><a href="https://etherscan.io/address/0x1bc47a0Dd0FdaB96E9eF982fdf1F34DC6207cfE3">0x1bc47a0Dd0FdaB96E9eF982fdf1F34DC6207cfE3</a></td></tr><tr><td>USDC</td><td><a href="https://etherscan.io/address/0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48">0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48</a></td></tr></tbody></table> **syrupUSDT** <table><thead><tr><th width="224.82421875">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolV2</td><td><a href="https://etherscan.io/address/0x356B8d89c1e1239Cbbb9dE4815c39A1474d5BA7D">0x356B8d89c1e1239Cbbb9dE4815c39A1474d5BA7D</a></td></tr><tr><td>SyrupRouter</td><td><a href="https://etherscan.io/address/0xF007476Bb27430795138C511F18F821e8D1e5Ee2">0xF007476Bb27430795138C511F18F821e8D1e5Ee2</a></td></tr><tr><td>WithdrawalManagerQueue</td><td><a href="https://etherscan.io/address/0x86eBDf902d800F2a82038290B6DBb2A5eE29eB8C">0x86eBDf902d800F2a82038290B6DBb2A5eE29eB8C</a></td></tr><tr><td>USDT</td><td><a href="https://etherscan.io/address/0xdAC17F958D2ee523a2206206994597C13D831ec7">0xdAC17F958D2ee523a2206206994597C13D831ec7</a></td></tr></tbody></table> **syrupUSDG** <table><thead><tr><th width="224.82421875">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolV2</td><td><a href="https://etherscan.io/address/0x87b65C4aAFFA76881f9E96F3e7ED945ddFC3Cd7A">0x87b65C4aAFFA76881f9E96F3e7ED945ddFC3Cd7A</a></td></tr><tr><td>SyrupRouter</td><td><a href="https://etherscan.io/address/0x191ac16255f49F7C6cB2e3b2502064A805943849">0x191ac16255f49F7C6cB2e3b2502064A805943849</a></td></tr><tr><td>WithdrawalManagerQueue</td><td><a href="https://etherscan.io/address/0xAf63C06970086d535F338565D77c5fA3bDC5fD79">0xAf63C06970086d535F338565D77c5fA3bDC5fD79</a></td></tr><tr><td>USDG</td><td><a href="https://etherscan.io/address/0xe343167631d89B6Ffc58B88d6b7fB0228795491D">0xe343167631d89B6Ffc58B88d6b7fB0228795491D</a></td></tr></tbody></table> **Shared (Global)** <table><thead><tr><th width="225.08984375">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolPermissionManager</td><td><a href="https://etherscan.io/address/0xBe10aDcE8B6E3E02Db384E7FaDA5395DD113D8b3">0xBe10aDcE8B6E3E02Db384E7FaDA5395DD113D8b3</a></td></tr></tbody></table> {% endtab %} {% tab title="Sepolia" %} **syrupUSDC** <table><thead><tr><th width="235.4921875">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolV2</td><td><a href="https://sepolia.etherscan.io/address/0x2d8D21FeE98d060655729eFD7b14bc432C375aC1">0x2d8D21FeE98d060655729eFD7b14bc432C375aC1</a></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><tr><td>USDC</td><td><a href="https://sepolia.etherscan.io/address/0xC40E5D31187ae7AFC6238594765DA5873A5bB8ed">0xC40E5D31187ae7AFC6238594765DA5873A5bB8ed</a></td></tr></tbody></table> **syrupUSDT** <table><thead><tr><th width="228.4453125">Contract</th><th>Address</th></tr></thead><tbody><tr><td>PoolV2</td><td><a hre
프로젝트로 돌아가기