# 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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://fsix.gitbook.io/the-sonic-index/bonds/developer-details.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.