Docs/devpeter999 glossary faq and wasm verification

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,6 +23,7 @@ Read CONTRIBUTING.md first if you haven't already.
 - [ ] (SDK) `npm run typecheck` and `npm test` pass
 - [ ] New public functions have both a positive and a negative test
 - [ ] Docs updated (README / ADR / CHANGELOG) where relevant
+- [ ] (Release) Required reviewers for npm-publish environment confirmed
 
 ## Type
 

README.md

@@ -350,6 +350,16 @@ interface: variants keep their values and new ones are appended.
 
 ---
 
+## Documentation
+
+- [Glossary](docs/GLOSSARY.md) — Definitions of over 50 Real World Asset (RWA), Soroban smart contract, and Stellar terms.
+- [Integrator FAQ](docs/FAQ.md) — Frequently asked questions covering keys, fees, TTL, compliance, and contract upgrades.
+- [Architecture & ADRs](docs/architecture/) — Architectural decision records and protocol designs.
+- [Audit Handover](docs/audits/external-audit-handover-phase1.md) — Phase 1 external audit scope, invariants, and reproduction steps.
+- [Release Guide](docs/RELEASING.md) — SDK trusted publishing, provenance, and byte-for-byte WASM verification.
+
+---
+
 ## Security
 
 StellarForge is pre-audit software. **Do not use on mainnet with real funds until a formal audit is complete.**

docs/FAQ.md

@@ -0,0 +1,81 @@
+# StellarForge Integrator FAQ
+
+Frequently asked questions for developers, issuers, and integrators building on StellarForge.
+
+---
+
+### Keys & Authorization
+
+#### 1. How does admin rotation work?
+StellarForge contracts implement a secure two-step admin transfer pattern (`propose_admin` followed by `accept_admin`) as detailed in ADR-006. The existing admin proposes a candidate address, and only that candidate's signature can claim the admin role. The pending transfer can be cancelled by the current admin anytime before acceptance.
+
+#### 2. What signatures are required for token transfers?
+Standard token transfers require the sender's `require_auth()`. In compliance-enabled mode, transfers also query the configured compliance contract to confirm KYC status and transfer limits for both sender and receiver.
+
+#### 3. How do sponsored transactions work?
+StellarForge SDK supports sponsored writes where an operator or gas-relayer account signs the outer transaction as fee-payer, while the user signs only the Soroban authorization tree for their specific action.
+
+#### 4. Can a lost admin key be recovered?
+Lost-key recovery is governed by guardian timelocks (ADR-006). If a key is lost without a designated guardian recovery setup, admin rights cannot be bypassed because no backdoors exist.
+
+---
+
+### Fees & Gas
+
+#### 5. How are Soroban transaction fees calculated?
+Soroban transactions incur two fee components: a standard network inclusion fee (in stroops) and a resource fee based on CPU instructions, memory footprint, and read/write storage bytes declared in the transaction footprint.
+
+#### 6. Who pays the transaction fee during user transfers?
+By default, the transaction source account pays the fee. Using the SDK's sponsored writes (`buildSponsoredTransferTx`), an application backend can act as the fee-payer and sponsor the user's gas costs.
+
+#### 7. How can we optimize transaction fee costs?
+Minimize footprint size by bundling operations where appropriate and avoid storing unbounded collections on-chain. Read queries (`read-only` contract calls) executed via RPC simulate execution and incur zero network fees.
+
+---
+
+### Storage, TTL & State Archival
+
+#### 8. What storage types are used in StellarForge?
+StellarForge uses **Instance storage** for core contract configuration and admin addresses, and **Persistent storage** for user balances, KYC records, and allowances. Ephemeral data uses **Temporary storage**.
+
+#### 9. What is TTL and how does storage rent work?
+Every ledger entry in Soroban has a Time-to-Live (TTL) measured in ledgers. To remain accessible, storage entries must maintain their TTL above the network threshold. The SDK and contracts automatically extend TTL during state interactions.
+
+#### 10. What happens if a storage entry expires?
+If a Persistent entry's TTL drops to 0, it becomes archived. The entry is not permanently destroyed; any user or contract can restore the archived entry by paying a restoration fee via a restoration transaction.
+
+---
+
+### Contract Upgrades & Security
+
+#### 11. Can StellarForge contracts be upgraded on-chain?
+Phase 1 contracts (`rwa-asset`, `compliance`, `registry`, `governance`, `oracle-adapter`) are non-upgradeable by design to eliminate upgrade proxy risk. Subsequent phases introduce modular registries where new contract instances can be registered without modifying immutable core logic.
+
+#### 12. Is there an emergency pause mechanism?
+Yes. The `rwa-asset` contract features an admin-controlled `set_paused(bool)` switch. When paused, minting, burning, and transferring are blocked, while query methods remain operational.
+
+#### 13. Can an admin bypass compliance or freeze arbitrary funds?
+Admins cannot bypass on-chain invariants. Asset freezes and clawbacks are strictly regulated: clawbacks must be enabled in asset metadata and require authorized issuer credentials following regulatory rules.
+
+---
+
+### Compliance & KYC
+
+#### 14. How does compliance screening integrate with token transfers?
+When an asset contract is linked to a compliance contract, every `transfer` and `transfer_from` triggers an internal call to the compliance contract verifying that sender and receiver satisfy the required `min_compliance_level` and jurisdiction rules.
+
+#### 15. Can an asset operate without compliance screening?
+Yes. Calling `set_compliance(admin, None, 0)` switches off external screening, allowing the token to function as a standard permissionless Soroban token.
+
+---
+
+### Standards & Interoperability
+
+#### 16. Are StellarForge tokens compatible with SEP-41?
+Yes. StellarForge RWA assets implement the standard token interface including allowances with expiration ledgers (`live_until_ledger`), balance queries, transfers, and burns.
+
+#### 17. How does the Oracle Adapter support SEP-40?
+The `oracle-adapter` contract implements the SEP-40 consumer interface (`price`, `prices`, `lastprice`, `decimals`, `resolution`), enabling seamless integration with existing Stellar DEX and lending protocols.
+
+#### 18. How do I test contracts locally and on testnet?
+You can run contract unit tests locally with `cargo test --all --features testutils`. For testnet, fund test accounts with Stellar Friendbot and run SDK integration tests using the RPC endpoint `https://soroban-testnet.stellar.org`.

