Skip to content

DOCUMENTATION_INDEX.md

Latest commit

 

History

History
568 lines (402 loc) · 20.1 KB

DOCUMENTATION_INDEX.md

File metadata and controls

568 lines (402 loc) · 20.1 KB
Raw

📑 Deployment Automation Documentation Index

Quick navigation for all deployment automation documentation.

🚀 Getting Started (Start Here!)

For Beginners

  1. QUICK_START.md - 5-minute setup guide

    • Minimal setup
    • Deploy your first contract
    • Verify success

  2. GETTING_STARTED.md - Complete onboarding

    • Checklist for setup
    • Common commands
    • Success criteria

For Decision Makers

Contributor & Community Policies

📚 Comprehensive Guides

Main Deployment Guide

SOROBAN_DEPLOYMENT.md - Complete deployment documentation

  • Overview of the system
  • Prerequisites and setup
  • Environment configuration
  • Local deployment instructions
  • CI/CD pipeline overview
  • Continuous validation details
  • Troubleshooting guide
  • Deployment verification
  • Performance optimization
  • Best practices

CI/CD Setup

docs/ci-cd-setup.md - GitHub Actions configuration

  • Step-by-step CI/CD setup
  • GitHub Secrets configuration
  • Workflow triggers
  • Deployment verification
  • Branch protection rules
  • Monitoring and notifications
  • Troubleshooting
  • Best practices for production

Contracts Fuzz Harness CI

docs/contracts-fuzz.md - Fuzz harness coverage

  • Bolero in-process property tests (every PR)
  • cargo-fuzz / cargo-bolero coverage-guided harness (nightly)
  • Cross-contract message wire format stability
  • Local reproduction recipes

Technical Architecture

ARCHITECTURE.md - System design and components

  • Component overview
  • Data flow diagrams
  • Deployment flow
  • Secret management
  • State management
  • Metrics collection
  • Deployment lifecycle

🛠️ Component Documentation

sanctifier-core: Parser + Contract Discovery

tooling/sanctifier-core/src/parser.rs — shared source parsing with input validation

  • parse_source(source: &str) -> Result<ParsedSource, ParseError> — single canonical entry point for all rules
  • Runs all guards from input_validation (size, null bytes) before any AST work
  • Returns ParseError::Validation or ParseError::Syntax on failure

tooling/sanctifier-core/src/contract_discovery.rs — Soroban contract discovery

  • discover_contracts(file: &syn::File) -> Vec<DiscoveredContract> — maps #[contract] structs to their #[contractimpl] blocks
  • Collects public functions per contract and #[contracttype] storage types
  • DiscoveredFunction.is_reserved flags __constructor / __check_auth entry-points
  • DiscoveredContract::public_functions() iterator excludes reserved entry-points
  • Unit tests in each module; integration tests in tests/parser_contract_discovery_test.rs
  • Fixtures: tests/fixtures/minimal_contract.rs, multi_contract.rs, contract_with_storage_types.rs

Contract ABI / Interface Reference

