Bloxchain Protocol

Open-source composable security framework for governed Ethereum applications.

Build on-chain security and authorization rules into vaults, tokens, payments, and governed accounts.

Install: npm install @bloxchain/sdk viem (TypeScript) · npm install @bloxchain/contracts (Solidity) · choose a path

Important

Audited core: contracts/core/ — Nethermind NM_0828 (policy). Example apps under contracts/examples/ are out of scope.
Official deployments: Sepolia today; Ethereum mainnet official deployments coming soon. Audit does not imply mainnet is live.
Security: SECURITY.md · Optional hosted Console: bloxchain.app (alpha, testnet-first) — docs.

Why Bloxchain

Reusable on-chain authorization and operation lifecycles — not ad-hoc signing, and not a wallet product. Pick a path:

I am…	Start here
Building smart contracts (Solidity)	What you can build · @bloxchain/contracts
Integrating from a product (TypeScript)	Quick start — SDK · Getting started
Deploying a governed account (testnet)	Deploy on Sepolia
Reviewing security	Nethermind report · AUDIT.md · Architecture
Evaluating for an organization	docs.bloxchain.app · Particle CS

The optional hosted Console (bloxchain.app) uses the same on-chain rules — not required to use the open protocol.

Architecture

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.

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 · State machine · Technical overview · Account pattern

Architecture graph (machine-readable)

graph TB
  EB["EngineBlox"]
  BSM["BaseStateMachine"]
  SO["SecureOwnable"]
  RBAC["RuntimeRBAC"]
  GC["GuardController"]
  ACC["Account"]
  EB --> BSM
  BSM --> SO
  BSM --> RBAC
  BSM --> GC
  SO --> ACC
  RBAC --> ACC
  GC --> ACC

Loading

Architecture guarantees (protocol engineers)

The audited core (contracts/core/) is a library architecture, not a single monolithic app:

1. Single mutation surface — SecureOperationState mutated only by EngineBlox (linked via DELEGATECALL).
2. Distinct authorization actions — direct approval can enforce a delay; meta-transaction approval separates signing from submission but does not inherit that delay. Effective separation depends on wallet-to-role assignments.
3. Defense in depth — redundant gates on handler vs execution selectors, permissions, and tx status before external calls.

What you can build

Compose only what you need. Account wires all three core components; most apps use a subset.

I want to build…	In plain terms	Protocol pieces	Example
Governed smart account / treasury	Full account stack with roles and execution rules	Account (SecureOwnable + RuntimeRBAC + GuardController)	AccountBlox · create-wallet
Asset vault (ETH / ERC-20)	Vault with ownership controls	SecureOwnable	SimpleVault
Scheduled payments	Payments with approval workflow	SecureOwnable	PayBlox
RWA / governed token	Token with on-chain governance	SecureOwnable + ERC-20	SimpleRWA20
Clone factory	Many instances from one template	BaseStateMachine	CopyBlox
Safe + extra policy	Safe with added on-chain rules	SecureOwnable + guard	GuardianSafe

More: contracts/examples/ · State abstraction vs account abstraction

Quick start

Pick one path. Node.js >=18.20.5 for npm packages (sdk/typescript/package.json).

Deploy on Sepolia

Deploy a governed account (full on-chain stack: ownership, roles, and execution rules):

npm run create-wallet

Uses AccountBlox after foundation is deployed. See Account pattern · Sepolia addresses.

Integrate with the SDK

npm install @bloxchain/sdk viem

import { SecureOwnable } from '@bloxchain/sdk';

// Placeholders — create publicClient / walletClient / chain and addresses per docs/getting-started.md
const secureOwnable = new SecureOwnable(publicClient, walletClient, contractAddress, chain);

// Request must come from RECOVERY_ROLE (new owner is snapshotted from getRecovery() at request time)
const request = await secureOwnable.transferOwnershipRequest({ from: recoveryAddress });
await request.wait();

const pending = await secureOwnable.getPendingTransactions();
const txId = pending[pending.length - 1];
const record = await secureOwnable.getTransaction(txId);

// Direct delayed approval requires chain time >= record.releaseTime — run this call later (or poll) after the timelock
await secureOwnable.transferOwnershipDelayedApproval(txId, { from: ownerAddress });

Sign in browser; optional relay per environment — meta-transactions · examples · getting started.

Build smart contracts

Package consumption (Node.js >=18.20.5):

npm install @bloxchain/contracts

Build from this monorepo (Node.js >=22.12.0):

git clone https://github.com/PracticalParticle/Bloxchain-Protocol.git
cd Bloxchain-Protocol
npm install
npm run compile:foundry
npm run test:foundry

