Movement 백서

Movement

원문

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

ple return: 1000000_00000000 (1,000,000 gMOVE) ``` **Use cases** * TVL calculation: `total_supply * exchange_rate` * Market cap tracking * Analytics dashboards *** ### 3. `get_total_value()` Returns the total value locked (TVL) in MOVE. **Signature** ```move #[view] public fun get_total_value(): u128 ``` **Returns** * `u128`: Total active stake in MOVE (8 decimals) **Example** ```bash movement move view \ --function-id <MODULE_ADDRESS>::liquid_staking::get_total_value # Example return: 1100000_00000000 (1,100,000 MOVE) ``` **Relationship** ```text exchange_rate = get_total_value() / get_total_supply() ``` *** ### 4. `get_protocol_statistics()` Returns comprehensive protocol statistics in a single call. **Signature** ```move #[view] public fun get_protocol_statistics(): (u128, u128, u128, u64) ``` **Returns (in order)** 1. `u128`: Total value (MOVE), 8 decimals 2. `u128`: Total supply (gMOVE), 8 decimals 3. `u128`: Exchange rate, 10^9 precision 4. `u64`: Active validator count **Example** ```bash movement move view \ --function-id <MODULE_ADDRESS>::liquid_staking::get_protocol_statistics # Example return: # [ # "5999913835", // 59.99913835 MOVE # "6000204652", // 60.00204652 gMOVE # "999951532", // 0.999951532 exchange rate # "1" // 1 active validator # ] ``` **Use cases** * Dashboard displays * Single RPC call for complete state * Monitoring and alerting *** ### 5. `get_user_unstake_requests(address)` Returns all pending unstake requests for a specific address. **Signature** ```move #[view] public fun get_user_unstake_requests(user: address): vector<UnstakeRequest> ``` **Parameters** * `user`: Address to query **Returns** * `vector<UnstakeRequest>`: List of pending unstake requests, each containing: * `user`: Address of the unstaker * `gmove_amount`: gMOVE burned * `coin_amount`: Expected MOVE to receive * `unlock_time`: Timestamp when claimable (seconds since epoch) * `validator_unstakes`: Per-validator breakdown **Example** ```bash movement move view \ --function-id <MODULE_ADDRESS>::liquid_staking::get_user_unstake_requests \ --args address:0x123... # Example return: # [{ "user": "0x123...", "gmove_amount": "3000000000", "coin_amount": "2999892291", # "unlock_time": "1770771292", "validator_unstakes": [...] }] ``` **Additional view functions** * `get_user_unstake_request(user, request_id)` - Get a specific request * `check_can_claim(user, request_id)` - Check if a request is ready to claim **Use cases** * Wallet displays showing pending withdrawals * Countdown timers for unlock * Claiming flow UI *** ### 6. `get_protocol_config()` Returns the protocol configuration including the resource account address. **Signature** ```move #[view] public fun get_protocol_config(): (address, u64, u128, bool) ``` **Returns (in order)** 1. `address`: Resource account address 2. `u64`: Minimum stake amount (octas) 3. `u128`: Precision multiplier (10^9) 4. `bool`: Whether the protocol is paused **Example** ```bash movement move view \ --function-id <MODULE_ADDRESS>::liquid_staking::get_protocol_config # Example return: # [ # "0xd77f9e4e2a5dc1c9e9c567a39ec49ac388997f137e75ba92e12d5de75981804c", # "1000100000", # "1000000000", # false # ] ``` **Use cases** * Block explorer integrations * Verifying delegation on validators * Checking protocol pause status * Advanced analytics *** ## Entry Functions (State-Changing) These functions modify blockchain state and require a transaction signature. ### 1. `stake_and_mint(amount: u64)` Stake MOVE and receive gMOVE. **Signature** ```move public entry fun stake_and_mint(account: &signer, amount: u64) ``` **Parameters** * `account`: Signer (user wallet) * `amount`: MOVE amount to stake (8 decimals) **Flow** 1. Withdraws `amount` MOVE from user's primary store 2. Delegates to validator via resource account 3. Calculates gMOVE to mint based on exchange rate 4. Mints gMOVE to user's primary store **Example** ```bash # Stake 100 MOVE movement move run \ --function-id <MODULE_ADDRESS>::liquid_staking::stake_and_mint \ --args u64:10000000000 ``` **Example in Move** ```move use liquid_staking; public entry fun stake_for_user(user: &signer) { let amount = 100_00000000; // 100 MOVE liquid_staking::stake_and_mint(user, amount); } ``` **Important** * User must have at least `amount` MOVE in primary store * User must have migrated to fungible store (`coin::migrate_to_fungible_store`) * First depositor has 10 MOVE permanently locked (MINIMUM\_LIQUIDITY protection) *** ### 2. `stake_and_mint_with_slippage(amount: u64, min_gmove_out: u64)` Stake MOVE with slippage protection. **Signature** ```move public entry fun stake_and_mint_with_slippage( account: &signer, amount: u64, min_gmove_out: u64 ) ``` **Parameters** * `account`: Signer * `amount`: MOVE amount to stake * `min_gmove_out`: Minimum gMOVE to receive (reverts if less) **Use cases** * Front-running protection * User specifies acceptable exchange rate range **Example** ```bash # Stake 100 MOVE, expect at least 95 gMOVE (5% slippage tolerance) movement move run \ --function-id <MODULE_ADDRESS>::liquid_staking::stake_and_mint_with_slippage \ --args u64:10000000000 u64:9500000000 ``` *** ### 3. `burn_and_unstake(amount: u64)` Burn gMOVE and initiate unstaking process. **Signature** ```move public entry fun burn_and_unstake(account: &signer, amount: u64) ``` **Parameters** * `account`: Signer * `amount`: gMOVE amount to unstake (8 decimals) **Flow** 1. Burns `amount` gMOVE from user 2. Calculates MOVE value based on exchange rate 3. Unlocks stake from validator (starts 14-day unbonding) 4. Records pending unstake for user with a `request_id` **After 14 days** * User calls `claim_unlocked(request_id)` to receive MOVE **Example** ```bash # Unstake 50 gMOVE movement move run \ --function-id <MODULE_ADDRESS>::liquid_staking::burn_and_unstake \ --args u64:5000000000 ``` **Important** * User waits 14 days before claiming MOVE * gMOVE is burned immediately (stops earning rewards) * User can have multiple pending unstake requests (each with a unique `request_id`) *** ### 4. `burn_and_unstake_with_slippage(amount: u64, min_move_out: u64)` Unstake with slippage protection. **Signature** ```move public entry fun burn_and_unstake_with_slippage( account: &signer, amount: u64, min_move_out: u64 ) ``` **Parameters** * `account`: Signer * `amount`: gMOVE amount to unstake * `min_move_out`: Minimum MOVE to receive after 14 days (reverts if less) *** ### 5. `claim_unlocked(request_id: u64)` Claim MOVE after the unbonding period. **Signature** ```move public entry fun claim_unlocked(account: &signer, request_id: u64) ``` **Parameters** * `account`: Signer * `request_id`: The ID of the unstake request to claim **Flow** 1. Checks if unbonding period has passed 2. Withdraws MOVE from validator delegation 3. Transfers MOVE to user's primary store 4. Removes the unstake request **Example** ```bash movement move run \ --function-id <MODULE_ADDRESS>::liquid_staking::claim_unlocked \ --args u64:0 ``` **Errors** * `EUNLOCK_NOT_READY`: Unbonding period hasn't passed yet * `EREQUEST_NOT_FOUND`: No unstake request with this ID * `EINVALID_REQUEST`: Request doesn't belong to the caller *** ### 6. `harvest_and_compound()` Anyone can call this to compound staking rewards and update the exchange rate. No signer required. **Signature** ```move public entry fun harvest_and_compound() ``` **Flow** 1. Withdraws accumulated rewards from validator 2. Restakes rewards back into validator 3. Exchange rate increases for all gMOVE holders **Example** ```bash movement move run \ --function-id <MODULE_ADDRESS>::liquid_staking::harvest_and_compound ``` **Use cases** * Protocol keepers call this periodically * Users can call to update exchange rate before large operations * Bots can call when it is economically beneficial *** ## Integration Patterns ### Pattern 1: Wallet Integration **Display gMOVE balance and value** ```tsx // Pseudocode async function getGMoveInfo(userAddress: string) { // Get user's gMOVE balance (from FA primary store) const gmoveBalance = await getBalance(userAddress, GMOVE_METADATA); // Get current exchange rate const rate = await view({ function: `${MODULE_ADDRESS}::liquid_staking::get_exchange_rate`, type_arguments: [], arguments: [] }); // Calculate MOVE value const exchangeRate = rate[0] / 1_000_000_000; const moveValue = gmoveBalance * exchangeRate; return { gmoveBalance, moveValue, exchangeRate }; } ``` **Show pending unstakes** ```tsx async function getPendingUnstake(userAddress: string) { const requests = await view({ function: `${MODULE_ADDRESS}::liquid_staking::get_user_unstake_requests`, type_arguments: [], arguments: [userAddress] }); return requests.map(req => { const now = Date.now() / 1000; const isReady = req.unlock_time <= now; const timeRemaining = isReady ? 0 : req.unlock_time - now; return { amount: req.coin_amount / 100_000_000, unlockTime: req.unlock_time, isReady, daysRemaining: timeRemaining / 86400 }; }); } ``` *** ### Pattern 2: DEX Integration **Price oracle for gMOVE/MOVE pool** ```move // In your DEX contract use liquid_staking; public fun get_gmove_fair_value(): u64 { // Get exchange rate from gMOVE protocol let rate = liquid_staking::get_exchange_rate(); // This is the fair value: 1 gMOVE = `rate` MOVE rate } public fun check_pool_health(pool_price: u64, max_deviation_bps: u64): bool { let fair_value = get_gmove_fair_value(); let deviation = if (pool_price > fair_value) { ((pool_price - fair_value) as u128) * 10000 / (fair_value as u128) } else { ((fair_value - pool_price) as u128) * 10000 / (fair_value as u128) }; (deviation as u64) <= max_deviation_bps } ``` **Arbitrage detection** ```tsx async function checkArbitrageOpportunity() { // Get fair value from protocol const rateRaw = await getExchangeRate(); const fairValue = rateRaw / 1_000_000_000; // Get DEX price const dexPrice = await getDexPrice('gMOVE', 'MOVE'); // Calculate deviation const deviation = (dexPrice - fairValue) / fairValue; if (Math.abs(deviation) > 0.01) { // 1% deviation return { hasOpportunity: true, fairValue, dexPrice, deviation, action: deviation > 0 ? 'SELL_GMOVE' : 'BUY_GMOVE' }; } return { hasOpportunity: false }; } ``` *** ### Pattern 3: Lending Protocol Integration **Use gMOVE as collateral** ```move use liquid_staking; use fungible_asset::{Self, FungibleAsset}; // Calculate borrowing power public fun get_borrow_power(gmove_collateral: u64, ltv_bps: u64): u64 { let exchange_rate = liquid_staking::get_exchange_rate(); // Convert gMOVE to MOVE value let move_value = (gmove_collateral as u128) * (exchange_rate as u128) / 1_000_000_000; // Apply LTV (e.g., 75% = 7500 bps) let borrow_power = move_value * (ltv_bps as u128) / 10000; (borrow_power as u64) } // Check if position is healthy public fun is_position_healthy( gmove_collateral: u64, debt: u64, liquidation_threshold_bps: u64 ): bool { let exchange_rate = liquid_staking::get_exchange_rate(); let collateral_value = (gmove_collateral as u128) * (exchange_rate as u128) / 1_000_000_000; let max_debt = collateral_value * (liquidation_threshold_bps as u128) / 10000; (debt as u128) <= max_debt } ``` *** ### Pattern 4: Dashboard / Analytics **Track protocol metrics** ```tsx async function getProtocolMetrics() { const [totalValue, totalSupply, exchangeRate, validatorCount] = await view({ function: `${MODULE_ADDRESS}::liquid_staking::get_protocol_statistics`, type_arguments: [], arguments: [] }); return { tvl: totalValue / 100_000_000, // MOVE supply: totalSupply / 100_000_000, // gMOVE exchangeRate: exchangeRate / 1_000_000_000, validatorCount, avgStakePerValidator: (totalValue / validatorCount) / 100_000_000 }; } ``` **Track exchange rate history** ```tsx // Poll exchange rate periodically and store async function trackExchangeRate() { const rate = await getExchangeRate(); const timestamp = Date.now(); // Store in database await db.insert({ timestamp, exchangeRate: rate / 1_000_000_000, block: await getCurrentBlock() }); // Calculate APY based on historical data const rateOneYearAgo = await db.getRateAt(timestamp - 365*24*60*60*1000); const apy = ((rate / rateOneYearAgo) - 1) * 100; return { currentRate: rate, estimatedAPY: apy }; } ``` *** ## Error Codes Understanding error codes for better error handling: | Error Code | Constant | Meaning | How to Fix | | ---------- | ------------------------- | -------------------------------------------- | --------------------------------------------- | | `2` | `EALREADY_INITIALIZED` | Protocol already initialized | N/A (admin only) | | `3` | `EZERO_AMOUNT` | Amount is zero | Require amount > 0 | | `4` | `EINSUFFICIENT_BALANCE` | User does not have enough MOVE/gMOVE | Check balance before transaction | | `5` | `ENO_EXCHANGE_RATE` | Exchange rate unavailable | Ensure protocol has stake | | `7` | `EINVALID_POOL` | Delegation pool does not exist | Contact admin | | `8` | `EPAUSED` | Protocol is paused | Wait for unpause | | `9` | `EMIN_STAKE_NOT_MET` | Below minimum stake (10.001 MOVE) | Increase stake amount | | `10` | `EINVALID_VALIDATOR_SET` | Invalid validator configuration | Contact admin | | `11` | `ESLIPPAGE_EXCEEDED` | Output less than min specified | Adjust slippage tolerance | | `12` | `EUNLOCK_NOT_READY` | Unbonding period not finished | Wait until unlock time | | `13` | `EINVALID_REQUEST` | Request does not belong to caller | Use correct account | | `14` | `EREQUEST_NOT_FOUND` | No pending unstake to claim | Check request ID | | `15` | `EUNAUTHORIZED` | Caller is not `@liquid_staking` admin | Only module deployer can call admin functions | | `16` | `ETOO_MANY_VALIDATORS` | Cannot add more validators | N/A (20 validator limit) | | `17` | `EVALIDATOR_HAS_STAKE` | Validator still has stake | Wait for stake to be fully withdrawn | | `18` | `EEXCHANGE_RATE_OVERFLOW` | Exchange rate calculation overflow | Contact admin | | `19` | `EVALIDATOR_NOT_INACTIVE` | Validator not in inactive list | Only applies to cleanup/admin unstake | | `20` | `EINVALID_MOVE_METADATA` | MOVE FA metadata not found | Ensure FA migration completed | | `21` | `EDUPLICATE_VALIDATOR` | Validator already in active or inactive list | Validator already tracked | | `22` | `EQUEUE_NOT_INITIALIZED` | UnstakeQueue not initialized | Wait for protocol initialization | **Example error handling** ```tsx try { await stake(amount); } catch (error) { if (error.includes('EINSUFFICIENT_BALANCE')) { showError('Insufficient MOVE balance'); } else if (error.includes('EPAUSED')) { showError('Protocol is temporarily paused'); } else if (error.includes('ESLIPPAGE_EXCEEDED')) { showError('Price moved unfavorably. Please try again.'); } } ``` *** ## Best Practices ### 1. Always use view functions for read operations * View functions are free (no gas) * Call via RPC, not via transactions * Cache results appropriately (exchange rate changes infrequently) ### 2. Use slippage protection for user-facing operations * Prefer `stake_and_mint_with_slippage()` over `stake_and_mint()` * Prefer `burn_and_unstake_with_slippage()` over `burn_and_unstake()` * Recommend 0.5% to 1% slippage tolerance for users ### 3. Monitor exchange rate * Should only increase (monotonically) * Set up alerts for unexpected behavior * Any decrease indicates slashing or critical issue ### 4. Handle precision correctly * gMOVE: 8 decimals (same as MOVE) * Exchange rate: 10^9 precision * Always use `u128` for intermediate calculations to avoid overflow ```move // WRONG - can overflow let value = gmove_amount * exchange_rate / 1_000_000_000; // CORRECT - use u128 let value = ((gmove_amount as u128) * (exchange_rate as u128) / 1_000_000_000) as u64; ``` ### 5. Educate users about the 14-day unbonding period * Make the 14-day wait **very clear** in UI * Offer DEX instant exit as an alternative * Show a countdown timer for pending unstakes ### 6. Batch view calls * Use `get_protocol_statistics()` instead of multiple individual calls * Reduces RPC load and improves performance ### 7. Respect epoch voting power limits * Large deposits may be rate-limited by validator epoch capacity * Break large deposits into smaller chunks if needed * Communicate this limitation to users staking large amounts *** ## Testing ### Testnet testing checklist * [ ] Successfully call all view functions * [ ] Stake small amount (e.g., 11 MOVE) * [ ] Verify gMOVE balance increased correctly * [ ] Check exchange rate matches expected value * [ ] Unstake small amount * [ ] Wait for testnet unbonding (6 hours) * [ ] Claim unstaked MOVE successfully * [ ] Test slippage protection (both directions) * [ ] Verify error handling for edge cases * [ ] Test with multiple accounts * [ ] Monitor exchange rate over time ### Example test script ```bash #!/bin/bash MODULE_ADDR="0xb52bac12e50458cd2b958b82b05e3a240834eefbfc4b1bc0729fd580c625f1ea" echo "1. Get initial exchange rate" movement move view --function-id $MODULE_ADDR::liquid_staking::get_exchange_rate echo "2. Stake 11 MOVE" movement move run --function-id $MODULE_ADDR::liquid_staking::stake_and_mint \ --args u64:1100000000 --profile test --assume-yes echo "3. Check protocol stats" movement move view --function-id $MODULE_ADDR::liquid_staking::get_protocol_statistics echo "4. Unstake 5 gMOVE" movement move run --function-id $MODULE_ADDR::liquid_staking::burn_and_unstake \ --args u64:500000000 --profile test --assume-yes echo "5. Check pending unstake requests" movement move view --function-id $MODULE_ADDR::liquid_staking::get_user_unstake_requests \ --args address:0x... # your address echo "6. Wait 6 hours (testnet unbonding)..." echo "7. Then claim:" # movement move run --function-id $MODULE_ADDR::liquid_staking::claim_unlocked \ # --args u64:0 --profile test --assume-yes ``` *** ## Appendix: Complete ABI ```move module liquid_staking { // ========== View Functions ========== #[view] public fun get_exchange_rate(): u128 #[view] public fun get_total_supply(): u128 #[view] public fun get_total_value(): u128 #[view] public fun get_protocol_statistics(): (u128, u128, u128, u64) #[view] public fun get_user_unstake_requests(user: address): vector<UnstakeRequest> #[view] public fun get_user_unstake_request(user: address, request_id: u64): UnstakeRequest #[view] public fun check_can_claim(user: address, request_id: u64): bool #[view] public fun get_protocol_config(): (address, u64, u128, bool) #[view] public fun get_active_validators(): vector<address> #[view] public fun get_validator_stakes(validator: address): (u64, u64, u64) #[view] public fun get_gmove_metadata(): Object<Metadata> #[view] public fun get_unbonding_duration(): u64 #[view] public fun get_minimum_stake_amount(): u64 #[view] public fun get_precision_multiplier(): u128 #[view] public fun is_protocol_initialized(): bool #[view] public fun preview_stake(move_amount: u64): u128 #[view] public fun preview_unstake(gmove_amount: u64): u128 // ========== Entry Functions ========== public entry fun stake_and_mint(account: &signer, amount: u64) public entry fun stake_and_mint_with_slippage( account: &signer, amount: u64, min_gmove_out: u64 ) public entry fun burn_and_unstake(account: &signer, amount: u64) public entry fun burn_and_unstake_with_slippage( account: &signer, amount: u64, min_move_out: u64 ) public entry fun claim_unlocked(account: &signer, request_id: u64) public entry fun harvest_and_compound() // ========== Admin Functions (@liquid_staking only) ========== // All admin functions require signer to be the module deployer address. // Calling from any other address will abort with EUNAUTHORIZED (15). public entry fun initialize(admin: &signer) public entry fun initialize_testnet(a
프로젝트로 돌아가기