docs(for-developer): overhaul — grouped by domain (contracts / API / SDK / overview)

SUMMARY.md

@@ -99,6 +99,7 @@
 
 * [Overview](for-developer/overview.md)
 * [Multi-Oracle](for-developer/multi-oracle.md)
+  * [Consuming Oracle Prices](for-developer/multi-oracle/consuming-prices.md)
 * [LISTA Governance](for-developer/lista-governance/README.md)
   * [Smart Contract](for-developer/lista-governance/smart-contract.md)
 * [Collateral Debt Position](for-developer/collateral-debt-position/README.md)
@@ -117,6 +118,11 @@
 * [Lista Lending](for-developer/lista-lending/README.md)
   * [Protocol Extensions](for-developer/lista-lending/protocol-extensions.md)
   * [Integration Patterns](for-developer/lista-lending/integration-patterns.md)
+  * [Moolah Lending SDK](for-developer/sdk.md)
+  * [Contract & Interface Reference](for-developer/lista-lending/contract-reference.md)
+  * [Events & Callbacks](for-developer/lista-lending/events-and-callbacks.md)
+  * [Interest Rate Model (IRM)](for-developer/lista-lending/irm.md)
+  * [Smart Lending & StableSwap](for-developer/lista-lending/stableswap-integration.md)
   * [Smart Contract](for-developer/lista-lending/smart-contract.md)
     * [BSC Core](for-developer/lista-lending/smart-contract-bsc-core.md)
     * [BSC Lending Brokers](for-developer/lista-lending/smart-contract-bsc-brokers.md)
@@ -125,12 +131,14 @@
     * [BSC Credit](for-developer/lista-lending/smart-contract-bsc-credit.md)
     * [Ethereum](for-developer/lista-lending/smart-contract-ethereum.md)
 * [V3 Dex](for-developer/dex/README.md)
+  * [Architecture & Mechanics](for-developer/dex/mechanics.md)
   * [Smart Contract](for-developer/dex/smart-contract.md)
 * [Lista Platform Services](for-developer/services/README.md)
   * [Position Data Maintenance](for-developer/services/position-data-maintenance.md)
   * [Liquidation Logic (Service)](for-developer/services/liquidation-logic.md)
   * [Subscription Module](for-developer/services/subscription-module.md)
   * [Moolah Lending API](for-developer/services/lending-api/README.md)
+    * [API Conventions](for-developer/services/lending-api/conventions.md)
     * [Overall](for-developer/services/lending-api/overall.md)
     * [Vault](for-developer/services/lending-api/vault.md)
     * [Market](for-developer/services/lending-api/market.md)

for-developer/clisbnb/delegation.md

@@ -1,18 +1,72 @@
 # Delegation
 
-When depositing collateral and triggering mint, the depositor can optionally set a delegate address to receive `slisBNBx` instead of the depositor address.
+`slisBNBx` is a non-transferable certificate, so a holder cannot move it with a normal ERC-20 `transfer`. Instead, the protocol lets an account choose **which wallet holds the `slisBNBx` minted on its behalf**. This is called delegation, and it is the mechanism used to route a position's `slisBNBx` (and therefore its Binance Launchpool eligibility) to another wallet, such as a Binance Web3 MPC wallet.
 
-This is useful when users want Launchpool rewards to accrue to another wallet, such as a Binance Web3 wallet.
+Delegation is managed by `SlisBNBxMinter`, the mint-and-burn engine for `slisBNBx`. See [Token Lifecycle](token-lifecycle.md) for how `slisBNBx` is minted and burned, and [Smart Contract](smart-contract.md) for addresses.
 
-## Rules
+## Delegation model
 
-* Only one delegate address can be set per depositor at mint time.
-* Once assigned for a position, delegate address cannot be changed or transferred.
-* `slisBNBx` remains non-transferable even in delegated accounts.
-* On withdrawal, burn is executed from the delegated holder address.
+| Property | Behavior |
+| --- | --- |
+| Scope | **Per account, not per position.** A single delegatee holds the account's *entire* `slisBNBx` balance across all collateral modules (the `slisBNB` provider and the `slisBNB/BNB` LP provider). |
+| Granularity | **No partial delegation.** You cannot split an account's `slisBNBx` between multiple wallets — it is all-or-nothing. |
+| Default | If an account has never set a delegatee, the holder defaults to **the account itself**. The first mint records `delegation[account] = account`. |
+| Mutability | **Can be changed at any time** via `delegateAllTo`. It is *not* fixed at mint time. |
+| Effect on collateral | Delegation only changes **who holds the `slisBNBx` certificate**. It does not move, re-own, or otherwise affect the underlying collateral in Moolah. |
 
