# Flashnet

> Flashnet is a decentralized exchange (DEX) infrastructure built natively on Bitcoin. It provides an AMM for BTC and USDB trading on Spark (a Bitcoin L2), cross-chain swap orchestration via the Orchestra API, and USDB, a dollar-backed stablecoin with BTC rewards. All operations are self-custodial and settle on Bitcoin through Spark. Flashnet uses the @flashnet/sdk (TypeScript) for AMM integration and a REST API with HMAC-SHA256 authentication for Orchestra.

- Flashnet AMM runs on Spark, a UTXO-based Bitcoin L2 using cryptographic messaging (not a blockchain)
- All trades are self-custodial: Flashnet never takes custody of user funds
- Users can unilaterally exit to Bitcoin L1 at any time, even with open orders
- USDB is redeemable 1:1 for USD and pays 3.5-6% rewards in BTC daily
- Orchestra supports cross-chain swaps between Bitcoin and Ethereum, Arbitrum, Optimism, Polygon, Solana, and Tron
- The AMM supports constant-product (V2), bonding curve (single-sided), and concentrated liquidity (V3) pools
- AMM SDK: `npm install @flashnet/sdk @buildonspark/spark-sdk`
- Orchestra API authentication: HMAC-SHA256 signed requests with API key and secret
- Error codes follow the format FSAG-XXXX with automatic fund recovery via clawback

## Docs

### Getting Started

