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

# Smart Contracts

The Footymarket smart contract is an Anchor program written in Rust, deployed on Solana. It is the trust layer of the protocol: every collateral movement, share mint, and settlement path is enforced by the program. The off-chain operator cannot alter or override any on-chain constraint.

## Market PDA

Every market is represented by a Program Derived Address (PDA) seeded deterministically from `[b"market", market_id]`. The PDA stores the complete state of the market.

```rust
pub struct Market {
    pub market_id: [u8; 32],          // Unique market identifier
    pub question: String,             // The market question
    pub category: MarketCategory,     // Match | Player | Season | Transfer | Live
    pub collateral_mint: Pubkey,      // USDC mint
    pub yes_mint: Pubkey,             // SPL mint for YES shares
    pub no_mint: Pubkey,              // SPL mint for NO shares
    pub creator: Pubkey,              // Market creator wallet
    pub oracle: Pubkey,               // Designated resolver wallet
    pub resolution_deadline: i64,     // Unix timestamp
    pub lock_time: Option<i64>,       // When trading halts (before resolution)
    pub status: MarketStatus,         // Open | Locked | Resolved | Voided
    pub outcome: Option<Outcome>,     // Yes | No (set at resolution)
    pub total_collateral: u64,        // USDC locked (in lamport-equivalent units)
    pub fee_bps: u16,                 // Protocol fee in basis points
    pub creator_fee_bps: u16,         // Creator fee in basis points
    pub bump: u8,                     // PDA bump seed
}
```

The PDA is deterministic: any client can derive the market address from the `market_id` without needing to query the program. This makes market lookups cheap and predictable.

## Order tracking

Each active order is tracked in an `OrderStatus` account. This account stores the remaining fillable amount of the order and a fill flag.

The account is packed into a single storage slot: `filled: bool` (1 byte) and `remaining: u248` (31 bytes). This layout minimises account rent costs for large order books.

## Core instructions

| Instruction      | Description                                                                    |
| ---------------- | ------------------------------------------------------------------------------ |
| `create_market`  | Initialise a new Market PDA and deploy the YES and NO SPL token mints          |
| `mint_shares`    | Deposit USDC and receive an equal quantity of YES and NO shares                |
| `redeem_shares`  | Return a YES/NO pair and receive USDC (available before resolution)            |
| `place_order`    | Submit a signed order to the off-chain CLOB operator                           |
| `settle_orders`  | Operator submits a matched order pair; program executes NORMAL, MINT, or MERGE |
| `lock_market`    | Freeze trading at the configured `lock_time`                                   |
| `resolve_market` | Oracle submits the YES or NO outcome on-chain                                  |
| `claim_winnings` | Winning share holders redeem USDC after resolution                             |
| `void_market`    | Return all collateral pro-rata if the market is voided                         |

## Security and audit

The Footymarket smart contract undergoes a security audit by an independent firm (OtterSec or Trail of Bits) before mainnet deployment. The mainnet launch uses a staged rollout with TVL caps that increase as the contract accumulates usage history.

The source code is open. All resolution transactions link to on-chain transactions that are publicly auditable.

{% hint style="info" %}
The `creator` and `oracle` fields in the Market PDA must be different wallet addresses. This prevents a single actor from both creating and resolving a market, which would allow collusion against traders.
{% endhint %}


---

# 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://docs.footymarket.xyz/protocol/smart-contracts.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.