Skip to content

README.md

Latest commit

 

History

History
289 lines (211 loc) · 11.7 KB

README.md

File metadata and controls

289 lines (211 loc) · 11.7 KB

FlashStack

The First Flash Loan Protocol for Bitcoin Layer 2

Status Tests Clarity Live License

Atomic, uncollateralized flash loans on Stacks (Bitcoin L2). Borrow any amount of STX with zero collateral, execute your strategy, and repay — all in one transaction. If repayment fails, the entire transaction reverts automatically.

Live App

flashstack.vercel.app

  • Flash Loan — borrow STX with zero collateral
  • LP Pool — deposit STX, earn yield from every flash loan fee
  • Arb Bot — one-click Bitflow STX/stSTX arbitrage with live price check
  • Receivers — deployed strategy contracts and build-your-own templates

Mainnet Deployment

Deployer Wallets

Wallet Address Purpose
STX wallet SP20XD46NGAX05ZQZDKFYCCX49A3852BQABNP0VG5 STX flash loan infrastructure (active)
sBTC wallet SP3TGRVG7DKGFVRTTVGGS60S59R916FWB4DAB9STZ sBTC flash loan infrastructure

STX Flash Loan Contracts — SP20XD46... (4 contracts)

Contract Explorer
flashstack-stx-core — flash loan core, 80 STX reserve View
flashstack-stx-pool — LP pool, 30 STX, anyone deposits View
stx-test-receiver — basic flash loan receiver View
bitflow-arb-receiver — Bitflow STX/stSTX arbitrage View

sBTC Flash Loan Contracts — SP3TGRVG7... (17 contracts)

Contract Explorer
flashstack-core — sBTC mint/burn flash loan core View
sbtc-token — SIP-010 sBTC token View
flash-receiver-trait — sBTC receiver interface View
stx-flash-receiver-trait — STX receiver interface View
test-receiver View
example-arbitrage-receiver View
liquidation-receiver View
leverage-loop-receiver View
collateral-swap-receiver View
yield-optimization-receiver View
dex-aggregator-receiver View
multidex-arbitrage-receiver View
snp-flashstack-receiver-v3 View
snp-flashstack-receiver View
stx-core-test2 test contract
stx-core-test3 test contract
test-trait-use test contract

Total confirmed on-chain: 21 contracts across 2 wallets

  • 4 production STX contracts (SP20XD46...)
  • 14 production sBTC contracts (SP3TGRVG7...)
  • 3 development/iteration contracts (stx-core-test2, stx-core-test3, test-trait-use)

M2 milestone submission referenced 16 production contracts (sBTC + STX infrastructure, excluding test iterations and the LP pool + arb receiver added post-submission).

Confirmed Mainnet Flash Loans (7 total)

# Asset Amount Contract Tx
1 sBTC 1 sBTC (u1000000) test-receiver View
2 sBTC 5 sBTC (u5000000) test-receiver View
3 sBTC 10 sBTC (u10000000) dex-aggregator-receiver View
4 STX 10 STX stx-test-receiver View
5 STX 50 STX stx-test-receiver View
6 STX 50 STX stx-test-receiver (frontend UI) View
7 STX test stx-test-receiver View

Quick Start

Smart Contracts

git clone https://github.com/mattglory/flashstack.git
cd flashstack
npm install
npm test          # 86 tests passing
npm run check     # Clarinet contract verification

Requirements: Node.js 16+, Clarinet 2.0+

Frontend

cd web
npm install
npm run dev       # http://localhost:3000

Opportunity Monitor Bot

# Dry-run — check for arb every 30s, prints opportunities, no execution
DEPLOYER_MNEMONIC="your twelve word mnemonic" \
  node scripts/monitor-opportunities.mjs

# Live — auto-execute when profitable (requires funded wallet)
EXECUTE=true \
  LOAN_STX=50 \
  DEPLOYER_MNEMONIC="your twelve word mnemonic" \
  node scripts/monitor-opportunities.mjs

Never hardcode your mnemonic in source files or commit it to git.

How It Works

STX Flash Loans (primary product)

  1. Call flash-loan(amount, receiver) on flashstack-stx-core or flashstack-stx-pool
  2. Protocol sends STX to your receiver contract
  3. Your receiver executes any strategy (arb, liquidation, swap, etc.)
  4. Receiver repays principal + 0.05% fee before returning
  5. If repayment fails, entire transaction reverts — zero risk to protocol

