Skip to main content

Unbonding Process

Overview​

The unbonding process in shMONAD allows users to withdraw their tokens from a policy after completing a mandatory escrow period. This mechanism ensures system stability and prevents rapid liquidity shifts while protecting against potential attacks.

Key Concepts​

Escrow Period​

  • Defined per policy during creation
  • Cannot be modified after policy creation
  • Applies to all unbonding operations within the policy
  • Measured in blocks for precise timing

Token States​

Tokens can exist in three states during the unbonding process:

  1. Bonded: Actively locked in a policy
  2. Unbonding: In the escrow period after initiating unbonding
  3. Claimable: Ready to be claimed after escrow period completion

Unbonding Operations​

Initiating Unbonding​

Start the unbonding process using:

function unbond(
    uint64 policyID,
    uint256 amount,
    uint256 newMinBalance
) external returns (uint256 unbondBlock);

Parameters:

  • policyID: Target policy identifier
  • amount: Amount of tokens to unbond
  • newMinBalance: Minimum balance to maintain in bonded state

Returns:

  • unbondBlock: Block number when unbonding will complete

Example:

// Initiate unbonding of 1000 tokens while maintaining 100 tokens bonded
uint256 completeBlock = shMonad.unbond(policyID, 1000 * 10**18, 100 * 10**18);

Monitoring Unbonding Status​

Track unbonding progress using view functions:

// Check when unbonding will complete
function unbondingCompleteBlock(
    uint64 policyID,
    address account
) external view returns (uint256);

// View amount currently unbonding
function balanceOfUnbonding(
    uint64 policyID,
    address account
) external view returns (uint256);

Claiming Process​

Basic Claim​

After the escrow period, claim unbonded tokens:

function claim(uint64 policyID, uint256 amount) external;

Advanced Claiming Operations​

Combine claiming with other actions for gas efficiency:

// Claim and immediately withdraw to MON
function claimAndWithdraw(
    uint64 policyID,
    uint256 amount
) external returns (uint256 shares);

// Claim and bond to another policy
function claimAndRebond(
    uint64 fromPolicyID,
    uint64 toPolicyID,
    address bondRecipient,
    uint256 amount
) external;

Security Mechanisms​

Hold System During Unbonding​

The holds mechanism remains active during unbonding to prevent:

  • Double-spending attempts
  • Front-running attacks
  • Manipulation of unbonding amounts
// Check current holds
function getHoldAmount(
    uint64 policyID,
    address account
) external view returns (uint256);

Minimum Balance Protection​

The newMinBalance parameter in unbonding:

  • Prevents accidental full withdrawals
  • Maintains required balances for agent operations
  • Ensures policy compliance

Integration Examples​

Complete Unbonding Workflow​

// Step 1: Start unbonding
uint256 unbondBlock = shMonad.unbond(policyID, amount, minBalance);

// Step 2: Monitor progress
uint256 completeBlock = shMonad.unbondingCompleteBlock(policyID, account);
uint256 unbondingAmount = shMonad.balanceOfUnbonding(policyID, account);

// Step 3: Claim when ready
if (block.number >= completeBlock) {
    shMonad.claim(policyID, unbondingAmount);
}

Advanced Claiming Workflow​

// Option 1: Claim and withdraw to MON
uint256 monReceived = shMonad.claimAndWithdraw(policyID, amount);

// Option 2: Claim and rebond to new policy
shMonad.claimAndRebond(
    fromPolicyID,
    toPolicyID,
    recipient,
    amount
);

Error Handling​

Common errors and their solutions:

  1. Escrow Period Not Complete

    error EscrowPeriodNotComplete(uint256 currentBlock, uint256 completeBlock);
    • Check unbondingCompleteBlock before claiming
    • Implement proper waiting mechanism

  2. Invalid Claim Amount

    error InvalidClaimAmount(uint256 available, uint256 requested);
    • Verify unbonding balance before claiming
    • Handle partial claims if needed

  3. Active Holds

    error ActiveHoldPresent(uint256 holdAmount);
    • Check for active holds before operations
    • Wait for holds to be released

Best Practices​

  1. Unbonding Management

    • Track unbonding status regularly
    • Implement proper error handling
    • Consider gas costs for bulk operations

  2. Claim Optimization

    • Use combined operations when possible
    • Batch claims for gas efficiency
    • Implement proper balance checks

  3. Security Considerations

    • Monitor holds during unbonding
    • Implement proper access controls
    • Regular auditing of unbonding positions

Gas Optimization Tips​

  1. Batch Operations

    • Combine multiple claims when possible
    • Use claimAndRebond for immediate rebonding
    • Consider gas costs in timing decisions

  2. Status Monitoring

    • Cache unbonding complete blocks
    • Batch status checks
    • Use events for tracking

  3. Balance Management

    • Track balances off-chain when possible
    • Optimize minimum balance settings
    • Consider gas costs in withdrawal strategies