Bucket Protocol on Sui

Bucket Protocol is a CDP (Collateralized Debt Position) stablecoin protocol on Sui, similar to Liquity. Users deposit collateral (SUI, etc.) into "bottles" to mint BUCK stablecoin. The protocol features a stability pool ("tank") for liquidations, BKT governance token staking ("well"), sBUCK savings vault, flash loans, and multi-collateral reservoirs.

Package IDs

| Package | Original ID | Description | |---------|------------|-------------| | Core | 0xce7ff77a83ea0cb6fd39bd8748e2ec89a3f41e8efdc3f4eb123e0ca37b184db2 | BucketProtocol, buckets, bottles, tanks, wells, pipes, reservoirs | | sBUCK | 0x1798f84ee72176114ddbf5525a6d964c5f8ea1b3738d08d50d0d3de4cf584884 | sBUCK savings vault (Flask) | | Oracle | 0xf145ee6d09aae034924f80672bc76db2415dfd1b1bed863ac289af9d94e2c4fc | BucketOracle, price aggregation |

Source Files

Decompiled Move source:

Core (v22): packages/mainnet_most_used/0x0b/6ba9889bb71abc5fa89e4ad5db12e63bc331dba858019dd8d701bc91184d79/decompiled_modules/
sBUCK (v3): packages/mainnet_most_used/0x77/d9c893b7ac9aa102ed1435c50bc935283ea23682e715ee0796739330922f3a/decompiled_modules/
Oracle (v4): packages/mainnet_most_used/0x7d/861b0e12694e099aba07b1fb49349abb06c96294739b5487b8d8261a60e17d/decompiled_modules/

Architecture

BucketProtocol: Shared singleton holding all buckets, tanks, wells, pipes, and reservoirs as dynamic fields. Indexed by collateral type.
Bucket<T>: Per-collateral-type CDP system. Contains bottle table (sorted linked list by collateral ratio), collateral vault, minted BUCK amount.
Bottle: Individual CDP with collateral_amount and buck_amount. Ordered in a linked list by collateral ratio (lowest first for liquidation).
BottleStrap<T>: Optional straptoken for managing bottle ownership independently.
Tank<BUCK, T>: Stability pool for a collateral type. Users deposit BUCK, earn collateral from liquidations + BKT rewards.
ContributorToken<BUCK, T>: Receipt token for tank deposits.
Well<T>: BKT staking pool. Stake BKT to earn protocol fees.
StakedBKT<T>: Receipt for staked BKT with time-lock.
Reservoir<T>: Algorithmic market for charging/discharging BUCK with collateral.
Flask<BUCK>: sBUCK savings vault -- deposit BUCK, receive sBUCK that appreciates over time.

Key Design: Sorted Bottle List

Bottles are kept in a sorted linked list by collateral ratio. When liquidating, the system picks the bottle with the lowest collateral ratio first. Recovery mode activates when total system collateral ratio drops below a threshold.

Constants

Fee precision: configurable base_fee_rate per bucket
Min bottle size: configurable per protocol
Recovery mode threshold: per bucket
BKT: governance/reward token

Key Modules

| Module | Purpose | |--------|---------| | buck | Main entry: borrow, repay, withdraw, redeem, liquidate, sBUCK ops, flash mint/borrow | | bucket | Bucket struct, bottle queries, collateral ratios, health checks | | bottle | Bottle/BottleTable struct, sorted linked list, collateral/debt tracking | | tank | Stability pool: deposit BUCK, claim collateral/BKT rewards | | well | BKT staking: stake, unstake, claim fee rewards | | reservoir | Charge (collateral->BUCK) and discharge (BUCK->collateral) | | pipe | Cross-asset input/output carrier system | | strap | BottleStrap token for bottle ownership management | | bkt | BKT token treasury and minting | | interest | Interest accrual on bottles | | constants | Fee precision and protocol constants |

Common Integration Patterns

Borrow BUCK (Deposit Collateral + Mint BUCK)

let buck_balance = buck::borrow<SUI>(
    protocol,           // &mut BucketProtocol
    oracle,             // &BucketOracle
    clock,              // &Clock
    sui_balance,        // Balance<SUI> collateral
    buck_amount,        // u64 amount of BUCK to mint
    option::none(),     // Option<address> insert hint
    ctx
);
// Returns: Balance<BUCK>

Repay BUCK (Return BUCK + Get Collateral Back)

let collateral = buck::repay<SUI>(
    protocol,           // &mut BucketProtocol
    buck_balance,       // Balance<BUCK> to repay
    ctx
);
// Returns: Balance<SUI>

Repay with Interest Accrual

let collateral = buck::repay_debt<SUI>(
    protocol, buck_balance, clock, ctx
);

Top Up Collateral

buck::top_up<SUI>(protocol, collateral_balance, debtor_address, insert_hint);

Withdraw Excess Collateral

let collateral = buck::withdraw<SUI>(
    protocol, oracle, clock, amount, insert_hint, ctx
);

Redeem BUCK for Collateral

let collateral = buck::redeem<SUI>(
    protocol, oracle, clock, buck_balance, insert_hint
);

Deposit to Stability Pool (Tank)

let token = tank::deposit<BUCK, SUI>(tank, buck_balance, ctx);
// Returns: ContributorToken<BUCK, SUI>

Claim Stability Pool Rewards

let (collateral, bkt) = tank::claim<BUCK, SUI>(tank, bkt_treasury, &mut token, ctx);
// Returns: (Balance<SUI>, Balance<BKT>)

Stake BKT in Well

let staked = well::stake<BUCK>(clock, well, bkt_balance, lock_duration, ctx);
// Returns: StakedBKT<BUCK>

Unstake BKT

let (bkt, reward) = well::unstake<BUCK>(clock, well, staked_bkt);
// Returns: (Balance<BKT>, Balance<BUCK>)

BUCK to sBUCK (Savings)

let sbuck = buck::buck_to_sbuck(protocol, flask, clock, buck_balance);
// Returns: Balance<SBUCK>

sBUCK to BUCK

let buck = buck::sbuck_to_buck(protocol, flask, clock, sbuck_balance);
// Returns: Balance<BUCK>

Flash Loan (Collateral)

let (collateral, receipt) = buck::flash_borrow<SUI>(protocol, amount);
// ... use collateral ...
buck::flash_repay<SUI>(protocol, collateral_with_fee, receipt);

Flash Mint BUCK

let (buck, receipt) = buck::flash_mint(protocol, config, amount);
// ... use BUCK ...
buck::flash_burn(protocol, config, buck_with_fee, receipt);

Query Bottle Info

let (collateral, debt) = buck::get_bottle_info_by_debtor<SUI>(protocol, debtor_addr);
// With interest accrual:
let (collateral, debt) = buck::get_bottle_info_with_interest_by_debtor<SUI>(protocol, debtor_addr, clock);

Check Liquidatability

let can_liq = buck::is_liquidatable<SUI>(protocol, oracle, clock, debtor_addr);

Related Skills

sui-framework -- Core Sui types (Coin, Balance, Clock)
pyth -- Price feeds used by BucketOracle