> For the complete documentation index, see [llms.txt](https://fsix.gitbook.io/the-sonic-index/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fsix.gitbook.io/the-sonic-index/bonds/developer-details.md).

# Developer Details

#### 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
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
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
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
solidity// Approve quote tokens first
quoteToken.approve(address(ghostBonds), amount);

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

#### Redeeming Vested Tokens

```solidity
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