Blox-Apps

Blox-Apps is the application hub for Bloxchain-based applications. Each application is a standalone on-chain application (in contract form); this repository centralizes official and community applications into one Blox hub, built on the Bloxchain Protocol.

⚠️ EXPERIMENTAL SOFTWARE WARNING
This repository contains experimental smart contract code. While the framework is feature-complete and tested, it is not yet audited for production use. Use at your own risk and do not deploy with real assets without proper security review.

Repository structure

Path	Description
`contracts/Official-Blox/`	Official Bloxchain applications (e.g. Bloxchain Wallet). Covered by the repository LICENSE (dual license: AGPL-3.0 / Commercial).
`contracts/community-blox/`	Community-contributed applications. Excluded from the repo LICENSE; each blox defines its own license (default MIT). See contracts/community-blox/README.md.

Official-Blox: Bloxchain Wallet

The Bloxchain Wallet is the first official application in the hub: the official on-chain smart programmable account for the Bloxchain Wallet app.

Bloxchain Wallet is the core on-chain infrastructure for the Bloxchain Wallet application. It is powered by the Bloxchain Protocol and provides:

GuardController – Execution workflows, time-locked transactions, and controlled external contract interactions
RuntimeRBAC – Runtime role creation and management with function-level permissions
SecureOwnable – Secure ownership transfer and multi-role security (Owner, Broadcaster, Recovery)

The contract serves as the single on-chain entry point for the Bloxchain Wallet app: all critical operations (ownership changes, role configuration, external calls) flow through this controller with mandatory multi-signature and time-lock guarantees.

Architecture Overview

Contract Hierarchy

BloxchainWallet is the account contract that wraps the internal Bloxchain Protocol components (via the Account pattern). The hierarchy:

BloxchainWallet   (account contract – wraps the components below)
    └── Account   (protocol pattern: GuardController + RuntimeRBAC + SecureOwnable)
            ├── GuardController   (execution workflows, time-locks, external call control)
            ├── RuntimeRBAC      (dynamic roles, function permissions, batch config)
            └── SecureOwnable    (owner/broadcaster/recovery, time-locked ownership)
                    └── BaseStateMachine (state machine, meta-transactions)
                            └── EngineBlox (core library: SecureOperationState, multi-phase workflows)

Core Components (from Bloxchain Protocol)

The account contract wraps the following protocol components:

Component	Role in Bloxchain Wallet
GuardController	Defines which external contracts and functions can be called, with time-lock or meta-transaction workflows.
RuntimeRBAC	Manages roles (beyond Owner/Broadcaster/Recovery), wallet limits per role, and which functions each role can request/approve/sign/execute.
SecureOwnable	Manages Owner, Broadcaster, and Recovery addresses and time-locked ownership transfer.
BaseStateMachine	Shared state, transaction records, time-lock period, and meta-transaction support.
EngineBlox	Core library: SecureOperationState, multi-phase workflows, and state machine logic; used by BaseStateMachine.

Security Model

Multi-signature workflows: Time-delay (request → wait → approve) or meta-transaction (sign → execute) with role separation.
No single-point failure: The contract controls storage and execution policy; individual keys cannot bypass workflows.
Explicit ETH handling: ETH must be sent via deposit(). Direct receive()/fallback() transfers revert to avoid accidental or malicious sends.
Bounded initialization: MAX_DEFINITION_CONTRACTS (50) and MAX_INITIAL_ROLES (50) limit gas and DoS risk during setup.

Contract Reference

Constants

Constant	Value	Description
`MIN_TIME_LOCK_PERIOD`	1 day	Minimum timelock period for time-delay operations.
`MAX_TIME_LOCK_PERIOD`	90 days	Maximum timelock period.
`MAX_DEFINITION_CONTRACTS`	50	Maximum definition contracts in `initializeWithRolesAndDefinitions`.
`MAX_INITIAL_ROLES`	50	Maximum custom roles in `initializeWithRolesAndDefinitions`.

Initialization

Two initializers are available:

1. `initialize` (simple)

Sets up Owner, Broadcaster, Recovery, timelock period, and optional event forwarder. Uses protocol default roles and definitions only.

function initialize(
    address initialOwner,
    address broadcaster,
    address recovery,
    uint256 timeLockPeriodSec,
    address eventForwarder
) public initializer

timeLockPeriodSec must be between MIN_TIME_LOCK_PERIOD and MAX_TIME_LOCK_PERIOD.
eventForwarder can be address(0) if not used.

