docs: correct confirmed factual errors in integration guides

docs: correct confirmed factual errors in integration guides

Author: mattglory

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

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\":[\"<serialized-contract-principal>\"]}"
+# 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

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)` |