> For the complete documentation index, see [llms.txt](https://bitbook.rwatokens.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://bitbook.rwatokens.net/sdk-and-development/sdk-and-development/contributing.md). # Contributing ## Contributing to RWA Tokens **Code Standards · PR Process · Security-Critical Rules · Documentation Requirements · Module-Aware** Thank you for your interest in contributing to the RWA Tokens platform — operated by Groovy Company, Inc. This document defines the standards, processes, and requirements for contributing to a securities-grade infrastructure codebase. The platform serves all three production modules — Equities (Module 1), Real Estate (Module 2), and CORECM — Carbon Ore, Rare Earth, and Critical Minerals (Module 3) — and the 42 immutable Transfer Hook controls (plus module-aware extensions for Module 2 NAV-deviation enforcement and Module 3 federal-action freeze coordination) protect real investors holding real equity. Every contribution must meet the security bar that responsibility demands. *** ### Table of Contents 1. ​Code of Conduct​ 2. ​Getting Started​ 3. ​Development Environment​ 4. ​Branch Strategy​ 5. ​Commit Standards​ 6. ​Pull Request Process​ 7. ​Code Style​ 8. ​Documentation Requirements​ 9. ​Security-Critical Contributions​ 10. ​Issue Reporting​ 11. ​Review Criteria​ 12. ​License *** ### 1. Code of Conduct The platform follows the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/). All interactions — issues, PRs, discussions, code review — must be professional, constructive, and respectful. Violations are addressed by maintainers and may result in contribution privileges being revoked. #### Key Principles * Technical disagreements are resolved with evidence, not authority. * Code review feedback is about the code, not the person. * Every contributor's time is valuable — respond to review comments within 48 hours or indicate you need more time. * Security vulnerabilities are reported privately (see §9), never in public issues. *** ### 2. Getting Started #### 2.1 Contribution Types | Type | Examples | Review Required | Security Review? | | ------------------------------------------- | ---------------------------------------------------------------------- | ----------------------------- | ---------------------------------------------------------------- | | **Bug fix** | Error handling, edge case, UI issue | 1 maintainer | If touches L2 controls (cross-module or module-aware extensions) | | **Feature** | New endpoint, SDK method, monitoring | 1 maintainer + CTO | If touches L2 / L4 / L6 | | **Transfer Hook change** | Any change to 42 controls | CTO + 2 maintainers + Certora | **Always** | | **Module 2 NAV-deviation extension change** | Any change to CB-21 NAV variant or NAV oracle handling | CTO + 2 maintainers + Certora | **Always** | | **Module 3 federal-action freeze change** | Any change to REG-42 federal variant or Classification oracle handling | CTO + 2 maintainers + Certora | **Always** | | **AMM / Pool change** | CPMM logic, fee routing | CTO + 1 maintainer + Certora | **Always** | | **Documentation** | Wiki, README, code comments | 1 maintainer | No | | **Test** | New tests, coverage improvement | 1 maintainer | No | | **Infrastructure** | CI/CD, monitoring, deployment | 1 maintainer + DevOps | No | #### 2.2 Before You Start 1. **Check existing issues** — your idea may already be tracked. 2. **Open a discussion** — for non-trivial features, open a GitHub Discussion before writing code. 3. **Claim the issue** — comment on the issue to indicate you're working on it. 4. **Read the architecture** — understand which layer and which module(s) your change affects (see Architecture Decisions). 5. **Identify module scope** — determine whether your change is cross-module or specific to Module 1, Module 2, or Module 3. #### 2.3 First-Time Contributors Good first issues are labeled `good-first-issue`. These are typically: * Documentation improvements. * Test coverage additions (cross-module or module-specific test fixtures). * Error message clarity. * SDK convenience methods. * Monitoring dashboard additions. These issues never touch Transfer Hook control logic, CPMM arithmetic, or the module-aware control extensions. *** ### 3. Development Environment #### 3.1 Setup ```bash # Clone the repository (URL published in Network Configuration) git clone cd rwa-tokens # Install dependencies yarn install # Build all programs anchor build # Start local validator solana-test-validator \ --bpf-program TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \ target/deploy/spl_token_2022.so \ --reset --quiet # Run tests anchor test --skip-local-validator ``` #### 3.2 Required Tools | Tool | Version | Install | | ---------- | ------- | -------------------------------------------------------------------- | | Rust | 1.75+ | `rustup update stable` | | Solana CLI | 1.18+ | `sh -c "$(curl -sSfL https://release.anza.xyz/stable/install)"` | | Anchor | 0.30+ | `cargo install --git https://github.com/coral-xyz/anchor anchor-cli` | | Node.js | 20 LTS | `nvm install 20` | | Yarn | 4+ | `corepack enable && yarn set version stable` | #### 3.3 IDE Configuration **VS Code (recommended):** ```json // .vscode/settings.json { "rust-analyzer.check.command": "clippy", "rust-analyzer.check.extraArgs": ["--", "-D", "warnings"], "editor.formatOnSave": true, "[rust]": { "editor.defaultFormatter": "rust-lang.rust-analyzer" }, "[typescript]": { "editor.defaultFormatter": "esbenp.prettier-vscode" } } ``` **Recommended extensions:** rust-analyzer, Solana (by Solana Labs), Prettier, ESLint. *** ### 4. Branch Strategy #### 4.1 Branch Naming ``` /- Examples: fix/142-custody-oracle-stale-check feat/205-sdk-batch-holding-query feat/210-module-2-nav-deviation-helper feat/215-module-3-federal-action-monitoring docs/310-oracle-integration-guide test/401-circuit-breaker-boundary test/410-reg-cf-holding-period chore/500-ci-fuzz-target ``` #### 4.2 Branch Types | Prefix | Use | Merges To | | ----------- | ------------------------------ | ------------------------------ | | `fix/` | Bug fixes | `develop` | | `feat/` | New features | `develop` | | `docs/` | Documentation only | `develop` | | `test/` | Test additions / improvements | `develop` | | `chore/` | CI / CD, tooling, dependencies | `develop` | | `security/` | Security-critical fixes | `develop` (expedited review) | | `release/` | Release preparation | `main` (maintainers only) | | `hotfix/` | Production emergency fix | `main` (CTO approval required) | #### 4.3 Protected Branches | Branch | Protection | Who Can Merge | | ----------- | ------------------------------------------------ | ---------------- | | `main` | Requires 2 approvals + CI pass + CTO sign-off | Maintainers only | | `develop` | Requires 1 approval + CI pass | Maintainers | | `release/*` | Requires 2 approvals + full test suite + Certora | CTO | *** ### 5. Commit Standards #### 5.1 Commit Message Format ``` (): [optional body] [optional footer] ``` #### 5.2 Types | Type | Description | Example | | ---------- | ------------------------------------- | ----------------------------------------------------------- | | `fix` | Bug fix | `fix(hook): correct wallet limit boundary at exactly 4.99%` | | `feat` | New feature | `feat(sdk): add batch holding period query` | | `docs` | Documentation | `docs(wiki): add oracle integration guide` | | `test` | Test addition / fix | `test(amm): add u128 overflow fuzz target` | | `refactor` | Code restructure (no behavior change) | `refactor(hook): extract control validation into module` | | `perf` | Performance improvement | `perf(amm): reduce CU by caching oracle read` | | `chore` | Tooling, CI, dependencies | `chore(ci): add cargo-tarpaulin coverage gate` | | `security` | Security-related change | `security(hook): fix stale attestation edge case` | #### 5.3 Scopes | Scope | Programs / Areas | Module Scope | | ---------------- | ------------------------------------------------ | ------------ | | `hook` | `transfer_hook` — 42 controls | All modules | | `amm` | `amm` — CPMM engine | All modules | | `pool` | `liquidity_pool` — Global Pool | All modules | | `gov` | `governance` | All modules | | `oracle` | `oracle_aggregator` (cross-module oracles) | All modules | | `nav` | NAV oracle and CB-21 NAV variant | **Module 2** | | `classification` | Classification oracle and REG-42 federal variant | **Module 3** | | `sdk` | `@rwatokens/sdk` | All modules | | `api` | CEDEX REST / WebSocket API | All modules | | `ci` | GitHub Actions, CI / CD | All modules | | `docs` | Documentation, wiki | All modules | | `infra` | Kubernetes, monitoring, RPC | All modules | #### 5.4 Rules * Subject line: imperative mood, ≤72 characters, no period. * Body: explain *what* and *why*, not *how* (the code explains how). * Reference issue: `Closes #142` or `Refs #205`. * Security commits: include `SECURITY:` prefix in body if applicable. ``` fix(hook): correct holding period boundary check The boundary check used `>` instead of `>=` for the holding period comparison, allowing transfers exactly at the threshold to incorrectly fail. Reg D (6 months), Reg S (12 months), and Reg CF (12 months) should pass when elapsed time equals holding_period_secs, not only when it exceeds it. SECURITY: This affects Control HP-24 behavior at exact boundaries across all three regimes and applies uniformly to Module 1, Module 2, and Module 3 mints. Closes #142 ``` *** ### 6. Pull Request Process #### 6.1 PR Template Every PR must use the repository's PR template: ```markdown ## Description ## Type ## Layer Impact - [ ] Layer 1 (Solana Foundation) - [ ] Layer 2 (Transfer Hook — 42 controls) - [ ] Layer 3 (Liquidity Pool) - [ ] Layer 4 (AMM) - [ ] Layer 5 (CEDEX) - [ ] Layer 6 (Oracle Network) - [ ] Layer 7 (Governance) - [ ] Layer 8 (Wallet) - [ ] Layer 9 (AI / IDOS Module) - [ ] SDK / API - [ ] Infrastructure / CI - [ ] Documentation only ## Module Impact - [ ] Cross-module (affects all of Module 1, Module 2, and Module 3) - [ ] Module 1 — Equities - [ ] Module 2 — Real Estate (touches NAV oracle / NAV-deviation extension?) - [ ] Module 3 — CORECM (touches Classification oracle / federal-action extension?) ## Security Impact - [ ] No security impact - [ ] Security impact — requires security review (describe below) ## Testing - [ ] Unit tests added / updated - [ ] Integration tests added / updated (per affected module) - [ ] Fuzz testing verified (if applicable) - [ ] Formal verification re-run (if applicable) ## Checklist - [ ] `cargo fmt --all` — clean - [ ] `cargo clippy --workspace` — zero warnings - [ ] `cargo test --workspace` — all pass - [ ] `anchor test` — all pass (if applicable) - [ ] Module-specific integration tests pass (Module 1 / 2 / 3 as applicable) - [ ] Documentation updated (if applicable) - [ ] Changelog entry added (if user-facing change) ``` #### 6.2 Review Process ``` CONTRIBUTOR REVIEWERS MERGE │ │ │ ├─ Open PR ──────────────────► │ │ │ │ │ │ ◄─── Review comments ───────┤ │ │ │ │ ├─ Address feedback ──────────►│ │ │ │ │ │ ◄─── Approval (1+) ────────┤ │ │ │ │ │ CI PASSES ───────────┼─────────────────────────►│ │ │ │ │ │ Maintainer merges ``` #### 6.3 Review SLAs | PR Type | First Review | Merge (after approval) | | ----------------- | -------------------- | ---------------------- | | Documentation | 24 hours | Same day | | Tests | 24 hours | Same day | | Bug fix | 48 hours | 24 hours | | Feature | 72 hours | 48 hours | | Security-critical | 24 hours (expedited) | CTO approval required | #### 6.4 What Reviewers Look For | Area | Criteria | | ------------- | ---------------------------------------------------------------------------------------------------------------- | | Correctness | Does the code do what the PR description says? Edge cases handled across all three modules? | | Security | Any new attack surface? Any weakened controls? Any module-aware extensions weakened? Any key management changes? | | Tests | Are new code paths tested? Coverage maintained? Boundary conditions? Module-specific scenarios? | | Performance | CU impact? Latency impact? Memory impact? Module 2 / Module 3 oracle read overhead? | | Style | Matches project conventions? `cargo fmt` + `cargo clippy` clean? | | Documentation | Public functions documented? Wiki updated if needed? Module-aware behavior surfaced? | | Terminology | Correct current terminology? No obsolete terms? (See Terminology section below.) | *** ### 7. Code Style #### 7.1 Rust ```bash # Format check (must pass CI) cargo fmt --all -- --check # Lint check (must pass CI — zero warnings) cargo clippy --workspace -- -D warnings ``` **Key conventions:** ```rust // Use checked arithmetic — never raw operators on financial values let result = amount.checked_mul(fee_bps as u64) .ok_or(TransferHookError::ArithmeticOverflow)?; // Never do this let result = amount * fee_bps as u64; // Use descriptive error variants return Err(TransferHookError::WalletLimitExceeded.into()); // Never use generic errors return Err(ProgramError::Custom(1)); // Document public functions /// Verifies the custody oracle attestation is valid and fresh. /// /// Operates uniformly across Module 1, Module 2, and Module 3 mints — /// asset class is recorded in the SecurityConfig, not the oracle. /// /// # Errors /// - `CustodyDiscrepancy` (6001): token supply exceeds custodied balance /// - `CustodyOracleUnavailable` (6002): attestation stale (>1 slot) pub fn verify_custody_oracle(oracle: &CustodyOracle, clock: &Clock) -> Result<()> { // ... } // Use constants, not magic numbers pub const MAX_WALLET_PERCENT_BPS: u16 = 499; // 4.99% default ceiling pub const M2_MAX_WALLET_UPPER_BPS: u16 = 999; // 9.99% Module 2 upper bound pub const REG_D_HOLDING_SECS: i64 = 15_778_800; // Reg D 6 months pub const REG_S_HOLDING_SECS: i64 = 31_536_000; // Reg S 12 months pub const REG_CF_HOLDING_SECS: i64 = 31_536_000; // Reg CF 12 months // Never hardcode values if wallet_percent > 499 { /* ... */ } ``` **Naming conventions:** | Item | Convention | Example | | -------------- | ---------------- | ----------------------------------------------------------------------------------------------------------- | | Structs | PascalCase | `SecurityConfig`, `HoldingPeriodAccount`, `NAVOracleState`, `ClassificationOracleState` | | Functions | snake\_case | `verify_custody_oracle`, `check_wallet_limit`, `compute_nav_deviation_bps`, `enforce_federal_action_freeze` | | Constants | SCREAMING\_SNAKE | `MAX_WALLET_PERCENT_BPS`, `REG_D_HOLDING_SECS`, `REG_S_HOLDING_SECS`, `REG_CF_HOLDING_SECS` | | Modules | snake\_case | `security_config`, `holding_period`, `nav_oracle`, `classification_oracle` | | Error variants | PascalCase | `WalletLimitExceeded`, `TokensLocked`, `RegulatoryOverride` | | PDA seeds | byte literals | `b"security-config"`, `b"holding-period"`, `b"nav-oracle"`, `b"classification-oracle"` | | Module enum | PascalCase | `ModuleId::Equities`, `ModuleId::RealEstate`, `ModuleId::Corecm` | | Regime enum | PascalCase | `HoldingRegime::RegD`, `HoldingRegime::RegS`, `HoldingRegime::RegCF` | #### 7.2 TypeScript ```bash # Format (must pass CI) yarn prettier --check "**/*.ts" # Lint (must pass CI — zero errors) yarn eslint "**/*.ts" ``` **Key conventions:** ````typescript // Explicit types on public API boundaries export async function getSecurityConfig(mint: PublicKey): Promise { // ... } // Use BigInt for token amounts (not number) const amount: bigint = 50_000_000_000n; // Never use number for token amounts (precision loss at >2^53) const amount: number = 50000000000; // Handle errors with typed catches try { await client.cedex.placeOrder(params); } catch (error) { if (error instanceof TransferHookError) { console.log(error.code, error.controlId, error.moduleScope); } } // Document exported functions with JSDoc /** * Verifies an ST22 mint has the Transfer Hook permanently attached. * Works uniformly across Module 1, Module 2, and Module 3 mints. * * @param mint - ST22 mint address * @returns Transfer Hook verification status including all 42 control states * @throws {RwaTokensError} If the mint does not exist or is not Token-2022 * * @example * ```typescript * const status = await client.hooks.verify(mintAddress); * console.log(status.controlsActive); // 42 * ``` */ export async function verify(mint: PublicKey): Promise { // ... } ```` #### 7.3 Tests ```rust // Test names describe the scenario, not the method #[test] fn test_wallet_limit_rejects_at_5_percent() { /* ... */ } // Not descriptive #[test] fn test_wallet_limit() { /* ... */ } // Test the boundary, not just pass/fail #[test] fn test_holding_period_passes_at_exact_threshold_reg_d() { /* ... */ } #[test] fn test_holding_period_fails_one_second_before_threshold_reg_d() { /* ... */ } #[test] fn test_holding_period_passes_at_exact_threshold_reg_cf() { /* ... */ } // Module-specific test naming #[test] fn test_nav_deviation_exceeds_threshold_module_2() { /* ... */ } #[test] fn test_federal_action_active_blocks_module_3() { /* ... */ } // Assert specific error codes assert_eq!(result.unwrap_err(), TransferHookError::TokensLocked.into()); // Don't just assert failure assert!(result.is_err()); ``` *** ### 8. Documentation Requirements #### 8.1 Code Documentation Every public function, struct, and module must be documented: ```rust /// Security configuration for a single ST22 mint. /// /// One `SecurityConfig` account exists per mint, created at mint initialization. /// Stores all parameters governing the 42 Transfer Hook controls for the token's /// entire existence. The same schema serves Module 1, Module 2, and Module 3 — /// module-specific extension fields (NAV bounds for Module 2; classification /// bounds and federal-action toggle for Module 3) are populated based on the /// mint's module. /// /// PDA: `[b"security-config", mint.key().as_ref()]` /// /// # Size /// Base: ~408 bytes + module-specific extension fields + 4 + (32 × blacklist_len) /// Maximum: 10,240 bytes (Solana account limit) #[account] pub struct SecurityConfig { /// Associated ST22 token mint address pub mint: Pubkey, /// Admin authority — 5-of-9 multi-sig pub authority: Pubkey, /// Schema version pub version: u8, /// Module identifier — drives module-aware behavior pub module: ModuleId, // ... } ``` #### 8.2 When to Update Wiki | Change Type | Wiki Update Required? | Which Page? | | -------------------------------------------------- | --------------------- | ------------------------------------------------------------------------------------------------------- | | New SDK method (cross-module or module-specific) | Yes | SDK Reference | | New error code | Yes | Smart Contract Reference, CEDEX API Reference | | New instruction | Yes | Smart Contract Reference | | Parameter change (cross-module or module-specific) | Yes | Smart Contract Reference, Changelog | | New oracle integration | Yes | Oracle Integration Guide | | Module 2 NAV-extension change | Yes | Smart Contract Reference, Oracle Integration Guide, Transfer Hook Reference | | Module 3 federal-action extension change | Yes | Smart Contract Reference, Oracle Integration Guide, Transfer Hook Reference, Incident Response Playbook | | Deployment procedure change | Yes | Deployment Guide | | New test pattern | Optional | Testing Guide | | Internal refactor | No | — | #### 8.3 Terminology The platform has legally load-bearing terminology. Using the wrong term in documentation or code comments can create regulatory confusion. The following terms are authoritative. **Always use** | Term | Context | | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- | | Groovy Company, Inc. | Operating entity (Wyoming domicile; CIK 1499275; OTC: GROO) — no dba | | RWA Tokens | Platform branding | | Module 1 — Equities | First production module | | Module 2 — Real Estate | Second production module | | Module 3 — CORECM | Third production module — Carbon Ore, Rare Earth, and Critical Minerals | | Common Class B | Backing instrument for Module 1 (Equities) ST22 tokens | | Single-asset entity (SAE) equity | Backing instrument for Module 2 (Real Estate) ST22 tokens | | Basin-asset entity (BAE) equity | Backing instrument for Module 3 (CORECM) ST22 tokens | | `custodied_balance` / `custodiedBalance` | Custody oracle field — module-agnostic | | ST22 Digital Securities | Token classification for issuer equity tokens | | GROO Utility Token | GROO — explicitly NOT a security | | Groovy Security Token (STO) | Groovy Company, Inc. Common Class B share offering | | Empire Stock Transfer | Qualified custodian and sole investor onboarding authority | | CEDEX | Compliant Exchange for Digital Securities | | cedex.market | Trading venue URL | | rwatokens.net | Platform URL | | Legal Counsel | Legal advisory role (generic) | | OTCID | OTC Markets tier (replaces Pink Current) | | Transfer Hook | SPL Token-2022 compliance mechanism | | Reg D | Regulation D — US accredited investors (6-month holding period) | | Reg S | Regulation S — non-US investors (12-month holding period) | | Reg CF | Regulation Crowdfunding — US retail (12-month holding period; FINRA-registered funding portal partnership) | | NAV oracle | Module 2 oracle holding appraised Net Asset Value | | Classification oracle | Module 3 oracle holding USGS / DOE / federal-action status | | Federal-action freeze | Module 3 Control 42 variant with 60-minute SLA | **Never use (obsolete or prohibited)** | Prohibited Term | Correct Term | Why | | ---------------------------------------------- | ------------------------------------------ | ---------------------------------------------------------------- | | OTCM Protocol | RWA Tokens | Platform rebranded May 1, 2026 | | OTCM Protocol Inc. (as platform entity) | Groovy Company, Inc. | OTCM Protocol Inc. (FL) is a separate entity Frank is evaluating | | `dba OTCM Protocol` | Groovy Company, Inc. (no dba) | dba was cancelled May 1, 2026 | | `@otcm-protocol/sdk` | `@rwatokens/sdk` | SDK package renamed | | `OtcmClient` | `RwaTokensClient` | SDK client class renamed | | `OtcmError` | `RwaTokensError` | SDK error class renamed | | `common_b_balance` | `custodied_balance` | Module-agnostic field naming | | `commonBBalance` | `custodiedBalance` | Module-agnostic field naming | | Series M / Preferred Series M | Common Class B | SEC Crypto Task Force March 2026 directive | | Security Meme Token / SMT | ST22 Digital Securities | Terminology obsolete | | Howey Shield | *(removed entirely)* | Framework obsolete | | OTCM.VIP / cedex.otcm.io | cedex.market | URL obsolete | | otcm.io (platform site) | rwatokens.net | URL obsolete | | Pink Current | OTCID | OTC Markets renamed | | GROO STO / OTCM STO | GROO Utility Token / Groovy Security Token | GROO is a utility token; the STO is the Groovy Security Token | | OTCM Security Token | Groovy Security Token (STO) | Renamed alongside platform brand | | / | | Email domain updated | | | | Email domain updated | | | | Email domain updated | | Jeff Turner / JDT Legal / CLO | Legal Counsel | Attribution retired | | Berj Abajian / former CEO | *(removed entirely)* | Terminated for Cause effective May 1, 2026 | | John Morgan | *(removed entirely)* | No longer on team | | Rule 506(c) / Reg D 506(c) / 506(c) qualifier | Reg D | Standard phrasing is just "Reg D" — never paired with 506(c) | | "illiquid OTC microcap" / distress framing | Professional capability framing | No distress narratives | | "trapped shareholders" | Capability-led framing | Lead with infrastructure, not broken markets | | OTCM Protocol → RWA Tokens transition language | *(no transition language)* | Treat the platform brand as established | *** ### 9. Security-Critical Contributions #### 9.1 What Is Security-Critical? Any change that touches: * Transfer Hook control logic (any of the 42 controls). * **Module 2 NAV-deviation extension** — CB-21 NAV variant logic, NAV oracle verification, NAV staleness handling. * **Module 3 federal-action freeze coordination** — REG-42 federal variant logic, Classification oracle verification, federal-action detection and SLA handling. * CPMM arithmetic (`calculate_output_amount` and related functions). * Fee routing or distribution. * Oracle verification (Ed25519, staleness, consensus) — including NAV oracle (Module 2) and Classification oracle (Module 3). * Key management (multi-sig, upgrade authority, appraiser key registry, Classification relay authority). * PDA derivation seeds. * Error code definitions or behavior. * Account schema changes. * Holding-period regimes (Reg D, Reg S, Reg CF) and constants. #### 9.2 Security-Critical PR Requirements | Requirement | Standard PR | Security-Critical PR | | ------------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | Reviewers | 1 maintainer | CTO + 2 maintainers | | Unit tests | Required | Required — 100% coverage of changed paths (including module-aware paths) | | Integration tests | Required | Required — Module 1, Module 2, and Module 3 lifecycle tests must pass as applicable | | Fuzz testing | Not required | Required — 100,000 runs on affected target (`transfer_hook_fuzz`, `cpmm_fuzz`, `nav_deviation_fuzz`, `classification_fuzz` as applicable) | | Formal verification | Not required | **Required — all 6 Certora invariants must re-pass; E.4 covers module-aware extensions** | | Security review | Not required | **Required — documented threat assessment** | | Changelog | If user-facing | Always | | Audit impact | N/A | Must document: "Does this change invalidate any existing audit finding from Quantstamp, Halborn, or OtterSec?" | #### 9.3 Security-Critical PR Template Addition Security-critical PRs must include this additional section: ```markdown ## Security Assessment ### Threat Analysis ### Control Impact ### Module Scope ### Invariant Impact ### Audit Impact ### Formal Verification - [ ] All 6 Certora invariants re-verified on the new code - [ ] Certora output attached to PR ``` #### 9.4 Vulnerability Reporting **DO NOT** report security vulnerabilities in public GitHub issues. | Channel | Contact | | ------------ | ------------------------------------------- | | Email | | | Encrypted | PGP key at rwatokens.net/security/pgp | | Response SLA | Acknowledgment: 24 hours. Triage: 72 hours. | | Bug bounty | Up to $100,000 for critical vulnerabilities | See **Security Model — Responsible Disclosure** for full details. *** ### 10. Issue Reporting #### 10.1 Bug Reports Use the `Bug Report` issue template: ```markdown **Describe the bug** Clear, concise description. **To Reproduce** 1. Step one 2. Step two 3. Error observed **Expected behavior** What should have happened. **Module Scope** - Cross-module / Module 1 / Module 2 / Module 3 **Environment** - OS: [e.g., Ubuntu 24.04] - Rust: [e.g., 1.75.0] - Solana CLI: [e.g., 1.18.x] - Anchor: [e.g., 0.30.x] - Cluster: [localnet / devnet / mainnet] **Logs / Error output** ``` #### 10.2 Feature Requests Use the `Feature Request` issue template. Include: * Problem statement (what's missing or painful). * Proposed solution. * Which layer(s) and which module(s) affected. * Security implications (if any). #### 10.3 Labels | Label | Meaning | | ------------------ | ---------------------------------------------------------------------------- | | `good-first-issue` | Suitable for new contributors | | `bug` | Confirmed bug | | `feature` | New functionality | | `security` | Security-sensitive (restricted visibility) | | `P0-critical` | Production impact — immediate response | | `P1-high` | Significant but not production-blocking | | `layer-2` | Affects Transfer Hook | | `layer-4` | Affects AMM | | `layer-6` | Affects Oracle Network | | `module-1` | Affects Module 1 (Equities) | | `module-2` | Affects Module 2 (Real Estate) — NAV oracle / NAV-deviation extension | | `module-3` | Affects Module 3 (CORECM) — Classification oracle / federal-action extension | | `cross-module` | Affects all three modules | | `sdk` | SDK change | | `docs` | Documentation | | `needs-certora` | Requires formal re-verification | *** ### 11. Review Criteria #### 11.1 Approval Matrix | Change Scope | Required Approvers | CI Gates | | ------------------------------ | --------------------- | ------------------------------------------ | | Documentation only | 1 maintainer | Lint | | Tests only | 1 maintainer | Unit + integration | | SDK / API | 1 maintainer | Unit + integration + lint | | Infrastructure | 1 maintainer + DevOps | Unit + lint | | Feature (non-security) | 1 maintainer + CTO | Full test suite | | Bug fix (security) | CTO + 2 maintainers | Full suite + fuzz | | Transfer Hook change | CTO + 2 maintainers | Full suite + fuzz + Certora | | Module 2 NAV-extension change | CTO + 2 maintainers | Full suite + fuzz + Certora | | Module 3 federal-action change | CTO + 2 maintainers | Full suite + fuzz + Certora | | AMM / Pool change | CTO + 2 maintainers | Full suite + fuzz + Certora | | Release | CTO + 2 maintainers | Full suite + fuzz + Certora + load + chaos | #### 11.2 Merge Rules * **Squash merge** for all PRs to `develop` (clean commit history). * **Merge commit** for `release/*` → `main` (preserve release structure). * **Delete branch** after merge (automatic). * **No force push** on `develop` or `main`. #### 11.3 Stale PRs PRs with no activity for 14 days receive a `stale` label and a comment. After 7 more days, they are closed. Re-open by commenting. *** ### 12. License The platform is released under the **Business Source License 1.1 (BSL 1.1)**. * Source code is viewable and auditable by anyone. * Production use requires a commercial license from Groovy Company, Inc. * After the Change Date (specified in `LICENSE`), the code converts to Apache 2.0. * Contributions are licensed under the same terms. By submitting a pull request, you agree that your contribution is licensed under the BSL 1.1 and that you have the right to license the contribution. *** ### Quick Reference ``` SETUP: git clone → yarn install → anchor build → anchor test BRANCH: fix/142-description or feat/205-description COMMIT: fix(hook): correct wallet limit boundary at exactly 4.99% SCOPE: hook | amm | pool | gov | oracle | nav (M2) | classification (M3) PR: Fill template → CI passes → 1+ approval → squash merge Tag Module Impact: cross-module / M1 / M2 / M3 STYLE: cargo fmt + cargo clippy (zero warnings) + prettier + eslint SECURITY: Touches L2 / L4 / L6 / NAV / Classification? → CTO + 2 reviewers + Certora TERMINOLOGY: Common Class B (M1). SAE equity (M2). BAE equity (M3). GROO Utility Token (not STO). Groovy Security Token (STO). custodied_balance, not common_b_balance. Reg D / Reg S / Reg CF — never "506(c)". REPORT VULN: security@rwatokens.net (NEVER in public issues) ``` *** ### Related Documentation * **Deployment Guide** — Build, deploy, verify procedures (module-specific oracle initialization). * **Testing Guide** — Test methodology and coverage requirements (module-aware fuzz, integration, chaos). * **Smart Contract Reference** — Program specifications with module-aware program behavior. * **Transfer Hook Reference** — Standalone reference for the 42 controls including module-aware extensions. * **Security Model** — Threat model and vulnerability reporting (module-specific threat surfaces). * **Architecture Decisions** — ADRs covering cross-module and module-specific decisions. * **Oracle Integration Guide** — Custody, OFAC, AML, TWAP, EDGAR (M1), NAV (M2), Classification (M3) relay architecture. * **Governance Deep Dive** — Module-aware governance surface and Control 42 federal-action variant. *** *RWA Tokens · Contributing Guide · Groovy Company, Inc.* --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://bitbook.rwatokens.net/sdk-and-development/sdk-and-development/contributing.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.