PracticalParticle · ElectroCoderX · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026 · Aug 17, 2026
diff --git a/.github/dependabot.yml b/.github/dependabot.yml
@@ -26,6 +26,11 @@ updates:
     schedule:
       interval: "weekly"
     target-branch: "dev"
+    ignore:
+      # docgen intentionally remains on the isolated Hardhat 2.x toolchain.
+      - dependency-name: "hardhat"
+        update-types:
+          - "version-update:semver-major"
 
   # Published contract package
   - package-ecosystem: "npm"

diff --git a/.github/requirements/README.md b/.github/requirements/README.md
@@ -0,0 +1,19 @@
+# Security analyzer lockfiles
+
+Particle CI installs Slither and Mythril from hash-verified lockfiles so manual
+security scans do not resolve mutable transitive dependencies at run time.
+
+- `slither.in` is the direct dependency input for `slither.txt`.
+- `mythril.in` records the direct Mythril pin and its `pytest-cov` compatibility
+  constraint.
+- `mythril-resolved.in` is the Python 3.10 resolved graph used to generate
+  `mythril.txt`. Mythril 0.24.8 requires `coverage<7`, so unconstrained current
+  `pytest-cov` releases are incompatible.
+
+Regenerate the `.txt` files with Python 3.10 and `pip-compile
+--generate-hashes`. Verify them by installing with:
+
+```bash
+python -m pip install --require-hashes -r .github/requirements/slither.txt
+python -m pip install --require-hashes -r .github/requirements/mythril.txt
+```
diff --git a/.github/requirements/mythril-resolved.in b/.github/requirements/mythril-resolved.in
@@ -0,0 +1,92 @@
+asn1crypto==1.5.1
+bitarray==3.10.1
+blake2b-py==0.3.2
+cached-property==1.5.2
+certifi==2026.7.22
+cffi==2.1.1
+cfgv==3.5.0
+charset-normalizer==3.5.1
+ckzg==1.0.2
+coincurve==21.0.0
+coloredlogs==15.0.1
+configparser==7.2.0
+contourpy==1.3.2
+coverage==6.5.0
+cycler==0.12.1
+cytoolz==1.1.0
+dictionaries==0.0.2
+distlib==0.4.3
+eth-abi==4.2.1
+eth-account==0.11.3
+eth-bloom==1.0.4
+eth-hash==0.3.3
+eth-keyfile==0.8.1
+eth-keys==0.4.0
+eth-rlp==0.3.0
+eth-typing==3.5.2
+eth-utils==2.3.2
+ethereum_input_decoder==0.2.2
+exceptiongroup==1.3.1
+filelock==3.32.3
+fonttools==4.63.0
+hexbytes==0.2.3
+humanfriendly==10.0
+identify==2.6.19
+idna==3.18
+importlib_resources==7.1.0
+iniconfig==2.3.0
+Jinja2==3.1.6
+joblib==1.5.3
+kiwisolver==1.5.0
+lru-dict==1.4.1
+MarkupSafe==2.0.1
+matplotlib==3.10.6
+mock==5.2.0
+mypy_extensions==0.4.4
+mythril==0.24.8
+nodeenv==1.10.0
+numpy==2.2.6
+packaging==26.3
+parsimonious==0.9.0
+persistent==6.7
+pillow==12.3.0
+platformdirs==4.11.3
+pluggy==1.6.0
+pre-commit==2.20.0
+py-ecc==1.4.7
+py-evm==0.7.0a1
+py-flags==1.1.4
+py-solc==3.2.0
+py-solc-x==1.1.1
+pycparser==3.0
+pycryptodome==3.23.0
+pyethash==0.1.27
+Pygments==2.21.0
+pyparsing==2.4.7
+pytest==9.1.1
+pytest-cov==4.1.0
+pytest-mock==3.15.1
+python-dateutil==2.9.0.post0
+python-discovery==1.5.2
+PyYAML==6.0.3
+regex==2026.7.19
+requests==2.34.2
+rlp==3.0.0
+scikit-learn==1.7.2
+scipy==1.15.3
+semantic-version==2.10.0
+six==1.17.0
+sortedcontainers==2.4.0
+threadpoolctl==3.6.0
+toml==0.10.2
+tomli==2.4.1
+toolz==1.1.0
+transaction==5.1
+trie==2.2.0
+typing_extensions==4.16.0
+urllib3==2.7.0
+virtualenv==21.7.4
+z3-solver==4.12.5.0
+zope.deferredimport==6.1.1
+zope.interface==8.5
+zope.proxy==7.2
diff --git a/.github/requirements/mythril.in b/.github/requirements/mythril.in
@@ -0,0 +1,3 @@
+mythril==0.24.8
+# Mythril caps coverage below 7; newer pytest-cov releases require coverage 7+.
+pytest-cov==4.1.0
diff --git a/.github/requirements/mythril.txt b/.github/requirements/mythril.txt
diff --git a/.github/requirements/slither.in b/.github/requirements/slither.in
@@ -0,0 +1 @@
+slither-analyzer==0.11.6
diff --git a/.github/requirements/slither.txt b/.github/requirements/slither.txt
diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml
@@ -26,15 +26,15 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/init@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
         with:
           languages: javascript-typescript
           build-mode: none
 
       - name: Perform CodeQL analysis
