bucket

name	bucket
description	This skill should be used when the user asks about Bucket Protocol, BUCK stablecoin, Bucket CDP, sBUCK, BKT token, or wants to integrate with Bucket on Sui. Covers CDP/bottle management, BUCK minting/redemption, stability pool (tank), staking (well), flash loans, and liquidations.

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