docs/contract-interfaces.md - Public ABI for all contracts in contracts/*

  • Function signatures and descriptions for every contract
  • Error code tables
  • Machine-readable JSON at docs/generated/contract-interfaces.json
  • Regenerate with make contract-docs; CI enforces freshness via make contract-docs-check

Contract Security Disclaimers

docs/contract-security-disclaimers.md - Security disclaimer framework for contracts

  • Security level classification (Critical, High, Medium, Low)
  • Disclaimer categories (Audit, Usage, Upgrade, Emergency)
  • Implementation guide and usage examples
  • Testing and validation procedures
  • Security best practices and monitoring
  • Integration examples for contract developers

Live Testnet Status Widget

LIVE_TESTNET.md — deployed contract addresses and on-chain verification

Runtime Guard Wrapper Contract

contracts/runtime-guard-wrapper/README.md

  • Contract architecture
  • Public functions
  • Internal guards
  • Storage layout
  • Configuration
  • Events
  • Testing
  • Deployment
  • Performance
  • Security considerations
  • Integration examples
  • Troubleshooting

VS Code Extension

Location: vscode-extension/

  • API stability — activate() returns a typed SanctifierExtensionApi (version, getFindings(uri)) that other extensions can consume via vscode.extensions.getExtension(...).exports
  • sanctifier.minSeverity — filter in-editor diagnostics to error, warning (default), or information
  • sanctifier.toggleEnable — toggle the extension on/off from the command palette or status bar click
  • sanctifier.showOutput — reveal the persistent output channel
  • sanctifier.analyzeWorkspace — run the CLI and stream results to the output channel (respects minSeverity)
  • Status bar item shows live finding count; click to toggle

Sanctifier CLI Deploy Command

Location: tooling/sanctifier-cli/src/commands/deploy.rs

  • Integrated into sanctifier CLI
  • Single-command deployment
  • Automatic validation

Rule Authoring Guide

docs/rule-authoring-guide.md

  • Rule anatomy and matcher types
  • Built-in rules (S001–S012) overview
  • Custom rule authoring (TOML inline + YAML files)
  • .sanctify.toml configuration reference
  • Testing fixtures and CI validation
  • Severity guidelines and output stability
  • Contribution checklist for rule PRs

Finding Code Documentation

docs/rules/s003-arithmetic-overflow.md - S003: Arithmetic Overflow / Underflow Detection

  • Unchecked arithmetic operation detection (+, -, *, /, %, compound assignments)
  • Custom math method detection (mul_div, fixed_point_*)
  • Test code and index expression exclusions
  • Comprehensive remediation guidance with checked/saturating alternatives
  • Deduplication strategy and output formats
  • Known limitations and configuration options

docs/rules/s001-auth-gap.md - S001: Missing Authorization Guard (auth_gap)

  • What constitutes a privileged operation (storage mutation, external call)
  • Vulnerable vs fixed code examples
  • Input validation behaviour (null bytes, oversized source)
  • Auto-fix notes and suppression guidance

docs/rules/s012-sep41-interface.md - S012: SEP-41 Token Interface Compliance

  • Complete SEP-41 standard interface verification
  • All 10 required function signatures
  • Authorization pattern checking
  • Issue types: MissingFunction, SignatureMismatch, AuthorizationMismatch
  • Examples and remediation guidance
  • Reference implementations and test coverage

Rule Engine Orchestration — Integration/E2E Coverage

specs/rule-engine-behavior.md

  • Formal specification: discovery order, filtering, deduplication, exit codes
  • Integration/e2e test suite: tooling/sanctifier-core/tests/rule_engine_orchestration_test.rs
    • Registry population and deduplication
    • Per-rule firing and run_all consistency
    • Determinism across repeated calls
    • Custom regex rule execution
    • Registry extensibility without breaking existing rules
    • End-to-end multi-file scan pipeline
    • Output format (RuleViolation) JSON stability
  • CI job: rule-engine-e2e in .github/workflows/rust.yml

Z3 Backend Invariants (S011) — Module Boundaries

Finding code: S011 — see docs/error-codes.md

Module layout (tooling/sanctifier-core/src/smt/):

Sub-module File Responsibility
types src/smt/types.rs All shared data types and error enums
invariants src/smt/invariants.rs #[invariant] AST parsing + Z3 verification
backend src/smt/backend.rs SmtVerifier, fixed-point proof dispatch
benchmark src/smt/benchmark.rs Latency micro-benchmark for CI artifact
mod src/smt/mod.rs Public re-export facade (zero breaking surface)

WASM Module Versioning & Input Validation

docs/wasm-versioning-alignment.md - WASM module hardening

  • Versioning strategy
  • Input validation
  • API changes
  • Migration guide
  • Performance considerations
  • Testing guide
  • CSP Security Hardening

Bash Deployment Script

Location: scripts/deploy-soroban-testnet.sh

  • Production-ready automation
  • Comprehensive configuration options
  • Detailed logging
  • Continuous validation support

GitHub Actions Workflow

Location: .github/workflows/soroban-deploy.yml

  • Automated CI/CD
  • Multiple job types
  • Scheduled validation
  • Artifact management

Sanctifier Scan GitHub Action

Location: action.yml

  • Composite action for running sanctifier analyze in CI
  • Support matrix: docs/github-action-support-matrix.md (includes debug logging mode)
  • Threat model notes: docs/github-action-threat-model.md

Docs and Specs Maintenance

Release Artifacts (data/ + schemas/)

📚 Documentation Map by Use Case

"I want to deploy now"

→ QUICK_START.md (5 min)
→ Run: ./scripts/deploy-soroban-testnet.sh --network testnet

"I want to understand the system"

→ ARCHITECTURE.md (15 min)
→ IMPLEMENTATION_SUMMARY.md (10 min)

"I need to set up CI/CD"

→ docs/ci-cd-setup.md (20 min)
→ Add GitHub secrets
→ Push to main

"I need complete details"

→ SOROBAN_DEPLOYMENT.md (45 min)
→ Complete reference

"Something is broken"

→ SOROBAN_DEPLOYMENT.md - Troubleshooting
→ Check logs: tail -f .deployment.log

"I'm planning deployment"

→ COMPLETION_REPORT.md
→ Check feature list and statistics

"I need production guidelines"

→ docs/ci-cd-setup.md - Security section
→ SOROBAN_DEPLOYMENT.md - Best practices

🎯 Documentation by Topic

Setup & Configuration

Document Time Topics
QUICK_START.md 5 min Quick setup
GETTING_STARTED.md 10 min Full checklist
SOROBAN_DEPLOYMENT.md 30 min All setup options
docs/ci-cd-setup.md 20 min GitHub setup

Understanding the System

Document Time Topics
ARCHITECTURE.md 15 min System design
IMPLEMENTATION_SUMMARY.md 10 min What's included
COMPLETION_REPORT.md 5 min Deliverables
Contract README 20 min Contract details
docs/rule-authoring-guide.md 15 min Rule authoring

Deployment Operations

Document Time Topics
QUICK_START.md 5 min First deployment
SOROBAN_DEPLOYMENT.md 30 min All operations
.github/workflows/soroban-deploy.yml 10 min CI/CD workflow

Troubleshooting & Support

Document Time Topics
docs/troubleshooting-guide.md 5 min Owner map
SOROBAN_DEPLOYMENT.md#troubleshooting 15 min Common issues
docs/ci-cd-setup.md#troubleshooting 10 min CI/CD issues
GETTING_STARTED.md#troubleshooting-quick-links 5 min Quick answers

📋 Quick Reference

Common Commands

Deploy

./scripts/deploy-soroban-testnet.sh --network testnet

See: QUICK_START.md - Common Commands

Verify

cat .deployment-manifest.json | jq '.'

See: SOROBAN_DEPLOYMENT.md - Verification

Monitor

tail -f .deployment.log

See: QUICK_START.md - Verification

🔐 Security & Best Practices

Secrets Management

GitHub Action Hardening

Production Setup

🎓 Learning Path

Day 1: Getting Started

  1. Read QUICK_START.md (5 min)
  2. Set up environment (5 min)
  3. Run dry-run (2 min)
  4. Deploy contract (5 min)
  5. Verify deployment (3 min) Total: 20 minutes ✅

Week 1: Production Setup

  1. Read ARCHITECTURE.md (15 min)
  2. Review SOROBAN_DEPLOYMENT.md (30 min)
  3. Set up GitHub Actions (20 min)
  4. Configure branch protection (10 min)
  5. Test CI/CD (15 min) Total: 90 minutes ✅

Month 1: Advanced Topics

  1. Extend Runtime Guardians
  2. Multi-network deployment
  3. Custom monitoring
  4. Performance tuning
  5. Disaster recovery planning

📞 Checklists

Pre-Deployment

  • Read QUICK_START.md
  • Copy .env.example to .env.local
  • Add SOROBAN_SECRET_KEY
  • Run --dry-run
  • Ready to deploy

Post-Deployment

  • Check .deployment-manifest.json
  • Call health_check()
  • Review .deployment.log
  • Get get_stats()
  • Deployment successful!

CI/CD Setup

  • Add GitHub secrets
  • Review workflow file
  • Test manual dispatch
  • Verify automatic triggers
  • Monitor first run
  • CI/CD operational!

🔗 External Resources

Soroban Documentation

GitHub Resources

Related Sanctifier Docs

📊 Documentation Statistics

Document Pages Read Time Focus
QUICK_START.md 4 5 min Getting started
GETTING_STARTED.md 8 10 min Planning
SOROBAN_DEPLOYMENT.md 12 30 min Complete reference
docs/ci-cd-setup.md 10 20 min GitHub Actions
ARCHITECTURE.md 10 15 min System design
IMPLEMENTATION_SUMMARY.md 8 10 min Deliverables
COMPLETION_REPORT.md 6 5 min Summary
Contract README 11 20 min Technical
Total 69 115 min Complete

🎯 Next Steps

  1. Start Here: QUICK_START.md
  2. Then: Set up environment and deploy
  3. Next: Review SOROBAN_DEPLOYMENT.md
  4. Finally: Set up GitHub Actions

✅ What You Get

✅ Complete Automation

  • CLI tool
  • Bash script
  • GitHub Actions workflow

✅ Comprehensive Documentation

  • 7 guides
  • Code examples
  • Troubleshooting

✅ Production Ready

  • Error handling
  • Security hardened
  • Fully tested

✅ Easy to Use

  • 5-minute setup
  • Single command deployment
  • Automatic validation

Last Updated: February 25, 2026
Version: 1.0
Status: Production Ready

🎉 Start with QUICK_START.md and deploy your first contract in 5 minutes!