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

# Settlement Process

Understand settlement from oracle price to auto-claim, including validator consensus.

![Settlement](https://2863428870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F80Mih2wy0x6vMgmpFKdI%2Fuploads%2Fgit-blob-bec305d46540e877a47dd90ee2a54d29dcb3cad1%2Fdoc-card-05-settlement.png?alt=media)

Settlement finalizes a market and determines rewards. It is a fully automated, multi-step process that ensures accuracy, fairness, and security through independent validator consensus.

## Steps

![Full Settlement Pipeline](https://2863428870-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2F80Mih2wy0x6vMgmpFKdI%2Fuploads%2Fgit-blob-fc13d77c3d85986a7da9ed1a712e87e922023417%2F14-full-settlement-pipeline.png?alt=media)

### 1. Event Close Detection

The settlement system continuously monitors all active markets. When a market's close time arrives, the system automatically initiates settlement.

If the service restarts for any reason, a catchup process identifies any markets that should have been settled but were missed, and processes them automatically.

### 2. Oracle Price Resolution & On-Chain Recording

Production settlement currently uses Pyth Network. Its price update is obtained through Hermes and includes a cryptographic proof that the price was genuinely produced by the oracle at the event's scheduled settlement time. Paper-trading events use Uniocean's own on-chain oracle adaptor.

The Pyth contract accepts the submitted update only when its publish time falls within the configured allowance beginning at the market close time. This check is performed on-chain while parsing the VAA.

{% hint style="warning" %}
**The final oracle price for the exact scheduled settlement time is then recorded on the blockchain**, creating an immutable, publicly verifiable record. This recorded value—not a later chart value or rounded display value—is used for ranking and rewards.
{% endhint %}

Once the oracle price has been recorded successfully, the application can proceed to settle the event. If settlement cannot proceed, the platform follows the applicable cancellation process; this is not an automatic cancellation for every temporary oracle or processing failure.

### 3. Forecast Retrieval

All on-chain forecasts for the market are retrieved from blockchain indexers. These indexers have already catalogued every forecast transaction submitted during the market's live period.

### 4. Ranking (Using Recorded On-Chain Price)

Using the oracle price that was recorded on-chain in Step 2, forecasts are ranked by accuracy using the same deterministic algorithm as the live rankings:

1. Calculate distance from oracle price for every forecast
2. Sort by distance (ascending)
3. For equal distances, apply tie-breaking in order: timestamp → block number → log index
4. Assign sequential ranks

The same algorithm runs identically across all settlement nodes, ensuring consensus.

### 5. Reward Calculation

The Uniocean Community Price Reward Algorithm (UCPRA) distributes the reward pool:

* The event's published reward configuration determines the rewarded range
* Rankers receive premium top rewards
* Bucket Winners receive the event's configured payout band

The standard public configuration uses a **51%** win rate, but validators and audit reports always use the exact fee and reward configuration published for that specific event.

### 6. Merkle Tree Construction

A Merkle tree is built from all winner rewards. Each leaf contains a wallet address and reward amount. The Merkle root — a single cryptographic fingerprint — represents the entire reward dataset.

This allows efficient on-chain verification without storing every individual reward on the blockchain.

### 7. Validator Consensus (BFT)

Before the Merkle root is submitted on-chain, it must be verified by independent validator nodes.

Each validator independently:

1. Fetches all forecasts from blockchain indexers
2. Retrieves the oracle close price
3. Recomputes rankings using the same algorithm
4. Regenerates the Merkle tree
5. Compares its computed Merkle root with the proposed root
6. Signs the settlement only if results match

A quorum of at least 3 out of 5 validators must agree. If any validator computes a different result, it refuses to sign. This Byzantine Fault Tolerant (BFT) approach means:

* No single compromised node can approve fraudulent results
* Settlement requires majority consensus
* Each validator operates independently with its own signing keys

### 8. On-Chain Submission

Once enough validator signatures are collected, the settlement transaction is submitted to the blockchain. This transaction includes:

* The Merkle root
* Validator signatures

The smart contract verifies the validator signatures and records the settlement permanently.

### 9. Reward Distribution

After on-chain settlement, rewards are automatically claimed for all winners. Users do not need to take any action.

### 10. Event Audit Report Generation

A comprehensive settlement receipt is generated containing:

* Market metadata (asset, duration, timestamps)
* Final oracle price and source
* Complete participant ranking
* Event reward configuration used for settlement
* Reward amounts for each winner
* Merkle root and proof data
* Validator signatures

This report is stored permanently and made available for public verification.

## Settlement Decisions

| Condition                                                                                      | Action                                                     |
| ---------------------------------------------------------------------------------------------- | ---------------------------------------------------------- |
| Participation meets the event's published threshold                                            | Normal settlement with reward distribution                 |
| Participation is at or below the event's published threshold (currently 14 forecasts or fewer) | May be cancelled under the platform's cancellation process |
| Suspicious activity identified                                                                 | May be cancelled by a platform administrator               |
| Settlement exceeds the configured deadline                                                     | A separate timeout-cancellation path may apply             |

## Settlement Timing

Settlement typically completes within minutes after a market closes. The process is fully automated and does not require human intervention.

| Phase                   | Typical Duration |
| ----------------------- | ---------------- |
| Oracle price fetch      | 1–5 seconds      |
| Ranking computation     | Under 1 second   |
| Validator consensus     | 10–30 seconds    |
| On-chain submission     | 5–30 seconds     |
| Auto-claim execution    | 1–5 minutes      |
| Audit report generation | 10–30 seconds    |

***

## Related Pages

* [Oracle Price](/settlement/oracle-price.md)
* [Merkle Proofs](/settlement/merkle-proofs.md)
* [Auto Claims](/settlement/auto-claims.md)
* [Auto Refunds](/settlement/auto-refunds.md)
* [Public Verification](/transparency-and-security/public-verification.md)