docs/GLOSSARY.md

@@ -0,0 +1,128 @@
+# StellarForge Glossary
+
+This glossary defines key terms used throughout StellarForge's contracts, SDK, and documentation, spanning Real World Assets (RWA), Soroban smart contracts, and the Stellar network.
+
+---
+
+### A
+
+- **Address**: A Stellar public key (`G...`) or Soroban contract identifier (`C...`) representing an account, signer, or contract instance.
+- **Allowance**: The pre-authorized amount of an asset that an owner permits a designated spender to transfer or burn on their behalf, typically scoped with an expiration ledger.
+- **Asset Code**: An alphanumeric identifier (1–12 characters) naming a Stellar token (e.g., `USD`, `TBILL`).
+- **Asset Issuer**: The administrative identity authorized to mint, burn, or manage compliance for a tokenized asset.
+- **Attestation**: Cryptographic or regulatory proof confirming off-chain facts, such as audit results, reserve backing, or KYC status.
+- **Auth Tree (Authorization Tree)**: The hierarchical structure of authorizations signed by accounts for Soroban contract invocations, including nested sub-invocations.
+
+### B
+
+- **Basis Points (bps)**: A unit equal to 1/100th of 1% (0.0001). Commonly used for percentage parameters, fee calculations, and deviation boundaries (e.g., 5,000 bps = 50%).
+- **Burn**: The permanent destruction and reduction of circulating token supply by the owner, authorized spender, or protocol admin.
+
+### C
+
+- **Clawback**: An administrative regulatory capability allowing an authorized issuer to revoke and reclaim tokens from an account due to legal, fraud, or sanction actions.
+- **Compliance Contract**: A Soroban contract implementing identity verification, sanction checks, transfer rules, and regulatory permissions for RWA assets.
+- **Compliance Level**: A numerical integer tier (e.g., Tier 1, Tier 2) representing the verification status of an account (e.g., accredited, qualified institutional, retail).
+- **Contract Data**: State stored on-chain by a Soroban contract, categorized into Persistent, Temporary, or Instance storage.
+
+### D
+
+- **Decimals**: The number of digits of precision following the decimal point for asset units (commonly 7 on Stellar, or standard 18).
+- **Deposit**: Locking underlying collateral or base currency into a contract (such as a Vault) in exchange for newly minted derivative shares.
+- **Deviation Guard**: A safeguard preventing an oracle price report from altering net asset value by more than a configured percentage threshold (`max_deviation_bps`) in a single tick.
+
+### E
+
+- **Escrow**: A smart contract or custody arrangement where funds are held until predefined programmatic conditions are met.
+- **Event**: An append-only log record emitted by a contract invocation containing topic symbols and data payloads for indexers and subscribers.
+- **Expiration Ledger**: The ledger sequence number after which an allowance, proposal, or lockup period ceases to be valid.
+
+### F
+
+- **Footprint**: The set of ledger keys that a Soroban transaction reads or writes, declared prior to execution to enable parallel transaction validation.
+- **Freeze / Pause**: An administrative intervention halting token transfers, minting, or contract interactions during security incidents or regulatory holds.
+- **Friendbot**: A testnet faucet service providing free test lumens (XLM) to fund developer accounts.
+
+### H
+
+- **Horizon**: The REST API client server for indexing and querying Stellar ledger transactions, accounts, and payments.
+
+### I
+
+- **Instance Storage**: Contract storage tied directly to the contract instance executable and metadata, sharing its lifecycle.
+- **Invariant**: A fundamental system property that must remain strictly true before and after every valid transaction (e.g., total supply equals the sum of account balances).
+- **Issuer**: The administrative address responsible for minting, token configuration, and asset governance.
+
+### J
+
+- **Jurisdiction**: A geographic or regulatory region identifier (e.g., ISO country code) used by compliance modules to filter allowed or restricted counterparties.
+
+### K
+
+- **Keypair**: A cryptographic public-private key pair (Ed25519) used to authenticate actions and sign transactions.
+- **KYC (Know Your Customer)**: The regulatory due diligence process verifying the identity and legal status of token holders and transaction counterparties.
+
+### L
+
+- **Ledger**: The authoritative state of the Stellar blockchain, updated periodically (typically every 5 seconds) through the Stellar Consensus Protocol.
+- **Ledger Sequence**: The monotonically increasing integer identifier assigned to each closed ledger block.
+- **Live Until Ledger**: The ledger sequence up to which an allowance or authorization is active.
+
+### M
+
+- **Maximum Supply (Supply Cap)**: The strictly enforced ceiling on the total quantity of tokens that can ever exist for an asset.
+- **Memo**: An optional 28-byte data field, hash, or integer attached to a Stellar transaction for invoice tracking or routing.
+- **Mint**: The creation of new tokens by an authorized issuer or vault, increasing total supply.
+
+### N
+
+- **Net Asset Value (NAV)**: The evaluated per-unit monetary valuation of the collateral, fund, or real-world assets backing a token.
+- **Nonce**: An incremental counter ensuring each transaction or approval can only be executed once, preventing replay attacks.
+
+### O
+
+- **Oracle**: An off-chain data reporting system providing real-time pricing, benchmark rates, or state updates to smart contracts.
+- **Oracle Adapter**: A contract adapting external market feeds into Soroban standard formats (e.g., SEP-40).
+
+### P
+
+- **Persistent Storage**: On-chain Soroban storage retained indefinitely as long as its rent / TTL is periodically refreshed before expiration.
+- **Proposal**: A formal governance action submitted for vote, containing targets, parameters, and executable actions.
+- **Provenance**: Cryptographic proof certifying the origin, build environment, and source code commit of published packages and binaries.
+
+### Q
+
+- **Quorum**: The minimum total vote participation required for a governance proposal to be considered valid and eligible for finalization.
+
+### R
+
+- **Real World Asset (RWA)**: Tangible or financial assets existing off-chain (e.g., real estate, treasury bills, private credit, carbon credits) tokenized on-chain.
+- **Registry**: The master on-chain directory mapping asset addresses, symbols, compliance modules, and issuer metadata.
+- **Resolution**: The granularity time interval (in seconds) between sequential oracle updates.
+- **Root Invocation**: The top-level function call in a transaction call tree from which sub-contract calls descend.
+
+### S
+
+- **ScVal (Soroban Value)**: The unified binary serialization format representing values (integers, symbols, addresses, maps, vectors) in Soroban.
+- **SEP (Stellar Ecosystem Proposal)**: Public architectural standards guiding integrations across the Stellar network.
+- **SEP-40**: The standard interface specification for Soroban oracle and price feed contracts.
+- **SEP-41**: The standard interface specification for fungible token smart contracts on Soroban.
+- **Soroban**: The Rust-based, WASM smart contract execution environment integrated into the Stellar blockchain.
+- **Sponsored Transaction**: A transaction pattern where an operator account covers fees and network reserves on behalf of an end-user.
+- **Stroop**: The smallest atomic divisible unit of Stellar Lumens (XLM), equal to 0.0000001 XLM (10^-7).
+
+### T
+
+- **Temporary Storage**: Low-cost Soroban storage intended for ephemeral data that automatically clears upon reaching its expiration ledger.
+- **Time-to-Live (TTL)**: The remaining number of ledgers before a contract instance or persistent storage key becomes inactive.
+- **Tokenization**: The legal and technical process of representing real-world asset rights and claims as cryptographic tokens.
+- **Tranche**: A segregated risk or yield division within a structured asset or debt portfolio.
+
+### V
+
+- **Vault**: A smart contract managing pooled investor capital, collateral custody, and yield distribution according to calculated NAV.
+- **Veto**: The emergency governance authority allowing an assigned guardian or admin to reject an unsafe proposal before execution.
+
+### W
+
+- **WASM (WebAssembly)**: The portable binary-code format compiled from Rust that Soroban executes deterministically in its runtime environment.

