@lamdanghoang/sui-pay-wal 0.1.0

package/README.md

@@ -0,0 +1,263 @@
+# @lamdanghoang/sui-pay
+
+Pay Walrus storage costs with SUI directly — no need to acquire WAL tokens separately.
+
+This SDK provides automatic SUI → WAL swapping using Pyth Oracle for real-time pricing, making it seamless for users to pay for Walrus decentralized storage.
+
+## Features
+
+- 🔄 **Automatic SUI → WAL swap** via Pyth Oracle pricing
+- 💰 **Accurate cost estimation** using Walrus pricing formula
+- 🔌 **Wallet agnostic** — works with any Sui wallet
+- 📦 **Zero WAL required** — users only need SUI
+- ⚡ **Single transaction** swap execution
+
+## Installation
+
+```bash
+npm install @lamdanghoang/sui-pay @mysten/sui
+```
+
+## Quick Start
+
+```typescript
+import { WalrusSuiPay } from '@lamdanghoang/sui-pay'
+
+// Initialize the client
+const client = new WalrusSuiPay({
+  network: 'testnet',
+  exchangePackageId: '0x...', // Your deployed contract
+  exchangeObjectId: '0x...', // Your exchange object
+})
+
+// Check if user has enough WAL, get SUI needed if not
+const check = await client.checkBalance(
+  userAddress,
+  fileSize,  // bytes
+  3          // epochs
+)
+
+if (!check.sufficient) {
+  console.log(`Need to swap ${check.suiNeeded} SUI for WAL`)
+}
+
+// Ensure WAL balance before upload (auto-swaps if needed)
+const result = await client.ensureWalBalance(
+  fileSize,
+  epochs,
+  userAddress,
+  signAndExecute  // Your wallet's signing function
+)
+
+if (result.success) {
+  // Now upload to Walrus...
+}
+```
+
+## API Reference
+
+### `WalrusSuiPay`
+
+Main client class for swap operations.
+
+#### Constructor
+
+```typescript
+new WalrusSuiPay({
+  network?: 'testnet' | 'mainnet',  // Default: 'testnet'
+  rpcUrl?: string,                   // Custom RPC URL
+  exchangePackageId: string,         // WAL Exchange contract package ID
+  exchangeObjectId: string,          // WAL Exchange object ID
+})
+```
+
+#### Methods
+
+##### `getWalBalance(address: string): Promise<bigint>`
+Get WAL balance for an address (in FROST, 1 WAL = 1e9 FROST).
+
+##### `getSuiBalance(address: string): Promise<bigint>`
+Get SUI balance for an address.
+
+##### `quoteSuiToWal(suiAmount: bigint): Promise<SwapQuote | null>`
+Get a quote for swapping SUI to WAL.
+
+##### `quoteWalToSui(walAmount: bigint): Promise<SwapQuote | null>`
+Get a quote for swapping WAL to SUI.
+
+##### `checkBalance(address, fileSizeBytes, epochs, bufferPercent?): Promise<BalanceCheckResult>`
+Check if user has enough WAL for storage, calculate SUI needed if not.
+
+##### `ensureWalBalance(fileSizeBytes, epochs, address, signAndExecute, bufferPercent?): Promise<Result>`
+Ensure user has enough WAL, automatically swapping SUI if needed.
+
+##### `createSwapSuiToWalTransaction(suiAmount, slippageBps?): Promise<SwapTransactionResult | null>`
+Create a swap transaction for wallet signing.
+
+##### `swapSuiToWal(suiAmount, signAndExecute, slippageBps?): Promise<SwapResult>`
+Execute a SUI → WAL swap.
+
+### Storage Cost Utilities
+
+```typescript
+import { 
+  calculateStorageCost,
+  calculateStorageCostLive,
+  estimateWalNeeded,
+  estimateWalNeededLive,
+  getWalrusSystemInfo,
+  formatWal,
+  formatSui 
+} from '@lamdanghoang/sui-pay'
+
+// Calculate with default pricing (fast, no RPC)
+const cost = calculateStorageCost(fileSize, epochs)
+console.log(`Storage: ${cost.totalWal} WAL`)
+
+// Calculate with live on-chain pricing (accurate)
+const costLive = await calculateStorageCostLive(fileSize, epochs, 'testnet')
+console.log(`Storage: ${costLive.totalWal} WAL (live pricing)`)
+console.log(`System info:`, costLive.systemInfo)
+
+// Estimate with buffer (default pricing)
+const walNeeded = estimateWalNeeded(fileSize, epochs, 20) // 20% buffer
+
+// Estimate with buffer (live pricing)
+const walNeededLive = await estimateWalNeededLive(fileSize, epochs, 'testnet', 20)
+
+// Get system info directly
+const systemInfo = await getWalrusSystemInfo('testnet')
+console.log(`nShards: ${systemInfo.nShards}`)
+console.log(`Storage price: ${systemInfo.storagePricePerUnit} FROST/unit/epoch`)
+console.log(`Write price: ${systemInfo.writePricePerUnit} FROST/unit`)
+
+// Format amounts
+console.log(formatWal(1000000000n)) // "1.0000"
+console.log(formatSui(1000000000n)) // "1.0000"
+```
+
+### Pyth Oracle Functions
+
+```typescript
+import { getSwapPrices, getSuiUsdPrice, getWalUsdPrice } from '@lamdanghoang/sui-pay'
+
+// Get both prices
+const prices = await getSwapPrices()
+console.log(`SUI: $${prices.suiUsd}, WAL: $${prices.walUsd}`)
+console.log(`Rate: 1 SUI = ${prices.suiWalRate} WAL`)
+
+// Get individual prices
+const sui = await getSuiUsdPrice()
+const wal = await getWalUsdPrice()
+```
+
+## Usage with Different Wallets
+
+### With @mysten/dapp-kit (React)
+
+```typescript
+import { useSignAndExecuteTransaction } from '@mysten/dapp-kit'
+
+function UploadComponent() {
+  const { mutateAsync: signAndExecute } = useSignAndExecuteTransaction()
+  
+  const handleUpload = async () => {
+    await client.ensureWalBalance(
+      fileSize,
+      epochs,
+      address,
+      signAndExecute
+    )
+  }
+}
+```
+
+### With Sui Wallet Standard
+
+```typescript
+const signAndExecute = async ({ transaction }) => {
+  const result = await wallet.signAndExecuteTransactionBlock({
+    transactionBlock: transaction,
+  })
+  return { digest: result.digest }
+}
+
+await client.ensureWalBalance(fileSize, epochs, address, signAndExecute)
+```
+
+### With zkLogin
+
+```typescript
+import { signWithZkLogin } from './your-zklogin-utils'
+
+const signAndExecute = async ({ transaction }) => {
+  const txBytes = await transaction.build({ client: suiClient })
+  const signature = await signWithZkLogin(txBytes, credentials)
+  
+  const result = await suiClient.executeTransactionBlock({
+    transactionBlock: txBytes,
+    signature,
+  })
+  return { digest: result.digest }
+}
+```
+
+## Contract Deployment
+
+The SDK requires a WAL Exchange contract to be deployed. See the `contracts/` directory for the Move source code.
+
+### Environment Variables
+
+```env
+NEXT_PUBLIC_WAL_EXCHANGE_PACKAGE_ID=0x...
+NEXT_PUBLIC_WAL_EXCHANGE_OBJECT_ID=0x...
+```
+
+## Storage Cost Formula
+
+Walrus uses the following pricing formula:
+
+```
+Total = encodedUnits × (writePricePerUnit + storagePricePerUnit × epochs)
+```
+
+Where:
+- `encodedUnits = ceil(encodedSize / 1 MiB)`
+- `encodedSize` is calculated using RedStuff encoding (varies by file size and nShards)
+- Prices are fetched from on-chain Walrus system object
+
+### On-Chain System Info
+
+The SDK fetches live pricing from the Walrus system object:
+
+```typescript
+import { getWalrusSystemInfo } from '@lamdanghoang/sui-pay'
+
+const systemInfo = await getWalrusSystemInfo('testnet')
+console.log({
+  nShards: systemInfo.nShards,           // e.g., 1000
+  storagePricePerUnit: systemInfo.storagePricePerUnit,  // FROST per MiB per epoch
+  writePricePerUnit: systemInfo.writePricePerUnit,      // FROST per MiB
+  currentEpoch: systemInfo.currentEpoch,
+})
+```
+
+### Live vs Default Pricing
+
+```typescript
+// Use live on-chain pricing (recommended)
+const costLive = await calculateStorageCostLive(fileSize, epochs, 'testnet')
+
+// Use default pricing (faster, no RPC call)
+const costDefault = calculateStorageCost(fileSize, epochs)
+
+// Check balance with live pricing
+const check = await client.checkBalance(address, fileSize, epochs, 20, true)
+
+// Check balance with default pricing
+const checkFast = await client.checkBalance(address, fileSize, epochs, 20, false)
+```
+
+## License
+
+MIT

