Merge pull request #208 from PracticalParticle/dev

Dev

Author: JaCoderX

.github/workflows/particle-ci.yml

@@ -19,11 +19,11 @@ jobs:
       - name: Checkout code
         uses: actions/checkout@v4
 
-      # Step 2: Setup Node.js (must satisfy engines.node >=18.20.5 with engine-strict)
+      # Step 2: Setup Node.js (must satisfy root engines.node with engine-strict)
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
+          node-version: '22'
           cache: 'npm'
 
       # Step 3: Install dependencies

.github/workflows/release-please.yml

@@ -17,22 +17,13 @@ jobs:
     outputs:
       release_created: ${{ steps.release.outputs.release_created }}
       tag_name: ${{ steps.release.outputs.tag_name }}
-    
+
     steps:
       - name: Checkout code
         uses: actions/checkout@v4
         with:
           fetch-depth: 0
 
-      - name: Setup Node.js
-        uses: actions/setup-node@v4
-        with:
-          node-version: '20'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
-
       - name: Run release-please
         id: release
         uses: google-github-actions/release-please-action@v4

.github/workflows/sync-contract-versions.yml

@@ -26,11 +26,7 @@ jobs:
       - name: Setup Node.js
         uses: actions/setup-node@v4
         with:
-          node-version: '20'
-          cache: 'npm'
-
-      - name: Install dependencies
-        run: npm ci
+          node-version: '22'
 
       - name: Verify EngineBlox.VERSION mirror
         run: node scripts/sync-versions.cjs --verify

CONTRIBUTING.md

@@ -58,7 +58,7 @@ Maintainers merge contributions at their discretion. Opening a PR does not creat
 
 ## Core Contracts (`contracts/core/`)
 
-The core protocol library under `contracts/core/` is the **audited source of truth** for Bloxchain behavior. It has undergone **external security review**; changes affect deployed security assumptions and require controlled release management.
+The core protocol library under `contracts/core/` is the **audited source of truth** for Bloxchain behavior. It has been independently audited by **Nethermind** (report [NM_0828](audits/nethermind/)); see **[contracts/core/AUDIT.md](contracts/core/AUDIT.md)** for scope, the published report, and change policy. Changes affect deployed security assumptions and require controlled release management.
 
 ### Who may change core
 
