> For the complete documentation index, see [llms.txt](https://docs.helio.bet/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.helio.bet/developer-reference.md).

# Developer reference

The website source documented here is `onlybejita/heliobet`, `main` commit `5663b9923232694c1fb6582bdb6c387e2ed3ec76`. The app uses Next.js 16.2.12, React 19, viem, and wallet integration through Privy. Contracts use Solidity 0.8.28 and Foundry.

## Contract map

| Source                                                   | Responsibility                                                             |
| -------------------------------------------------------- | -------------------------------------------------------------------------- |
| `contracts/src/v2/HelioExchange.sol`                     | Order book, collateral ledger, ERC1155 boundary, escrow, fees, redemption  |
| `contracts/src/v2/HelioRoundManager.sol`                 | Series configuration and round lifecycle                                   |
| `contracts/src/v2/oracles/UniswapV3HistoricalOracle.sol` | Fixed-pool historical geometric TWAP                                       |
| `contracts/src/v2/oracles/HistoricalIndexOracle.sol`     | Fixed-weight normalized index implementation, outside the pilot deployment |
| `contracts/src/v2/HelioLiquidityVault.sol`               | Vault and factory implementation, outside the pilot deployment             |
| `contracts/src/pilot/PilotMarkets.sol`                   | Six-market pool and token manifest                                         |
| `contracts/src/pilot/HelioTestUSDG.sol`                  | Pilot collateral                                                           |
| `lib/exchange/abi.ts`                                    | Generated exchange, manager, and vault ABIs                                |

The index adapter supports 2–16 distinct constituent oracles. It combines fixed weights and fixed reference bases with a published base level. Each component reads the same boundary and window. Source compatibility and quote units need qualification before any index is listed.

## Identifiers and units

A round's market ID is:

```solidity
keccak256(abi.encode(block.chainid, address(roundManager), seriesId, startTime))
```

The ERC1155 outcome ID is:

```solidity
uint256(keccak256(abi.encode(marketId, isUp)))
```

Collateral and outcomes use six decimals. Order quantity is a multiple of 10,000 base units, equivalent to 0.01 share. Price ticks are 1–9,999, with 10,000 representing one collateral unit. Historical oracle prices use 18 decimals.

`placeOrder` accepts the selected outcome's price tick. The stored book normalizes DOWN orders to `10000 - priceTick`. Fill-event prices use normalized UP ticks.

| Intent     | Value |
| ---------- | ----: |
| BUY\_UP    |     0 |
| SELL\_DOWN |     1 |
| SELL\_UP   |     2 |
| BUY\_DOWN  |     3 |

| Time in force | Value |
| ------------- | ----: |
| GTC           |     0 |
| IOC           |     1 |
| FOK           |     2 |
| POST\_ONLY    |     3 |

## Main methods

| Purpose                  | Methods                                                                |
| ------------------------ | ---------------------------------------------------------------------- |
| Collateral               | `deposit`, `withdraw`, `freeCollateral`                                |
| Orders                   | `placeOrder`, `cancel`, `cancelBatch`, `replaceOrders`, `expireOrders` |
| Outcome inventory        | `split`, `merge`, `withdrawOutcome`, `depositOutcome`, `redeem`        |
| Order-book reads         | `getOrder`, `bestTicks`, `liveDepth`, `levelOrders`, `accountOrders`   |
| Positions and accounting | `accountMarkets`, `getRound`, `accountedCollateral`                    |
| Manager reads            | `seriesCount`, `getSeries`, `currentStart`, `marketId`, `getRound`     |
| Permissionless lifecycle | `openRound`, `settleRound`, `finalizeInvalid`                          |

Use the ABI to distinguish the exchange's round record from the manager's historical-reference record. Pagination and depth reads are bounded. The recent records visible in the app are not a complete historical index.

Track `Deposited`, `Withdrawn`, `OrderPlaced`, `OrderFilled`, `OrderCancelled`, `CompleteSetsSplit`, `CompleteSetsMerged`, and `Redeemed` on the exchange. Track `SeriesCreated`, `SeriesPauseChanged`, `RoundOpened`, and `RoundResolved` on the manager.

## Local development

In a checkout of the documented commit, install dependencies with `pnpm install --frozen-lockfile` and initialize the repository's contract submodules. Use a dedicated local Anvil chain for the v2 rehearsal.

```sh
anvil --host 127.0.0.1 --port 8548 --chain-id 31337
```

In another terminal, from the repository root:

```sh
pnpm test:exchange
pnpm exchange:local
pnpm abis:v2
pnpm exchange:dev
```

The local v2 app uses port 3003. The local deployment runner writes its deployment configuration under `.local/`. It deploys fresh local contracts and uses mock oracle fixtures. Those fixtures do not certify live stock prices.

Run `pnpm test:exchange-ui` for the exchange's frontend unit tests. The mainnet fork test requires its explicit RPC environment; an offline test pass does not mean the fork case ran.

## Website configuration

The v2 app selects its contracts through `NEXT_PUBLIC_EXCHANGE_ADDRESS`, `NEXT_PUBLIC_ROUND_MANAGER_ADDRESS`, and `NEXT_PUBLIC_USD_ADDRESS`. Pilot mode uses `NEXT_PUBLIC_HELIO_PILOT=true` and `NEXT_PUBLIC_CHAIN=robinhood`. `NEXT_PUBLIC_EXCHANGE_START_BLOCK` bounds event history.

The pilot runner leaves `NEXT_PUBLIC_LP_VAULT_ADDRESS` empty. Read traffic can use the app's server-side RPC gateway. Transactions still require a wallet and ETH gas. Server-only provider credentials and signing secrets do not belong in public configuration.

Read the bundled Next.js documentation before changing application code. This repository's installed Next.js version has conventions that differ from earlier releases.


---

# 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, and the optional `goal` query parameter:

```
GET https://docs.helio.bet/developer-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.