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

# Bonus Locking Engine

The bonus supports 2 kinds of bonus engines

## **Simple Bonus Engine**

When players claim for a bonus, the system will simply issue bonus amount into Bonus wallet, so the player will have 2 wallets:

* Main wallet: deposit amount will go to this one
* Bonus wallet: bonus amount will go to this one

When wagering funds will be taken from wallets by this order  Main wallet -> Bonus wallet

Whichever wallet is used for game debit, the system will use the same one for game credit for winnings. In case there's 2 wallets combined for 1 bet, payout will be credited to both wallets with the respective proportion used for the bet

## Locked Bonus Engine

Locked bonus engine is created to be able to forfeit winnings of players when they cancel the bonus in the middle of the play thru progress (meaning playing toward wagering requirements to satisfy conditions of bonuses).

When players claim for a bonus with Locked Bonus Engine, the system will automatically lock the deposit amount by the percentage configured at bonus setup in a Locked Wallet so that players can't withdraw immediately.

When wagering funds will be taken from wallets by this order:

* Locked wallet
* Main wallet
* Bonus wallet

Whichever wallet is used for game bet, winnings will go to the exact same wallets but with these exceptions

* If the bet used Locked wallet, winnings will NOT credit exceeding the initial Locked amount, only credit up to the initial Locked amount and remainders will go to Bonus wallet
* In regards of combination of 2 or 3 wallets for a bet, winnings will go to Bonus

Cancelling a bonus will lead to forfeit remaining bonus balances, and transfer remaining balance from Locked wallet to Main wallet. 

Upon satisfying the bonus wagering requirements, bonus and locked balances will automatically transfer to Main wallet.

**Scenario 1: Deposit: $100 and Claim 100% FTD Bonus**

* Main: 0
* Locked: $100
* Bonus: $100

The player made $50 bet, wallets now will look like:

* Main: 0
* Locked: $50
* Bonus: $100

\=> And the player got payout of 100 (won: 50)

* Main: 0
* Locked: 50 + **50** = **100** (+ 50: only credit up to the initial Locked amount, remainders go to Bonus wallet)
* Bonus: 100 + **50** = **150**

The player made another $100 bet and lost the bet, wallets now will look like:

* Main: 0
* Locked: 0
* Bonus: 150

The player now cancel the bonus:

* Main: 0
* Locked: 0
* Bonus: **0**

**Scenario 2: Make another deposit while having Locked Wallet**

Initial wallet state

* Main: 0
* Locked: 0
* Bonus: 150

The player made $200 deposit, now wallet looks like:

* Main: **200**
* Locked: 0
* Bonus: 150

The player made $50 bet:

* Main: **150**
* Locked: 0
* Bonus: 150

\=> And the player got payout of 200 (won: $150)

* Main: **350**
* Locked: 0
* Bonus: 150

The player now satisfied wagering requirement and wallets will be:

* Main: 350 + **150** = **500**
* Locked: 0
* Bonus: 0