{"id":30413086,"url":"https://github.com/longcipher/suiflash","last_synced_at":"2026-02-09T21:15:29.906Z","repository":{"id":310088236,"uuid":"1037229428","full_name":"longcipher/suiflash","owner":"longcipher","description":"Flash Loan Aggregator for SUI blockchain","archived":false,"fork":false,"pushed_at":"2025-10-15T13:25:41.000Z","size":578,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-16T09:40:00.007Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/longcipher.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-08-13T09:00:30.000Z","updated_at":"2025-10-15T13:25:45.000Z","dependencies_parsed_at":"2025-08-15T17:46:52.367Z","dependency_job_id":"8e85acad-ee2f-45b5-8069-e802dcb471b3","html_url":"https://github.com/longcipher/suiflash","commit_stats":null,"previous_names":["longcipher/suiflash"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/longcipher/suiflash","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fsuiflash","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fsuiflash/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fsuiflash/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fsuiflash/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/longcipher","download_url":"https://codeload.github.com/longcipher/suiflash/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/longcipher%2Fsuiflash/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29281641,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T19:05:41.198Z","status":"ssl_error","status_checked_at":"2026-02-09T19:05:37.449Z","response_time":56,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-22T02:33:52.990Z","updated_at":"2026-02-09T21:15:29.892Z","avatar_url":"https://github.com/longcipher.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# SuiFlash\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/suiflash_banner.jpeg\" alt=\"SuiFlash Logo\" width=\"600\"\u003e\n\u003c/p\u003e\n\nCapital‑light, multi‑protocol flash loan routing on Sui.\n\nSuiFlash is a production‑grade, capital‑light flash loan aggregator for the Sui blockchain. It unifies access to multiple lending protocols (NAVI, Bucket, Scallop) behind a single, composable interface, performing smart routing, secure user callbacks, atomic settlement, and transparent fee capture in one programmable transaction.\n\n## 📡 Current Deployment (Sui Devnet)\n\n| Component | Address | Description |\n|-----------|---------|-------------|\n| Package ID | `0x0ea1cc59ece4c8c6ff7342dd89f192873303980efda1cb6d0e55beb93d13f7e3` | Main contract package |\n| Config Object | `0x27695e4c7aa292b3f1bc712daf3a4a0d5548f7ca159010428b4bf92182d0552b` | Shared config object |\n| Network | Sui Devnet | \u003chttps://fullnode.devnet.sui.io:443\u003e |\n| Service Fee | 40 bps | 0.40% service fee |\n\n## ✨ Key Features\n\n- Unified API \u0026 Move entrypoint: one `flash_loan` call instead of three integrations.\n- Smart routing strategies: explicit selection, lowest fee, or highest liquidity.\n- Atomic user callback: borrow → execute custom logic → repay + fees, all or nothing.\n- Protocol abstraction layer: isolated integration modules per protocol.\n- Configurable service fee (basis points) with on‑chain admin controls (pause, fee update, asset allowlist).\n- Deterministic fee model: `total_fee = protocol_fee + aggregator_service_fee`.\n- Event emission for off‑chain indexing \u0026 analytics.\n- Hardened settlement: repayment sufficiency checks and revert on shortfall.\n\n## 🧱 Architecture Overview\n\n| Layer | Component | Responsibility |\n|-------|-----------|----------------|\n| On‑chain | `suiflash::flash_router` | Entry `flash_loan\u003cT\u003e` + routing + settlement + callback dispatch |\n| On‑chain | `state` | AdminCap, Config (treasury, service_fee_bps, pause flag, allowlist) |\n| On‑chain | `integrations::{navi,bucket,scallop}` | Borrow + repay wrappers, protocol fee surfaces |\n| On‑chain | `interfaces` | Documented callback signature contract expectation |\n| On‑chain | `errors` | Canonical error codes (protocol invalid, amount too low, insufficient repayment, paused) |\n| Off‑chain | Collectors | Periodic fetching / caching of liquidity + fee data |\n| Off‑chain | Strategy Engine | Route selection \u0026 plan generation |\n| Off‑chain | Executor | Builds \u0026 signs PTB with router + user callback steps |\n| Off‑chain | REST API | External interface: submit requests, query status |\n\n## 🔄 Flash Loan Lifecycle\n\n### Architecture Diagram\n\n```mermaid\nflowchart TD\n    User[User / Bot] --\u003e REST[REST API\u003cbr/\u003esuiflash_bot]\n    REST --\u003e Strategy[Strategy Engine]\n    Strategy --\u003e Executor[Executor / PTB Builder]\n    Executor --\u003e Router[On-chain Module\u003cbr/\u003esuiflash::flash_router]\n    Router --\u003e|Borrow| Protocols{Underlying Protocols\u003cbr/\u003eNAVI / Bucket / Scallop}\n    Protocols --\u003e|Loaned Funds| Router\n    Router --\u003e Callback[User Callback Contract\u003cbr/\u003eexecute_operation]\n    Callback --\u003e Router\n    Router --\u003e|Repay + Protocol Fee| Protocols\n    Router --\u003e|Service Fee| Treasury[Treasury Address]\n    Router --\u003e Event[FlashLoanExecuted Event]\n    Event --\u003e Indexer[Observers / Indexers / Analytics]\n    Executor --\u003e|Result / Digest| REST\n    REST --\u003e User\n    \n    classDef onchain fill:#e3f2fd,stroke:#1e88e5,stroke-width:1px\n    classDef offchain fill:#f1f8e9,stroke:#43a047,stroke-width:1px\n    classDef protocol fill:#fff3e0,stroke:#fb8c00,stroke-width:1px\n    \n    class Router,Callback,Event,Treasury onchain\n    class User,REST,Strategy,Executor,Indexer offchain\n    class Protocols protocol\n```\n\n1. Client POSTs `/flashloan` with JSON payload (asset, amount, route_mode, optional explicit protocol, user callback metadata, payload bytes).\n2. Bot validates request \u0026 reads freshest protocol metrics from in‑memory snapshot (collector feed).\n3. Strategy selects protocol (or allocation) producing an `ExecutionPlan` with expected fees \u0026 total cost.\n4. Executor builds a Sui Programmable Transaction Block invoking:\n\t- `suiflash::flash_router::flash_loan\u003cAsset\u003e(config, protocol_selector, amount, recipient_contract, payload)`\n\t- (Within the same PTB) user callback function `execute_operation` in the recipient contract.\n5. Underlying protocol funds are borrowed; user callback executes custom logic atomically.\n6. Repayment + aggregator service fee returned to router.\n7. Router verifies sufficiency, repays protocol, transfers service fee to treasury, emits `FlashLoanExecuted`.\n8. API responds with transaction digest, protocol used, and fee breakdown.\n\n## 🧩 Move Contract Surface (Conceptual)\n\n```move\npublic entry fun flash_loan\u003cCoinType\u003e(\n\tcfg: \u0026Config,\n\tprotocol_selector: u64,\n\tamount: u64,\n\trecipient: address,\n\tpayload: vector\u003cu8\u003e,\n\tctx: \u0026mut TxContext\n);\n```\n\nCallback contract must implement:\n\n```move\npublic entry fun execute_operation\u003cCoinType\u003e(\n\tloaned_coin: Coin\u003cCoinType\u003e,\n\tpayload: vector\u003cu8\u003e,\n\tctx: \u0026mut TxContext\n): Coin\u003cCoinType\u003e; // returns principal + protocol fee + service fee\n```\n\n## 🧠 Routing Strategies\n\n| Mode | Description |\n|------|-------------|\n| Explicit | User specifies target protocol. |\n| BestCost | Minimizes fee (protocol fee + service fee) given current snapshots. |\n| BestLiquidity | Prioritizes max available liquidity to reduce slippage \u0026 ensure fill. |\n\n## ⚙️ Configuration\n\nThe bot now uses a layered configuration system (implemented with the `config` crate) that merges multiple sources with a deterministic priority.\n\nPriority (highest → lowest):\n\n1. Environment variables prefixed with `SUIFLASH_` (e.g. `SUIFLASH_PRIVATE_KEY`)\n2. Legacy environment variables without prefix (backward compatibility)\n3. `config.toml` file (if present in project root)\n4. Built‑in defaults\n\nMinimum required to run: signing key (`private_key` / `SUIFLASH_PRIVATE_KEY`), deployed package \u0026 config object IDs.\n\nSupported keys / variables:\n\n| Key / Env Var | Purpose | Default |\n|---------------|---------|---------|\n| `sui_rpc_url` / `SUIFLASH_SUI_RPC_URL` / `SUI_RPC_URL` | Fullnode RPC endpoint | `https://fullnode.testnet.sui.io:443` |\n| `private_key` / `SUIFLASH_PRIVATE_KEY` / `PRIVATE_KEY` | Bot signing key (hex / Base64) | (required) |\n| `sui_flash_package_id` / `SUIFLASH_SUI_FLASH_PACKAGE_ID` / `SUI_FLASH_PACKAGE_ID` | Published SuiFlash package ID | (required) |\n| `sui_flash_config_object_id` / `SUIFLASH_SUI_FLASH_CONFIG_OBJECT_ID` / `SUI_FLASH_CONFIG_OBJECT_ID` | On‑chain Config object ID | (required) |\n| `server_port` / `SUIFLASH_SERVER_PORT` / `SERVER_PORT` | REST server port | `3000` |\n| `refresh_interval_ms` / `SUIFLASH_REFRESH_INTERVAL_MS` / `REFRESH_INTERVAL_MS` | Collector refresh cadence (ms) | `10000` |\n| `strategy` / `SUIFLASH_STRATEGY` / `STRATEGY` | `cheapest` or `highest_liquidity` | `cheapest` |\n| `contract_package_id` / `SUIFLASH_CONTRACT_PACKAGE_ID` / `CONTRACT_PACKAGE_ID` | Default user callback package (optional) | `0x1` |\n| `navi_package_id` / `SUIFLASH_NAVI_PACKAGE_ID` / `NAVI_PACKAGE_ID` | NAVI protocol package id | `0x2` |\n| `bucket_package_id` / `SUIFLASH_BUCKET_PACKAGE_ID` / `BUCKET_PACKAGE_ID` | Bucket protocol package id | `0x3` |\n| `scallop_package_id` / `SUIFLASH_SCALLOP_PACKAGE_ID` / `SCALLOP_PACKAGE_ID` | Scallop protocol package id | `0x4` |\n| `service_fee_bps` / `SUIFLASH_SERVICE_FEE_BPS` / `SERVICE_FEE_BPS` | Aggregator service fee (basis points) | `40` (0.40%) |\n\nQuick start using a file (recommended): copy `suiflash-bot/config.example.toml` to `config.toml` and edit your real IDs / key.\n\nExample minimal `config.toml`:\n\n```toml\nsui_rpc_url = \"https://fullnode.testnet.sui.io:443\"\nprivate_key = \"\u003chex_or_base64_private_key\u003e\"\nsui_flash_package_id = \"0x...\"            # deployed package id\nsui_flash_config_object_id = \"0x...\"       # on-chain config object\nservice_fee_bps = 40                       # 0.40%\nstrategy = \"cheapest\"\n```\n\nOverride anything at runtime with a prefixed env var, e.g.:\n\n```bash\nexport SUIFLASH_REFRESH_INTERVAL_MS=5000\nexport SUIFLASH_STRATEGY=highest_liquidity\n```\n\nFor deeper detail (validation, examples) see `suiflash-bot/README.md`.\n\n## 🛣 REST API\n\n| Method | Path | Description |\n|--------|------|-------------|\n| `POST` | `/flashloan` | Submit flash loan request |\n| `GET` | `/health` | Liveness probe |\n| `GET` | `/protocols` | Current protocol fee + liquidity snapshot (aggregated) |\n| `GET` | `/status` | Aggregator status \u0026 metrics |\n\n### Example Request\n\n```bash\ncurl -X POST http://localhost:3000/flashloan \\\n\t-H 'Content-Type: application/json' \\\n\t-d '{\n\t\t\"asset\": \"SUI\",\n\t\t\"amount\": 1000000000,\n\t\t\"route_mode\": \"BestCost\",          // BestCost | BestLiquidity | Explicit\n\t\t\"explicit_protocol\": null,          // e.g. \"Navi\" when route_mode = \"Explicit\"\n\t\t\"user_operation\": \"arbitrage:DEXA-\u003eDEXB\",\n\t\t\"callback_recipient\": \"0xabc...def\", // optional contract handling callback\n\t\t\"callback_payload\": \"base64_or_hex\"   // optional opaque payload\n\t}'\n```\n\n### Example Response\n\n```json\n{\n\t\"transaction_digest\": \"8J6...abc\",\n\t\"protocol_used\": \"Scallop\",\n\t\"protocol_fee\": 500000,\n\t\"service_fee\": 400000,\n\t\"total_fee\": 900000\n}\n```\n\n## 🔐 Security Model\n\n| Control | Mechanism |\n|---------|-----------|\n| Atomicity | Single PTB; full revert on any failure |\n| Fee Enforcement | On‑chain repayment check before releasing funds |\n| Admin Controls | AdminCap: pause, adjust service_fee_bps, update treasury |\n| Asset Allowlist | Config‑maintained permitted assets list |\n| Protocol Isolation | Separate integration modules \u0026 receipt verification |\n| Reentrancy Guard | Loan receipt \u0026 single active loan per execution flow |\n\n## 🧪 Development \u0026 Testing\n\nRun backend:\n\n```bash\ncargo run --bin suiflash_bot\n```\n\nRun tests:\n\n```bash\ncargo test\n```\n\nBuild Move package:\n\n```bash\nsui move build\n```\n\n## 📦 Project Structure\n\n```text\nsuiflash/\n\tdocs/DESIGN.md\n\tsuiflash-contract/ (Move package)\n\tsuiflash-bot/      (Rust Artemis backend)\n```\n\n## Navi Protocol\n\n\u003e **⚠️ Integration Status**: The Navi Protocol integration is currently in **MOCK/PLACEHOLDER** state.\n\u003e - ✅ **Working**: Fee configuration (6 bps), address setup, API integration, architecture\n\u003e - ❌ **Not Implemented**: Actual on-chain calls to Navi's `flash_loan_with_ctx` and `flash_repay_with_ctx`\n\u003e - 📊 **Completion**: ~30% (configuration and structure only)\n\u003e \n\u003e See `docs/NAVI_INTEGRATION_REVIEW.md` for complete status and required work for production.\n\n### Navi Protocol Docs\n\n- \u003chttps://naviprotocol.gitbook.io/navi-protocol-docs/developers-docs/hackathon-overflow-navi-bounty\u003e\n- \u003chttps://naviprotocol.gitbook.io/navi-protocol-docs/getting-started/flash-loan\u003e\n\n### Navi Protocol Interfaces\n\n- \u003chttps://github.com/naviprotocol/protocol-interface/blob/main/lending_core/sources/flash_loan.move\u003e\n\n### Navi Protocol SDKs\n\n- \u003chttps://github.com/naviprotocol/navi-sdk/blob/main/src/libs/PTB/commonFunctions.ts\u003e\n\n### SuiFlash Navi Integration Docs\n\n- `docs/NAVI_ADDRESSES.md` - Mainnet addresses and API reference\n- `docs/NAVI_INTEGRATION.md` - Integration guide (intended architecture)\n- `docs/NAVI_INTEGRATION_REVIEW.md` - Current status and complete review\n- `suiflash-contract/suiflash-router/sources/integrations/navi_real_example.move` - Reference implementation\n\n## Scallop Protocol\n\n### Scallop Protocol Docs\n\n- \u003chttps://docs.scallop.io/scallop-lend/borrowing\u003e\n\n### Scallop Protocol Interfaces\n\n- \u003chttps://github.com/scallop-io/sui-lending-protocol/blob/main/contracts/protocol/sources/user/flash_loan.move\u003e\n\n### Protocol SDKs\n\n* \u003chttps://github.com/scallop-io/sui-scallop-sdk/blob/main/src/builders/coreBuilder.ts\u003e\n\n\n\n## Bucket Protocol\n\n### Protocol Docs\n\n- \u003chttps://docs.bucketprotocol.io/mechanisms/flash-loan\u003e\n- \u003chttps://docs.bucketprotocol.io/mechanisms/borrowing\u003e\n\n### Protocol Interfaces\n\n- \u003chttps://github.com/Bucket-Protocol/bucket-interface/blob/main/bucket-protocol/sources/buck.move\u003e\n\n### Bucket Protocol SDKs\n\n- \u003chttps://github.com/Bucket-Protocol/bucket-protocol-sdk/blob/main/sdk/src/client.ts\u003e\n\n## 📝 License\n\nApache-2.0 (or compatible) – ensure compliance when distributing derivatives.\n\n## 🙌 Acknowledgements\n\nBuilt on the Sui ecosystem \u0026 inspired by prior multi‑protocol aggregators in DeFi.\n\n---\n\nSuiFlash makes flash liquidity programmable, composable, and strategy‑driven on Sui.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongcipher%2Fsuiflash","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flongcipher%2Fsuiflash","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flongcipher%2Fsuiflash/lists"}