Extend patterns under contracts/examples/. Pin exact versions in production — VERSIONING.

Security

• Audit scope: contracts/core/ — Nethermind NM_0828 · AUDIT.md. Examples are out of scope.
• Reporting: SECURITY.md only.
• Model notes: Direct approval can enforce a delay; meta-transaction approval separates signing from submission and does not inherit that delay. See WHITEPAPER.md.

FAQ — organizations

What is Bloxchain in one sentence?
An open-source framework so teams run blockchain operations through auditable on-chain rules — roles, waiting periods, and controlled external calls — instead of ad-hoc signing.

Can we use this on mainnet today?
Official Protocol deployments are on Sepolia today. Ethereum mainnet official deployments are coming soon. Completing an audit does not mean mainnet is live.

What is bloxchain.app?
An optional hosted Console to operate governed accounts in the browser (alpha, testnet-first). Same on-chain rules as self-hosted integrations — docs.bloxchain.app.

What was audited?
The Protocol core framework (not every example app). Nethermind NM_0828 · AUDIT.md.

FAQ — developers

Is this only for smart accounts?
No. See what you can build — vaults, tokens, factories, and Safe integrations compose subsets of the core.

How is this different from ERC-4337 / smart wallets?
Operation-level governed workflows on-chain — not wallet UX or bundler infrastructure. State abstraction vs account abstraction.

Are meta-transactions timelocked?
Not by the core meta-transaction approval path. Direct approval enforces releaseTime; meta approval uses separately permissioned signing and submission. See the technical paper.

How is this different from OpenZeppelin AccessControl + Timelock?
Unified transaction lifecycle (request → approve, sign → execute), guarded external execution, function schemas, and a single audited EngineBlox state machine.

Can I contribute to contracts/core/?
No public PRs — audited core is maintained by Particle CS. See CONTRIBUTING.md for docs, SDK, tooling, and examples.

Deployments

Sepolia & deployed addresses

Try on Sepolia

npm run create-wallet

Interactive: choose network, AccountBlox or custom blox, set owner / broadcaster / recovery and time-lock. Uses .env.deployment and prints the clone address.

Non-interactive: CREATE_WALLET_USE_DEFAULTS=1 node scripts/deployment/create-wallet-copyblox.js

Deployment

1. Copy env.deployment.example to .env.deployment — set DEPLOY_RPC_URL, DEPLOY_PRIVATE_KEY; Sepolia: DEPLOY_CHAIN_ID=11155111.
2. Foundation: npm run deploy:hardhat:foundation
3. Example (CopyBlox): npx hardhat run scripts/deployment/deploy-example-copyblox.js --network sepolia

Addresses are written to deployed-addresses.json.

Official Sepolia addresses

Contract	Address
EngineBlox	0x726d78c9683a96d66196d2b8350923e8ca0d8597
SecureOwnableDefinitions	0xcb8834e55c2c7b012e5643de98a1bf5fda22191c
RuntimeRBACDefinitions	0x27c103b2b1a1e7dc345aeff766aa3656b4825653
GuardControllerDefinitions	0x6ce6f314fa35d34782f2743db4d0c1f824639938
AccountBlox	0x783eb64d7d5de55f6913f9cb42ef5a4c402884c0
CopyBlox (example)	0x928a2bd6c13e4f48a0850d2171a8d79b29959fc7

Development & testing

npm run compile:foundry          # add :size for 24KB check
npm run test:foundry
npm run test:foundry:fuzz        # 37 suites, 309 tests — see test/foundry/docs/
npm run test:e2e                 # SDK sanity on remote_evm
npm run docgen

See CONTRIBUTING.md for the full command matrix.

Documentation

Topic	Link
Public docs (Platform + SDK + Protocol)	docs.bloxchain.app
Protocol technical thesis	WHITEPAPER.md
Account pattern	docs/account-pattern.md
Getting started (SDK)	docs/getting-started.md
API reference	docs/api-reference.md
Core audit policy	contracts/core/AUDIT.md

Contributing

Selective contributions welcome (docs, SDK aligned with core, tooling, examples) — not public PRs to contracts/core/ (audited; Particle CS only). Security: SECURITY.md only. DCO sign-off required (git commit -s). Code of Conduct.

License

MPL-2.0 — LICENSE. contracts/examples/ use per-file licenses (typically MIT).

Support

GitHub Issues · Discussions · Particle CS

Star History

---

Created by Particle Crypto Security · Copyright © 2026 Particle Crypto Security