Developer Details

The nerdy code stuff

Roles

• DEFAULT_ADMIN_ROLE: Can manage all other roles

• AUCTIONEER_ROLE: Can create and manage bond markets

• TOKEN_WHITELISTER_ROLE: Can whitelist new tokens for bonding

• EMERGENCY_ADMIN_ROLE: Can pause/unpause the contract

Contract Interface

Administrative Functions

grantAuctioneerRole(address _auctioneer)

Grants the AUCTIONEER_ROLE to an address.

• Requires DEFAULT_ADMIN_ROLE

• Emits RoleGranted event

whitelistToken(address _token)

Adds a token to the whitelist of acceptable payout tokens.

• Requires TOKEN_WHITELISTER_ROLE

• Validates token implements IERC20Metadata

• Adds token to _payoutTokens array

pauseContract() / unpauseContract()

Emergency controls to pause/unpause contract operations.

• Requires EMERGENCY_ADMIN_ROLE

• Emits ContractPaused/ContractUnpaused events

Market Creation & Management

newBond()

solidity function newBond(
    address payoutToken_,
    IERC20 _quoteToken,
    uint256[4] memory _terms,
    uint32[2] memory _vestingTerms
) external returns (uint256 marketID)

Creates a new bond market with specified parameters:

• payoutToken_: Token to be distributed to bonders

• _quoteToken: Token to be received from bonders

• _terms: Array containing:

  • [0] amountToBond: Total tokens available for bonding

  • [1] controlVariable: Scaling factor for price

  • [2] minimumPrice: Price floor

  • [3] maxDebt: Maximum debt ratio allowed

• _vestingTerms: Array containing:

  • [0] bondEnds: Timestamp when bond expires

  • [1] vestingTerm: Duration of vesting in seconds

closeBond(uint256 _id)

Closes an existing bond market early.

• Only callable by original auctioneer

• Returns remaining payout tokens to auctioneer

User Functions

deposit()

solidity function deposit(
    uint256 _id,
    uint256 amount,
    address user
) public returns (bool)

Deposits quote tokens to receive vesting payout tokens:

• _id: Market identifier

• amount: Amount of quote tokens to deposit

• user: Address to receive the bond

Requirements:

• Market must be live

• Amount must meet minimum deposit

• Total debt must not exceed maximum

redeem(uint256 _id, address user)

Claims vested tokens from a bond:

• Calculates claimable amount based on vesting schedule

• Transfers available tokens to user

• Updates bond record

• Returns total amount redeemed

View Functions

bondPrice(uint256 id_)

Returns current price for a specific market

isLive(uint256 id_)

Checks if a market is active

calculateLinearPayout(address user, uint256 _bondId)

Calculates currently claimable amount for a specific bond

Market Pricing

The bond price is determined by:

1. Control Variable (CV)

2. Debt Ratio

3. Minimum Price Floor

Formula:

price = max(CV * debtRatio, minimumPrice)

The CV can be adjusted over time using the adjustment mechanism to target specific price levels.

Examples

Creating a New Market

solidity // Example parameters for a 7-day bond
uint256[4] memory terms = [
    1000000e18,  // 1M tokens for bonding
    400,         // Control variable
    50000,       // Minimum price (5 quote tokens per 1 payout token)
    100000       // Max debt
];

uint32[2] memory vestingTerms = [
    uint32(block.timestamp + 7 days),  // Ends in 7 days
    uint32(86400 * 7)                  // 7 day vesting
];

uint256 marketId = ghostBonds.newBond(
    payoutToken,
    quoteToken,
    terms,
    vestingTerms
);

Depositing Into a Bond

solidity// Approve quote tokens first
quoteToken.approve(address(ghostBonds), amount);

// Deposit into bond
ghostBonds.deposit(marketId, amount, recipient);

Redeeming Vested Tokens

solidity// Claim available tokens
uint256 redeemed = ghostBonds.redeem(marketId, user);

Security Considerations

1. Slippage Protection

   • Users should verify expected output before depositing

   • Price can change between blocks

2. Token Approvals

   • Only approve exact amounts needed

   • Revoke approvals after use

3. Market Parameters

   • Verify control variables are reasonable

   • Check minimum price aligns with expectations

Events

• ContractPaused(address indexed by)

• ContractUnpaused(address indexed by)

• newBondCreated(uint256 indexed id, address indexed payoutToken, address indexed quoteToken, uint256 initialPrice)

• BondEnded(uint256 indexed id)

• BondDeposited(address indexed user, uint256 indexed marketId, uint256 depositAmount, uint256 totalOwed, uint256 bondPrice)

• QuoteTokensWithdrawn(uint256 indexed marketId, address indexed auctioneer, uint256 amount, uint256 daoFee)

Error Conditions

The contract will revert if:

• Invalid role permissions

• Market is closed or expired

• Deposit amount too low/high

• Maximum debt exceeded

• Contract is paused

• Token transfers fail

• Invalid parameters provided

Best Practices

1. Always check isLive() before depositing

2. Monitor debt ratio to understand pricing

3. Verify market parameters before participation

4. Use view functions to simulate outcomes

5. Consider gas costs during high network usage