> For the complete documentation index, see [llms.txt](https://boncurs.gitbook.io/boncurs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://boncurs.gitbook.io/boncurs/boncurs-bonding-curve-library/boncurs-curve/boncurscurve/boncursformula.md).

# BoncursFormula

[Git Source](https://github.com/dustinstacy/boncurs/blob/7928cae257b46ede89b50d06eaae18601fcd0340/contracts/experimental/utils/BoncursFormula.sol)

This contract provides functions for calculating the purchase and sale return values on a uinque curve using a scaling factor. The formula converts a desired token amount into a reserve token cost and the sale of a token amount into a reserve token return.

This formula is a custom curve that sees an initial diminishing return on the cost to mint a token, but as the supply increases and the reserve balance grows, the value of the token increases and cannot go down. Used to reward early adopters and incentivize the holding of the token. Also, with the way the curve tends to move towards flat over time, it does not punish late adopters.

## State Variables

### MIN\_SCALE

*Minimum scale in basis points. Prevents loss of value*

```solidity
uint32 constant MIN_SCALE = 10000;
```

### MAX\_SCALE

*Maximum scale in basis points*

```solidity
uint32 constant MAX_SCALE = 1000000;
```

### WAD

*Wei as decimal precision for calculations*

```solidity
uint256 constant WAD = 10 ** 18;
```

## Functions

### \_calculateBoncursPurchaseCost

Returns the purchase cost for a given conversion (in the reserve token) for a desired amount (in the main token).

```solidity
function _calculateBoncursPurchaseCost(
    uint256 supply,
    uint256 reserveBalance,
    uint256 initialCost,
    uint32 scalingFactor,
    uint256 amount
) internal pure returns (uint256 purchaseCost);
```

**Parameters**

| Name             | Type      | Description                                          |
| ---------------- | --------- | ---------------------------------------------------- |
| `supply`         | `uint256` | token total supply                                   |
| `reserveBalance` | `uint256` | current balance of the reserve token                 |
| `initialCost`    | `uint256` | initial cost of the token                            |
| `scalingFactor`  | `uint32`  | scaling factor, represented in basis points, 1-10000 |
| `amount`         | `uint256` | amount of tokens to purchase                         |

**Returns**

| Name           | Type      | Description            |
| -------------- | --------- | ---------------------- |
| `purchaseCost` | `uint256` | cost of the conversion |

### \_calculateBoncursSaleReturn

Returns the sale value for a given amount (in the main token) as a conversion into the reserve token.

```solidity
function _calculateBoncursSaleReturn(uint256 supply, uint256 reserveBalance, uint256 amount)
    internal
    pure
    returns (uint256);
```

**Parameters**

| Name             | Type      | Description                          |
| ---------------- | --------- | ------------------------------------ |
| `supply`         | `uint256` | token total supply                   |
| `reserveBalance` | `uint256` | current balance of the reserve token |
| `amount`         | `uint256` | amount of tokens to sell             |

**Returns**

| Name     | Type      | Description                         |
| -------- | --------- | ----------------------------------- |
| `<none>` | `uint256` | saleReturn return of the conversion |

## Errors

### BoncursFormula\_\_InvalidInput

```solidity
error BoncursFormula__InvalidInput();
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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://boncurs.gitbook.io/boncurs/boncurs-bonding-curve-library/boncurs-curve/boncurscurve/boncursformula.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.