package/contracts/Move.toml

@@ -0,0 +1,9 @@
+[package]
+name = "walrus_sui_pay"
+edition = "2024.beta"
+
+[dependencies]
+Sui = { git = "https://github.com/MystenLabs/sui.git", subdir = "crates/sui-framework/packages/sui-framework", rev = "framework/testnet" }
+
+[addresses]
+walrus_sui_pay = "0x0"

package/contracts/sources/wal_exchange_pyth.move

@@ -0,0 +1,315 @@
+/// Generic SUI <-> Token Exchange with Pyth Oracle pricing
+/// T = the token type to exchange with SUI (e.g., WAL)
+/// 
+/// Pyth Price Feed IDs:
+/// - SUI/USD: 0x23d7315113f5b1d3ba7a83604c44b94d79f4fd69af77f804fc7f920a6dc65744
+/// - WAL/USD: 0xeba0732395fae9dec4bae12e52760b35fc1c5671e2da8b449c9af4efe5d54341
+module walrus_sui_pay::wal_exchange_pyth {
+    use sui::coin::{Self, Coin};
+    use sui::balance::{Self, Balance};
+    use sui::sui::SUI;
+    use sui::event;
+    use sui::clock::Clock;
+
+    // === Errors ===
+    const EInsufficientLiquidity: u64 = 0;
+    const EZeroAmount: u64 = 1;
+    const EInvalidPrice: u64 = 3;
+    const ESlippageExceeded: u64 = 4;
+    const EPaused: u64 = 6;
+
+    // === Constants ===
+    const FEE_BPS: u64 = 30;  // 0.3% fee
+    const BPS_DENOMINATOR: u64 = 10_000;
+    const MAX_PRICE_AGE_SECONDS: u64 = 60;
+
+    // === Structs ===
+
+    /// Generic exchange pool for SUI <-> T swaps
+    public struct Exchange<phantom T> has key {
+        id: UID,
+        sui_balance: Balance<SUI>,
+        token_balance: Balance<T>,
+        admin: address,
+        paused: bool,
+        /// Token/USD price scaled by 1e8
+        token_usd_price: u64,
+        max_price_age: u64,
+    }
+
+    /// Admin capability
+    public struct AdminCap has key, store {
+        id: UID,
+        exchange_id: ID,
+    }
+
+    // === Events ===
+
+    public struct ExchangeCreated has copy, drop {
+        exchange_id: ID,
+        admin: address,
+    }
+
+    public struct SwapExecuted has copy, drop {
+        user: address,
+        sui_amount: u64,
+        token_amount: u64,
+        is_sui_to_token: bool,
+        sui_price: u64,
+        token_price: u64,
+        fee_amount: u64,
+    }
+
+    public struct LiquidityAdded has copy, drop {
+        provider: address,
+        sui_amount: u64,
+        token_amount: u64,
+    }
+
+    // === Initialization ===
+
+    /// Create a new exchange for SUI <-> T
+    public fun create_exchange<T>(
+        initial_token_price: u64,
+        ctx: &mut TxContext
+    ): (Exchange<T>, AdminCap) {
+        let exchange = Exchange<T> {
+            id: object::new(ctx),
+            sui_balance: balance::zero(),
+            token_balance: balance::zero(),
+            admin: ctx.sender(),
+            paused: false,
+            token_usd_price: initial_token_price,
+            max_price_age: MAX_PRICE_AGE_SECONDS,
+        };
+
+        let exchange_id = object::id(&exchange);
+        let admin_cap = AdminCap {
+            id: object::new(ctx),
+            exchange_id,
+        };
+
+        event::emit(ExchangeCreated {
+            exchange_id,
+            admin: ctx.sender(),
+        });
+
+        (exchange, admin_cap)
+    }
+
+    /// Create and share exchange (entry function for deployment)
+    public entry fun create_and_share_exchange<T>(
+        initial_token_price: u64,
+        ctx: &mut TxContext
+    ) {
+        let (exchange, admin_cap) = create_exchange<T>(initial_token_price, ctx);
+        transfer::share_object(exchange);
+        transfer::transfer(admin_cap, ctx.sender());
+    }
+
+    // === Swap Functions ===
+
+    /// Swap SUI for Token using real-time Pyth prices
+    /// 
+    /// @param exchange - The exchange pool
+    /// @param sui_coin - SUI to swap
+    /// @param sui_price - SUI/USD price from Pyth (scaled by 1e8)
+    /// @param token_price - Token/USD price from Pyth (scaled by 1e8)
+    /// @param min_token_out - Minimum tokens to receive (slippage protection)
+    /// @param clock - Sui clock object
+    public fun swap_sui_for_token<T>(
+        exchange: &mut Exchange<T>,
+        sui_coin: Coin<SUI>,
+        sui_price: u64,
+        token_price: u64,
+        min_token_out: u64,
+        _clock: &Clock,
+        ctx: &mut TxContext
+    ) {
+        assert!(!exchange.paused, EPaused);
+        assert!(sui_price > 0, EInvalidPrice);
+        assert!(token_price > 0, EInvalidPrice);
+
+        let sui_amount = coin::value(&sui_coin);
+        assert!(sui_amount > 0, EZeroAmount);
+
+        // Calculate token output: (sui_amount * sui_price) / token_price
+        let sui_value_usd = (sui_amount as u128) * (sui_price as u128);
+        let token_amount_raw = sui_value_usd / (token_price as u128);
+
+        // Deduct fee (0.3%)
+        let fee = (token_amount_raw * (FEE_BPS as u128)) / (BPS_DENOMINATOR as u128);
+        let token_amount = ((token_amount_raw - fee) as u64);
+
+        assert!(token_amount >= min_token_out, ESlippageExceeded);
+        assert!(balance::value(&exchange.token_balance) >= token_amount, EInsufficientLiquidity);
+
+        // Execute swap
+        balance::join(&mut exchange.sui_balance, coin::into_balance(sui_coin));
+        let token_out = coin::from_balance(
+            balance::split(&mut exchange.token_balance, token_amount),
+            ctx
+        );
+        transfer::public_transfer(token_out, ctx.sender());
+
+        event::emit(SwapExecuted {
+            user: ctx.sender(),
+            sui_amount,
+            token_amount,
+            is_sui_to_token: true,
+            sui_price,
+            token_price,
+            fee_amount: (fee as u64),
+        });
+    }
+
+    /// Swap Token for SUI using real-time Pyth prices
+    public fun swap_token_for_sui<T>(
+        exchange: &mut Exchange<T>,
+        token_coin: Coin<T>,
+        sui_price: u64,
+        token_price: u64,
+        min_sui_out: u64,
+        _clock: &Clock,
+        ctx: &mut TxContext
+    ) {
+        assert!(!exchange.paused, EPaused);
+        assert!(sui_price > 0, EInvalidPrice);
+        assert!(token_price > 0, EInvalidPrice);
+
+        let token_amount = coin::value(&token_coin);
+        assert!(token_amount > 0, EZeroAmount);
+
+        // Calculate SUI output
+        let token_value_usd = (token_amount as u128) * (token_price as u128);
+        let sui_amount_raw = token_value_usd / (sui_price as u128);
+
+        let fee = (sui_amount_raw * (FEE_BPS as u128)) / (BPS_DENOMINATOR as u128);
+        let sui_amount = ((sui_amount_raw - fee) as u64);
+
+        assert!(sui_amount >= min_sui_out, ESlippageExceeded);
+        assert!(balance::value(&exchange.sui_balance) >= sui_amount, EInsufficientLiquidity);
+
+        // Execute swap
+        balance::join(&mut exchange.token_balance, coin::into_balance(token_coin));
+        let sui_out = coin::from_balance(
+            balance::split(&mut exchange.sui_balance, sui_amount),
+            ctx
+        );
+        transfer::public_transfer(sui_out, ctx.sender());
+
+        event::emit(SwapExecuted {
+            user: ctx.sender(),
+            sui_amount,
+            token_amount,
+            is_sui_to_token: false,
+            sui_price,
+            token_price,
+            fee_amount: (fee as u64),
+        });
+    }
+
+    // === Liquidity Functions ===
+
+    /// Add both SUI and Token liquidity
+    public fun add_liquidity<T>(
+        exchange: &mut Exchange<T>,
+        sui_coin: Coin<SUI>,
+        token_coin: Coin<T>,
+        ctx: &TxContext
+    ) {
+        let sui_amount = coin::value(&sui_coin);
+        let token_amount = coin::value(&token_coin);
+
+        balance::join(&mut exchange.sui_balance, coin::into_balance(sui_coin));
+        balance::join(&mut exchange.token_balance, coin::into_balance(token_coin));
+
+        event::emit(LiquidityAdded {
+            provider: ctx.sender(),
+            sui_amount,
+            token_amount,
+        });
+    }
+
+    /// Add SUI liquidity only
+    public fun add_sui_liquidity<T>(
+        exchange: &mut Exchange<T>,
+        sui_coin: Coin<SUI>,
+    ) {
+        balance::join(&mut exchange.sui_balance, coin::into_balance(sui_coin));
+    }
+
+    /// Add Token liquidity only
+    public fun add_token_liquidity<T>(
+        exchange: &mut Exchange<T>,
+        token_coin: Coin<T>,
+    ) {
+        balance::join(&mut exchange.token_balance, coin::into_balance(token_coin));
+    }
+
+    // === Admin Functions ===
+
+    /// Update the stored token price (for reference only, swaps use Pyth prices)
+    public fun update_token_price<T>(
+        exchange: &mut Exchange<T>,
+        _admin_cap: &AdminCap,
+        new_price: u64,
+    ) {
+        assert!(new_price > 0, EInvalidPrice);
+        exchange.token_usd_price = new_price;
+    }
+
+    /// Pause/unpause the exchange
+    public fun set_paused<T>(
+        exchange: &mut Exchange<T>,
+        _admin_cap: &AdminCap,
+        paused: bool,
+    ) {
+        exchange.paused = paused;
+    }
+
+    /// Remove liquidity (admin only)
+    public fun remove_liquidity<T>(
+        exchange: &mut Exchange<T>,
+        _admin_cap: &AdminCap,
+        sui_amount: u64,
+        token_amount: u64,
+        ctx: &mut TxContext
+    ) {
+        if (sui_amount > 0) {
+            let sui_coin = coin::from_balance(
+                balance::split(&mut exchange.sui_balance, sui_amount),
+                ctx
+            );
+            transfer::public_transfer(sui_coin, ctx.sender());
+        };
+
+        if (token_amount > 0) {
+            let token_coin = coin::from_balance(
+                balance::split(&mut exchange.token_balance, token_amount),
+                ctx
+            );
+            transfer::public_transfer(token_coin, ctx.sender());
+        };
+    }
+
+    // === View Functions ===
+
+    /// Get current balances in the pool
+    public fun get_balances<T>(exchange: &Exchange<T>): (u64, u64) {
+        (
+            balance::value(&exchange.sui_balance),
+            balance::value(&exchange.token_balance)
+        )
+    }
+
+    /// Get stored token price
+    public fun get_token_price<T>(exchange: &Exchange<T>): u64 {
+        exchange.token_usd_price
+    }
+
+    /// Check if exchange is paused
+    public fun is_paused<T>(exchange: &Exchange<T>): bool {
+        exchange.paused
+    }
+}