@@ -151,7 +151,7 @@ By signing off, you certify the DCO terms (original work or right to submit, per
 
 Before contributing, ensure you have:
 
-- **Node.js** (v16 or higher)
+- **Node.js** **>=22.12.0** for monorepo development (root `engines`; matches `@commitlint/cli` 21.x). SDK **consumers** need **>=18.20.5** at runtime per `sdk/typescript/package.json`.
 - **npm** (v8 or higher)
 - **Truffle** (v5.15 or higher)
 - **Git** (latest version)
@@ -391,7 +391,7 @@ npm run test:coverage
 
 ## Documentation
 
-**Source of truth:** Solidity contracts are the source of truth for protocol API and behavior. The `docs/` directory is generated from contract NatSpec; do not edit those generated files by hand. For the full documentation map, updating process, and audit checklist, see **[CODEBASE_DOCUMENTATION.md](CODEBASE_DOCUMENTATION.md)**.
+**Source of truth:** Solidity contracts are the source of truth for protocol API and behavior. The `docs/` directory is generated from contract NatSpec; do not edit those generated files by hand. For reviewer context and audit scope, see **[TECHNICAL_OVERVIEW.md](TECHNICAL_OVERVIEW.md)** and **[contracts/core/AUDIT.md](contracts/core/AUDIT.md)**; published third-party reports live under **[audits/](audits/README.md)**.
 
 ### Contract Documentation
 - **NatSpec comments** for all public functions

README.md

@@ -7,7 +7,7 @@
 [![Sepolia](https://img.shields.io/badge/Sepolia-Testnet-purple.svg)](https://sepolia.etherscan.io/)
 [![Particle CS](https://img.shields.io/badge/Particle-CS-blue.svg)](https://particlecs.com/)
 
-> **Security audit status:** A third-party security audit of the protocol smart contracts is in progress; no independent audit report has been published yet.
+> **Core audit:** [`contracts/core/`](./contracts/core/) independently audited by [Nethermind](./audits/nethermind/). Report: [`Nethermind-Bloxchain-Core-NM_0828.pdf`](./audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf) · [details](./contracts/core/AUDIT.md). **Network:** pre-mainnet today; mainnet deployment coming soon. Security: [SECURITY.md](./SECURITY.md).
 
 ## System overview
 
@@ -131,7 +131,7 @@ Two workflow patterns share the same **PENDING → EXECUTING → terminal** prog
 
 ## 🚀 Quick Start
 
-**Prerequisites:** Node.js **>=18.20.5** (required for published `@bloxchain/sdk` ESM JSON import attributes; enforced via `engines` + `.npmrc` `engine-strict=true`)
+**Prerequisites:** Node.js **>=22.12.0** for this monorepo (dev tooling, CI, `npm ci`; enforced via root `engines` + `.npmrc` `engine-strict=true`). Published **`@bloxchain/sdk`** consumers still need **>=18.20.5** at runtime (see `sdk/typescript/package.json`).
 
 ```bash
 git clone https://github.com/PracticalParticle/Bloxchain-Protocol.git
@@ -213,7 +213,7 @@ npm run test:foundry:fuzz
 
 ## 🔧 Development Tools
 
-Requires Node.js **>=18.20.5** (maintenance/security floor for SDK ESM; see `engines` in `package.json`).
+Requires Node.js **>=22.12.0** for repo development (see root `package.json` `engines`). SDK runtime floor for npm consumers remains **>=18.20.5** in `sdk/typescript/package.json`.
 
 ```bash
 npm run compile:foundry          # compile; add :size for 24KB check
@@ -228,7 +228,7 @@ npm run docgen                  # docs
 
 ## 📚 Documentation
 
-- **[Codebase documentation process & audit checklist](CODEBASE_DOCUMENTATION.md)** – Source of truth, how to update docs, audit-ready checklist
+- **[Core audit & change policy](contracts/core/AUDIT.md)** · **[Nethermind report](audits/nethermind/)** · **[Technical overview](TECHNICAL_OVERVIEW.md)** – Source of truth, reviewer context, published audit
 - **[Versioning & releases](docs/VERSIONING.md)** – npm packages, on-chain `EngineBlox.VERSION`, Release Please
 - [Protocol Architecture](./docs/bloxchain-architecture.md) · [State Machine](./docs/state-machine-engine.md) · [Getting Started](./docs/getting-started.md) · [API Reference](./docs/api-reference.md) · [SecureOwnable](./docs/secure-ownable.md) · [RuntimeRBAC](./docs/runtime-rbac.md) · [Best Practices](./docs/best-practices.md) · [Examples](./docs/examples-basic.md)
 - **Contract API (generated):** [docs/](docs/) – generated from Solidity NatSpec via `npm run docgen`

SECURITY.md

@@ -2,16 +2,18 @@
 
 ## Supported Versions
 
-**⚠️ IMPORTANT: Bloxchain Protocol is currently in testing phase and not yet live on mainnet.**
+**⚠️ IMPORTANT: Bloxchain Protocol is not yet live on Ethereum mainnet.** Testnet validation continues; **mainnet deployment is planned soon.**
 
 We actively maintain security updates for the following versions:
 
 | Version | Supported          | Status |
 | ------- | ------------------ | ------ |
-| 1.0.x   | :white_check_mark: | Testing phase (third-party audit in progress) |
+| 1.0.x   | :white_check_mark: | Pre-mainnet; core audited by Nethermind (see below) |
 | < 1.0   | :x:                | End of life |
 
-**Note**: A third-party security audit of the protocol smart contracts is in progress; no independent audit report has been published yet. This security policy will become fully effective after third-party audit completion, which will mark the official launch of version 1.0.0.
+**Core smart contracts (`contracts/core/`):** Independently audited by **Nethermind** ([audit index](audits/README.md), [report PDF](audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf), [core policy](contracts/core/AUDIT.md)). The audit applies to the commit recorded in [audits/nethermind/README.md](audits/nethermind/README.md) (see the report PDF for the exact SHA). Later changes to core are outside that report until a re-audit or addendum.
+
+Examples, community contracts, and application code under `contracts/examples/` and `contracts/community/` are **not** covered by that engagement.
 
 ## Reporting a Vulnerability
 
@@ -72,36 +74,49 @@ Our State Abstraction framework implements multiple layers of security:
 ### Security Best Practices
 
 #### For Developers
-- Always use the latest version of our contracts
+- Always use the latest supported version of our contracts
 - Implement proper access controls using our RBAC system
 - Follow our secure development guidelines
 - Test thoroughly using our provided test suites
+- Pin releases and verify them against the [audited core commit](audits/nethermind/README.md) before production use
 
 #### For Auditors
-- Review our security architecture documentation
-- Focus on the EngineBlox library core functions
+- Start with [contracts/core/AUDIT.md](contracts/core/AUDIT.md) and the [Nethermind report](audits/nethermind/)
+- Review [TECHNICAL_OVERVIEW.md](TECHNICAL_OVERVIEW.md) and the EngineBlox library
 - Verify multi-signature workflow implementations
 - Check meta-transaction signature validation
 
 ## Security Audit Status
 
-A third-party security audit of the protocol smart contracts is in progress; no independent audit report has been published yet.
+### Third-party audit (core)
+
+| Item | Status |
+|------|--------|
+| **Auditor** | Nethermind |
+| **Scope** | `contracts/core/` |
+| **Report** | [audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf](audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf) (NM_0828) |
+| **Engagement details** | [audits/nethermind/README.md](audits/nethermind/README.md) |
+
+### Deployment and launch
+
+| Item | Status |
+|------|--------|
+| **Mainnet** | Not live yet; deployment planned soon |
+| **Development** | Testing and validation on testnets (e.g. Sepolia) |
+| **Bug bounty** | Program details to be announced around mainnet launch |
 
-### Current Status
-- **Development Phase**: Testing and validation ongoing
-- **Third-Party Security Audit**: In progress (report not yet published)
-- **Official Launch**: After third-party audit completion
+### Completed reviews
 
-### Completed Reviews
-- **Internal Security Review**: Completed (v1.0.0)
-- **Code Review**: Ongoing with each release
+- **Nethermind (core):** Completed — see [audits/nethermind/](audits/nethermind/)
+- **Internal security review:** Ongoing with releases
+- **Code review:** Ongoing with each release
 
 ## Bug Bounty Program
 
-We are developing a bug bounty program for security researchers. Details will be announced after third-party audit completion and the official launch of version 1.0.0.
+We are developing a bug bounty program for security researchers. Details will be announced in coordination with **mainnet deployment**.
 
 ### Scope
-- Smart contract vulnerabilities
+- Smart contract vulnerabilities in **audited core** (`contracts/core/`) at the published commit
 - Protocol design flaws
 - Implementation bugs
 - Cryptographic weaknesses
@@ -111,6 +126,7 @@ We are developing a bug bounty program for security researchers. Details will be
 - Physical security issues
 - Issues in third-party dependencies
 - Issues in experimental features
+- Example and community contracts unless explicitly listed in a future program scope
 
 ## Security Updates
 
@@ -145,4 +161,4 @@ We appreciate the security research community's efforts to help keep Bloxchain P
 
 *This security policy is subject to updates. Please check back regularly for the latest information.*
 
-**Last Updated**: May 2026
+**Last Updated**: June 2026

TECHNICAL_OVERVIEW.md

@@ -34,6 +34,10 @@ This document provides:
 
 **For AI auditors**: Use this as the primary context document. Cross-reference each invariant and restriction with the Codex (section and vector ID) to confirm test coverage and protection status.
 
+### Published third-party audit (core)
+
+`contracts/core/` was independently audited by **Nethermind** (report NM_0828). Index: [audits/nethermind/README.md](audits/nethermind/README.md) · PDF: [Nethermind-Bloxchain-Core-NM_0828.pdf](audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf) · Policy: [contracts/core/AUDIT.md](contracts/core/AUDIT.md). Record the audited git commit from the report on the engagement README; changes after that commit are outside the report until re-audit.
+
 ### Quick Reference: File → Primary Responsibility
 
 | File | Responsibility |
@@ -265,6 +269,8 @@ The file **test/foundry/docs/ATTACK_VECTORS_CODEX.md** is the authoritative list
 
 Use **ATTACK_VECTORS_CODEX.md** for the full list of vector IDs, locations, and related tests.
 
+For the formal third-party report, see **[audits/nethermind/](audits/nethermind/README.md)** (complements this document; does not replace it).
+
 ---
 
-*This technical overview is the single source of context for the Bloxchain core protocol. For threat coverage and test references, always cross-check with the Attack Vectors Codex.*
+*This technical overview is the single source of context for the Bloxchain core protocol. For threat coverage and test references, cross-check with the Attack Vectors Codex; for Nethermind engagement scope and report, see [audits/](audits/README.md).*

audits/README.md

@@ -0,0 +1,22 @@
+# Security audits
+
+Third-party and published security reviews for Bloxchain Protocol.
+
+## Published audits
+
+| Auditor | Report ID | Scope | Summary | Report |
+|---------|-----------|-------|---------|--------|
+| [Nethermind](https://nethermind.io/) | NM_0828 | [`contracts/core/`](../contracts/core/) | Independent review of the core protocol library | [Engagement page](./nethermind/README.md) · [PDF](./nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf) |
+
+## Not covered by the Nethermind engagement
+
+- [`contracts/examples/`](../contracts/examples/) — per-file licenses; not core MPL assurance
+- [`contracts/community/`](../contracts/community/) — community-maintained; not maintainer-audited
+- [`contracts/components/`](../contracts/components/) — official components; outside NM_0828 scope unless a future report states otherwise
+- TypeScript SDK, deployment scripts, and example applications
+
+For core-specific policy and change rules, see [`contracts/core/AUDIT.md`](../contracts/core/AUDIT.md).
+
+## Security contact
+
+Report vulnerabilities per [`SECURITY.md`](../SECURITY.md) — **security@particlecs.com** (do not use public issues for undisclosed flaws).

audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf

@@ -0,0 +1,45 @@
+# Nethermind audit — Bloxchain core (`contracts/core/`)
+
+| Field | Value |
+|-------|--------|
+| **Auditor** | [Nethermind](https://nethermind.io/) |
+| **Report ID** | NM_0828 |
+| **Scope** | All Solidity under [`contracts/core/`](../../contracts/core/) |
+| **Full report** | [`Nethermind-Bloxchain-Core-NM_0828.pdf`](./Nethermind-Bloxchain-Core-NM_0828.pdf) |
+
+## Status
+
+- **Audit:** Completed by Nethermind for the in-scope core tree.
+- **Report in repository:** [`Nethermind-Bloxchain-Core-NM_0828.pdf`](./Nethermind-Bloxchain-Core-NM_0828.pdf)
+- **Audited commit:** _Record the git commit SHA from the report here when maintaining this page._
+
+## Scope (in-repo paths)
+
+| Path | Role |
+|------|------|
+| `lib/EngineBlox.sol` | State machine, RBAC, meta-tx, payments |
+| `base/BaseStateMachine.sol` | `_secureState`, EngineBlox wrappers |
+| `security/SecureOwnable.sol` | Owner, broadcaster, recovery, timelock |
+| `access/RuntimeRBAC.sol` | Dynamic roles and batch config |
+| `execution/GuardController.sol` | Guarded execution and config |
+| `pattern/Account.sol` | Composition of core components |
+| `lib/utils/SharedValidation.sol` | Shared errors and validation |
+| `*/lib/definitions/*Definitions.sol` | Function schemas and default permissions |
+| `*/interface/*.sol` | Core interfaces |
+
+## Out of scope
+
+Examples, community contracts, components, standards, SDK, and deployment tooling — see [`../README.md`](../README.md).
+
+## Using this audit
+
+1. Read [`Nethermind-Bloxchain-Core-NM_0828.pdf`](./Nethermind-Bloxchain-Core-NM_0828.pdf) for findings, severities, and the **exact commit** audited.
+2. Update the **Audited commit** line above with that SHA.
+3. Compare your deployment or fork to that commit; changes to `contracts/core/` after that commit are **outside** the report until a re-audit or addendum.
+4. For maintainer change policy and vulnerability reporting, see [`../../contracts/core/AUDIT.md`](../../contracts/core/AUDIT.md) and [`../../SECURITY.md`](../../SECURITY.md).
+
+## Related documentation
+
+- [`../../contracts/core/AUDIT.md`](../../contracts/core/AUDIT.md) — core audit notice and contribution alignment
+- [`../../TECHNICAL_OVERVIEW.md`](../../TECHNICAL_OVERVIEW.md) — technical map for reviewers
+- [`../../test/foundry/docs/ATTACK_VECTORS_CODEX.md`](../../test/foundry/docs/ATTACK_VECTORS_CODEX.md) — internal test-backed threat catalog (separate from this third-party report)