-## Operational Impact
+The minter stores delegation as a single mapping, `delegation[account] => delegatee`, and tracks the total `slisBNBx` minted for each account across every module in `userTotalBalance[account]`. Both are read-only and queryable on-chain.
 
-* Deposit path can credit certificate ownership to a separate reward wallet.
-* Withdrawal path must burn from that same delegated holder.
-* Delegation affects who holds the certificate, not collateral ownership rules in Moolah.
+## Changing the delegatee
+
+Reassigning the delegatee is **atomic**: the minter burns the account's entire `slisBNBx` balance from the old holder and mints the same amount to the new delegatee in a single call. No rebalance against collateral happens during the switch — only the holder changes.
+
+### `delegateAllTo` (called by the account)
+
+```solidity
+function delegateAllTo(address newDelegatee) external;
+```
+
+Called by the account itself (`msg.sender`). It delegates the account's whole `slisBNBx` balance to `newDelegatee`.
+
+* No-op if `newDelegatee` already equals the current delegatee (this equality check runs first).
+* Otherwise, the zero address is rejected as a new delegatee.
+* Internally: reads `userTotalBalance[account]`, burns that amount from the current holder (the old delegatee, or the account itself if none was set), records `delegation[account] = newDelegatee`, then mints the burned amount to `newDelegatee`.
+
+### `syncDelegatee` (called by a module)
+
+```solidity
+function syncDelegatee(address account, address newDelegatee) external;
+```
+
+The module-callable variant. It is restricted to registered collateral modules (`msg.sender` must be a configured module), and performs the same atomic burn-from-old / mint-to-new as `delegateAllTo`. It exists so a provider module can carry a user's existing delegation over to the minter during the migration to the `SlisBNBxMinter` architecture; integrators delegate through `delegateAllTo`, not this function.
+
+### Burn-tolerant reassignment
+
+The burn step uses a safe-burn that tolerates a holder whose actual `slisBNBx` balance is lower than the recorded total (balances can drift from collateral value, exchange-rate, or fee-rate changes). If less than the expected amount can be burned, `userTotalBalance[account]` is adjusted down to the amount actually burned, and only that amount is minted to the new delegatee. This keeps the certificate accounting consistent rather than reverting.
+
+## Legacy `SlisBNBProvider.delegateAllTo` is disabled
+
+The `SlisBNBProvider` collateral module also exposes a `delegateAllTo(address)` function from an earlier design. Once the provider has been wired to the minter (`slisBNBxMinter` is set), this legacy path **reverts with `"not supported"`**. All delegation must go through `SlisBNBxMinter.delegateAllTo`.
+
+```solidity
+// SlisBNBProvider.delegateAllTo — legacy path, gated off once the minter is set
+require(slisBNBxMinter == address(0), "not supported");
+```
+
+## Events
+
+Index these to track delegation and the resulting certificate movements:
+
+| Event | Emitted by | Signature | Meaning |
+| --- | --- | --- | --- |
+| `ChangeDelegateTo` | `SlisBNBxMinter` | `ChangeDelegateTo(address account, address oldDelegatee, address newDelegatee, uint256 amount)` | Delegatee reassigned; `amount` is the `slisBNBx` actually burned from the old holder and minted to the new one. |
+| `UserModuleRebalanced` | `SlisBNBxMinter` | `UserModuleRebalanced(address account, address module, uint256 userPart, uint256 feePart)` | Per-module `slisBNBx` recomputed for the account during a rebalance. |
+| `Rebalance` | `SlisBNBxMinter` | `Rebalance(address account, uint256 latestModuleBalance, address module, uint256 latestTotalBalance)` | A module triggered a rebalance; `latestTotalBalance` is the account's new total across modules. |
+
+> The `SlisBNBProvider` contract emits its own `ChangeDelegateTo(address account, address oldDelegatee, address newDelegatee)` (note: **no `amount` field**) only from the legacy, now-disabled path. For the current minter architecture, listen for the `SlisBNBxMinter` event above.
+
+## Integration notes
+
+* **Read, don't expect transfers.** `slisBNBx` is non-transferable. To find an account's certificate holder, read `delegation[account]`; to find the minted total, read `userTotalBalance[account]`.
+* **Delegation does not auto-rebalance.** `delegateAllTo` moves the existing balance as-is. Subsequent collateral supply/withdraw will rebalance the certificate to the *current* delegatee. See [Token Lifecycle](token-lifecycle.md).
+* **The new holder receives Launchpool eligibility.** Because eligibility is computed off-chain from `slisBNBx` balances, the wallet that holds the certificate after delegation is the one credited with rewards.