2. `initializeWithRolesAndDefinitions` (extended)

Same base setup as above, plus:

Custom roles: Array of RoleConfig (role name + max wallets). Roles are created as non-protected so they can be modified later.
Definition contracts: Array of IDefinition addresses. Each definition supplies function schemas and role–permission mappings. Definitions are loaded after roles so that permissions can reference the new roles.

struct RoleConfig {
    string roleName;
    uint256 maxWallets;
}

function initializeWithRolesAndDefinitions(
    address initialOwner,
    address broadcaster,
    address recovery,
    uint256 timeLockPeriodSec,
    address eventForwarder,
    RoleConfig[] memory roles,
    IDefinition[] memory definitionContracts
) public initializer

roles.length must be ≤ MAX_INITIAL_ROLES.
definitionContracts.length must be ≤ MAX_DEFINITION_CONTRACTS.
Function permissions for custom roles are not set in RoleConfig; they are added via definition contracts.

ETH Deposit

Function	Description
`deposit()`	Payable. Sends ETH to the wallet and emits `EthReceived(from, amount)`. Use this for all ETH inflows.
`receive()`	Reverts with `SharedValidation.NotSupported()`. Prevents accidental or direct ETH transfers.
`fallback()`	Reverts with `SharedValidation.NotSupported()`. Rejects unknown calls and accidental ETH.

Only deposit() is accepted for ETH. This keeps behavior explicit and avoids misdirected funds.

Events

EthReceived(address indexed from, uint256 amount) – Emitted when ETH is deposited via deposit().

Inheritance and Overrides

supportsInterface(bytes4) – Aggregates GuardController, RuntimeRBAC, and SecureOwnable EIP-165 support.
_updateTimeLockPeriod(uint256) – Validates against MIN_TIME_LOCK_PERIOD and MAX_TIME_LOCK_PERIOD, then delegates to SecureOwnable.

Quick Start

Prerequisites

Node.js (v18+)
npm or yarn

Installation

git clone https://github.com/PracticalParticle/Blox-Apps.git
cd Blox-Apps

npm install

The project depends on @bloxchain/contracts and @bloxchain/sdk; they are installed with npm install.

Compile

# Foundry
npm run compile:foundry

# Contract size report (e.g. stay under 24KB)
npm run compile:foundry:size

# Hardhat
npm run build:contracts

Test

# Foundry
npm run test:foundry

# Verbose
npm run test:foundry:verbose

# Fuzz (higher runs)
npm run test:foundry:fuzz

# Coverage
npm run test:foundry:coverage

Usage with the Bloxchain Protocol SDK

Bloxchain Wallet is a AccountBlox-style contract. Use the same SDK clients as for other Bloxchain controllers: SecureOwnable, RuntimeRBAC, and Definitions (and GuardController-related helpers as exposed by the SDK).

Basic setup

import {
  SecureOwnable,
  RuntimeRBAC,
  type Address,
  type PublicClient,
  type WalletClient,
} from "@bloxchain/sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { sepolia } from "viem/chains";

const publicClient = createPublicClient({ chain: sepolia, transport: http() });
const walletClient = createWalletClient({ chain: sepolia, transport: http() });

const walletAddress = "0x..."; // Deployed BloxchainWallet

const secureOwnable = new SecureOwnable(
  publicClient,
  walletClient,
  walletAddress,
  sepolia
);

const runtimeRBAC = new RuntimeRBAC(
  publicClient,
  walletClient,
  walletAddress,
  sepolia
);

Ownership (SecureOwnable)

// Request time-locked ownership transfer
const { hash } = await secureOwnable.transferOwnershipRequest({
  from: ownerAddress,
});

// After timelock, approve
await secureOwnable.transferOwnershipDelayedApproval(txId, {
  from: ownerAddress,
});

Roles (RuntimeRBAC)

// Create custom role via batch (e.g. after initialization)
// See Bloxchain Protocol docs for roleConfigBatch / meta-transaction flows
const role = await runtimeRBAC.getRole(roleHash);
const wallets = await runtimeRBAC.getWalletsInRole(roleHash);

Depositing ETH (front-end / script)

Users and scripts must call the wallet’s deposit() with the desired value. Example (viem):

await walletClient.writeContract({
  address: walletAddress,
  abi: BloxchainWalletABI,
  functionName: "deposit",
  value: parseEther("1"),
  account: userAccount,
});

