fix: add tool-install guards to Makefile audit/deny targets and update docs/CI (#46)

.github/workflows/ci.yml

@@ -108,3 +108,41 @@ jobs:
           cache-on-failure: true
       - name: cargo check --target wasm32v1-none (contracts)
         run: cargo check ${{ env.CONTRACTS }} --target wasm32v1-none
+
+  security-audit:
+    name: Security audit
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          cache: false
+      - name: Cache cargo registry and target
+        uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Install cargo-audit
+        run: cargo install cargo-audit --locked
+      - name: cargo audit
+        run: cargo audit
+
+  license-check:
+    name: License check
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install Rust toolchain
+        uses: dtolnay/rust-toolchain@stable
+        with:
+          cache: false
+      - name: Cache cargo registry and target
+        uses: Swatinem/rust-cache@v2
+        with:
+          cache-on-failure: true
+      - name: Install cargo-deny
+        run: cargo install cargo-deny --locked
+      - name: cargo deny check
+        run: cargo deny check

CONTRIBUTING.md

@@ -0,0 +1,130 @@
+# Contributing to OrbitChain
+
+Thank you for your interest in contributing to OrbitChain! This document outlines the development workflow, prerequisites, and guidelines.
+
+## Prerequisites
+
+Before setting up the project, ensure you have the following tools installed:
+
+### Required
+
+- **Rust toolchain** (stable) — managed automatically by `rust-toolchain.toml`
+  ```bash
+  curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+  ```
+- **wasm32v1-none target** — auto-installed when running `rustup show` in the project root
+- **`stellar-cli`** — for contract deployment and interaction
+  ```bash
+  cargo install --locked stellar-cli --features opt
+  ```
+
+### Security Scanning Tools
+
+These tools are required to run `make audit` and `make deny` locally. CI jobs install them automatically.
+
+- **`cargo-audit`** — vulnerability scanning
+  ```bash
+  cargo install cargo-audit --locked
+  ```
+- **`cargo-deny`** — license compliance and policy checks
+  ```bash
+  cargo install cargo-deny --locked
+  ```
+
+## Getting Started
+
+1. **Fork and clone the repository**
+
+   ```bash
+   git clone https://github.com/YOUR_USERNAME/OrbitChain-Contracts.git
+   cd OrbitChain-Contracts
+   ```
+
+2. **Verify the toolchain**
+
+   ```bash
+   rustup show
+   ```
+
+3. **Build the project**
+
+   ```bash
+   make build
+   ```
+
+4. **Run tests**
+
+   ```bash
+   make test
+   ```
+
+## Development Workflow
+
+### Branch Naming
+
+Use conventional branch names:
+
+- `feat/<description>` — new features
+- `fix/<description>` — bug fixes
+- `docs/<description>` — documentation updates
+- `refactor/<description>` — code refactoring
+- `chore/<description>` — maintenance tasks
+
+### Commit Messages
+
+Use [conventional commits](https://www.conventionalcommits.org/):
+
+```
+feat: add wallet connection modal
+fix: resolve donation API error
+docs: update project README
+refactor: clean up project creation form
+```
+
+### Before Submitting a Pull Request
+
+1. Ensure the project builds successfully:
+   ```bash
+   make build
+   ```
+
+2. Run all tests and ensure they pass:
+   ```bash
+   make test
+   ```
+
+3. Format your code:
+   ```bash
+   make fmt
+   ```
+
+4. Run the linter and fix any warnings:
+   ```bash
+   make lint
+   ```
+
+5. Run security scans (requires `cargo-audit` and `cargo-deny`):
+   ```bash
+   make audit
+   make deny
+   ```
+
+## Pull Request Process
+
+1. Create a branch from `main` with a descriptive name.
+2. Make your changes and commit them with conventional commit messages.
+3. Push your branch to your fork.
+4. Open a pull request against the `main` branch of the upstream repository.
+5. Ensure all CI checks pass (including security scans).
+6. Request review from the maintainers.
+
+## Code Style
+
+- Follow Rust's standard formatting (`rustfmt`) — run `make fmt` before committing.
+- Adhere to Clippy lint recommendations — run `make lint` to check.
+- Write documentation comments for public APIs.
+- Add unit tests for new functionality.
+
+## Questions?
+
+If you have questions or need help, open a GitHub Discussion or reach out to the maintainers.

Makefile

@@ -7,7 +7,7 @@
 ##   make clippy       - Lint code
 
 .PHONY: build build-wasm build-tools test fmt lint clean optimize help \
-        setup deploy-testnet deploy-sandbox sandbox-start audit deny
+        setup deploy-testnet deploy-sandbox sandbox-start audit deny audit-ci deny-ci
 
 # Default target
 build: build-wasm build-tools
@@ -82,12 +82,36 @@ deploy-testnet: build-wasm
 
 # Run cargo-audit for vulnerability scanning
 audit:
+	@if ! command -v cargo-audit >/dev/null 2>&1; then \
+		echo "❌ cargo-audit not installed. Run 'cargo install cargo-audit --locked' then retry." >&2; \
+		exit 1; \
+	fi
 	@echo "🔒 Running security audit..."
 	cargo audit
 	@echo "✅ Security audit passed"
 
 # Run cargo-deny for license compliance
 deny:
+	@if ! command -v cargo-deny >/dev/null 2>&1; then \
+		echo "❌ cargo-deny not installed. Run 'cargo install cargo-deny --locked' then retry." >&2; \
+		exit 1; \
+	fi
+	@echo "📋 Checking license compliance..."
+	cargo deny check
+	@echo "✅ License check passed"
+
+# Security audit (CI variant — installs tool if missing)
+audit-ci:
+	@echo "🔒 Installing cargo-audit (CI)..."
+	cargo install cargo-audit --locked 2>&1 | tail -1
+	@echo "🔒 Running security audit..."
+	cargo audit
+	@echo "✅ Security audit passed"
+
+# License check (CI variant — installs tool if missing)
+deny-ci:
+	@echo "📋 Installing cargo-deny (CI)..."
+	cargo install cargo-deny --locked 2>&1 | tail -1
 	@echo "📋 Checking license compliance..."
 	cargo deny check
 	@echo "✅ License check passed"
@@ -113,4 +137,6 @@ help:
 	@echo "  make deploy-sandbox - Deploy contract to local sandbox"
 	@echo "  make deploy-testnet - Deploy contract to Stellar testnet"
 	@echo "  make optimize       - Optimize WASM with wasm-opt -Oz"
+	@echo "  make audit          - Run cargo audit (requires cargo-audit)"
+	@echo "  make deny           - Run cargo deny (requires cargo-deny)"
 	@echo "  make help           - Show this help message"

README.md

@@ -536,6 +536,18 @@ Open a Pull Request from your fork back to the main branch.
 
 This project uses `cargo-audit` and `cargo-deny` to maintain high security standards and license compliance.
 
+### Prerequisites
+
+Before running security scans locally, install the required tools:
+
+```bash
+# Install cargo-audit for vulnerability scanning
+cargo install cargo-audit --locked
+
+# Install cargo-deny for license and policy compliance
+cargo install cargo-deny --locked
+```
+
 ### Local Scans
 
 You can run the security scans locally using the following commands:
@@ -567,7 +579,7 @@ If a license or ban policy violation is found:
 
 ### Automated CI
 
-Security scans are automatically run on every push and pull request. CI will fail if any known vulnerabilities or policy violations are detected.
+Security scans are automatically run on every push and pull request via dedicated CI jobs. The CI pipeline installs `cargo-audit` and `cargo-deny` automatically before running the scans. CI will fail if any known vulnerabilities or policy violations are detected.
 
 # 📜 License
 

campaign/Cargo.toml

@@ -2,6 +2,8 @@
 name = "orbitchain-campaign"
 version = "0.1.0"
 edition = "2021"
+license = "MIT"
+publish = false
 description = "OrbitChain campaign smart contract — milestones, donations, refunds, and lifecycle"
 
 [lib]

common/Cargo.toml

@@ -2,6 +2,8 @@
 name = "orbitchain-common"
 version = "0.1.0"
 edition = "2021"
+license = "MIT"
+publish = false
 description = "OrbitChain common types — shared CampaignStatus, MilestoneStatus, AssetInfo, and ErrorCode"
 
 [lib]

crates/contracts/core/Cargo.toml

@@ -3,6 +3,8 @@ name = "orbitchain-core"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+license = "MIT"
+publish = false
 description = "Legacy OrbitChain campaign reference contract; canonical implementation lives in orbitchain-campaign"
 
 [lib]

crates/tools/Cargo.toml

@@ -3,6 +3,8 @@ name = "orbitchain-tools"
 version.workspace = true
 edition.workspace = true
 rust-version.workspace = true
+license = "MIT"
+publish = false
 description = "OrbitChain CLI tools — key management, signing, asset issuing, and payment processing"
 
 [[bin]]

deny.toml

@@ -0,0 +1,59 @@
+# cargo-deny configuration
+# Run `cargo deny check` to verify license compliance
+
+[advisories]
+# Advisories to ignore (after review)
+ignore = [
+    # dotenv v0.15.0 is unmaintained (RUSTSEC-2021-0141);
+    # used by orbitchain-tools for environment variable loading
+    "RUSTSEC-2021-0141",
+]
+# How to handle yanked crates: deny, warn (default), or allow
+yanked = "warn"
+# How to handle unmaintained advisories: all, workspace, transitive, none
+unmaintained = "workspace"
+# How to handle unsound advisories: all, workspace (default), transitive, none
+unsound = "workspace"
+# Warn about unused ignored advisories
+unused-ignored-advisory = "warn"
+
+[licenses]
+# List of allowed licenses.
+# See https://spdx.org/licenses/ for full list.
+allow = [
+    "MIT",
+    "Apache-2.0",
+    "Apache-2.0 WITH LLVM-exception",
+    "BSD-2-Clause",
+    "BSD-3-Clause",
+    "Unicode-3.0",
+    "Unlicense",
+    "Zlib",
+]
+# Confidence threshold for license detection (0.0 - 1.0)
+confidence-threshold = 0.8
+# Warn about unused allowed licenses
+unused-allowed-license = "warn"
+
+# Specific exceptions for crates that need additional licenses
+# [[licenses.exceptions]]
+# allow = ["License-Id"]
+# crate = "crate-name"
+
+[bans]
+# Specific crates that are banned
+deny = [
+    # Example: { name = "openssl", reason = "Using rustls instead" },
+]
+# Skip these specific crates from being checked
+skip = []
+# Skip entire trees
+skip-tree = []
+
+[sources]
+# Only allow crates from crates.io by default
+allow-registry = ["https://github.com/rust-lang/crates.io-index"]
+# Deny unknown registries
+unknown-registry = "deny"
+# Deny git sources unless explicitly allowed
+unknown-git = "deny"

token-bridge/Cargo.toml

@@ -2,6 +2,8 @@
 name = "orbitchain-token-bridge"
 version = "0.1.0"
 edition = "2021"
+license = "MIT"
+publish = false
 description = "OrbitChain cross-chain token bridge contract"
 
 [lib]