From faf01e2e61ba977636a944a7290742aa18b7a7d2 Mon Sep 17 00:00:00 2001 From: Hillaryhardy Date: Mon, 8 Jun 2026 09:20:53 +0300 Subject: [PATCH] docs: correct remaining factual errors in integration guides Rebased on current main; the max-single-loan fix already merged upstream is dropped. Remaining verifiable corrections, each checked against contract source, live mainnet reads, or the test suite: - README: STX receiver impl-trait pointed at the wrong contract; corrected to SP3TGRVG7DKGFVRTTVGGS60S59R916FWB4DAB9STZ.stx-flash-receiver-trait (the snippet as written would not deploy) - README: standardize the test count to 82 (matches the badge and `vitest run`: 82 passed) - INTEGRATION_GUIDE: Clarity has no `max` builtin; use the raw-fee / if form - INTEGRATION_GUIDE: the is-approved-receiver read-only call requires a serialized contract principal (0x06...), not the ascii-hex of the string - TESTING_GUIDE_STX: fix the one remaining max-loan figure in the error table (5,000,000,000 -> 500,000,000,000) - TESTING_GUIDE_STX: get-stats field names corrected to total-loans / total-fees - TESTING_GUIDE_STX: STX is-approved-receiver returns a bare bool, not (ok bool) - TESTING_GUIDE_STX: clarify legacy flashstack-core vs live flashstack-sbtc-core --- README.md | 8 ++++---- docs/INTEGRATION_GUIDE.md | 8 ++++++-- docs/TESTING_GUIDE_STX.md | 12 ++++++------ 3 files changed, 16 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 4f74f6e..5e8b3e9 100644 --- a/README.md +++ b/README.md @@ -126,7 +126,7 @@ LP shares are yield-bearing collateral. The `flashstack-pool-oracle` exposes `ge git clone https://github.com/mattglory/Flashstack.git cd flashstack npm install -npm test # 86 tests passing +npm test # 82 tests passing npm run check # Clarinet contract verification ``` @@ -171,7 +171,7 @@ EXECUTE=true LOAN_STX=100 \ ### STX Receiver ```clarity -(impl-trait 'SP20XD46NGAX05ZQZDKFYCCX49A3852BQABNP0VG5.flashstack-stx-core.stx-flash-receiver-trait) +(impl-trait 'SP3TGRVG7DKGFVRTTVGGS60S59R916FWB4DAB9STZ.stx-flash-receiver-trait.stx-flash-receiver-trait) (define-public (execute-stx-flash (amount uint) (core principal)) (let ( @@ -279,7 +279,7 @@ flashstack/ velar-sbtc-arb-receiver.clar # Velar sBTC arb receiver zest-liquidation-receiver.clar # Zest zero-capital liquidator (4 modes) alex-arb-receiver.clar # ALEX STX/ALEX arb receiver - tests/ # 86 Vitest + Clarinet simnet tests + tests/ # 82 Vitest + Clarinet simnet tests scripts/ # Deploy + monitor scripts docs/ # Guides and integration specs TESTING_GUIDE_STX.md @@ -302,7 +302,7 @@ flashstack/ - [x] Security hardening — all audit findings resolved - [x] Mainnet deployment — STX + canonical sBTC flash loan engines -- [x] 86-test suite (Vitest + Clarinet simnet) +- [x] 82-test suite (Vitest + Clarinet simnet) - [x] Production frontend — STX + sBTC flash loans, wallet connect, live stats - [x] LP pool — external liquidity providers earn STX yield - [x] Bitflow arb receiver — live DEX integration proven on mainnet diff --git a/docs/INTEGRATION_GUIDE.md b/docs/INTEGRATION_GUIDE.md index a1aaccc..089d5d2 100644 --- a/docs/INTEGRATION_GUIDE.md +++ b/docs/INTEGRATION_GUIDE.md @@ -142,7 +142,10 @@ Only approved receivers can borrow from FlashStack. Open a GitHub issue at https curl -s -X POST \ "https://api.hiro.so/v2/contracts/call-read/SP20XD46NGAX05ZQZDKFYCCX49A3852BQABNP0VG5/flashstack-stx-core/is-approved-receiver" \ -H "Content-Type: application/json" \ - -d "{\"sender\":\"YOUR-ADDRESS\",\"arguments\":[\"0x$(printf 'YOUR-ADDRESS.my-receiver' | xxd -p)\"]}" + -d "{\"sender\":\"YOUR-ADDRESS\",\"arguments\":[\"\"]}" +# NOTE: the argument must be a Clarity-serialized contract-principal (hex starting 0x06...), +# NOT the ascii-hex of the string. Generate it in JS: +# Cl.serialize(Cl.contractPrincipal("YOUR-ADDRESS", "my-receiver")) ``` Or check on Hiro Explorer: navigate to your contract address and call `is-approved-receiver` with your receiver principal as argument. @@ -266,7 +269,8 @@ Borrow the debt amount, call the lending protocol's liquidation function, receiv (let ( (fee-bp (unwrap! (contract-call? 'SP20XD46NGAX05ZQZDKFYCCX49A3852BQABNP0VG5.flashstack-stx-core get-fee-basis-points) ERR-REPAY)) - (fee (max (/ (* amount fee-bp) u10000) u1)) + (raw-fee (/ (* amount fee-bp) u10000)) + (fee (if (> raw-fee u0) raw-fee u1)) (total-owed (+ amount fee)) ) ;; Repay borrower's debt to the lending protocol diff --git a/docs/TESTING_GUIDE_STX.md b/docs/TESTING_GUIDE_STX.md index d2735c8..96f57c4 100644 --- a/docs/TESTING_GUIDE_STX.md +++ b/docs/TESTING_GUIDE_STX.md @@ -15,7 +15,7 @@ FlashStack has two generations of implementation in this repo: | sBTC flash loans (`flashstack-core`, `sbtc-token`) | Legacy — SP3TGRVG7... wallet | No — reference only | | STX flash loans (`flashstack-stx-core`, `flashstack-stx-pool`) | Active — SP20XD46... wallet | Yes — this is the focus | -The Clarinet local tests and `docs/archive/` cover the sBTC path. Ignore them for active testing — they are kept for historical reference only. +The Clarinet local tests and `docs/archive/` cover the **legacy** sBTC path (`flashstack-core`, SP3TGRVG7...) — kept for historical reference only. Note: the canonical sBTC engine `flashstack-sbtc-core` (SP20XD46...) is **live and active** (reserve ~15,010 sats, fee 5 bps; see `docs/TESTING_GUIDE_SBTC.md`). Only the old `flashstack-core` path is legacy. --- @@ -74,9 +74,9 @@ receiver: SP20XD46NGAX05ZQZDKFYCCX49A3852BQABNP0VG5.stx-test-receiver **What success looks like:** - Transaction confirmed (green checkmark in Explorer) - No error code in the result -- `get-stats` on `flashstack-stx-core` shows `total-flash-mints` incremented by 1 +- `get-stats` on `flashstack-stx-core` shows `total-loans` incremented by 1 - `get-stats` shows `total-volume` increased by 10000000 -- `get-stats` shows `total-fees-collected` increased by 5000 (0.05% of 10 STX) +- `get-stats` shows `total-fees` increased by 5000 (0.05% of 10 STX) **What failure looks like:** - `(err u302)` — `ERR-REPAY-FAILED` — receiver didn't repay (shouldn't happen with stx-test-receiver) @@ -101,8 +101,8 @@ Call `get-reserve-balance` on `flashstack-stx-core`. The result must be ≥ your | `get-fee-basis-points` | `(ok u5)` — 0.05% fee | | `get-max-single-loan` | `(ok u500000000000)` — 500,000 STX limit | | `get-admin` | `(ok SP20XD46NGAX05ZQZDKFYCCX49A3852BQABNP0VG5)` | -| `is-approved-receiver` with `SP20XD46...stx-test-receiver` | `(ok true)` | -| `is-approved-receiver` with `SP20XD46...bitflow-arb-receiver-v4` | `(ok true)` | +| `is-approved-receiver` with `SP20XD46...stx-test-receiver` | `true` (STX core returns a bare bool, not `(ok ...)`) | +| `is-approved-receiver` with `SP20XD46...bitflow-arb-receiver-v4` | `true` | | `calculate-fee u10000000` | `(ok u5000)` — fee on 10 STX | --- @@ -168,7 +168,7 @@ These should all fail cleanly with no fund loss: | Test | How to trigger | Expected error | |------|---------------|----------------| | Loan exceeds reserve | `flash-loan` with amount > `get-reserve-balance` | `(err u303)` | -| Loan exceeds max | `flash-loan` with amount > 5000000000 | `(err u304)` | +| Loan exceeds max | `flash-loan` with amount > 500000000000 | `(err u304)` | | Unapproved receiver | `flash-loan` with your own unwhitelisted contract | `(err u306)` | | Zero amount | `flash-loan` with `u0` | `(err u301)` |