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. 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

# Clone the repository (URL published in Network Configuration)
git clone <RWA_TOKENS_REPO_URL>
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):

// .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

<type>/<issue-number>-<short-description>

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

<type>(<scope>): <description>

[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:

## Description
<!-- What does this PR do? Why is it needed? -->

## Type
<!-- fix / feat / docs / test / refactor / perf / chore / security -->

## Layer Impact
<!-- Which layers of the nine-layer stack does this touch? -->
- [ ] 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
<!-- Which production module(s) does this change affect? -->
- [ ] 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
<!-- Does this change affect any Transfer Hook control, oracle verification,
     CPMM arithmetic, fee routing, key management, or module-aware
     extensions (Module 2 NAV-deviation, Module 3 federal-action freeze)? -->
- [ ] No security impact
- [ ] Security impact — requires security review (describe below)

## Testing
<!-- What tests were added or modified? -->
- [ ] 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

# Format check (must pass CI)
cargo fmt --all -- --check

# Lint check (must pass CI — zero warnings)
cargo clippy --workspace -- -D warnings

Key conventions:

// 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

# Format (must pass CI)
yarn prettier --check "**/*.ts"

# Lint (must pass CI — zero errors)
yarn eslint "**/*.ts"

Key conventions:

// Explicit types on public API boundaries
export async function getSecurityConfig(mint: PublicKey): Promise<SecurityConfig> {
  // ...
}

// 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<TransferHookStatus> {
  // ...
}

7.3 Tests

// 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:

/// 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
[e-mail] / [e-mail]	[e-mail]	Email domain updated
[e-mail]	[e-mail]	Email domain updated
[e-mail]	[e-mail]	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:

## Security Assessment

### Threat Analysis
<!-- What attack vectors does this change introduce, modify, or mitigate? -->

### Control Impact
<!-- Which of the 42 Transfer Hook controls are affected? List by ID. -->
<!-- Module 2: does this affect the CB-21 NAV-deviation extension? -->
<!-- Module 3: does this affect the REG-42 federal-action freeze coordination? -->

### Module Scope
<!-- Cross-module / Module 1 / Module 2 / Module 3 specific. -->

### Invariant Impact
<!-- Which Certora invariants (E.1–E.6) are affected? -->
<!-- E.4 covers module-aware extensions; verify NAV-deviation and federal-action
     enforcement are preserved. -->

### Audit Impact
<!-- Does this change invalidate any finding from Quantstamp, Halborn, or OtterSec? -->

### 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	[e-mail]
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:

**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:  [e-mail] (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.