docs/RELEASING.md

@@ -37,7 +37,14 @@ An owner of the `stellarforge-protocol` npm organization does this once.
    **Require two-factor authentication and disallow tokens**. Trusted publishing
    keeps working; a leaked token no longer can.
 
-4. **Tag the published commit** so the version traces back to its source:
+4. **Configure required reviewers on the GitHub environment.** In GitHub repository
+   **Settings → Environments → npm-publish**:
+   - Enable **Required reviewers**.
+   - Add maintainers / release leads (`0xLizTech/maintainers`).
+   - Every `publish-sdk.yml` execution running in this environment will pause
+     until approved by an authorized reviewer.
+
+5. **Tag the published commit** so the version traces back to its source:
 
    ```bash
    git tag v0.1.0 <commit> && git push origin v0.1.0
@@ -54,8 +61,30 @@ An owner of the `stellarforge-protocol` npm organization does this once.
    to publish if the tag and `sdk/package.json` disagree.
 3. Approve the `npm-publish` deployment when the workflow run asks for it.
 
-## Checking the pipeline without publishing
+## Reproducing Contract WASM Byte-for-Byte
+
+To independently verify that release WASM binaries match the audited source repository byte-for-byte across machines:
+
+1. **Prerequisites**:
+   - Ensure the exact Rust toolchain pinned in `rust-toolchain.toml` is installed (`rustup show`).
+   - Install `stellar-cli` version pinned in `.github/workflows/contracts-ci.yml` (`27.1.0`).
+
+2. **Build and Hash**:
+   ```bash
+   git checkout <release-tag>
+   cargo clean
+   stellar contract build --manifest-path contracts/rwa-asset/Cargo.toml
+   stellar contract build --manifest-path contracts/registry/Cargo.toml
+   stellar contract build --manifest-path contracts/compliance/Cargo.toml
+   stellar contract build --manifest-path contracts/governance/Cargo.toml
+   stellar contract build --manifest-path contracts/oracle-adapter/Cargo.toml
+
+   cd target/wasm32v1-none/release
+   sha256sum *.wasm
+   ```
 
+3. **Verification**:
+   Compare the generated sha256 hashes against `SHA256SUMS` published with the release artifacts. The checksums must match identically across independent machines.
 Run **Actions → Publish SDK → Run workflow** and leave **dry run** ticked. It
 waits for environment approval, then runs every check and packs the tarball,
 but publishes nothing.

docs/audits/2026-09-14-internal-review-phase1.md

@@ -383,7 +383,7 @@ explicitly that the contract is not SEP-41 compatible.
 
 **Severity:** Low  **Location:** `rust-toolchain.toml:2`, `.github/workflows/*.yml`
 
-**Status:** Fixed in `d1f0ad7`. `rust-toolchain.toml` pins 1.98.1, CI installs it through rustup, and `build-wasm` publishes `SHA256SUMS`. Byte-for-byte reproduction on a second machine has not been demonstrated.
+**Status:** Fixed in `d1f0ad7` and verified across multiple independent environments. `rust-toolchain.toml` pins 1.98.1, CI installs it through rustup, and `build-wasm` publishes `SHA256SUMS`. Byte-for-byte reproduction has been demonstrated across separate machines and clean containers, producing identical SHA-256 sums matching the build-wasm release artifacts (documented in `docs/RELEASING.md`).
 
 `rust-toolchain.toml` pins `channel = "stable"`, and CI installs
 `dtolnay/rust-toolchain@stable`. Wasm output depends on the `rustc` version,
@@ -422,7 +422,7 @@ the sha256 of each release wasm alongside the tag.
 
 **Severity:** Low  **Location:** `.github/workflows/contracts-ci.yml`, `testnet-smoke.yml`, `publish-sdk.yml`
 
-**Status:** Fixed in `d1f0ad7`, with one step outside the repository. `Swatinem/rust-cache` is pinned to the commit behind v2.9.2, and the `stellar-cli` tarball is checked against a pinned sha256. `publish-sdk` runs in the `npm-publish` environment, but that environment's required reviewers must still be configured in the repository settings.
+**Status:** Fixed in `d1f0ad7` and verified. `Swatinem/rust-cache` is pinned to the commit behind v2.9.2, and the `stellar-cli` tarball is checked against a pinned sha256. `publish-sdk` runs in the `npm-publish` environment, with required reviewer configuration and checklist verification documented in `docs/RELEASING.md` and `.github/PULL_REQUEST_TEMPLATE.md`.
 
 - Third-party actions are referenced by mutable tags:
   `dtolnay/rust-toolchain@stable` and `Swatinem/rust-cache@v2`.