Listen for EthReceived to confirm deposits.

Relationship to Bloxchain Protocol

Bloxchain Protocol provides the security primitives (GuardController, RuntimeRBAC, SecureOwnable, BaseStateMachine, EngineBlox, definitions).
Bloxchain Wallet is a concrete application: a single contract that composes these primitives as the on-chain controller for the Bloxchain Wallet app.

For deeper concepts (multi-phase workflows, meta-transactions, RBAC, GuardController target whitelisting, definition data layer), see the Bloxchain Protocol README and its documentation.

Development

Scripts (from `package.json`)

Script	Command	Description
Build (Hardhat)	`npm run build:contracts`	Compile with Hardhat.
Build (Foundry)	`npm run compile:foundry`	Compile with Forge.
Size	`npm run compile:foundry:size`	Show contract sizes.
Test	`npm run test:foundry`	Run Forge tests.
Fuzz	`npm run test:foundry:fuzz`	Fuzz with 10k runs.
Coverage	`npm run test:foundry:coverage`	Forge coverage.
Invariant	`npm run test:foundry:invariant`	Invariant tests.

Foundry config (`foundry.toml`)

Solidity: 0.8.33
Optimizer: enabled, 200 runs
Via-IR: enabled
EVM: Osaka
Remappings: OpenZeppelin and forge-std; @bloxchain/contracts resolves via node_modules (from libs).

Security Considerations

Explicit deposits only: Use deposit() for ETH; direct transfers are rejected.
Time-lock bounds: Timelock is enforced between 1 and 90 days.
Initialization limits: Bounded roles and definition contracts to reduce gas and DoS risk.
Definition trust: Definition contracts are called during initialization; only use audited or trusted definitions.
Upgradeability: The contract uses initializer modifiers; deployment pattern (e.g. proxy) is defined by the deployer. Follow the Bloxchain Protocol and OpenZeppelin upgrade guidelines if using a proxy.

For protocol-level security (multi-sig, RBAC, GuardController), see the Bloxchain Protocol documentation.

License

Official-Blox (including Bloxchain Wallet) is dual-licensed: GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) and Bloxchain Wallet Commercial License. See LICENSE and LICENSE-COMMERCIAL.md.
contracts/community-blox/ is excluded from the repository LICENSE; each community blox defines its own license (default MIT). See contracts/community-blox/README.md.

Contributing

We welcome contributions to official apps and new community blox. See:

CONTRIBUTING.md – Development setup, code standards, pull request process, and adding applications
SECURITY.md – How to report vulnerabilities
CODE_OF_CONDUCT.md – Community standards

Acknowledgments

Bloxchain Protocol – Core security framework and AccountBlox template
Particle Crypto Security – Blox-Apps and Bloxchain Wallet
OpenZeppelin – Upgradeable and security patterns
Foundry / Hardhat – Compilation and testing

Name		Name	Last commit message	Last commit date
Latest commit History 29 Commits
contracts		contracts
.gitignore		.gitignore
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
LICENSE-COMMERCIAL.md		LICENSE-COMMERCIAL.md
README.md		README.md
SECURITY.md		SECURITY.md
env.deployment.example		env.deployment.example
foundation-libraries.json		foundation-libraries.json
foundry.toml		foundry.toml
hardhat.config.js		hardhat.config.js
package-lock.json		package-lock.json
package.json		package.json

License

Licenses found

PracticalParticle/Blox-Apps

Folders and files

Latest commit

History

Repository files navigation

Blox-Apps

Repository structure

Official-Blox: Bloxchain Wallet

Architecture Overview

Contract Hierarchy

Core Components (from Bloxchain Protocol)

Security Model

Contract Reference

Constants

Initialization

1. initialize (simple)

2. initializeWithRolesAndDefinitions (extended)

ETH Deposit

Events

Inheritance and Overrides

Quick Start

Prerequisites

Installation

Compile

Test

Usage with the Bloxchain Protocol SDK

Basic setup

Ownership (SecureOwnable)

Roles (RuntimeRBAC)

Depositing ETH (front-end / script)

Relationship to Bloxchain Protocol

Development

Scripts (from package.json)

Foundry config (foundry.toml)

Security Considerations

License

Contributing

Acknowledgments

About

Resources

License

Licenses found

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

1. `initialize` (simple)

2. `initializeWithRolesAndDefinitions` (extended)

Scripts (from `package.json`)

Foundry config (`foundry.toml`)

Packages