diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 39f6f3d..e256826 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.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 diff --git a/README.md b/README.md index c427012..a4162da 100644 --- a/README.md +++ b/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.** diff --git a/docs/FAQ.md b/docs/FAQ.md new file mode 100644 index 0000000..233f093 --- /dev/null +++ b/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`. diff --git a/docs/GLOSSARY.md b/docs/GLOSSARY.md new file mode 100644 index 0000000..9bdfa74 --- /dev/null +++ b/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. diff --git a/docs/RELEASING.md b/docs/RELEASING.md index cf05e98..0a89fe7 100644 --- a/docs/RELEASING.md +++ b/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 && 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 + 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. diff --git a/docs/audits/2026-09-14-internal-review-phase1.md b/docs/audits/2026-09-14-internal-review-phase1.md index e798742..e698ce9 100644 --- a/docs/audits/2026-09-14-internal-review-phase1.md +++ b/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`.