LP Pool

  1. Anyone deposits STX into flashstack-stx-pool
  2. Depositor receives shares proportional to deposit
  3. Every flash loan fee accumulates in the pool
  4. Share value increases automatically as fees grow
  5. Withdraw anytime — receive principal + all accrued yield

sBTC Flash Loans (mint/burn model)

Same atomic guarantee but using a mint/burn mechanism for sBTC.

Strategies

Bitflow STX/stSTX Arbitrage (live — use Arb Bot page)

stSTX accumulates staking yield every ~2 weeks. When yield accrues, stSTX briefly trades above 1:1 STX on Bitflow before arbitrageurs equalize it.

Borrow 1000 STX (zero collateral)
  -> Buy stSTX on Bitflow (stSTX above peg)
  -> Sell stSTX back to STX (at higher rate)
  -> Repay 1000.05 STX (principal + 0.05% fee)
  -> Keep spread as profit

Use the live bot at flashstack.vercel.app/arb or run:

EXECUTE=true DEPLOYER_MNEMONIC="..." node scripts/monitor-opportunities.mjs

Cross-DEX Arbitrage

Borrow STX -> Buy TOKEN cheap on DEX A -> Sell TOKEN on DEX B -> Repay -> Keep spread

Self-Liquidation

Borrowers approaching liquidation can flash-borrow to repay their own debt and avoid liquidation penalties.

Build a Receiver Contract

;; Implement this single function
(impl-trait 'SP3TGRVG7DKGFVRTTVGGS60S59R916FWB4DAB9STZ.stx-flash-receiver-trait.stx-flash-receiver-trait)

(define-public (execute-stx-flash (amount uint) (core principal))
  (let (
    (fee       (/ (* amount u5) u10000))  ;; 0.05%
    (total-owed (+ amount fee))
  )
    ;; Your strategy here — you have (amount) STX right now

    ;; Repay principal + fee
    (unwrap! (as-contract (stx-transfer? total-owed tx-sender core)) (err u500))
    (ok true)
  )
)

Deploy to mainnet, then open a GitHub issue or email mattglory14@gmail.com to get whitelisted. Include your deployed contract address.

Security

Status: Mainnet, not professionally audited. Use at your own risk.

All findings from an independent security review were addressed before mainnet deployment:

ID Severity Finding Status
C-01 Critical Anyone could call mint on sbtc-token Fixed
C-02 Critical Supply invariant not enforced after callback Fixed
H-01 High Supply inflates after each flash loan Fixed
H-03 High Fee hardcoded in receivers Fixed — dynamic fee lookup
M-01 Medium No circuit breaker Fixed — max loan + max block volume
L-01 Low Fee rounds to zero for tiny loans Fixed — minimum fee of 1 unit

Testing

npm test           # 86 tests
npm run test:watch # Watch mode

86 tests covering: initialization, access control, fee calculations, collateral ratios, circuit breakers, whitelist management, flash loan execution, end-to-end mint-burn cycle, boundary values, security invariants.

Project Structure

flashstack/
  contracts/              # 20 Clarity smart contracts
  tests/                  # 86 Vitest tests
  scripts/                # Deploy + monitor scripts
    monitor-opportunities.mjs   # Arb bot (Bitflow STX/stSTX)
    deploy-pool-and-liquidation.mjs
    seed-pool.mjs
  web/                    # Next.js 14 frontend
    src/app/
      page.tsx            # Marketing landing page
      (app)/
        dashboard/        # Protocol stats
        flash-loan/       # Execute flash loans
        pool/             # LP pool deposit/withdraw
        arb/              # Bitflow arb bot UI
        receivers/        # Deployed contracts + templates

Roadmap

  • Security hardening (all audit findings addressed)
  • Mainnet deployment — 21 contracts across 2 wallets
  • 86-test suite (Vitest + Clarinet simnet)
  • Frontend — flash loan execution, wallet connection, live stats
  • STX reserve flash loans (no collateral required)
  • LP pool — external liquidity providers earn yield
  • Arb bot — Bitflow STX/stSTX, live price check + one-click execute
  • Mobile-responsive UI
  • Professional audit
  • Zest Protocol liquidation integration
  • Multi-asset LP pool
  • External developer onboarding (M3)
  • Bug bounty

License

MIT

Author

Glory Matthew — @mattglory