From 0efd5dc721fd0a90fd6febbf8a02d0583556ba6c Mon Sep 17 00:00:00 2001 From: Odeh Samuel Date: Mon, 19 Oct 2026 12:23:33 +0100 Subject: [PATCH] docs: add descriptive link text and replace bare URLs (#1005) --- CONTRIBUTING.md | 6 +++--- contracts/README.md | 4 ++-- docs/ADRs/README.md | 16 ++++++++-------- docs/API_REFERENCE.md | 14 +++++++------- docs/COMMUNICATION_TEMPLATES.md | 2 +- docs/COMPREHENSIVE_API_DOCS.md | 12 ++++++------ docs/CONTRACTS.md | 4 ++-- docs/DEVELOPER_ENVIRONMENT.md | 18 +++++++++--------- docs/OPERATIONAL_RUNBOOK.md | 2 +- docs/QUERY_OPTIMIZATION.md | 6 +++--- docs/RETENTION_AND_PRUNING.md | 2 +- docs/SECURITY_REVIEW_CHECKLIST.md | 4 ++-- docs/STORAGE.md | 6 +++--- docs/TOKEN_SETUP.md | 2 +- docs/UPGRADE_AND_ROLLBACK.md | 2 +- docs/error_codes.md | 4 ++-- docs/videos/README.md | 6 +++--- examples/README.md | 12 ++++++------ 18 files changed, 61 insertions(+), 61 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index f1eb67e..ca97f2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,7 +2,7 @@ ## Dev Environment Setup -1. Install Rust: https://rustup.rs +1. Install Rust: [rustup, the Rust toolchain installer](https://rustup.rs) 2. Add Wasm target: ```bash rustup target add wasm32-unknown-unknown @@ -156,5 +156,5 @@ the output. ## Resources -- [Soroban Documentation](https://developers.stellar.org/docs/smart-contracts) -- [Soroban SDK](https://docs.rs/soroban-sdk) +- [Stellar smart contracts documentation (Soroban)](https://developers.stellar.org/docs/smart-contracts) +- [soroban-sdk Rust crate API reference (docs.rs)](https://docs.rs/soroban-sdk) diff --git a/contracts/README.md b/contracts/README.md index c320ab7..24f2688 100644 --- a/contracts/README.md +++ b/contracts/README.md @@ -10,7 +10,7 @@ ## Versioning -All crates follow semantic versioning. Query a live contract with `get_version` / `get_version_metadata`. See [../docs/VERSIONING.md](../docs/VERSIONING.md). +All crates follow semantic versioning. Query a live contract with `get_version` / `get_version_metadata`. See [the contract versioning guide (VERSIONING.md)](../docs/VERSIONING.md). ## Architecture @@ -46,7 +46,7 @@ cargo test ## Deploy -See [../scripts/deploy_testnet.sh](../scripts/deploy_testnet.sh) +See [the testnet deployment script (deploy_testnet.sh)](../scripts/deploy_testnet.sh) ## Contract Addresses (Testnet) diff --git a/docs/ADRs/README.md b/docs/ADRs/README.md index ac8a3f9..1313a87 100644 --- a/docs/ADRs/README.md +++ b/docs/ADRs/README.md @@ -30,14 +30,14 @@ graph LR | ADR ID | Title | Status | Date | Component | |--------|-------|--------|------|-----------| -| [ADR-0000](0000-template.md) | Standard Architecture Decision Record Template | Accepted | 2026-01-15 | All | -| [ADR-0001](0001-soroban-smart-contract-platform.md) | Adoption of Stellar Soroban Rust Smart Contract Platform | Accepted | 2026-01-20 | Core / Platform | -| [ADR-0002](0002-escrow-architecture-and-state-machine.md) | Escrow Contract State Machine and CEI Pattern | Accepted | 2026-02-01 | Escrow | -| [ADR-0003](0003-commission-agreement-milestone-flow.md) | Multi-Milestone Commission Agreements and Concurrency Locks | Accepted | 2026-02-15 | Commission Agreement | -| [ADR-0004](0004-dispute-resolution-and-arbitration.md) | Autonomous Dispute Arbiter & Cross-Contract Resolution | Accepted | 2026-03-01 | Dispute Arbiter | -| [ADR-0005](0005-platform-fee-and-revenue-distribution.md) | Dynamic Platform Fee Governance and Multi-Party Splits | Accepted | 2026-03-10 | Platform Config / Revenue | -| [ADR-0006](0006-event-driven-architecture.md) | Structured Event Emission for Off-Chain Indexing | Accepted | 2026-03-25 | All Contracts | -| [ADR-0007](0007-storage-data-model-and-ttl-management.md) | Soroban Storage Tiering and TTL Extension Strategy | Accepted | 2026-04-05 | Storage / Lifecycle | +| [ADR-0000 (`0000-template.md`)](0000-template.md) | Standard Architecture Decision Record Template | Accepted | 2026-01-15 | All | +| [ADR-0001 (`0001-soroban-smart-contract-platform.md`)](0001-soroban-smart-contract-platform.md) | Adoption of Stellar Soroban Rust Smart Contract Platform | Accepted | 2026-01-20 | Core / Platform | +| [ADR-0002 (`0002-escrow-architecture-and-state-machine.md`)](0002-escrow-architecture-and-state-machine.md) | Escrow Contract State Machine and CEI Pattern | Accepted | 2026-02-01 | Escrow | +| [ADR-0003 (`0003-commission-agreement-milestone-flow.md`)](0003-commission-agreement-milestone-flow.md) | Multi-Milestone Commission Agreements and Concurrency Locks | Accepted | 2026-02-15 | Commission Agreement | +| [ADR-0004 (`0004-dispute-resolution-and-arbitration.md`)](0004-dispute-resolution-and-arbitration.md) | Autonomous Dispute Arbiter & Cross-Contract Resolution | Accepted | 2026-03-01 | Dispute Arbiter | +| [ADR-0005 (`0005-platform-fee-and-revenue-distribution.md`)](0005-platform-fee-and-revenue-distribution.md) | Dynamic Platform Fee Governance and Multi-Party Splits | Accepted | 2026-03-10 | Platform Config / Revenue | +| [ADR-0006 (`0006-event-driven-architecture.md`)](0006-event-driven-architecture.md) | Structured Event Emission for Off-Chain Indexing | Accepted | 2026-03-25 | All Contracts | +| [ADR-0007 (`0007-storage-data-model-and-ttl-management.md`)](0007-storage-data-model-and-ttl-management.md) | Soroban Storage Tiering and TTL Extension Strategy | Accepted | 2026-04-05 | Storage / Lifecycle | --- diff --git a/docs/API_REFERENCE.md b/docs/API_REFERENCE.md index 7f72208..d2aa4e7 100644 --- a/docs/API_REFERENCE.md +++ b/docs/API_REFERENCE.md @@ -2,7 +2,7 @@ Reference for the public Soroban entry points in the workspace contracts, plus the shared helper modules. Error codes and canonical suggestions for every -value are in [docs/error_codes.md](./error_codes.md). +value are in [the error codes reference (error_codes.md)](./error_codes.md). Conventions: @@ -43,7 +43,7 @@ Conventions: | `get_idempotency_record(admin, caller, key)` | `Option` | | | `extend_idempotency_ttl(admin, caller, key, ledgers)` | `Result<(), EscrowError>` | | -Semantics in [docs/IDEMPOTENCY.md](./IDEMPOTENCY.md). +Semantics in [the idempotency specification (IDEMPOTENCY.md)](./IDEMPOTENCY.md). ### Timeouts (closes #665) @@ -60,7 +60,7 @@ Semantics in [docs/IDEMPOTENCY.md](./IDEMPOTENCY.md). `TimeoutPolicy { timeout_ledgers, max_attempts }`, `CallAttempt { started_ledger, deadline_ledger, attempts, retry_after_ledger }`. Full semantics in -[docs/TIMEOUT_POLICY.md](./TIMEOUT_POLICY.md). +[the timeout policy guide (TIMEOUT_POLICY.md)](./TIMEOUT_POLICY.md). ### Admin / lifecycle / ops @@ -70,8 +70,8 @@ deadline_ledger, attempts, retry_after_ledger }`. Full semantics in `route_to_canary`, `set_rollback_trigger`, `trigger_rollback`, `should_rollback`, `get_rollout_state`; `health_check`, `get_health_metrics`, `get_sla_targets`, `detect_anomaly`, `report_ok`, -`report_error`. See [docs/PAUSE_AND_EMERGENCY.md](./PAUSE_AND_EMERGENCY.md), -[docs/UPGRADE.md](./UPGRADE.md), [docs/SLA.md](./SLA.md). +`report_error`. See [the pause and emergency runbook (PAUSE_AND_EMERGENCY.md)](./PAUSE_AND_EMERGENCY.md), +[the upgrade procedures (UPGRADE.md)](./UPGRADE.md), [the SLA definitions (SLA.md)](./SLA.md). ## contracts/platform_config @@ -93,7 +93,7 @@ deadline_ledger, attempts, retry_after_ledger }`. Full semantics in | `is_promotion_active()` | `bool` | `Error` codes: `InvalidTier=6`, `InvalidPromotion=7`, `InvalidReferralBps=8`, -`PromotionNotActive=9`. Fee math details in [docs/FEES.md](./FEES.md). +`PromotionNotActive=9`. Fee math details in [the fee calculation documentation (FEES.md)](./FEES.md). ### Token metadata / admin @@ -149,6 +149,6 @@ Run the crate doc-tests for interactive copies: `cargo test --doc -p shared`. ## Error codes Numeric code → cause → suggestion handle mapping is defined once in -`contracts/*/src/errors.rs` and documented in [docs/error_codes.md](./error_codes.md). +`contracts/*/src/errors.rs` and documented in [the error codes reference (error_codes.md)](./error_codes.md). Every contract exposes `get_suggestion(code)` and a unit test asserting each code's Display + suggestion. \ No newline at end of file diff --git a/docs/COMMUNICATION_TEMPLATES.md b/docs/COMMUNICATION_TEMPLATES.md index 19a0944..a3a9c6b 100644 --- a/docs/COMMUNICATION_TEMPLATES.md +++ b/docs/COMMUNICATION_TEMPLATES.md @@ -4,7 +4,7 @@ Do **not** include secret keys, unreleased WASM hashes that embed secrets, or individual user balances. Post to the status page, Discord `#status`, and email `ops@` / `users@` as applicable. -Run these inside a [maintenance window](./MAINTENANCE_WINDOWS.md). +Run these inside a [maintenance window (MAINTENANCE_WINDOWS.md)](./MAINTENANCE_WINDOWS.md). ## Scheduled maintenance (T–72h / T–48h / T–24h) diff --git a/docs/COMPREHENSIVE_API_DOCS.md b/docs/COMPREHENSIVE_API_DOCS.md index c6d86fe..6e58bd2 100644 --- a/docs/COMPREHENSIVE_API_DOCS.md +++ b/docs/COMPREHENSIVE_API_DOCS.md @@ -59,8 +59,8 @@ contracts/ └── mentorship/ # Mentorship program contract (NEW — #613) ``` -See [docs/architecture.md](./architecture.md) and the individual ADRs under -[docs/ADRs/](./ADRs/) for design rationale. +See [the architecture guide (architecture.md)](./architecture.md) and the individual ADRs under +[the Architecture Decision Records index (docs/ADRs/)](./ADRs/) for design rationale. --- @@ -91,7 +91,7 @@ cargo test --workspace ./scripts/deploy_testnet.sh ``` -See [docs/DEPLOY.md](./DEPLOY.md) for full deployment instructions. +See [the deployment runbook (DEPLOY.md)](./DEPLOY.md) for full deployment instructions. --- @@ -520,7 +520,7 @@ pub struct FeeBreakdown { | 10 | `AlreadyReviewed` | reputation | Reviewer already submitted | One review per commission | | 11 | `InvalidRating` | reputation | Rating outside 1–5 | Pass a value between 1 and 5 | -Full error code documentation: [docs/error_codes.md](./error_codes.md). +Full error code documentation: [the error codes reference (error_codes.md)](./error_codes.md). --- @@ -629,7 +629,7 @@ The `rating` parameter must be an integer between 1 and 5 inclusive. ### Contract paused If a contract is in the paused state, all mutating transactions will fail. -Only the admin may call `unpause`. See [docs/PAUSE_AND_EMERGENCY.md](./PAUSE_AND_EMERGENCY.md). +Only the admin may call `unpause`. See [the pause and emergency runbook (PAUSE_AND_EMERGENCY.md)](./PAUSE_AND_EMERGENCY.md). --- @@ -641,4 +641,4 @@ Only the admin may call `unpause`. See [docs/PAUSE_AND_EMERGENCY.md](./PAUSE_AN - Usage and certification events are immutable once emitted; build audit pipelines on top of event streams. - For the full threat model and audit checklist see - [docs/SECURITY_REVIEW_CHECKLIST.md](./SECURITY_REVIEW_CHECKLIST.md). + [the security review checklist (SECURITY_REVIEW_CHECKLIST.md)](./SECURITY_REVIEW_CHECKLIST.md). diff --git a/docs/CONTRACTS.md b/docs/CONTRACTS.md index aa0339f..c3e3ca4 100644 --- a/docs/CONTRACTS.md +++ b/docs/CONTRACTS.md @@ -819,7 +819,7 @@ Topics are listed as `[contract address, …]`, since the contract address is al ### dispute_arbiter -> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)" +> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004 (0004-dispute-resolution-and-arbitration.md)](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)" Source: `contracts/dispute_arbiter/` @@ -1487,7 +1487,7 @@ Each shape is emitted from exactly one site; there are no repeats. This crate pu ### platform_config -> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4) +> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005 (0005-platform-fee-and-revenue-distribution.md)](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4) Source: `contracts/platform_config/` diff --git a/docs/DEVELOPER_ENVIRONMENT.md b/docs/DEVELOPER_ENVIRONMENT.md index 63829b5..abc8cfc 100644 --- a/docs/DEVELOPER_ENVIRONMENT.md +++ b/docs/DEVELOPER_ENVIRONMENT.md @@ -9,12 +9,12 @@ Before you begin, ensure you have the following software installed on your syste ### Required Software | Software | Version | Description | Installation Link | |----------|---------|-------------|-------------------| -| Rust | 1.75+ | Primary language for smart contract development | https://www.rust-lang.org/tools/install | -| Soroban CLI | Latest | Stellar's smart contract development toolkit | https://developers.stellar.org/docs/build/sdks-and-tools/soroban-cli | -| Node.js | 18.x+ | For TypeScript SDK and frontend development | https://nodejs.org/ | -| Git | 2.40+ | Version control | https://git-scm.com/downloads | -| Docker | 24.x+ | For local testing and containerized services | https://www.docker.com/get-started/ | -| VS Code | Latest | Recommended IDE with Rust/Soroban extensions | https://code.visualstudio.com/ | +| Rust | 1.75+ | Primary language for smart contract development | [Rust installation guide](https://www.rust-lang.org/tools/install) | +| Soroban CLI | Latest | Stellar's smart contract development toolkit | [Soroban CLI setup guide](https://developers.stellar.org/docs/build/sdks-and-tools/soroban-cli) | +| Node.js | 18.x+ | For TypeScript SDK and frontend development | [Node.js download page](https://nodejs.org/) | +| Git | 2.40+ | Version control | [Git download page](https://git-scm.com/downloads) | +| Docker | 24.x+ | For local testing and containerized services | [Docker get started guide](https://www.docker.com/get-started/) | +| VS Code | Latest | Recommended IDE with Rust/Soroban extensions | [Visual Studio Code download](https://code.visualstudio.com/) | ### System Requirements - **Operating System**: Windows 10+, macOS 13+, or Linux (Ubuntu 20.04+) @@ -255,6 +255,6 @@ If you encounter issues not listed here: ## Additional Resources - [Stellar Developer Documentation](https://developers.stellar.org/) -- [Soroban Documentation](https://developers.stellar.org/docs/build/smart-contracts/overview) -- [StellarAid Architecture Guide](architecture.md) -- [Deployment Configuration Guide](DEPLOYMENT_CONFIGURATION.md) \ No newline at end of file +- [Soroban smart contracts overview](https://developers.stellar.org/docs/build/smart-contracts/overview) +- [StellarAid Architecture Guide (architecture.md)](architecture.md) +- [Deployment Configuration Guide (DEPLOYMENT_CONFIGURATION.md)](DEPLOYMENT_CONFIGURATION.md) diff --git a/docs/OPERATIONAL_RUNBOOK.md b/docs/OPERATIONAL_RUNBOOK.md index 00db0a2..b50a4a4 100644 --- a/docs/OPERATIONAL_RUNBOOK.md +++ b/docs/OPERATIONAL_RUNBOOK.md @@ -96,7 +96,7 @@ Key metrics to monitor: ### Maintenance windows Planned pauses and upgrades run inside the windows defined in -[docs/MAINTENANCE_WINDOWS.md](../docs/MAINTENANCE_WINDOWS.md) (Tuesday / +[the maintenance windows guide (MAINTENANCE_WINDOWS.md)](../docs/MAINTENANCE_WINDOWS.md) (Tuesday / Thursday 02:00–04:00 UTC, plus emergency). Follow that document for pause order, state backup, upgrade timeline, and communication templates. diff --git a/docs/QUERY_OPTIMIZATION.md b/docs/QUERY_OPTIMIZATION.md index 93f88b2..206eda9 100644 --- a/docs/QUERY_OPTIMIZATION.md +++ b/docs/QUERY_OPTIMIZATION.md @@ -2,7 +2,7 @@ > Closes **#650** — implement query optimization. > -> Related: [STORAGE.md](./STORAGE.md), [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md), [RETENTION_AND_PRUNING.md](./RETENTION_AND_PRUNING.md). +> Related: [STORAGE.md](./STORAGE.md), [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md), [RETENTION_AND_PRUNING.md](./RETENTION_AND_PRUNING.md). --- @@ -146,7 +146,7 @@ benchmark. `temporary()` one. It is cleared on both the success and error paths, and a panic reverts the whole transaction, so it is correct — but `temporary()` storage would be the cheaper primitive for a mutex (see - [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md), which + [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md), which classes mutex locks as temporary). Worth revisiting; not changed here. - `extend_escrow_ttl` is called on write and on dispute, with the dispute TTL configurable. The retention behaviour is deliberate and is documented in @@ -183,7 +183,7 @@ benchmark. contract entry point and cannot be added cheaply: it would need a second storage key per record, written and pruned in lockstep, doubling the write cost of the hottest money-moving path in the workspace. **If such a query is - needed, build it off-chain from events** ([ADR-0006](./ADRs/0006-event-driven-architecture.md)), + needed, build it off-chain from events** ([ADR-0006 (0006-event-driven-architecture.md)](./ADRs/0006-event-driven-architecture.md)), which is what the correlation events in [CONTRACTS.md](./CONTRACTS.md) are for. - Nothing in the workspace scans a persistent keyspace on-chain. That is a diff --git a/docs/RETENTION_AND_PRUNING.md b/docs/RETENTION_AND_PRUNING.md index 79949cb..c0fa1d4 100644 --- a/docs/RETENTION_AND_PRUNING.md +++ b/docs/RETENTION_AND_PRUNING.md @@ -3,7 +3,7 @@ > Closes **#651** — add contract state pruning strategy. > > Related: [STORAGE.md](./STORAGE.md), -> [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md), +> [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md), > [QUERY_OPTIMIZATION.md](./QUERY_OPTIMIZATION.md), > [OPERATIONAL_RUNBOOK.md](./OPERATIONAL_RUNBOOK.md), > [EMERGENCY_PROCEDURES.md](./EMERGENCY_PROCEDURES.md). diff --git a/docs/SECURITY_REVIEW_CHECKLIST.md b/docs/SECURITY_REVIEW_CHECKLIST.md index a66331f..2392d92 100644 --- a/docs/SECURITY_REVIEW_CHECKLIST.md +++ b/docs/SECURITY_REVIEW_CHECKLIST.md @@ -162,8 +162,8 @@ The following items must be complete before engaging an external auditor: - [x] This checklist reviewed and signed off by the team lead - [x] Dependency tree audited with `cargo audit` — no critical CVEs - [x] Deployment scripts reviewed for secret exposure -- [x] Architecture diagrams up to date ([docs/architecture.md](./architecture.md)) -- [x] ADRs written for non-obvious design decisions ([docs/ADRs/](./ADRs/)) +- [x] Architecture diagrams up to date ([the architecture guide (architecture.md)](./architecture.md)) +- [x] ADRs written for non-obvious design decisions ([the Architecture Decision Records index (docs/ADRs/)](./ADRs/)) - [ ] Formal verification scope agreed with auditor (in progress) - [ ] Bug-bounty programme scope defined (planned for Phase 2) diff --git a/docs/STORAGE.md b/docs/STORAGE.md index dd20792..76f3cec 100644 --- a/docs/STORAGE.md +++ b/docs/STORAGE.md @@ -11,7 +11,7 @@ Per-contract storage layout and TTL policy for every crate in the workspace. > storage-layout observations behind it. > - **Interfaces, events and errors:** [CONTRACTS.md](./CONTRACTS.md). > - **Dependency supply chain:** §9 of this document. -> - **Design rationale:** [ADR-0007](./ADRs/0007-storage-data-model-and-ttl-management.md). +> - **Design rationale:** [ADR-0007 (0007-storage-data-model-and-ttl-management.md)](./ADRs/0007-storage-data-model-and-ttl-management.md). ## How to read this @@ -375,7 +375,7 @@ No other ledger-denominated constants exist. `voting_period` and `timelock_ledge ### dispute_arbiter -> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)" +> "Dispute Arbiter Smart Contract — Autonomous arbitration and dispute settlement for StellarAid escrows. Architecture Decision: [ADR-0004 (0004-dispute-resolution-and-arbitration.md)](../../docs/ADRs/0004-dispute-resolution-and-arbitration.md)" Source: `contracts/dispute_arbiter/` @@ -666,7 +666,7 @@ The crate declares no ledger-denominated constant at all. The `3000` (30% max ro ### platform_config -> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4) +> "Platform Configuration Contract — Protocol-wide parameters, fee governance, and admin authority delegation. Architecture Decision: [ADR-0005 (0005-platform-fee-and-revenue-distribution.md)](../../docs/ADRs/0005-platform-fee-and-revenue-distribution.md)" (`//!` doc comment, contracts/platform_config/src/lib.rs:1-4) Source: `contracts/platform_config/` diff --git a/docs/TOKEN_SETUP.md b/docs/TOKEN_SETUP.md index 3d7b1d3..2439db0 100644 --- a/docs/TOKEN_SETUP.md +++ b/docs/TOKEN_SETUP.md @@ -21,4 +21,4 @@ cargo run --bin worker -- setup-token - Asset Code: `AID` - Network: Testnet (default), Mainnet -- Horizon: https://horizon-testnet.stellar.org +- Horizon: [Stellar Testnet Horizon API (`https://horizon-testnet.stellar.org`)](https://horizon-testnet.stellar.org) diff --git a/docs/UPGRADE_AND_ROLLBACK.md b/docs/UPGRADE_AND_ROLLBACK.md index 1156320..2a82bf4 100644 --- a/docs/UPGRADE_AND_ROLLBACK.md +++ b/docs/UPGRADE_AND_ROLLBACK.md @@ -4,7 +4,7 @@ This document describes the safe process for upgrading Soroban contracts and rol > **Closes #595** — Backward compatibility strategy for upgrades with state migration functions and upgrade safety checks. -Version numbers, compatibility rules, and `get_version` querying are defined in [VERSIONING.md](./VERSIONING.md). Run upgrades inside a [maintenance window](./MAINTENANCE_WINDOWS.md). +Version numbers, compatibility rules, and `get_version` querying are defined in [VERSIONING.md](./VERSIONING.md). Run upgrades inside a [maintenance window (MAINTENANCE_WINDOWS.md)](./MAINTENANCE_WINDOWS.md). ## Upgrade Safety Architecture diff --git a/docs/error_codes.md b/docs/error_codes.md index b608024..167f572 100644 --- a/docs/error_codes.md +++ b/docs/error_codes.md @@ -108,8 +108,8 @@ enum yet or not: Both are raised **before** the state change they protect, so a rejected call leaves nothing behind. See -[the balance module](../contracts/campaign/src/balance.rs) and -[the sanitization module](../contracts/campaign/src/sanitize.rs). +[the balance module (`balance.rs`)](../contracts/campaign/src/balance.rs) and +[the sanitization module (`sanitize.rs`)](../contracts/campaign/src/sanitize.rs). ## New codes diff --git a/docs/videos/README.md b/docs/videos/README.md index 85464b2..d529880 100644 --- a/docs/videos/README.md +++ b/docs/videos/README.md @@ -10,9 +10,9 @@ These walkthroughs provide in-depth code reviews, architecture diagrams, runtime | Episode | Title | Target Contract | Duration | Focus Area | Companion Guide | |---------|-------|-----------------|----------|------------|-----------------| -| **01** | **Escrow Contract & CEI Pattern** | `contracts/escrow` | 18:45 | Locking, Payouts, Refunds, Mutex Guards | [View Guide](escrow-contract-walkthrough.md) | -| **02** | **Commission Lifecycle & Milestones** | `contracts/commission_agreement` | 21:30 | Multi-Milestone State Machine, Agency Roster, Pro-rata Payouts | [View Guide](commission-flow-walkthrough.md) | -| **03** | **Dispute Resolution & Auto-Arbitration** | `contracts/dispute_arbiter` | 16:15 | Cross-Contract Calls, Timelock Fallback, Split Calculations | [View Guide](dispute-resolution-walkthrough.md) | +| **01** | **Escrow Contract & CEI Pattern** | `contracts/escrow` | 18:45 | Locking, Payouts, Refunds, Mutex Guards | [`escrow-contract-walkthrough.md`](escrow-contract-walkthrough.md) | +| **02** | **Commission Lifecycle & Milestones** | `contracts/commission_agreement` | 21:30 | Multi-Milestone State Machine, Agency Roster, Pro-rata Payouts | [`commission-flow-walkthrough.md`](commission-flow-walkthrough.md) | +| **03** | **Dispute Resolution & Auto-Arbitration** | `contracts/dispute_arbiter` | 16:15 | Cross-Contract Calls, Timelock Fallback, Split Calculations | [`dispute-resolution-walkthrough.md`](dispute-resolution-walkthrough.md) | --- diff --git a/examples/README.md b/examples/README.md index 3802337..487cc0b 100644 --- a/examples/README.md +++ b/examples/README.md @@ -17,12 +17,12 @@ cargo run --bin read_health | Binary | Demonstrates | |---|---| -| [`deploy_contract`](src/bin/deploy_contract.rs) | Deploying a contract — building a `CreateContract` host function, simulating the deployment, and validating the WASM is accepted. | -| [`invoke_function`](src/bin/invoke_function.rs) | Invoking any function — generic `InvokeHostFunction` construction with typed `ScVal` arguments (`address:`, `u64:`, `i128:`, `symbol:`, `string:`). | -| [`campaign_donation`](src/bin/campaign_donation.rs) | Using the SDK's own donation builder (`sdk::transaction_builder`) — the exact code path the worker uses. | -| [`token_transfer`](src/bin/token_transfer.rs) | Building Stellar Asset Contract calls (`transfer`/`balanceOf`) with correct `i128` amount and `Address` encoding. | -| [`listen_for_events`](src/bin/listen_for_events.rs) | Listening for events — polling `getTransactionStatus` to terminal state, the pattern the worker uses instead of long-lived subscriptions. | -| [`read_health`](src/bin/read_health.rs) | Read-only access — RPC health and Horizon account sequencing with no signing. | +| [`deploy_contract.rs`](src/bin/deploy_contract.rs) | Deploying a contract — building a `CreateContract` host function, simulating the deployment, and validating the WASM is accepted. | +| [`invoke_function.rs`](src/bin/invoke_function.rs) | Invoking any function — generic `InvokeHostFunction` construction with typed `ScVal` arguments (`address:`, `u64:`, `i128:`, `symbol:`, `string:`). | +| [`campaign_donation.rs`](src/bin/campaign_donation.rs) | Using the SDK's own donation builder (`sdk::transaction_builder`) — the exact code path the worker uses. | +| [`token_transfer.rs`](src/bin/token_transfer.rs) | Building Stellar Asset Contract calls (`transfer`/`balanceOf`) with correct `i128` amount and `Address` encoding. | +| [`listen_for_events.rs`](src/bin/listen_for_events.rs) | Listening for events — polling `getTransactionStatus` to terminal state, the pattern the worker uses instead of long-lived subscriptions. | +| [`read_health.rs`](src/bin/read_health.rs) | Read-only access — RPC health and Horizon account sequencing with no signing. | ## Requirements