> For the complete documentation index, see [llms.txt](https://maplefun.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://maplefun.gitbook.io/docs/core-mechanics/smart-contract-guide.md).

# Smart Contract Guide

### Instructions

The program exposes the following instructions for pool management and user interactions. All instructions validate inputs and emit events for off-chain indexing.

***

#### Factory Instructions

**create\_native\_pool**

Creates a native SOL pool with a deterministic PDA address.

Parameters:

* `seed`: u64 (arbitrary seed for PDA derivation)
* `cfg`: VaultConfig (pool configuration, see State section)
* `principal`: Pubkey (principal address for admin controls)
* `bootstrap_amount_lamports`: u64 (initial SOL amount, must be greater than 0)

The instruction validates the config, creates and initializes a NonTransferable Token-2022 mint, creates the owner's shares ATA, transfers SOL to the pool PDA, mints 1:1 bootstrap shares to the owner, sets pool state, and emits PoolCreated.

**create\_token\_pool**

Creates an SPL token pool. Parameters are similar to create\_native\_pool but uses `initial_amount`: u64 instead of lamports. Transfers underlying tokens via CPI and uses transfer\_checked for safety.

***

#### User Flow Instructions

**deposit\_native**

Deposits SOL into a native pool and mints shares.

Parameters:

* `amount`: u64 (deposit amount)
* `min_shares`: u64 (slippage guard)

The instruction checks for pauses and stopped deposits, transfers SOL to the PDA, computes the effective fee dynamically based on TVL and time, mints shares proportionally, updates the member timestamp and exchange rate, and emits Deposited.

**deposit\_token**

Deposits SPL tokens. Parameters are the same as deposit\_native. Flow is similar but uses token CPI.

**withdraw**

Withdraws from any pool by burning shares.

Parameters:

* `shares`: u64 (shares to burn)
* `min_out`: u64 (slippage guard)

The instruction checks for pauses and owner lock, computes penalties (cooldown linear decay plus fast-exit floor), burns shares, transfers net assets to the user, splits fees 50/50 between creator and project, updates the exchange rate, and emits Withdrawn.

***

#### Admin Instructions

**fund\_native / fund\_token:** Adds liquidity to existing pools. Owner only.

**stop\_pool / resume\_pool:** Toggles deposits on or off. Principal only.

**unpause:** Resumes pool operation after a loss-cap pause. Principal only.

***

### State

**Pool Account**

Stores pool metadata, configuration, and accounting. Size is approximately 300 bytes.

Key fields:

* `is_native`: bool (SOL vs SPL)
* `shares_mint`: Pubkey (Token-2022 mint)
* `deposit_fee_bps`: u16 (base deposit fee)
* `fast_exit_window_secs`: u32 (fast-exit penalty window)
* `last_exchange_rate`: u128 (assets/shares at 1e18 scale)

**Member Account**

Stores per-user state for each pool. The main field is `last_deposit_ts`: i64, used for calculating cooldown penalties.

**VaultConfig Struct**

Input struct for pool creation. Fields mirror the Pool config, for example `discount_durations`: \[u32; 4].

***

### Events

Events are emitted for transparency and off-chain indexing.

**PoolCreated:** pool, owner, principal, creator, is\_native, underlying\_mint, initial\_amount

**Deposited:** pool, user, amount, fee\_bps, fee\_amount, shares\_minted

**Withdrawn:** pool, user, shares, gross\_amount, withdrawal\_fee, project\_fee, penalty\_amount, net\_amount

**Funded:** pool, caller, amount

**DepositsStoppedEvt, DepositsResumedEvt, PoolUnpausedEvt** are emitted for admin actions.

***

### Errors

Custom error codes handle common failures.

**DustInVault:** Assets greater than 0 with zero shares outstanding.

**ExceedsMaxDeposit:** Deposit violates max deposit percentage.

**ReserveTooLow:** Post-withdrawal reserve falls below required ratio.

**SeederLocked:** Owner attempts withdrawal before bootstrap lock expires.

**Overflow:** Arithmetic overflow detected.

Full list available in the ErrorCode enum in the contract source.

***

### Security and Best Practices

**PDA Signing:** All CPIs use secure PDA authority.

**Validation:** Fee bounds are enforced, durations must be increasing, and total withdrawal fees cannot exceed 100%.

**Protections:** Loss cap triggers automatic pause, reserve ratios prevent liquidity drain, and dust prevention blocks edge cases.

**Token Handling:** Generic interfaces support both SPL and Token-2022. All transfers use transfer\_checked for decimal safety.

**Audits:** Recommended before production deployment. No known vulnerabilities, but edge cases like zero-supply scenarios should be tested.