-        uses: github/codeql-action/analyze@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/analyze@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
diff --git a/.github/workflows/dco-signoff.yml b/.github/workflows/dco-signoff.yml
@@ -17,7 +17,7 @@ jobs:
     if: github.actor != 'dependabot[bot]'
     steps:
       - name: Checkout pull request head
-        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.sha }}
           fetch-depth: 0

diff --git a/.github/workflows/particle-ci.yml b/.github/workflows/particle-ci.yml
@@ -18,12 +18,12 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '22'
           cache: 'npm'
@@ -52,12 +52,10 @@ jobs:
         if: github.event_name == 'workflow_dispatch'
         run: |
           python -m venv .venv-slither
-          .venv-slither/bin/python -m pip install --upgrade pip
-          .venv-slither/bin/python -m pip install slither-analyzer==0.11.6
+          .venv-slither/bin/python -m pip install --require-hashes -r .github/requirements/slither.txt
 
           python -m venv .venv-mythril
-          .venv-mythril/bin/python -m pip install --upgrade pip
-          .venv-mythril/bin/python -m pip install mythril==0.24.8
+          .venv-mythril/bin/python -m pip install --require-hashes -r .github/requirements/mythril.txt
 
       - name: Run Slither
         if: github.event_name == 'workflow_dispatch'

diff --git a/.github/workflows/scorecard.yml b/.github/workflows/scorecard.yml
@@ -21,7 +21,7 @@ jobs:
 
     steps:
       - name: Checkout code
-        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           persist-credentials: false
 
@@ -40,6 +40,6 @@ jobs:
           retention-days: 5
 
       - name: Upload to code-scanning
-        uses: github/codeql-action/upload-sarif@e46ed2cbd01164d986452f91f178727624ae40d7 # v4.35.3
+        uses: github/codeql-action/upload-sarif@ff2f1c621b7f889edc0d3c761ac2e6a3f8cdb0dd # v4.37.7
         with:
           sarif_file: results.sarif
diff --git a/.github/workflows/sync-contract-versions.yml b/.github/workflows/sync-contract-versions.yml
@@ -18,14 +18,14 @@ jobs:
 
     steps:
       - name: Checkout PR branch
-        uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           ref: ${{ github.event.pull_request.head.ref }}
           fetch-depth: 0
           persist-credentials: false
 
       - name: Setup Node.js
-        uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020 # v4
+        uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
         with:
           node-version: '22'
 

diff --git a/README.md b/README.md
@@ -1,31 +1,16 @@
 <p align="center">
   <a href="https://github.com/PracticalParticle/Bloxchain-Protocol">
