Reserve Rights 백서

Reserve Rights

원문

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

cing deep onchain liquidity from DEXs and solver networks (e.g., CoW Swap) for rebalancing. * **Continuous fees & protocol revenue.** Block-by-block TVL (management) and Mint fees accrue transparently in DTF shares, routed according to governance specification. * **Custom onchain governance.** Flexibly-structured onchain governance can be governed by any token. This document surveys the core mechanics that keep an Index DTF reliable and decentralized, from efficient rebalancing to fee flows and onchain governance. ## Rebalancing & tracking Index DTFs are periodically rebalanced to target weights through onchain Dutch auctions. Rebalance timing is set by governance. Auctions are executed onchain through an autonomous process: {% stepper %} {% step %} ### Measure the live basket Current token proportions are calculated onchain. {% endstep %} {% step %} ### Open auctions Any surplus token is offered along a declining-price curve in exchange for a deficit token. {% endstep %} {% step %} ### Clear via open markets Solvers such as CoW Swap and direct DEX takers compete to fill orders, minimizing slippage and MEV. {% endstep %} {% step %} ### Settle and update weights Whenever an auction fills a bid the basket’s composition is updated atomically. {% endstep %} {% endstepper %} Because every step is deterministic and transparent, arbitrageurs quickly remove price discrepancies, keeping the market price close to NAV and limiting tracking error. Auction cadence & duration are adjustable by governance, enabling different index strategies without touching core code. ## Fees & revenue Unlike Yield DTFs, Index DTFs do not rely on yield-bearing collateral for revenue. Instead, two fee streams compensate governance, RSR holders, and governance-chosen addresses. | Fee type | Basis | Range | Accrual method | | -------------------- | ----------------- | -------- | ------------------------------ | | **TVL (management)** | Basket NAV | < 5% APY | Mint new DTF shares once a day | | **Mint** | Incoming issuance | < 1% | Fee deducted from each mint | All newly minted shares flow first to the platform take-rate, with the remainder split between addresses set by governance. Currently, the platform fee is used to automatically buy and burn RSR. ## Governance Each Index DTF acts like its own miniature protocol with governance rules chosen at deployment. The deployer selects any ERC-20 token—RSR by default—for vote-locking, and holders of that locked token steer the DTF’s evolution via onchain proposals. The Reserve Optimistic Governor provides a dual-path model: a **standard path** for high-impact decisions that require full community voting, and an **optimistic path** for routine operations that execute quickly unless vetoed by token holders. ### What governance decides | Area | Typical settings | | --------------------------- | ----------------------------------------------------------------------------------------------- | | **Assets & target weights** | Add, remove, or re-weight assets to reflect the desired index methodology | | **Fee schedule** | TVL (management) and Mint fees, plus the split between the platform and DTF-specific recipients | | **Rebalancing parameters** | Auction cadence & duration | | **Revenue routing** | Addresses and allocations for fee revenue | ### How it works in practice * **Standard proposals** are created, voted on, and executed entirely onchain, with timelocks to ensure time to react. This path is used for high-impact changes such as fees, basket composition, and role assignments. * **Optimistic proposals** skip affirmative voting and execute automatically after a short veto window, unless enough token holders vote Against. This path is used for routine operations like launching rebalance auctions. * Every proposal, vote, and execution is permanently recorded onchain, giving users, auditors, and regulators a transparent change history. Read more about how **Reserve Optimistic Governance** works [here](/core-components/index-dtfs/optimistic-governance). Because governance is modular and token-agnostic, one Index DTF might run a simple one-token DAO, while another could delegate voting power across multiple stakeholders or adopt more sophisticated vote-lock mechanics over time. {% hint style="warning" %} As with any smart contract application, the actual behavior may vary from the intended behavior, and it's safest to wait for an application to be in use for a long period of time before trusting it to behave as expected. This overview and subsequent documentation describe the intended behavior. {% endhint %} {% hint style="info" %} The Reserve Register does not yet support permissionless creation of Index DTFs. {% endhint %} ## Non-compatible ERC20 assets The following types of ERC20s are not supported to be used directly in an Index DTF. These tokens should be wrapped into a compatible ERC20 token to be used within the protocol. * Tokens that take a "fee" on transfer * Tokens that do not expose the decimals() function in their interface. Decimals should always be between 1 and 27. * ERC777 tokens which could allow reentrancy attacks * Tokens with multiple entry points (multiple addresses) * Tokens that do not adhere to the ERC20 standard in general # Pricing ### NAV <a href="#nav" id="nav"></a> The price of a DTF is based on a NAV (Net Asset Value) calculation. Given a DTF with a basket of `n` tokens, each with a spot price `p`, we can calculate the DTF's price as: <figure><img src="https://753544653-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEFwcfC1MMOt9iISSOBwK%2Fuploads%2Fgit-blob-20b5cf7524ae40618563c64af8fa9f9dcf55c3ab%2Fimage.png?alt=media" alt="" width="268"><figcaption></figcaption></figure> ### Onchain pricing <a href="#onchain-pricing" id="onchain-pricing"></a> The `toAssets()` function is used to convert a DTF share to its underlying assets. It will return the one-to-many exchange rate of the DTF. ``` function toAssets(uint256 shares, Math.Rounding rounding) returns (address[] memory _assets, uint256[] memory _amounts); ``` Solidity Code: [Folio.toAssets()](https://github.com/reserve-protocol/reserve-index-dtf/blob/main/contracts/Folio.sol#L311) #### Inputs <a href="#inputs" id="inputs"></a> * `shares` Number of DTF shares to quote * `rounding` Rounding method for output values (enum). One of: * \[0] Floor (Toward negative infinity) * \[1] Ceil (Toward positive infinity) * \[2] Trunc (Toward zero) * \[3] Expand (Away from zero) #### Outputs <a href="#outputs" id="outputs"></a> * `_assets` Array of addresses for each asset in the quote * `_amounts` Array of amounts of each asset in the quote # Minting & redeeming Minting/redeeming directly converts between Index DTFs and their underlying tokens—no authorized participants required. Anyone can mint or redeem permissionlessly. ![](https://753544653-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FEFwcfC1MMOt9iISSOBwK%2Fuploads%2Fgit-blob-4c9c4b656a4c0c376be9d59cb38c783ba0aa71ac%2Fissuance%20and%20redemption.svg?alt=media) For convenience, Register offers zapper helpers that let users enter or exit using other ERC‑20 and chain-native tokens in one transaction. Manual redemptions and direct contract calls enable more flexibility and provide an escape hatch if other methods are down, ensuring users are not reliant on offchain tools to exit positions. ## Protocol level vs. app level Market makers and integrators often ask what a mint or redeem actually does under the hood. The mechanics differ depending on whether you interact with the contracts directly or go through the app’s zapper—but in every case, the operation is atomic. ### At the protocol level Onchain, minting and redeeming are atomic operations in a single transaction: the user exchanges exact amounts of each basket token for an exact number of DTF tokens (or vice versa for a redeem). The exchange ratios are defined by—and readable from—the Folio.sol contracts, so the precise basket amounts for any mint or redeem can be computed in advance. ### In the app (via the zapper) When using the zapper, the user only specifies the input/output token and how much they want to spend. The zapper abstracts the rest: it trades the input token into the required basket tokens and executes the `mint` action—or executes the `redeem` action and then trades the basket tokens into the desired output token. The zapper transaction is **also** atomic, just with the added trading step packaged in series with the `mint`/`redeem` step. ### DTFs with offchain liquidity (RFQ / intents) {% hint style="info" %} Some DTFs utilize tokens whose main source of liquidity is offchain (e.g., Ondo or Universal assets). For these, the in‑app zapper might not function as well, because there is not sufficient liquidity onchain to route the trading step. Instead, we rely on RFQ / intent systems: approved minters source the underlying basket tokens as needed—effectively acting as the trading layer of the zapper—and execute the mint/redeem functionality to provide the end user with a seamless result. {% endhint %} ## How to mint or redeem There are three main ways to mint or redeem. The [Reserve app](https://app.reserve.org/) provides a convenient interface, but any front‑end can access the same permissionless contracts. {% stepper %} {% step %} ### Zapper (one‑step) *When to use:* You want to use a single ERC‑20 or ETH and let the app handle the swaps * Click the **Buy** or **Sell** button on any Index DTF page * In the **You use** or **You receive** field, pick any supported token (ETH, USDC, wBTC, etc.) * Enter an amount and review the quote Due to the volatile nature of DEXs (decentralized exchanges) and the way the zapper routes tokens, it is common to receive dust amounts of certain tokens. Generally, the amount of dust is on the order of 1–10 bps of the input value. {% endstep %} {% step %} ### Manual mint / redeem *When to use:* You hold/want the exact collateral tokens or need precise slippage control * Click **Switch to manual mode** on the DTF’s Mint/Redeem page * Review per‑token amounts to deposit/receive * Approve any necessary tokens and submit {% endstep %} {% step %} ### Direct contract call *When to use:* Integrations, scripts, advanced use cases Call `mint` or `redeem` on the DTF proxy. Basket ratios are calculated and enforced onchain. See the [smart contracts](/core-components/index-dtfs/smart-contracts) section for contract details and addresses. {% endstep %} {% endstepper %} ## Integration guides Third-party wallets, fintech applications, aggregators, and solvers can choose between two integration paths: * [**Integrate the Reserve Zapper**](/core-components/index-dtfs/minting-and-redeeming/integrating-the-zapper)**:** the recommended low-lift path for a single-token buy/sell experience. Embed the maintained React component or consume the Zapper quote API and execute its returned transaction. * [**Build native mint and redeem routes**](/core-components/index-dtfs/minting-and-redeeming/native-mint-and-redeem-integration)**:** call the Folio proxy directly, calculate the live basket and fees, and optionally compose component swaps in an integration router. # Integrating the Zapper Use the Reserve Zapper when users should be able to buy or sell an Index DTF with a single token. It quotes across supported execution providers and abstracts the component swaps plus the Folio mint or redemption. Native Zapper and aggregator routes return an atomic transaction; RFQ/intent routes such as CoW Swap instead require a signed order that is filled asynchronously by solvers. For most wallets and fintech applications, embedding the maintained React component is the shortest integration path. Applications with a custom interface can consume the same quote API directly. ## Option A: React component ### 1. Install ```bash pnpm add @reserve-protocol/react-zapper pnpm add react@^18 react-dom@^18 @tanstack/react-query@^5 wagmi@^2 viem@^2 ``` The package uses the application's existing Wagmi and TanStack Query providers. ### 2. Render the Zapper ```tsx import { Zapper } from '@reserve-protocol/react-zapper' import '@reserve-protocol/react-zapper/styles.css' export function DtfTrade({ dtfAddress }: { dtfAddress: `0x${string}` }) { return <Zapper chain={8453} dtfAddress={dtfAddress} mode="inline" /> } ``` Available display modes are `inline`, `modal`, and `simple`. The component handles quotes, input-token approvals, transaction simulation or intent signing, execution status, slippage controls, and both buy and sell flows. It consumes the host application's Wagmi account; provide the optional `connectWallet` callback when the component should open the host's wallet-connection UI. See the [React Zapper repository](https://github.com/reserve-protocol/react-zapper) and [live demo](https://react-zapper.reserve.org/) for provider setup and additional props. ## Option B: Zapper API Use this path for a non-React UI or backend-generated transaction flow. This endpoint selects the Reserve-native Zapper route and returns an atomic transaction rather than an RFQ/intent order. ### 1. Request a quote Send a `GET` request to: ``` https://api.reserve.org/api/zapper/{chainId}/swap ``` Required query parameters: | Parameter | Description | | ---------- | -------------------------------------------------------------------------------------------------------------- | | `chainId` | Base is `8453` | | `signer` | Wallet that will execute the transaction | | `tokenIn` | ERC-20 input token, or Viem's `ethAddress` native-token sentinel: `0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE` | | `amountIn` | Input amount in token base units | | `tokenOut` | DTF address for a mint; desired output token for a redemption | | `slippage` | Inverse-fraction convention: `200` = 1/200 = 0.5% | | `trade` | `true` to include component swaps | Example: quote 100 USDC into an Index DTF on Base: ``` GET https://api.reserve.org/api/zapper/8453/swap?chainId=8453&signer={WALLET}&tokenIn=0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913&amountIn=100000000&tokenOut={DTF_ADDRESS}&slippage=200&trade=true ``` To redeem, reverse `tokenIn` and `tokenOut`: use the DTF as `tokenIn`, the desired receive token as `tokenOut`, and express `amountIn` in the DTF's base units. ### 2. Inspect the response A response uses this envelope: ```json { "status": "success", "result": {} } ``` When `status` is `error`, handle the top-level `error` and do not submit a transaction. A successful `response.result` includes: * `amountOut` and `minAmountOut` * `approvalAddress` and `approvalNeeded` * `gas`, `priceImpact`, and possible component-token `dust` * `tx.to`, `tx.data`, and `tx.value` * `validUntil` when the quote has an explicit expiry Reject an error response, a missing `result.tx`, or an expired quote. Bind the response to the local request context for chain, tokens, amount, and signer because the result does not echo every request field. Applications with stricter transaction policies should also decode or allowlist the returned target and calldata before presenting it for signature. If `validUntil` is absent, apply a short local TTL and requote before submission; the React package uses 60 seconds. ### 3. Approve when required For an ERC-20 input, read the wallet's allowance to `approvalAddress`. If it is insufficient, ask the user to approve at least `amountIn`. Native-token inputs do not require an ERC-20 approval. Do not assume the spender address is constant; use the `approvalAddress` returned by the current quote. ### 4. Simulate and execute Simulate the returned transaction from `signer`, then submit: ``` to = result.tx.to data = result.tx.data value = result.tx.value ``` Fetch a new quote if simulation fails, the quote expires, or any input changes. After confirmation, determine the actual received amount from transaction logs or the wallet's balance change rather than assuming it equals the estimate. {% hint style="warning" %} A Zapper quote is wallet-specific and time-sensitive. Never reuse calldata for a different signer, and never weaken the returned minimum-output protection. {% endhint %} ## Production checklist * Use base units for every token amount. * Show `amountOut`, `minAmountOut`, price impact, estimated gas, and dust before execution. * Use the response's current `approvalAddress`. * Simulate every executable quote. * Refresh after approval and before expiry. * Preserve `tx.value` for native-token inputs. * Handle quote, approval, simulation, submission, and receipt failures independently. # Native mint and redeem integration Use direct Folio calls when an aggregator, solver, market maker, or advanced application wants to construct its own Index DTF routes. Minting and redemption are permissionless and atomic at the protocol level, but the caller must supply or receive every current basket token. This guide applies to Index DTFs. Yield DTFs use a different protocol and contract interface. ## Before integrating 1. Confirm the chain ID and canonical DTF proxy address. 2. Read the proxy's current implementation and verified ABI from the chain explorer. 3. Do not assume the implementation on the GitHub `main` branch matches the deployed proxy. 4. Read the basket and fee state for every new quote; both can change through governance. ## Native mint ### 1. Choose gross shares The `shares` argument is the gross number of DTF shares issued. The receiver gets fewer shares after the mint fee. Call: ```solidity toAssets(shares, Math.Rounding.Ceil) ``` The returned ordered `assets` and `amounts` are the exact basket tokens and quantities required for that gross issuance at the quoted state. Once a day, TVL fee accrual can result in the `amounts` changing in the downward direction. This can make a preceding view-only quote differ slightly at execution time; tightly bounded allowances, a fresh simulation, and atomic routing should cause stale quotes to fail safely. ### 2. Calculate net shares and `minSharesOut` Read `mintFee()` directly from the Folio and mirror the contract's upward rounding: ``` ceilDiv(x, y) = x == 0 ? 0 : (x - 1) / y + 1 totalFeeShares = ceilDiv(shares × mintFee, 1e18) expectedSharesOut = shares - totalFeeShares ``` Set: ``` minSharesOut = expectedSharesOut ``` for strict protection, or subtract a small, explicitly disclosed tolerance if the integration intentionally accepts a fee change between quote and execution. `minSharesOut` protects only the net DTF shares received. It does not protect the price or slippage of swaps used to acquire the basket. Use integer arithmetic rather than `shares × (1 - mintFee)` so the result matches the contract's rounding exactly. ### 3. Acquire and approve the basket Acquire every component token, approve the Folio proxy for no more than the quoted/tightly bounded amount, and keep the acquisition plus mint in one router transaction when offering a single-token UX. ### 4. Mint ```solidity mint(uint256 shares, address receiver, uint256 minSharesOut) ``` The Folio transfers each required component from `msg.sender` and mints the net shares to `receiver`. Refund any unused input or component-token dust from the integration router. ## Native redemption ### 1. Quote the current basket For the DTF shares being redeemed, call: ```solidity toAssets(shares, Math.Rounding.Floor) ``` Use the returned asset order exactly. Do not sort the addresses or reuse an array from an earlier quote. ### 2. Set component minimums Create `minAmountsOut` by applying the integration's tolerance to each expected component amount: ``` minAmountsOut[i] = floor(expectedAmounts[i] × (10_000 - toleranceBps) / 10_000) ``` These minimums protect the protocol-level component outputs. If components are subsequently swapped into one token, enforce a separate aggregate minimum output and deadline
프로젝트로 돌아가기