feat: add new skill to bucket sdk

skill/bucket-sdk/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: bucket-sdk
+description: Use when integrating Bucket Protocol on Sui with @bucket-protocol/sdk: CDP position updates, USDB mint and repay, PSM swaps, saving pools, flash mint, oracle prices, and protocol state queries.
+---
+
+# Bucket SDK
+
+Use this skill whenever the task touches `@bucket-protocol/sdk`.
+
+Official docs:
+- https://docs.bucketprotocol.io/
+- https://github.com/Bucket-Protocol/bucket-protocol-sdk
+
+## Trigger Scope
+
+Use for:
+- Building PTBs with `buildManagePositionTransaction`, `buildPSMSwapInTransaction`, saving pool builders, or flash mint.
+- Querying collateral, pool, oracle, position, account, or reward data.
+- Debugging Bucket integration issues (`Unsupported collateral type`, price feed issues, pool balance checks).
+
+Do not use for:
+- Generic Sui SDK tasks that do not involve Bucket Protocol.
+
+## Fast Workflow
+
+1. Initialize client:
+
+```ts
+import { BucketClient } from '@bucket-protocol/sdk';
+const client = await BucketClient.initialize({ network: 'mainnet' });
+```
+
+2. Resolve live types (never assume static lists):
+
+```ts
+const usdbType = await client.getUsdbCoinType();
+const collateralTypes = await client.getAllCollateralTypes();
+const oracleTypes = await client.getAllOracleCoinTypes();
+const psmTypes = Object.keys(await client.getAllPsmPoolObjects());
+const savingLpTypes = Object.keys(await client.getAllSavingPoolObjects());
+```
+
+3. Build PTB commands on `Transaction`, then sign and execute separately.
+4. For unsupported user input, validate against live lists/maps first and return a clear error.
+5. If config may be stale (protocol upgrade), call `await client.refreshConfig()`.
+
+## Coin Type Policy
+
+Keep context small. Do not paste long coin-type tables unless explicitly requested.
+
+Rules:
+1. CDP `coinType` must come from `getAllCollateralTypes()`.
+2. PSM `coinType` must come from keys of `getAllPsmPoolObjects()`.
+3. Saving `lpType` must come from keys of `getAllSavingPoolObjects()`.
+4. Oracle price queries should use `getAllOracleCoinTypes()` when possible.
+5. Use `references/coin-types.md` only when the user asks for static literals.
+
+## Core Behavior Notes
+
+- All write methods are PTB builders (`build*`): they append Move calls, not execute transactions.
+- Amounts are raw integers (smallest unit). No auto decimal scaling.
+- Most config-dependent methods are async; always `await`.
+- `buildManagePositionTransaction` auto-aggregates prices when borrow or withdraw is requested.
+- `accountObjectOrId` switches from EOA mode to Bucket Account mode.
+
+## Default Implementation Skeleton
+
+Use this shape unless the user asks for another architecture:
+
+```ts
+import { BucketClient } from '@bucket-protocol/sdk';
+import { Transaction } from '@mysten/sui/transactions';
+
+const client = await BucketClient.initialize({ network: 'mainnet' });
+const tx = new Transaction();
+
+// validate types from live config here
+// append build* commands here
+
+tx.setSender(address);
+await client.getSuiClient().signAndExecuteTransaction({ signer, transaction: tx });
+```
+
+If user asks for simulation only, use `simulateTransaction` after setting sender.
+
+## Method Map
+
+Query methods:
+- `getUsdbSupply`, `getAllVaultObjects`, `getAllPsmPoolObjects`, `getAllSavingPoolObjects`
+- `getUserPositions`, `getUserSavings`, `getUserAccounts`
+- `getOraclePrices`, `getAllOraclePrices`
+
+Build methods:
+- CDP: `buildManagePositionTransaction`, `buildClosePositionTransaction`, `buildClaimBorrowRewardsTransaction`
+- PSM: `buildPSMSwapInTransaction`, `buildPSMSwapOutTransaction`
+- Saving: `buildDepositToSavingPoolTransaction`, `buildWithdrawFromSavingPoolTransaction`, `buildClaimSavingRewardsTransaction`
+- Flash: `flashMint`, `flashBurn`
+
+## What To Open Next (Modular References)
+
+Read only what you need:
+- `references/api-workflows.md`
+  - End-to-end PTB examples for CDP, PSM, saving, flash, and composition.
+- `references/query-cheatsheet.md`
+  - Query API quick reference, return-shape expectations, and troubleshooting checks.
+- `references/protocol-concepts.md`
+  - CDP mechanics, CR/MCR, liquidation model, PSM peg behavior, and yield layers.
+- `references/coin-types.md`
+  - Dynamic type resolution patterns and a small literal snapshot.
+
+## Runtime Diagnostics
+
+Use the bundled script when you need a quick live state snapshot:
+
+```bash
+# Run in a project directory that has @bucket-protocol/sdk installed
+# <skill-root> is wherever you store this skill, for example:
+#   .github/skills/bucket-sdk
+#   .agents/skills/bucket-sdk
+#   .claude/skills/bucket-sdk
+node <skill-root>/scripts/query-state.mjs
+```
+
+It prints supply, prices, vault stats, PSM pools, saving pools, and supported collateral types.
+
+## Response Expectations
+
+- Return code that is copy-paste runnable in TypeScript.
+- Mention which live type source was used (`getAllCollateralTypes`, PSM keys, or saving LP keys).
+- When rejecting input, include the checked list source and a short fix suggestion.
+- Prefer small, composable PTBs over unrelated helper abstractions.
+
+## Quality Gates Before Finalizing
+
+1. Type validation done against live config (not hardcoded memory).
+2. Amount units are raw integer units.
+3. Transaction path is complete: build -> set sender -> sign+execute (or simulate).
+4. Failure handling includes useful checks:
+   - Unsupported collateral or PSM or lp type
+   - Missing price feed
+   - Insufficient pool balance
+   - Insufficient user balance

