> For the complete documentation index, see [llms.txt](https://docs.pretoke.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.pretoke.xyz/smart-contracts/architecture-overview.md).

# Architecture Overview

> This section is written for developers, auditors, and technically curious users who want to understand the on-chain mechanics powering the platform. If you just want to know how to use the app, see [How It Works](/how-it-works/system-overview.md) instead.

## Protocol basis

PreToke implements the **Conditional Tokens Framework (CTF)** — a system for creating, splitting, merging, and redeeming outcome-based positions backed by collateral — ported to TON using the **Tolk** smart contract language. It's directly inspired by Gnosis's Conditional Tokens contracts (Ethereum), adapted to TON's actor-based, asynchronous message-passing model, with an LMSR automated market maker on top (in the spirit of Gnosis's `conditional-tokens-market-makers`).

## The two contracts

### ConditionRegistry

The core bookkeeping contract. It manages:

* **Conditions** — yes/no (or multi-outcome) questions, registered by an oracle.
* **Positions** — tokenized stakes on specific outcomes, tracked in an internal balance ledger (not a separate token contract — positions live as entries in the registry's storage).
* **Split** — converting collateral (or a parent position) into outcome-specific positions.
* **Merge** — combining outcome positions back into collateral or a parent position.
* **Redeem** — burning resolved positions for a proportional payout once the oracle reports a result.

Full reference: [ConditionRegistry](/smart-contracts/condition-registry.md).

### LmsrMarketMaker

The automated market maker. It manages:

* **Market initialization** — funding a market with collateral, binding it to specific conditions.
* **LMSR pricing** — computing trade costs using the cost function `C(q) = b · ln(Σ exp(qᵢ / b))`.
* **Trade execution** — processing buy and sell trades, updating internal balances, collecting fees.
* **Lifecycle controls** — pause / resume / close, owner-only.
* **Fee collection** — accumulating and withdrawing trading fees.

Full reference: [LmsrMarketMaker](/smart-contracts/lmsr-market-maker.md).

### Supporting library: Fixed-Point Math

All LMSR pricing math runs in **Q64.64 fixed-point arithmetic** (since TVM has no native floating point). The math library implements multiplication, division, log2, exp2, ln, and exp with a 9-term Taylor series and an overflow-prevention offset technique.

Full reference: [Fixed-Point Math Library](/smart-contracts/fixed-point-math.md).

## How the two contracts talk to each other

Both contracts receive collateral via the standard TON **Jetton** transfer flow (TEP-74): a user (or, on this platform, the settlement service acting on a user's behalf) sends a Jetton transfer to the contract's Jetton wallet, which forwards a `transfer_notification` message containing a `forward_payload`. Each contract inspects the op-code inside that payload to decide what to do:

* A split-position payload sent to **ConditionRegistry**'s Jetton wallet → triggers `SplitPosition`.
* An init-market payload sent to **LmsrMarketMaker**'s Jetton wallet → triggers `InitMarket`.
* A trade payload sent to **LmsrMarketMaker**'s Jetton wallet → triggers a buy trade.

```
User / Settlement Service
  │
  ▼ Jetton transfer (forward_payload: op + params)
Jetton Wallet (of the target contract)
  │
  ▼ transfer_notification (op = 0x7362d09c)
ConditionRegistry  or  LmsrMarketMaker
  → decodes forward_payload op, executes the matching operation
```

## Conditional Tokens Framework concepts

| Term                                 | Meaning                                                                                                                               |
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| **Condition**                        | A question with a finite number of possible outcomes, registered by an oracle. Identified by a `condition_id`.                        |
| **Position**                         | A tokenized stake on a specific outcome combination, identified by a `position_id`.                                                   |
| **Index set**                        | A bitmask identifying a subset of outcomes within a condition (e.g. `0b01` = outcome A only).                                         |
| **Collection**                       | Identifies a specific outcome combination under a condition, allowing nested/hierarchical positions. Identified by a `collection_id`. |
| **Partition**                        | A set of disjoint index sets used when splitting or merging a position.                                                               |
| **Payout numerators / denominator**  | Reported by the oracle at resolution; a position's payout share is `numerator / denominator`.                                         |
| **Funding parameter (LMSR b value)** | The AMM's liquidity depth, set at market initialization — higher means tighter spreads and lower price impact per trade.              |

## Contract & tooling versions

These docs describe **contract version v0.1.0**, built with **Acton CLI 1.1.0**. Source lives in `contracts/src/` (Tolk) within the `ton-prediction-market/` project directory.

Continue to [ConditionRegistry](/smart-contracts/condition-registry.md) or jump straight to the [Error Codes Reference](/smart-contracts/error-codes.md).


---

# 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.pretoke.xyz/smart-contracts/architecture-overview.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.