Deploy the Protocol
Clone the Bloxchain Protocol at the pinned release, deploy it to Sepolia, and understand what you get: immutable account clones by default, upgradeable proxies only if you build them.
You need: Node.js 22.12 or later, Foundry, a funded Sepolia deployer key
Testnet only during alpha. Official Protocol deployments exist on Sepolia. Ethereum mainnet deployments are coming soon. Complete Production readiness before any deployment that will hold real value.
Before you start
You do not need to deploy anything to use Bloxchain. The Platform's Deploy account dialog and the SDK both create accounts from the official factory, BasicFactory, which mints a BasicAccount. Its addresses are in the published address catalog. Deploy the Protocol yourself when you need your own factory, a custom network, an extension, or a full audit trail of the bytecode you run.
Read Account pattern first. An account composes three components on one address: SecureOwnable (owner, recovery, broadcasters, time lock), RuntimeRBAC (roles and permissions) and GuardController (actions and allowlists).
Steps
1. Clone at the pinned commit
git clone https://github.com/PracticalParticle/Bloxchain-Protocol.git
cd Bloxchain-Protocol
git checkout 99beac2d6e6d7567c23b25cecaf6f4053f31c987
npm install
npm run compile:foundry
npm run test:foundryEvery Protocol page on this site describes this commit. Tags and release notes: GitHub releases. Version alignment: Releases and compatibility.
2. Deploy the foundation
The foundation is the set of shared libraries plus the AccountBlox template. Configure your deployer key and RPC in the repository's deployment environment file, then run:
The script writes the resulting addresses to deployed-addresses.json, which the SDK reads. That file is the record for your own deployment, for example a local chain. On a network in the published catalog, use the official addresses instead.
3. Deploy the example factory (CopyBlox)
CopyBlox is the open example factory that stamps out account clones from the template. On Sepolia it is also published as part of the developer toolkit. It is not the official mint path:
4. Create an account
The script is interactive: pick a supported network by number, then set broadcaster, recovery, and the time lock. It mints a BasicAccount through BasicFactory and prints the new account address and an explorer link.
5. Operate it
In the Platform: open bloxchain.app → Accounts → Import, choose the network, paste the address, select Import. See Import an account.
From code: point the SDK at the address. See SDK setup.
Then configure policy: register actions, create roles, assign signers, grant gates, fill allowlists. In the Platform this is On-chain access and Policies; in the SDK it is Runtime RBAC and Guard controller.
Official addresses
Official addresses ship in the @bloxchain/contracts npm package as official-deployed-addresses.json. Read them from that file rather than copying them into code. They are not environment variables. A chain that is not in the catalog, such as a local chain, uses its own deployed-addresses.json. Verify every address on a block explorer before relying on it.
Platform catalog
These are the contracts the Platform uses by default. Each one has the same address on every network in the published address catalog. The links open Sepolia Etherscan.
BasicFactory (official factory)
BasicAccount (account template)
SecureOwnableDefinitions
RuntimeRBACDefinitions
GuardControllerDefinitions
BasicAccount is the clone source for BasicFactory. Its initializers are disabled, so do not operate the template address as an account. EngineBlox is linked into BasicAccount when it is compiled; an account does not call it by address.
Sepolia developer toolkit
Sepolia also carries the developer toolkit: an open factory and a template for experiments. It is Sepolia only and it is not the default Platform path.
CopyBlox (open factory)
AccountBlox (template)
CopyBlox can clone any standard blox, including AccountBlox. AccountBlox accepts a time lock from 1 second, which suits quick tests. It links an earlier set of Sepolia libraries, not the catalog addresses above. CopyBlox is not exported from @bloxchain/sdk; use the @bloxchain/contracts artifacts with viem.
Official mint rules
BasicFactory clones the one BasicAccount it was deployed with and initialises the clone in the same transaction. cloneBlox gives a new address on each call. cloneBloxDeterministic gives a predictable address.
Owner is the sender
The initial owner must be the wallet that sends the mint. The factory reverts with RestrictedOwner for anyone else, so you cannot mint an account for another owner. Broadcaster and recovery are separate addresses you choose.
Send from a regular wallet
A mint uses about 16.16M gas. Networks that apply EIP-7825 cap one transaction at 16,777,216 gas (2^24), so only a direct call from a regular wallet (EOA) fits. Do not expect a Safe, an ERC-4337 smart account, a forwarder or a multicall to reach the factory. Relief is expected from a future network upgrade (Glamsterdam); there is no date.
Gas limit
Send with an explicit gas limit of 16,777,216, not a bare estimate. On Polygon PoS a mint measured about 17.88M gas, so the catalog sets a higher send limit there.
Time lock
BasicAccount accepts 1 day to 90 days.
Predictable address
The default is salt = 0 (bytes32 zero) and a stepped index (0, 1, 2, and so on). The address binds the minter, who is also the owner, the index and the salt. The same wallet, index and salt give the same address on every catalog network.
Audit
BasicFactory and BasicAccount are built on the audited core but are not in the NM_0828 scope. See Audit status.
Immutable vs upgradeable
Official factory (BasicFactory: Platform Deploy account, create-account, the addresses above) and the Sepolia developer toolkit (CopyBlox)
No. Each account is an EIP-1167 minimal-proxy clone fixed to the template implementation.
Bloxchain publishes the template at tagged releases; you own the account.
Custom factory (your own deploy)
Optional. The contracts use initializers, so you can wrap them in a UUPS or transparent proxy with your own factory.
You. The proxy admin key is as powerful as the owner key; guard it the same way. Storage layout across upgrades is your risk.
Immutable clones cannot be patched in place. When logic must change, deploy a new account, reconfigure policy, move assets through governed transfers, update integrators and allowlists, then retire the old account. The Platform-side steps are in Recovery and incidents.
Custom upgradeable proxies must run initialize atomically with creation. Follow the proxy deploy runbook and smoke-read owner(), getRecovery() and getTimeLockPeriodSec() on the proxy before funding it.
Troubleshooting
npm install refuses to run
The repository requires Node.js 22.12 or later (engine-strict). The published SDK only needs 18.20.
Deploy script cannot find a key
Fill the deployment environment file the repository README describes; never commit it.
Mint reverts with RestrictedOwner
The initial owner is not the sending wallet. Send the mint from the wallet that will own the account.
Mint runs out of gas
Send it directly from a regular wallet (EOA) with a gas limit of 16,777,216 (higher on Polygon PoS), not through a Safe, a smart account, a forwarder or a multicall. See Official mint rules.
Account deploys but every action is denied
Expected. A fresh account is a Vault: no actions, roles or allowlists yet. Configure policy first.
Related
Last updated
Was this helpful?