skill/bucket-sdk/references/api-workflows.md

@@ -0,0 +1,122 @@
+# API Workflows
+
+Use this file for write-path examples. Keep `SKILL.md` minimal and read this only when implementing flows.
+
+## Setup
+
+```ts
+import { BucketClient } from '@bucket-protocol/sdk';
+import { Transaction } from '@mysten/sui/transactions';
+
+const client = await BucketClient.initialize({ network: 'mainnet' });
+const tx = new Transaction();
+```
+
+## CDP: Deposit and Borrow
+
+```ts
+const [collateralCoin, usdbCoin] = await client.buildManagePositionTransaction(tx, {
+  coinType,
+  depositCoinOrAmount: 1_000_000_000,
+  borrowAmount: 800_000,
+});
+```
+
+## CDP: Repay and Withdraw
+
+```ts
+await client.buildManagePositionTransaction(tx, {
+  coinType,
+  repayCoinOrAmount: 500_000,
+  withdrawAmount: 200_000_000,
+});
+```
+
+## CDP: Close Position
+
+```ts
+const [allCollateral] = await client.buildClosePositionTransaction(tx, {
+  address,
+  coinType,
+});
+```
+
+## PSM: Stablecoin -> USDB
+
+```ts
+const usdbCoin = await client.buildPSMSwapInTransaction(tx, {
+  coinType: psmCoinType,
+  inputCoinOrAmount: 1_000_000,
+});
+```
+
+## PSM: USDB -> Stablecoin
+
+```ts
+const stableCoin = await client.buildPSMSwapOutTransaction(tx, {
+  coinType: psmCoinType,
+  usdbCoinOrAmount: 1_000_000,
+});
+```
+
+## Saving Pool: Deposit and Withdraw
+
+```ts
+await client.buildDepositToSavingPoolTransaction(tx, {
+  address,
+  lpType,
+  depositCoinOrAmount: 1_000_000,
+});
+
+const usdbOut = await client.buildWithdrawFromSavingPoolTransaction(tx, {
+  lpType,
+  amount: 500_000,
+});
+```
+
+## Saving Pool: Claim Rewards
+
+```ts
+const rewards = await client.buildClaimSavingRewardsTransaction(tx, { lpType });
+for (const coin of Object.values(rewards)) {
+  tx.transferObjects([coin], address);
+}
+```
+
+## Flash Mint
+
+```ts
+const [flashUsdb, receipt] = await client.flashMint(tx, { amount: 10_000_000 });
+// use flashUsdb in the same PTB
+await client.flashBurn(tx, { usdbCoin: flashUsdb, flashMintReceipt: receipt });
+```
+
+## Compose Operations Atomically
+
+Example: swap to USDB then deposit to saving pool in one PTB.
+
+```ts
+const usdbCoin = await client.buildPSMSwapInTransaction(tx, {
+  coinType: psmCoinType,
+  inputCoinOrAmount: 1_000_000,
+});
+
+await client.buildDepositToSavingPoolTransaction(tx, {
+  address,
+  lpType,
+  depositCoinOrAmount: usdbCoin,
+});
+```
+
+## Execution
+
+```ts
+tx.setSender(address);
+await client.getSuiClient().signAndExecuteTransaction({ signer, transaction: tx });
+```
+
+## Notes
+
+- Build methods append commands only; they do not execute on chain.
+- Use raw integer units, not decimal strings.
+- For dry run, set sender and call `simulateTransaction`.

skill/bucket-sdk/references/coin-types.md

@@ -0,0 +1,41 @@
+# Bucket Protocol - Coin Types (Lean Reference)
+
+Use runtime queries first. Do not rely on static tables unless the user explicitly asks for literals.
+
+## Live Type Discovery (Preferred)
+
+```ts
+const usdbType = await client.getUsdbCoinType();
+const collateralTypes = await client.getAllCollateralTypes();
+const oracleTypes = await client.getAllOracleCoinTypes();
+const psmTypes = Object.keys(await client.getAllPsmPoolObjects());
+const savingLpTypes = Object.keys(await client.getAllSavingPoolObjects());
+```
+
+Validation rules:
+- CDP `coinType`: must be in `collateralTypes`
+- PSM `coinType`: must be in `psmTypes`
+- Saving `lpType`: must be in `savingLpTypes`
+
+If not present, return an explicit unsupported-type error.
+
+## Minimal Literal Snapshot (Mainnet, May Change)
+
+These are common values only. Treat as a convenience snapshot, not source of truth.
+
+| Token | Type |
+| --- | --- |
+| SUI | `0x2::sui::SUI` |
+| USDB | `0xe14726c336e81b32328e92afc37345d159f5b550b09fa92bd43640cfdd0a0cfd::usdb::USDB` |
+| USDC | `0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC` |
+| USDT | `0x375f70cf2ae4c00bf37117d0c85a2c71545e6ee05c4a5c7d282cd66a4504b068::usdt::USDT` |
+| BUCK | `0xce7ff77a83ea0cb6fd39bd8748e2ec89a3f41e8efdc3f4eb123e0ca37b184db2::buck::BUCK` |
+| sUSDB LP | `0x38f61c75fa8407140294c84167dd57684580b55c3066883b48dedc344b1cde1e::susdb::SUSDB` |
+
+## When To Use Static Literals
+
+Use static literals only when:
+- user requests a documented literal string, or
+- runtime access is not available.
+
+Otherwise always resolve from live config.