- [Introduction](https://docs.flashnet.xyz/introduction.md): What Flashnet is, how it works, and how Spark enables near-instant zero-fee Bitcoin settlement
- [Architecture](https://docs.flashnet.xyz/architecture.md): System design including atomic swaps, intent-based execution, TEE validators, and isolated MPC wallets
- [Trust Model](https://docs.flashnet.xyz/architecture/trust-model.md): Security model, trust assumptions, validator coordination, and threat analysis

### AMM

- [AMM Overview](https://docs.flashnet.xyz/products/flashnet-amm/overview.md): Automated market maker for BTC and USDB on Spark with constant-product, bonding curve, and V3 pools
- [How It Works](https://docs.flashnet.xyz/products/flashnet-amm/how-it-works.md): AMM mechanics, price curves, trade execution, and settlement flow
- [Setup](https://docs.flashnet.xyz/products/flashnet-amm/setup.md): Install @flashnet/sdk, initialize a Spark wallet, and create a FlashnetClient
- [Config & Gating](https://docs.flashnet.xyz/products/flashnet-amm/config.md): Pool configuration parameters and feature gating options
- [Pool Creation](https://docs.flashnet.xyz/products/flashnet-amm/creation.md): Create constant-product, bonding curve, or concentrated liquidity pools
- [Liquidity](https://docs.flashnet.xyz/products/flashnet-amm/liquidity.md): Add and remove liquidity from AMM pools
- [Swaps](https://docs.flashnet.xyz/products/flashnet-amm/swaps.md): Execute token swaps with slippage protection
- [Route Swaps](https://docs.flashnet.xyz/products/flashnet-amm/route-swaps.md): Multi-hop swaps across multiple liquidity pools
- [Lightning Payments](https://docs.flashnet.xyz/products/flashnet-amm/lightning-payments.md): Pay Lightning Network invoices directly through AMM swaps
- [Querying Pools](https://docs.flashnet.xyz/products/flashnet-amm/pools.md): Fetch pool state, reserves, pricing data, and pool lists
- [Fees](https://docs.flashnet.xyz/products/flashnet-amm/fees.md): Fee structure, collection mechanics, and distribution to LPs and hosts
- [Hosts](https://docs.flashnet.xyz/products/flashnet-amm/hosts.md): Register as an AMM host, earn fees, and configure host namespaces
- [Error Handling](https://docs.flashnet.xyz/products/flashnet-amm/errors.md): FSAG-XXXX error codes, recovery strategies, and automatic clawback mechanisms

### Concentrated Liquidity (V3)

- [Concentrated Liquidity](https://docs.flashnet.xyz/products/flashnet-amm/concentrated-liquidity.md): Provide liquidity within custom price ranges for higher capital efficiency
- [Creating V3 Pools](https://docs.flashnet.xyz/products/flashnet-amm/concentrated-creation.md): Create concentrated liquidity pools with tick spacing and initial price
- [Managing Positions](https://docs.flashnet.xyz/products/flashnet-amm/concentrated-positions.md): Open, adjust, and close concentrated liquidity positions
- [Free Balances](https://docs.flashnet.xyz/products/flashnet-amm/concentrated-balances.md): Query withdrawable token balances from V3 positions

### Orchestra (Cross-Chain Swaps)

- [Orchestra Overview](https://docs.flashnet.xyz/products/orchestration/overview.md): Cross-chain Bitcoin swaps through a single REST API supporting Ethereum, Arbitrum, Optimism, Polygon, Solana, and Tron
- [Integration Guide](https://docs.flashnet.xyz/products/orchestration/integration.md): End-to-end flow for quoting, accepting deposits, and delivering output assets
- [Order Lifecycle](https://docs.flashnet.xyz/products/orchestration/order-lifecycle.md): How quotes become orders and how orders progress through execution states
- [Choosing a Flow](https://docs.flashnet.xyz/products/orchestration/choosing-a-flow.md): Compare quote/submit, accumulation addresses, and liquidation addresses
- [Stablecoin to BTC](https://docs.flashnet.xyz/products/orchestration/stablecoin-to-btc.md): Swap USDC, USDT, ETH, SOL, or TRX into BTC or USDB on Spark
- [BTC to Stablecoin](https://docs.flashnet.xyz/products/orchestration/btc-to-stablecoin.md): Swap BTC or USDB into stablecoins or native assets on any supported chain
- [Accumulation Address](https://docs.flashnet.xyz/products/orchestration/accumulation-address.md): Reusable deposit addresses on EVM/Solana/Tron that auto-deliver BTC or USDB
- [Liquidation Address](https://docs.flashnet.xyz/products/orchestration/liquidation-address.md): Reusable Bitcoin deposit addresses that auto-deliver to any supported chain
- [ZeroConf](https://docs.flashnet.xyz/products/orchestration/zeroconf.md): Instant credit for Bitcoin L1 deposits without waiting for confirmations
- [Webhooks](https://docs.flashnet.xyz/products/orchestration/webhooks.md): Receive HMAC-signed webhook events for order status updates with automatic retries

### Orchestra API Reference

- [API Overview](https://docs.flashnet.xyz/products/orchestration/api/overview.md): Authentication (HMAC-SHA256), error codes, rate limits, and API conventions
- [Quotes & Orders](https://docs.flashnet.xyz/products/orchestration/api/quotes-and-orders.md): Create quotes, submit deposits, and track order status via REST endpoints
- [Approval Flows](https://docs.flashnet.xyz/products/orchestration/api/approval-flows.md): Handle repricing requests and ZeroConf approval offers
- [Resources](https://docs.flashnet.xyz/products/orchestration/api/resources.md): CRUD operations for affiliates, webhooks, accumulation addresses, and liquidation addresses

### USDB Stablecoin

- [What is USDB?](https://docs.flashnet.xyz/usdb/overview.md): Dollar-backed stablecoin on Spark with 3.5-6% BTC rewards paid daily
- [Get USDB](https://docs.flashnet.xyz/usdb/get-usdb.md): Acquire USDB through minting, swapping, or purchasing from supported providers
- [Redeem USDB](https://docs.flashnet.xyz/usdb/redeem.md): Redeem USDB for USD or swap back to BTC
- [Rewards](https://docs.flashnet.xyz/usdb/rewards.md): How USDB holders earn BTC rewards and how reward rates are determined
- [Transparency](https://docs.flashnet.xyz/usdb/transparency.md): Reserve backing, audit information, and reward sustainability
- [FAQ](https://docs.flashnet.xyz/usdb/faq.md): Common questions about USDB minting, redemption, rewards, and eligibility

### Integrations

- [Integrate USDB](https://docs.flashnet.xyz/usdb/integrate.md): Add USDB support to wallets, exchanges, and apps with revenue sharing
- [Rewards Delegation](https://docs.flashnet.xyz/usdb/delegation.md): Configure reward endorsements to direct part of daily USDB rewards to other pubkeys
- [Integrator Rewards API](https://docs.flashnet.xyz/rewards/integrators/api.md): API endpoints for rewards, endorsements, Flashpoints, and system stats
- [Integrator Incentives](https://docs.flashnet.xyz/rewards/integrators/incentives.md): Volume bonuses, launch partner program, and leaderboard rewards for hosts
- [TEE Attestation](https://docs.flashnet.xyz/products/orchestration/tee-attestation.md): Verify Orchestra's Trusted Execution Environment attestation for security audits

## Examples

- [AMM Setup & First Swap](https://docs.flashnet.xyz/products/flashnet-amm/setup.md): Install the SDK, initialize a Spark wallet, create a FlashnetClient, and execute your first swap
- [Orchestra Integration](https://docs.flashnet.xyz/products/orchestration/integration.md): Complete example of quoting a cross-chain swap, submitting a deposit, and tracking delivery
- [USDB Integration](https://docs.flashnet.xyz/usdb/integrate.md): Step-by-step guide for adding USDB balances, rewards display, and swap functionality to your app

## API Reference

- [Orchestra REST API](https://docs.flashnet.xyz/products/orchestration/api/overview.md): Full REST API for cross-chain swaps with HMAC-SHA256 authentication
- [RFQ OpenAPI Spec](https://docs.flashnet.xyz/openapi/rfq.json): OpenAPI 3.0 specification for the Request-for-Quote API

## Optional

- [Swap History](https://docs.flashnet.xyz/products/flashnet-amm/history.md): Query historical swap records and trade data for analytics
- [Advanced Topics](https://docs.flashnet.xyz/products/flashnet-amm/advanced.md): Advanced AMM configuration, optimization techniques, and edge cases
- [Flashpoints Overview](https://docs.flashnet.xyz/rewards/flashpoints/overview.md): Points-based rewards program for Flashnet traders and liquidity providers
- [Earning Flashpoints](https://docs.flashnet.xyz/rewards/flashpoints/earning.md): Actions that earn Flashpoints and their multipliers
- [Leaderboard](https://docs.flashnet.xyz/rewards/flashpoints/leaderboard.md): Flashpoints leaderboard rankings, tiers, and seasonal resets