> For the complete documentation index, see [llms.txt](https://docs.bloxchain.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bloxchain.app/developers/deployment.md).

# 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

{% hint style="warning" %}
**Alpha.** Official deployments are live on the 15 supported networks, in the Platform and in the Protocol. Complete [Production readiness](/developers/deployment/production-readiness.md) before any deployment that will hold real value.
{% endhint %}

## 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](#official-addresses). 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](/protocol-reference/bloxchain-architecture/account-pattern.md) 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

```bash
git clone https://github.com/PracticalParticle/Bloxchain-Protocol.git
cd Bloxchain-Protocol
git checkout 99beac2d6e6d7567c23b25cecaf6f4053f31c987
npm install
npm run compile:foundry
npm run test:foundry
```

Every Protocol page on this site describes this commit. Tags and release notes: [GitHub releases](https://github.com/PracticalParticle/Bloxchain-Protocol/releases). Version alignment: [Releases and compatibility](/resources/releases.md).

### 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:

```bash
npm run deploy:hardhat:foundation
```

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](#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](#sepolia-developer-toolkit). It is not the official mint path:

```bash
npm run deploy:hardhat:copyblox
```

### 4. Create an account

```bash
npm run create-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](/platform-guide/accounts/import.md).
* **From code:** point the SDK at the address. See [SDK setup](/developers/sdk-setup.md).

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](/protocol-reference/api-reference/runtime-rbac.md) and [Guard controller](/protocol-reference/api-reference/guard-controller.md).

## 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](/introduction/supported-networks.md#published-address-catalog). The links open Sepolia Etherscan.

| Contract                        | Address                                                                                                                         |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| BasicFactory (official factory) | [`0x6b6e4fb86ab52728d983d1a316ad9d8b48513215`](https://sepolia.etherscan.io/address/0x6b6e4fb86ab52728d983d1a316ad9d8b48513215) |
| BasicAccount (account template) | [`0x234c0a76399456832a74fb29de3c78d13c22e182`](https://sepolia.etherscan.io/address/0x234c0a76399456832a74fb29de3c78d13c22e182) |
| EngineBlox                      | [`0xb1fde79830ee7f748022922d07b3f19042ee6526`](https://sepolia.etherscan.io/address/0xb1fde79830ee7f748022922d07b3f19042ee6526) |
| SecureOwnableDefinitions        | [`0xeb6ca70bb64d1f87bb708460868c9b19f6987ed6`](https://sepolia.etherscan.io/address/0xeb6ca70bb64d1f87bb708460868c9b19f6987ed6) |
| RuntimeRBACDefinitions          | [`0x55ff61c065025e4a521532f1366981805230f988`](https://sepolia.etherscan.io/address/0x55ff61c065025e4a521532f1366981805230f988) |
| GuardControllerDefinitions      | [`0x8e8f6c8a11161214fdf04c702981bcd8b78f2fe0`](https://sepolia.etherscan.io/address/0x8e8f6c8a11161214fdf04c702981bcd8b78f2fe0) |

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.

| Contract                | Address                                                                                                                         |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| CopyBlox (open factory) | [`0x928a2bd6c13e4f48a0850d2171a8d79b29959fc7`](https://sepolia.etherscan.io/address/0x928a2bd6c13e4f48a0850d2171a8d79b29959fc7) |
| AccountBlox (template)  | [`0x783eb64d7d5de55f6913f9cb42ef5a4c402884c0`](https://sepolia.etherscan.io/address/0x783eb64d7d5de55f6913f9cb42ef5a4c402884c0) |

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.

| Rule                           | What it means                                                                                                                                                                                                                                                                                                    |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **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. Glamsterdam increases the gas cost of a mint. |
| **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](/security/audit-status.md).                                                                                                                                                                    |

## Immutable vs upgradeable

| Path                                                                                                                                             | Upgradeable?                                                                                                             | Who is responsible                                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- |
| **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](/platform-guide/recovery.md#limits).

**Custom upgradeable proxies** must run `initialize` atomically with creation. Follow the [proxy deploy runbook](/protocol-reference/getting-started.md#2-proxy-deploy-runbook-atomic-initialize) and smoke-read `owner()`, `getRecovery()` and `getTimeLockPeriodSec()` on the proxy before funding it.

## Troubleshooting

| Symptom                                    | Fix                                                                                                                                                                                                                    |
| ------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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](#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

* [Protocol documentation](/protocol-reference/protocol.md)
* [Security model](/security/security-model.md)
* [License and terms](/resources/license.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.bloxchain.app/developers/deployment.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.