From 9da176d8671415311e2749ddf2c72e60a5ab02eb Mon Sep 17 00:00:00 2001 From: thisisouvik Date: Wed, 9 Sep 2026 23:17:45 +0530 Subject: [PATCH] chore: update documentation and add setup runbook for developer onboarding --- .gitignore | 1 - CONTRIBUTING.md | 4 + README.md | 11 +- SETUP.md | 305 ++++++++++++++++++++++++++++++++++++++++++++++++ docs/index.md | 1 + 5 files changed, 319 insertions(+), 3 deletions(-) create mode 100644 SETUP.md diff --git a/.gitignore b/.gitignore index 367e84b..81c7626 100644 --- a/.gitignore +++ b/.gitignore @@ -6,7 +6,6 @@ .vscode/ *.swp **/*.rs.bk -/scripts/ # Environment .env diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5d1269..36c9cd7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -9,6 +9,7 @@ Thank you for your interest in contributing! This is an open-source project in a - [Code of Conduct](#code-of-conduct) - [How to Contribute](#how-to-contribute) - [Development Setup](#development-setup) +- [Setup Runbook (SETUP.md)](./SETUP.md) - [Project Conventions](#project-conventions) - [Pull Request Process](#pull-request-process) - [Reporting Issues](#reporting-issues) @@ -39,6 +40,9 @@ We welcome contributions in several forms: ## Development Setup +> [!TIP] +> For an end-to-end guide on installing toolchains, deploying locally or on testnet, and troubleshooting, see [SETUP.md](./SETUP.md). + ### Prerequisites ```bash diff --git a/README.md b/README.md index a00bec7..4ca64fc 100644 --- a/README.md +++ b/README.md @@ -10,6 +10,7 @@ [![Protocol](https://img.shields.io/badge/stellar-protocol%2027-blue?style=for-the-badge&logo=stellar)](https://developers.stellar.org) [![License](https://img.shields.io/badge/license-Apache--2.0-green?style=for-the-badge)](./LICENSE) [![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen?style=for-the-badge)](./CONTRIBUTING.md) +[![Setup Guide](https://img.shields.io/badge/Setup-Guide-blue?style=for-the-badge)](./SETUP.md) @@ -183,8 +184,8 @@ wallet-contracts/ ├── scripts/ │ ├── deploy_testnet.sh # One-shot testnet deployment │ └── generate_bindings.sh # TypeScript binding generation -├── docs/ -│ └── threat-model.md # Security threat model & mitigations +├── docs/ # Technical & architectural documentation +├── SETUP.md # Step-by-step developer onboarding & runbook ├── MIGRATION.md # CAP-0071 / CAP-0072 upgrade roadmap ├── CONTRIBUTING.md ├── SECURITY.md @@ -203,6 +204,7 @@ wallet-contracts/ |---|---|---| | **Factory** | `CCCAMWJOF7IYTVCU7SR6HFTNH5XRMDMWPYN464NY5BCKUPMUM64RZ5CH` | [View on Stellar Expert](https://stellar.expert/explorer/testnet/contract/CCCAMWJOF7IYTVCU7SR6HFTNH5XRMDMWPYN464NY5BCKUPMUM64RZ5CH) | | **Policy** | `CCDM3O2SXX3E24MCWLRK5YBVQHJCA4OQKJFF6KWCK6FHZS65DGMT6DOY` | [View on Stellar Expert](https://stellar.expert/explorer/testnet/contract/CCDM3O2SXX3E24MCWLRK5YBVQHJCA4OQKJFF6KWCK6FHZS65DGMT6DOY) | +| **Demo Wallet** | `CAIIUPVI5VO2BCXKPUIRZX4BW4YQ6G6FWPJEWVKIVRN4H3KWJTUV3VXM` | [View on Stellar Expert](https://stellar.expert/explorer/testnet/contract/CAIIUPVI5VO2BCXKPUIRZX4BW4YQ6G6FWPJEWVKIVRN4H3KWJTUV3VXM) | | **Wallet (WASM Hash)** | `8c2e77ad251a8e32590280c95627fd24864f1ff1917d781e44510f450445d7c6` | [View Upload Tx](https://stellar.expert/explorer/testnet/tx/87d1ee48ae9f4b616fea84681d5094201765a8bee84ed5686a39a87bc7985b2d) | > **Mainnet**: Not yet deployed. This project is currently in open testnet. See our [community process](#-community--roadmap). @@ -226,6 +228,7 @@ wallet-contracts/ | Document | Description | |---|---| | [Documentation Index](./docs/index.md) | **Start Here:** Directory of all project documentation | +| [Environment Setup Guide](./SETUP.md) | **Developer Runbook:** Prerequisites, building, testnet deploy & troubleshooting | | [Getting Started](./docs/getting-started.md) | Setup, building, running tests, deploying, TypeScript bindings | | [Architecture](./docs/architecture.md) | Design decisions, module breakdown, storage layout, auth model | | [API Reference](./docs/api-reference.md) | Full function signatures, parameters, errors for all contracts | @@ -237,6 +240,9 @@ wallet-contracts/ ## 🚀 Getting Started +> [!TIP] +> For a full walkthrough including toolchain setup, manual contract invocation, and troubleshooting, see the [SETUP.md](./SETUP.md) guide. + ### Prerequisites ```bash @@ -328,6 +334,7 @@ This project is being released to the open-source community **first on testnet** We welcome contributions of all kinds — bug reports, feature requests, documentation improvements, and code! - Please read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR. +- Follow [SETUP.md](./SETUP.md) for local environment setup and testing runbook. - Please review our [CODE_OF_CONDUCT.md](./CODE_OF_CONDUCT.md) to ensure a welcoming environment. - Check the [CHANGELOG.md](./CHANGELOG.md) for version history. diff --git a/SETUP.md b/SETUP.md new file mode 100644 index 0000000..605b539 --- /dev/null +++ b/SETUP.md @@ -0,0 +1,305 @@ +# Environment Setup & Developer Runbook + +This guide covers complete instructions for onboarding, local environment configuration, compilation, running tests, local simulation, testnet deployment, and generating typed clients for **Rayos Wallet Contracts**. + +--- + +## 📋 Table of Contents + +- [System Requirements & Prerequisites](#-system-requirements--prerequisites) +- [Repository Setup](#-repository-setup) +- [Rust Toolchain & Target Verification](#-rust-toolchain--target-verification) +- [Building the Contracts](#-building-the-contracts) +- [Running Tests & Quality Assurance](#-running-tests--quality-assurance) +- [Testnet Deployment](#-testnet-deployment) +- [Client SDK & TypeScript Bindings](#-client-sdk--typescript-bindings) +- [Troubleshooting & Common Issues](#-troubleshooting--common-issues) +- [Further Documentation](#-further-documentation) + +--- + +## 🛠 System Requirements & Prerequisites + +Ensure the following tools are installed before proceeding: + +| Tool | Recommended Version | Purpose | Installation | +|---|---|---|---| +| **Rust** | Stable (≥ 1.84.0) | Contract development & host execution | `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs \| sh` | +| **`wasm32v1-none` target** | Latest | Soroban Protocol 27+ WASM compilation | `rustup target add wasm32v1-none` | +| **Stellar CLI** | `v22.0.0` or higher | Contract deployment, invocation & inspection | `cargo install stellar-cli --locked` | +| **Git** | ≥ 2.30.0 | Version control | [git-scm.com](https://git-scm.com/) | +| **GitHub CLI (`gh`)** | Latest (optional) | CI and repository administration | [cli.github.com](https://cli.github.com/) | +| **Node.js & npm** | ≥ 18.0.0 (optional) | Consuming generated TypeScript bindings | [nodejs.org](https://nodejs.org/) | + +> [!IMPORTANT] +> **Rust 1.84+ and `wasm32v1-none`**: Soroban SDK v27 requires the `wasm32v1-none` target. Do not use `wasm32-unknown-unknown` on newer Rust compilers, as it activates unsupported WebAssembly features. + +--- + +## 📂 Repository Setup + +1. **Clone the repository:** + + ```bash + git clone https://github.com/Rayos-Org/wallet-contracts.git + cd wallet-contracts + ``` + +2. **Verify directory structure:** + + ```text + wallet-contracts/ + ├── .cargo/ # Cargo aliases (wasm-build) + ├── .github/ # CI workflows & issue/PR templates + ├── contracts/ + │ ├── factory/ # Deterministic wallet deployer + │ ├── policy/ # Spend limits, session keys, allow-lists, recovery + │ └── wallet/ # Passkey WebAuthn smart account + ├── docs/ # In-depth architectural & API references + ├── scripts/ # Automated deployment and binding scripts + ├── tests/ # Cross-contract integration tests + ├── Cargo.toml # Workspace root manifest + ├── rust-toolchain.toml # Pinned toolchain definition + └── SETUP.md # This runbook + ``` + +--- + +## 🦀 Rust Toolchain & Target Verification + +Check that your active Rust toolchain matches `rust-toolchain.toml`: + +```bash +# Verify toolchain status +rustup show + +# Ensure the target is installed +rustup target add wasm32v1-none +``` + +Verify Cargo aliases: +The repository includes `.cargo/config.toml` which defines `cargo wasm-build` as a shortcut for: +`cargo build --target wasm32v1-none --release` + +--- + +## 🔨 Building the Contracts + +### 1. Build for Host (Fast type-checking and testing) + +```bash +cargo build +cargo check +``` + +### 2. Compile WebAssembly Binaries + +Compile all three contracts to optimized WASM: + +```bash +cargo wasm-build +``` + +Compiled WASM artifacts will be produced at: +- `target/wasm32v1-none/release/wallet.wasm` +- `target/wasm32v1-none/release/factory.wasm` +- `target/wasm32v1-none/release/policy.wasm` + +> [!NOTE] +> All contracts are optimized to remain well under the 128 KB Soroban bytecode budget. + +--- + +## 🧪 Running Tests & Quality Assurance + +### Run Unit & Integration Tests + +```bash +# Run all workspace unit tests +cargo test + +# Run tests for a specific contract +cargo test -p wallet +cargo test -p policy +cargo test -p factory + +# Run property-based fuzz tests (100 runs) +cargo test -p policy test_spend_limits_fuzz + +# Display test stdout / debug output +cargo test -- --nocapture +``` + +### Code Formatting & Linting + +Enforce codebase conventions before committing or submitting a PR: + +```bash +# Check formatting +cargo fmt --all -- --check + +# Format codebase +cargo fmt --all + +# Run Clippy with strict warnings check (matches CI gate) +cargo clippy --all-targets -- -D warnings +``` + +--- + +## 🌐 Testnet Deployment + +### Prerequisites for Deployment + +Configure the Stellar testnet and create a funded deployer identity: + +```bash +# Verify networks +stellar network ls + +# Generate and fund an identity via Friendbot +stellar keys generate deployer --network testnet +stellar keys fund deployer --network testnet +``` + +### Option A: Automated Script (Recommended) + +Run the automated testnet setup script: + +```bash +# On Linux/macOS or Windows Git Bash / WSL +bash scripts/deploy_testnet.sh +``` + +This script: +1. Compiles contracts via `cargo wasm-build`. +2. Verifies and funds the `deployer` key on testnet. +3. Installs `wallet.wasm` and captures the WASM hash. +4. Deploys and initializes the **Factory Contract**. +5. Deploys and initializes the **Policy Contract**. +6. Writes deployed contract addresses to `.testnet-addresses`. + +### Option B: Manual Step-by-Step Deployment + +```bash +# 1. Install Wallet WASM +WALLET_HASH=$(stellar contract upload \ + --wasm target/wasm32v1-none/release/wallet.wasm \ + --source deployer \ + --network testnet) + +# 2. Deploy Factory Contract +FACTORY_ADDRESS=$(stellar contract deploy \ + --wasm target/wasm32v1-none/release/factory.wasm \ + --source deployer \ + --network testnet) + +# 3. Initialize Factory with the Wallet WASM hash +stellar contract invoke \ + --id $FACTORY_ADDRESS \ + --source deployer \ + --network testnet \ + -- init --wasm_hash "$WALLET_HASH" + +# 4. Deploy Policy Contract +POLICY_ADDRESS=$(stellar contract deploy \ + --wasm target/wasm32v1-none/release/policy.wasm \ + --source deployer \ + --network testnet) + +# 5. Initialize Policy with deployer as initial owner +OWNER_ADDR=$(stellar keys address deployer) +stellar contract invoke \ + --id $POLICY_ADDRESS \ + --source deployer \ + --network testnet \ + -- init --owner "$OWNER_ADDR" + +# 6. Deploy a User Smart Wallet through the Factory +# Salt: 32 bytes hex, Credential ID: Hex, Public Key: 65 bytes uncompressed secp256r1 +WALLET_ADDR=$(stellar contract invoke \ + --id $FACTORY_ADDRESS \ + --source deployer \ + --network testnet \ + -- deploy_wallet \ + --salt "0000000000000000000000000000000000000000000000000000000000000001" \ + --credential_id "64656d6f63726564" \ + --public_key "0400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000") +``` + +### Reference Addresses (Stellar Testnet) + +| Contract | Address / Hash | +|---|---| +| **Factory** | `CCCAMWJOF7IYTVCU7SR6HFTNH5XRMDMWPYN464NY5BCKUPMUM64RZ5CH` | +| **Policy** | `CCDM3O2SXX3E24MCWLRK5YBVQHJCA4OQKJFF6KWCK6FHZS65DGMT6DOY` | +| **Demo Wallet** | `CAIIUPVI5VO2BCXKPUIRZX4BW4YQ6G6FWPJEWVKIVRN4H3KWJTUV3VXM` | +| **Wallet WASM Hash** | `8c2e77ad251a8e32590280c95627fd24864f1ff1917d781e44510f450445d7c6` | + +--- + +## 📦 Client SDK & TypeScript Bindings + +Generate strongly-typed TypeScript SDK bindings directly from deployed contract interfaces: + +```bash +# Execute binding generation script +bash scripts/generate_bindings.sh +``` + +Or manually: + +```bash +# Generate Factory client +stellar contract bindings typescript \ + --network testnet \ + --contract-id CCCAMWJOF7IYTVCU7SR6HFTNH5XRMDMWPYN464NY5BCKUPMUM64RZ5CH \ + --output-dir bindings/factory + +# Generate Policy client +stellar contract bindings typescript \ + --network testnet \ + --contract-id CCDM3O2SXX3E24MCWLRK5YBVQHJCA4OQKJFF6KWCK6FHZS65DGMT6DOY \ + --output-dir bindings/policy + +# Generate Wallet client (from bytecode) +stellar contract bindings typescript \ + --wasm target/wasm32v1-none/release/wallet.wasm \ + --output-dir bindings/wallet +``` + +--- + +## 🔍 Troubleshooting & Common Issues + +### 1. `unsupported target 'wasm32-unknown-unknown'` +- **Cause**: Newer Rust compilers enable WebAssembly features (such as reference types) unsupported on Soroban. +- **Fix**: Always build with `--target wasm32v1-none` or run `cargo wasm-build`. + +### 2. `error setting certificate file` on Windows Git Push +- **Cause**: Windows Git installation points to a missing `ca-bundle.crt`. +- **Fix**: Switch Git to the native Windows certificate store: + ```powershell + git config --global http.sslbackend schannel + ``` + +### 3. GitHub CLI Auth in Git operations +- If `git push` prompts for credentials or fails with `401 Unauthorized`: + ```bash + gh auth setup-git + ``` + +### 4. `CannotRemoveLastSigner` (Error code `102`) +- The wallet contract strictly forbids removing the final registered passkey to prevent permanently bricking accounts. Add a replacement signer before revoking an existing one. + +--- + +## 📖 Further Documentation + +- **[Main README](./README.md)** — Architectural summary & protocol overview +- **[Docs Index](./docs/index.md)** — Master guide to deep documentation +- **[Architecture Deep Dive](./docs/architecture.md)** — Contract boundaries, TTL and auth flows +- **[API Reference](./docs/api-reference.md)** — Comprehensive interface specifications +- **[Threat Model](./docs/threat-model.md)** — Security boundaries & attack mitigations +- **[Architecture Decision Records (ADR)](./docs/decisions.md)** — Design rationale log +- **[Contributing Guide](./CONTRIBUTING.md)** — Contributor onboarding & PR conventions diff --git a/docs/index.md b/docs/index.md index 2847427..ecba48e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -6,6 +6,7 @@ Welcome to the Rayos Wallet Contracts documentation. Start here to find the righ | Document | Audience | Description | |---|---|---| +| [Environment Setup](../SETUP.md) | **Developers / operators** | Prerequisites, toolchain setup, build runbook, testnet deployment | | [Getting Started](./getting-started.md) | **New developers** | Setup, building, running tests, deploying to testnet, TypeScript bindings | | [Architecture](./architecture.md) | **Contributors / auditors** | Design philosophy, module breakdown, storage layout, auth model, cross-contract communication | | [API Reference](./api-reference.md) | **Integrators / dApp devs** | Every function, parameter, return type, and error code across all three contracts |