-    <img src="./docs/assets/logo-lockup-light.svg#gh-light-mode-only" alt="Bloxchain" width="100%">
-    <img src="./docs/assets/logo-lockup-dark.svg#gh-dark-mode-only" alt="Bloxchain" width="100%">
+    <img src="./docs/assets/logo-lockup-dark.svg" alt="Bloxchain" width="100%">
   </a>
 </p>
 
 # Bloxchain Protocol
 
-**Composable security framework for governed Ethereum applications.**
+**Open-source composable security framework for governed Ethereum applications.**
 
 Build on-chain security and authorization rules into vaults, tokens, payments, and governed accounts.
 
-[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0)
-[![Audited by Nethermind](./docs/assets/badge-audit-nethermind.svg)](./audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf)
-[![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/PracticalParticle/Bloxchain-Protocol/badge)](https://scorecard.dev/viewer/?uri=github.com/PracticalParticle/Bloxchain-Protocol)
-[![npm](https://img.shields.io/npm/v/@bloxchain/sdk.svg)](https://www.npmjs.com/package/@bloxchain/sdk)
-[![CI](https://github.com/PracticalParticle/Bloxchain-Protocol/actions/workflows/particle-ci.yml/badge.svg)](https://github.com/PracticalParticle/Bloxchain-Protocol/actions/workflows/particle-ci.yml)
-[![Docs](https://img.shields.io/badge/docs-bloxchain.app-yellow)](https://docs.bloxchain.app)
-[![Sepolia](https://img.shields.io/badge/Sepolia-Official_deployments-purple.svg)](https://sepolia.etherscan.io/)
-
-<p align="center">
-  <picture>
-    <source media="(prefers-color-scheme: dark)" srcset="./docs/assets/protocol-composition-dark.svg">
-    <source media="(prefers-color-scheme: light)" srcset="./docs/assets/protocol-composition-light.svg">
-    <img src="./docs/assets/protocol-composition-light.svg" alt="How the protocol fits together: shared rules engine, on-chain state, optional ownership roles and guards, full governed account, and example applications" width="920">
-  </picture>
-</p>
+[![License: MPL-2.0](https://img.shields.io/badge/License-MPL--2.0-blue.svg)](https://opensource.org/licenses/MPL-2.0) [![Audited by Nethermind](./docs/assets/badge-audit-nethermind.svg)](./audits/nethermind/Nethermind-Bloxchain-Core-NM_0828.pdf) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/PracticalParticle/Bloxchain-Protocol/badge)](https://scorecard.dev/viewer/?uri=github.com/PracticalParticle/Bloxchain-Protocol) [![npm](https://img.shields.io/npm/v/@bloxchain/sdk.svg)](https://www.npmjs.com/package/@bloxchain/sdk) [![CI](https://github.com/PracticalParticle/Bloxchain-Protocol/actions/workflows/particle-ci.yml/badge.svg)](https://github.com/PracticalParticle/Bloxchain-Protocol/actions/workflows/particle-ci.yml) [![Docs](https://img.shields.io/badge/docs-bloxchain.app-yellow)](https://docs.bloxchain.app) [![Sepolia](https://img.shields.io/badge/Sepolia-Official_deployments-purple.svg)](https://sepolia.etherscan.io/)
 
 **Install:** `npm install @bloxchain/sdk viem` (TypeScript) · `npm install @bloxchain/contracts` (Solidity) · [choose a path](#quick-start)
 
@@ -52,6 +37,17 @@ The optional hosted Console ([bloxchain.app](https://bloxchain.app)) uses the sa
 
 EngineBlox is the shared library. BaseStateMachine owns storage. SecureOwnable, RuntimeRBAC, and GuardController are **optional siblings** — most apps use a subset. The **Account** pattern composes all three. Example applications sit below as evidence, not as the product.
 
+<p align="center">
+  <img src="./docs/assets/protocol-composition-dark.svg" alt="How the protocol fits together: shared rules engine, on-chain state, optional ownership roles and guards, full governed account, and example applications" width="920">
+</p>
+
+**Composition (text):** EngineBlox → BaseStateMachine → optional SecureOwnable / RuntimeRBAC / GuardController → Account. Most apps use a subset; examples (vaults, payments, tokens, factories, Safe) sit below Account as evidence.
+
+Full diagrams: [Architecture](./docs/bloxchain-architecture.md) · [State machine](./docs/state-machine-engine.md) · [Technical overview](./TECHNICAL_OVERVIEW.md) · [Account pattern](./docs/account-pattern.md)
+
+<details>
+<summary><strong>Architecture graph (machine-readable)</strong></summary>
+
 ```mermaid
 graph TB
   EB["EngineBlox"]
@@ -69,7 +65,7 @@ graph TB
   GC --> ACC
 ```
 
-Full diagrams: [Architecture](./docs/bloxchain-architecture.md) · [State machine](./docs/state-machine-engine.md) · [Technical overview](./TECHNICAL_OVERVIEW.md) · [Account pattern](./docs/account-pattern.md)
+</details>
 
 <details>
 <summary><strong>Architecture guarantees (protocol engineers)</strong></summary>

diff --git a/docs/assets/README.md b/docs/assets/README.md
@@ -2,16 +2,21 @@
 
 Visual system for **Protocol README IA + Visual System Reset** — Particle monochrome figure with soft atmosphere; colorful OSS badges stay as industry-standard trust chips.
 
-| File | Purpose |
-|------|---------|
-| `logo-bloxchain.svg` | `[Bx]` mark alone (light) |
-| `logo-bloxchain-dark.svg` | `[Bx]` mark alone (dark) |
-| `logo-lockup-light.svg` | Full-width gradient hero strip + centered mark/wordmark |
-| `logo-lockup-dark.svg` | Full-width hero strip (dark) |
-| `protocol-composition-light.svg` | Soft-field composition figure + plain-language labels |
-| `protocol-composition-dark.svg` | Same geometry, dark atmosphere |
-| `badge-audit-nethermind.svg` | Shields-style `audit \| Nethermind NM_0828` → PDF |
-| `social-preview.svg` | Source for OG card |
+**Dark plates only.** No light variants and no `#gh-*-mode-only` / `<picture>` theme switching in `README.md`.
+
+| File | README placement | Purpose |
+|------|------------------|---------|
+| `logo-lockup-dark.svg` | Hero (header only) | Full-width hero strip + mark/wordmark |
+| `protocol-composition-dark.svg` | `## Architecture` only | Composition figure + plain-language labels |
+| `logo-bloxchain-dark.svg` | Not embedded | `[Bx]` mark alone (reuse / OG source) |
+| `badge-audit-nethermind.svg` | Badge row | Shields-style `audit \| Nethermind NM_0828` → PDF |
+| `social-preview.svg` | Not in body | Source for OG card |
+
+## README IA
+
+1. **Hero** — dark lockup only (brand).
+2. **Architecture** — one composition SVG for humans; Mermaid lives in a `<details>` block for agents / raw markdown.
+3. Do not embed the composition figure in the hero (avoids duplicate topology).
 
 ## Social preview
 
@@ -21,5 +26,7 @@ Raster: [`.github/social-preview.png`](../../.github/social-preview.png) (1280×
 
 - Logo lockup SVG carries large **Bloxchain** wordmark + soft wash/gradient; outer plate uses card radius (`rx="20"`)
 - Composition figure: same outer plate radius; Title Case names; plain-language subtitles; soft plate/glow — no side rails
+- Composition embeds a washed `[Bx]` mark (no diagram title); annotated optional siblings use wider cards so labels fit
 - No ALL-CAPS node titles; hierarchy via weight and stroke, not case
 - OG image is not embedded in the README body
+- Do not reintroduce light/dark dual embedding in `README.md`
diff --git a/docs/assets/logo-bloxchain.svg b/docs/assets/logo-bloxchain.svg
diff --git a/docs/assets/logo-lockup-light.svg b/docs/assets/logo-lockup-light.svg