diff --git a/src/App.tsx b/src/App.tsx index f686df5..94caf10 100644 --- a/src/App.tsx +++ b/src/App.tsx @@ -260,15 +260,14 @@ export default function App() { const [coverageGuideOpen, setCoverageGuideOpen] = useState(false); const [auditGuideOpen, setAuditGuideOpen] = useState(false); const [checkedPrerequisites, setCheckedPrerequisites] = useState>({}); + const [installFaqOpen, setInstallFaqOpen] = useState(false); + const [auditWarningsGuideOpen, setAuditWarningsGuideOpen] = useState(false); + const [limitsInterpretationGuideOpen, setLimitsInterpretationGuideOpen] = useState(false); + const [multiContractExamplesOpen, setMultiContractExamplesOpen] = useState(false); const comparePanelRef = useRef(null); - const [showBackToTop, setShowBackToTop] = useState(false); - const [categoryFilter, setCategoryFilter] = useState(null); - const [selectedModule, setSelectedModule] = useState(null); // #117 — mobile nav toggle const [mobileMenuOpen, setMobileMenuOpen] = useState(false); const mobileMenuRef = useRef(null); - // #118 — module table of contents - const [tocOpen, setTocOpen] = useState(false); // #116 — accessibility statement modal const [a11yOpen, setA11yOpen] = useState(false); const [activeSection, setActiveSection] = useActiveSection(navSectionIds); @@ -1408,6 +1407,317 @@ export default function App() { )} +
+
+

Guide: Resolving audit warnings

+ +
+ {auditWarningsGuideOpen && ( +
+

+ Common audit warnings fall into three categories: authentication, arithmetic safety, and TTL management. + Each category has specific resolution patterns. +

+

Authentication warnings

+
    +
  • Missing require_auth: Add explicit authorization checks before state-changing operations. Use address.require_auth() to verify caller identity.
    • +
  • Unchecked caller privilege: Validate that the authenticated caller has permission for the requested action using role checks or ownership verification.
    • +
  • Authorization bypass: Ensure all entry points that modify contract state include proper authentication gates before execution.
    • +
+

Arithmetic safety warnings

+
    +
  • Potential overflow: Use checked arithmetic operations or validate input ranges. Replace a + b with a.checked_add(b) for critical calculations.
    • +
  • Division by zero: Add explicit zero checks before division operations. Return early or panic with clear error messages.
    • +
  • Underflow risk: Validate that subtraction operands maintain proper ordering. Use checked_sub for balance calculations.
    • +
+

TTL and storage warnings

+
    +
  • Missing TTL extension: Call env.storage().instance().extend_ttl() before reading persistent data to prevent expiry-related failures.
    • +
  • Unbounded storage growth: Implement cleanup logic or periodic archival for collections that grow indefinitely. Consider pagination for large datasets.
    • +
  • Persistent key without extension: Always extend TTL when reading critical state. Treat persistent storage as requiring active maintenance.
    • +
+

+ After addressing warnings, re-run the audit with --strict to confirm all issues are resolved. Add regression tests for each fixed warning. +

+
+ )} +
+ +
+
+

Guide: Interpreting resource limit results

+ +
+ {limitsInterpretationGuideOpen && ( +
+

+ The soroban-testkit limits command ramps a contract input parameter until execution hits resource boundaries. Understanding the output helps you design scalable contracts. +

+

Reading the results

+
    +
  • Last successful count: The highest parameter value that completed without exceeding limits. This represents your practical ceiling for production.
    • +
  • Instruction count: Total WASM instructions executed. Stellar contracts have a per-invocation instruction budget; staying well below prevents timeout failures.
    • +
  • Memory usage: Peak memory allocated during execution. High memory usage may indicate inefficient data structures or unnecessary copying.
    • +
  • Failed ramp value: The first parameter value that exceeded limits. This boundary helps you understand where optimization becomes critical.
    • +
+

Common patterns and what they mean

+
+
Linear scaling with flat memory
+
Indicates efficient iteration without extra allocations. This is ideal for batch operations like token transfers.
+ +
Exponential instruction growth
+
Suggests nested loops or recursive patterns. Consider flattening algorithms or batching work across multiple transactions.
+ +
Sharp memory increase at boundary
+
Points to collection pre-allocation hitting capacity thresholds. Review vector sizing and consider streaming patterns.
+ +
Early instruction ceiling with low memory
+
Indicates computation-heavy logic. Look for redundant calculations, expensive cryptographic operations, or unoptimized sorting.
+ +
Memory ceiling before instruction limit
+
Signals data structure overhead. Consider using maps instead of vectors for lookups, or splitting large structures across storage keys.
+
+

Optimization strategies

+
    +
  • Batch size tuning: Use limits results to set safe default batch sizes in your contract API. Document maximum supported values.
    • +
  • Pagination: If limits are too restrictive, split operations across multiple contract calls with cursor-based continuation.
    • +
  • Data structure choice: High memory usage suggests switching from vectors to iterators, or using compact representations.
    • +
  • Algorithm complexity: Exponential growth indicates the need for more efficient algorithms. Profile and refactor hot paths.
    • +
+

+ Run limits tests after each optimization to quantify improvements. Track metrics over time to detect performance regressions. +

+
+ )} +
+ +
+
+

FAQ: Common CLI installation errors

+ +
+ {installFaqOpen && ( +
+

cargo install fails with "failed to compile"

+

Cause: Outdated Rust toolchain or missing system dependencies.

+

Solution:

+
    +
  1. Update Rust to the latest stable version: rustup update stable
    2. +
  2. Ensure you have build essentials: sudo apt install build-essential (Linux) or install Xcode Command Line Tools (macOS)
    3. +
  3. Try installing with --locked flag: cargo install soroban-testkit-cli --locked
    4. +
+ +

wasm32v1-none target not found

+

Cause: The WebAssembly compilation target isn't installed for your Rust toolchain.

+

Solution:

+
    +
  1. Add the target explicitly: rustup target add wasm32v1-none
    2. +
  2. Verify installation: rustup target list | grep wasm32v1
    3. +
  3. If the target doesn't exist, update Rust: rustup update (requires Rust 1.84+)
    4. +
+ +

soroban-testkit: command not found

+

Cause: Cargo's bin directory isn't in your shell PATH.

+

Solution:

+
    +
  1. Add Cargo bin to PATH. For bash/zsh, add to ~/.bashrc or ~/.zshrc: export PATH="$HOME/.cargo/bin:$PATH"
    2. +
  2. Reload your shell: source ~/.bashrc or open a new terminal
    3. +
  3. Verify: which soroban-testkit should show the binary path
    4. +
+ +

cargo-llvm-cov: not found when running coverage

+

Cause: The LLVM coverage tool isn't installed.

+

Solution:

+
    +
  1. Install the tool: cargo install cargo-llvm-cov
    2. +
  2. Verify: cargo llvm-cov --version
    3. +
  3. If you only need limits or audit, you can skip this installation
    4. +
+ +

Permission denied errors during installation

+

Cause: Insufficient permissions for the cargo install directory.

+

Solution:

+
    +
  1. Never use sudo with cargo install. This breaks Rust's user-local installation model.
    2. +
  2. Ensure ~/.cargo is owned by your user: ls -la ~/.cargo
    3. +
  3. If ownership is wrong, reclaim it: sudo chown -R $USER:$USER ~/.cargo
    4. +
+ +

OpenSSL or pkg-config errors on Linux

+

Cause: Missing system libraries required for compiling dependencies.

+

Solution:

+
    +
  1. Ubuntu/Debian: sudo apt install pkg-config libssl-dev
    2. +
  2. Fedora/RHEL: sudo dnf install pkg-config openssl-devel
    3. +
  3. Arch: sudo pacman -S pkg-config openssl
    4. +
+ +

stellar-cli installation fails

+

Cause: Network issues or crates.io being temporarily unavailable.

+

Solution:

+
    +
  1. Retry with verbose output: cargo install stellar-cli -v
    2. +
  2. Check network connectivity and proxy settings
    3. +
  3. Try an alternative mirror if available in your region
    4. +
  4. Install a specific version: cargo install stellar-cli --version 22.0.0
    5. +
+ +

+ Still stuck? Check the full installation guide or open an issue on the core repository. +

+
+ )} +
+ +
+
+

Examples: Projects with multiple contracts

+ +
+ {multiContractExamplesOpen && ( +
+

+ Soroban projects often contain multiple contracts in a Cargo workspace. Each workflow supports this pattern with specific conventions. +

+ +

Workspace structure

+ 
+                {`project-root/
+├── Cargo.toml          # Workspace manifest
+├── contracts/
+│   ├── token/
+│   │   ├── Cargo.toml
+│   │   └── src/lib.rs
+│   ├── escrow/
+│   │   ├── Cargo.toml
+│   │   └── src/lib.rs
+│   └── auction/
+│       ├── Cargo.toml
+│       └── src/lib.rs
+└── tests/
+    └── integration_tests.rs`}
+
+ +

Coverage: Test all contracts together

+

Run coverage from the workspace root to include all contract crates:

+ 
+                soroban-testkit coverage . --format html --open
+
+

+ The workspace-aware coverage report aggregates results across all members. Each contract's test coverage appears in the unified HTML output. +

+ +

Coverage: Single contract in workspace

+

Target a specific contract by providing its subdirectory:

+ 
+                soroban-testkit coverage contracts/escrow --format html
+
+

This isolates coverage to just the escrow contract and its tests, ignoring sibling contracts.

+ +

Audit: Workspace-wide scan

+

Audit all contract sources from the workspace root:

+ 
+                soroban-testkit audit contracts --strict
+
+

The scanner recursively processes all .rs files under contracts/, reporting findings across every contract.

+ +

Audit: Per-contract scanning

+

Focus the audit on a single contract's source directory:

+ 
+                soroban-testkit audit contracts/token/src
+
+

This scans only the token contract, useful for incremental security reviews.

+ +

Limits: Testing each contract separately

+

Each contract compiles to its own WASM artifact. Test limits for the auction contract:

+ 
+                {`soroban-testkit limits \\
+  --contract target/wasm32v1-none/release/auction.wasm \\
+  --fn place_bid \\
+  --ramp bidders`}
+
+

Repeat for each contract, adjusting the --contract path, --fn, and --ramp parameters.

+ +

Limits: Batch testing script

+

Automate limits testing across multiple contracts with a shell script:

+ 
+                {`#!/bin/bash
+for contract in token escrow auction; do
+  echo "Testing $contract..."
+  soroban-testkit limits \\
+    --contract target/wasm32v1-none/release/$contract.wasm \\
+    --fn execute \\
+    --ramp items
+done`}
+
+ +

Build optimization for workspaces

+

When working with multiple contracts, build them all at once to share dependencies:

+ 
+                {`cargo build --release --target wasm32v1-none --workspace`}
+
+

+ This ensures all contracts are up-to-date before running limits tests or deploying. +

+ +

Cargo.toml workspace configuration

+

Define workspace members in the root Cargo.toml:

+ 
+                {`[workspace]
+members = [
+  "contracts/token",
+  "contracts/escrow",
+  "contracts/auction",
+]
+resolver = "2"
+
+[workspace.dependencies]
+soroban-sdk = "27.0.0"
+soroban-testkit = "0.2.0"`}
+
+

+ Individual contract Cargo.toml files inherit shared dependencies using workspace = true. +

+ +

+ All three workflows (coverage, audit, limits) respect Cargo workspace conventions. Point the CLI at the workspace root for aggregate analysis or at specific subdirectories for focused testing. +

+
+ )} +
+