Bloch Genesis-4 developer portal

The integration reference for the Bloch Genesis-4 chain: a post-quantum proof-of-stake L1 with an extended-UTXO ledger and explicit Casper-FFG finality. Written for engineers — exchange integrators, wallet builders, node operators.

This portal documents the network at the deepest honest level. Where something does not exist yet — a transaction index, an EVM, official SDKs, a joinable sync path for brand-new nodes — this page says so plainly instead of papering over it. Every figure here was verified against source commit 72e5525 and the live network on 2026-09-07; where a feature is in source but not yet on the fleet, it is labeled next release.

Network parameters

The integer rule: every *_sat field is a string

// JS: correct handling of *_sat fields
const res = await fetch("https://posternlabs.com/g4rpc", {
  method: "POST",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "getbalance",
                         params: ["7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000"] })
});
const { result } = await res.json();
const balance = BigInt(result.balance_sat);   // string -> BigInt. Never Number().
const utxoCount = result.utxo_count;          // plain count -> ordinary number is fine

Endpoints & transport

Public proxy (recommended)

POST https://posternlabs.com/g4rpc

JSON-RPC 2.0 over HTTP POST. The proxy exposes a read-method allowlist plus sendrawtransaction. It is backed by multiple upstream nodes with read corroboration: branch-sensitive reads require a quorum of ≥ 2 upstream nodes agreeing before a response is served. CORS is answered at the proxy, so browser apps can call it directly.

Gateway 2.0.0 cache TTLs are disclosed by getcapabilities (methods[].cache_ttl_ms). Cached results retain corroboration checks; critical reads are never served from a stale fallback. Representative TTLs:

Direct archival nodes

POST http://139.180.166.5:8080  ·  POST http://139.180.173.231:8080

Two keyless observer nodes, plain HTTP, POST only. No TLS — treat the transport as untrusted and corroborate any answer across both nodes (this is exactly what the public proxy automates for you). Useful when you want raw node behavior without the proxy's cache or allowlist.

Explorer & wallet

• Explorer: blochl1.com — blocks, validators, epochs, analytics, transactions.
• Wallet: posternlabs.com/apps/wallet/ — a PWA with client-side signing; usable as a reference integration for the signing flow documented on this page.

Transport rules

• One call per connection. The node answers with Connection: close; there is no keep-alive at the node. Pool at your HTTP client's peril — open a fresh connection per request.
• Request body cap: 1 MiB.
• Both positional-array and named-object params are accepted.
• Batch arrays and notifications are refused with -32600. Send one JSON-RPC 2.0 call per request with an explicit string, safe integer or null id.

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"getchaininfo","params":[]}'

JSON-RPC reference — live surface

The methods below are the surface the public proxy and the live fleet serve today. Methods that exist in source but are not yet on the fleet are listed under Next release. All sample responses use illustrative values (heights, hashes, and balances are made up); shapes and field names are the contract.

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getchaininfo","params":[]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "block_id": "7c1e29aa40b3d8f15e6a0c92d4b7f81326c5a90e8f1d3b6407e2c9a51b8d4f60",
    "slot": 71182,
    "height": 34120,
    "finalized_height": 34064,
    "epoch": 2224,
    "slot_in_epoch": 14,
    "slots_per_epoch": 32,
    "state_root": "e0a4c1d293b85f671c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7",
    "justified": { "epoch": 2223, "root": "44f0b2c9d81e6a35970c4d2f8b1e5a603d7c92f406b8e1a5c2d94f705e8a1b36" },
    "finalized": { "epoch": 2222, "root": "b2d94f705e8a1b3644f0b2c9d81e6a35970c4d2f8b1e5a603d7c92f406b8e1a5" },
    "previous_justified": { "epoch": 2222, "root": "b2d94f705e8a1b3644f0b2c9d81e6a35970c4d2f8b1e5a603d7c92f406b8e1a5" },
    "validators": { "total": 64, "active": 64 },
    "total_active_stake_sat": "3200000000000000000",
    "base_fee_millisat_per_gas": "1000",
    "next_base_fee_millisat_per_gas": "1024",
    "mempool": 3,
    "blocks_known": 34121,
    "wall_slot": 71182,
    "behind_by_slots": 0,
    "transport": { "name": "devnet", "peers": 8 }
  }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblockcount","params":[]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "height": 34120,
    "slot": 71182,
    "epoch": 2224,
    "finalized_height": 34064,
    "justified_epoch": 2223,
    "finalized_epoch": 2222
  }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getblockbyslot","params":[71180]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "block_id": "7c1e29aa40b3d8f15e6a0c92d4b7f81326c5a90e8f1d3b6407e2c9a51b8d4f60",
    "version": 2970353669,
    "parent": "9d3b6407e2c9a51b8d4f607c1e29aa40b3d8f15e6a0c92d4b7f81326c5a90e8f",
    "slot": 71180,
    "epoch": 2224,
    "height": 34118,
    "proposer_index": 41,
    "timestamp": 1788792079,
    "state_root": "e0a4c1d293b85f671c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7",
    "body_root": "970c4d2f8b1e5a603d7c92f406b8e1a5c2d94f705e8a1b3644f0b2c9d81e6a35",
    "randao_reveal": "a3b1…(hybrid signature, ~4589 bytes hex, truncated here)",
    "randao_mix": "a5c3e71b94d6f28c07e1a538b2f4d96e05a7c31d48f6b20f31a7c059e64b2d80",
    "justified_root": "44f0b2c9d81e6a35970c4d2f8b1e5a603d7c92f406b8e1a5c2d94f705e8a1b36",
    "finalized_root": "b2d94f705e8a1b3644f0b2c9d81e6a35970c4d2f8b1e5a603d7c92f406b8e1a5",
    "attestation_root": "0c92d4b7f81326c5a90e8f1d3b6407e2c9a51b8d4f607c1e29aa40b3d8f15e6a",
    "coherence_root": "1c2d3e4f5a6b7c8d9e0f1a2b3c4d5e6f708192a3b4c5d6e7e0a4c1d293b85f67",
    "finality": "justified",
    "finalized": false,
    "tx_count": 1,
    "attestation_count": 42
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32007, "message": "no canonical block at slot" }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getvalidator","params":[41]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "index": 41,
    "pubkey_hash": "5a0e8d21c47bf93602de5a81b64c9f307e12ad85f09c36b4d871e25a40c3b96f",
    "pubkey_bytes": 3749,
    "state": "active",
    "own_stake_sat": "50000000000000000",
    "effective_stake_sat": "50000000000000000",
    "commission_bps": "500",
    "randao_commitment": "d871e25a40c3b96f5a0e8d21c47bf93602de5a81b64c9f307e12ad85f09c36b4",
    "slashed": false,
    "activation_epoch": 0,
    "exit_epoch": null,
    "withdrawable_epoch": null
  }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getvalidatorcount","params":[]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": { "total": 64, "active": 64, "total_active_stake_sat": "3200000000000000000" }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getbalance","params":["7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000"]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "script_hash": "7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000",
    "balance_sat": "125000000000",
    "utxo_count": 3
  }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getutxos","params":["7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000", 100]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "script_hash": "7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000",
    "total": 3,
    "returned": 3,
    "truncated": false,
    "utxos": [
      { "txid": "f31a7c059e64b2d80a5c3e71b94d6f28c07e1a538b2f4d96e05a7c31d48f6b20",
        "vout": 0, "value_sat": "100000000000",
        "script_hash": "7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000" },
      { "txid": "28c07e1a538b2f4d96e05a7c31d48f6b20f31a7c059e64b2d80a5c3e71b94d6f",
        "vout": 1, "value_sat": "20000000000",
        "script_hash": "7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000" },
      { "txid": "6f28c07e1a538b2f4d96e05a7c31d48f6b20f31a7c059e64b2d80a5c3e71b94d",
        "vout": 0, "value_sat": "5000000000",
        "script_hash": "7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000" }
    ]
  }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"gettxout","params":["f31a7c059e64b2d80a5c3e71b94d6f28c07e1a538b2f4d96e05a7c31d48f6b20", 0]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "txid": "f31a7c059e64b2d80a5c3e71b94d6f28c07e1a538b2f4d96e05a7c31d48f6b20",
    "vout": 0,
    "unspent": true,
    "utxo": {
      "txid": "f31a7c059e64b2d80a5c3e71b94d6f28c07e1a538b2f4d96e05a7c31d48f6b20",
      "vout": 0,
      "value_sat": "100000000000",
      "script_hash": "7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000"
    },
    "at_slot": 71182
  }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"getmempoolinfo","params":[]}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "size": 2,
    "max": 4096,
    "bytes": 9178,
    "next_base_fee_millisat_per_gas": "1024",
    "barred": 0,
    "barred_hits": 0,
    "expired": 1,
    "evicted_low_fee": 0
  }
}

curl -s -X POST https://posternlabs.com/g4rpc -H 'content-type: application/json' \
  -d '{"jsonrpc":"2.0","id":1,"method":"sendrawtransaction","params":{"hex":"06a1b2c3…"}}'

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "accepted": true,
    "status": "accepted",
    "kind": "transfer_v2",
    "bytes": 4890,
    "tx_hash": "b94d6f28c07e1a538b2f4d96e05a7c31d48f6b20f31a7c059e64b2d80a5c3e71",
    "tx_hash_note": "node-local digest over raw bytes; not the consensus txid — compute the txid client-side",
    "confirmation": "queue acknowledgement only; not evidence of inclusion"
  }
}

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": { "code": -32005, "message": "no transaction index on this chain (by design)" }
}

Next-release methods

Error codes

Standard JSON-RPC

Dedicated codes

Retry discipline

• -32008: rebuild, never resubmit. The bytes are terminally refused.
• -32009: retry after until_slot, or rebuild against the current base fee — usually faster.
• -32003 / -32004: capacity/availability — back off and retry the same bytes.
• Identical duplicate bytes while pending: Admitted::Duplicate — a success response, not an error. Safe to use as an idempotent redelivery strategy.

Transactions & fees

The txid: computed by you, before broadcast

txid = SHA3-256( "BLCH4:TXID" ‖ spend_signing_root )

The consensus transaction id is deterministic and non-malleable — it excludes witnesses, so no third party can mutate it in flight. Because it is a pure function of the spend signing root, you compute it client-side, before broadcast. Outpoints are (txid, vout). This txid is how you track everything on this chain: the node will never look a transaction up for you (no transaction index, by design), but gettxout(txid, vout) answers exactly for any outpoint you know.

Fees: exactly one valid base fee

• A transaction commits to exactly one valid base fee — the one committed by the block that includes it. There is no fee range, no tolerance.
• Read next_base_fee_millisat_per_gas (from getchaininfo or getmempoolinfo) immediately before building — it is a one-block look-ahead.
• If the base fee moves before your transaction is included, the signed bytes fail ValueNotConserved. Rebuild against the new fee; do not resubmit.
• Conservation is an equality: spent == created + fee — not a tolerance.

TransferV2 (wire tag 0x06)

Live since epoch 800. Witness-table format: ~40 bytes per input instead of full per-input keys as in V1. The practical input ceiling rises from ~61 inputs (V1) to ~1,000 — which is also the UTXO enumeration bound (getutxos limit clamp), so the two constraints align. V1 remains valid; a single-input payment may reasonably choose V1.

Mempool & block mechanics

• Transactions in a block are packed by tip_millisat_per_gas descending.
• Per-source pending cap: 64 transactions per spend-authority source (-32010 at the node when exceeded).
• Mempool TTL: 100 slots unincluded → dropped. Rebuild and resubmit after expiry (the fee has almost certainly moved by then anyway).

Client-side signing flow

1. Select inputs — getutxos for the first page; gettxout for exact checks.
2. Read next_base_fee_millisat_per_gas — immediately before building.
3. Set tip and outputs.
4. Fix the tx_bytes budget — Falcon signatures vary in length; budget the declared size, not the size of one sample signature.
5. Sign — the spend_signing_root fixes the txid at this moment; record it.
6. Broadcast — sendrawtransaction {"hex": …}; track by your recorded txid.

Addresses & keys

Address format

bloch1q + 48 hex = 55 characters

• The 48 hex characters are: 40 hex = the 20-byte SHA3-256 prefix of the raw public key (this is not RIPEMD — there is no hash160 anywhere), followed by 8 hex = a SHA3 double-checksum.
• The network emits lowercase. The reference parser accepts mixed-case hex — validate leniently, emit lowercase.

# illustrative address anatomy
bloch1q 7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4 0a9b3c7d
prefix  20-byte SHA3-256 prefix of raw pubkey    checksum
(7)     (40 hex)                                 (8 hex)

script_hash — what every balance/UTXO method keys on

The 32-byte script_hash has two valid forms:

To derive the Carried script_hash from an address: strip bloch1q, take the first 40 hex characters, zero-pad to 64 hex.

# address -> Carried script_hash (shell)
addr="bloch1q7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f40a9b3c7d"
hex="${addr#bloch1q}"                # drop the prefix
hex="${hex:0:40}"                    # 20 address bytes (drops the 8-hex checksum)
printf '%s%024d\n' "$hex" 0          # zero-pad to 64 hex
# -> 7d02c4a19e5f60b3d8a1f2c47e9b0d6a35c8e1f4000000000000000000000000

// address -> Carried script_hash (JS)
function scriptHashFromAddress(addr) {
  const a = addr.toLowerCase();
  if (!/^bloch1q[0-9a-f]{48}$/.test(a)) throw new Error("not a bloch address");
  // NOTE: a full implementation verifies the 8-hex SHA3 double-checksum here.
  return a.slice(7, 47).padEnd(64, "0");
}

Keys are hybrid ML-DSA-65 ‖ Falcon-1024; the node never sees them — generation, storage, and signing are entirely client-side (see the signing flow).

Crediting deposits — the rule

Normative procedure for anyone crediting incoming payments: exchanges, merchants, custody providers. It exists because this chain has no transaction index and no per-output creation height — detection and settlement are built from primitives.

1. Detect

• Poll getbalance(script_hash) cheaply per deposit address.
• On change, call getutxos to see which outpoints arrived.
• Use gettxout(txid, vout) to confirm a specific expected payment — the only exact check for addresses past 1,000 outputs.

2. Cross-reference an observed height

When gettxout shows unspent: true, read height H from getblockcount in the same round-trip. You now know: the output existed at or before height H. (Remember: gettxout.at_slot is the node's head, not the output's age — this cross-reference is the substitute for a creation height the RPC does not expose.)

3. Credit

Credit the deposit when all of the following hold:

1. finalized_height ≥ H, plus
2. a prudence margin of ~30 epochs (~8 h) of continued, uninterrupted finality advance beyond that, and
3. two independently operated nodes agree on the same finalized root at the same epoch.

Reverify immediately before releasing funds.

Reorg handling

Above the finalized checkpoint, reorgs to any depth are normal LMD-GHOST behavior for included-but-unfinalized transactions. An included transaction is not settled; only the rule above settles.

Run a node

The source is public: github.com/tiagobeltraoacioli-sketch/bloch-sis-pow. Running your own observer node is the recommended posture for any serious integrator: it validates every block independently, serves the full RPC surface, and signs nothing (no validator.key).

Requirements

• Linux x86-64; 2+ vCPU, 8 GB RAM, 80 GB SSD.
• Full replay from genesis measured ≈ 21–22 min (~34k blocks, peak RSS ~934 MB). Replay cost is O(chain length) — there is no snapshot layer yet, so expect this to grow with the chain.

Download and verify the pinned release

Do not build an unpinned main revision for this network. The deployed release is 58da5ce209acb6e293b3b381dfd826dedb8741fd: metadata, checksums and source archive. Linux x86-64 requires glibc 2.34 or newer.

Download and read the public preparation script. It verifies pinned artifacts, stages the signed checkpoint and creates the launch script without generating a validator key or broadcasting a transaction. Separately authenticate the signer set before trusting the checkpoint.

curl --fail --show-error --location \
  --output prepare-node.sh https://blochl1.com/downloads/prepare-node.sh
less prepare-node.sh
bash prepare-node.sh "$HOME/bloch-observer-20260914"
cd "$HOME/bloch-observer-20260914"

Run as a keyless observer

./run-node.sh

Do not run the identity helper or deposit steps. The generated launch script supplies the checkpoint and signer-set arguments required for fresh synchronization. Public bootnodes are 139.180.166.5:19100 and 139.180.173.231:19100. Keep RPC bound to loopback; use an authenticated proxy if remote access is required.

Wait for full replay, a head following the network and advancing finality. See sections 1–2 of the pinned installation instructions and the timestamped fresh-observer test. That test does not certify signer independence or exchange crediting readiness.

Observability

Monitor synchronization and finality through getchaininfo. The pinned release also supports an optional metrics endpoint configured with --metrics-port; keep operational endpoints private.

SDKs & tooling

The practical integration path today:

• Direct JSON-RPC. This portal's method reference is the contract — the surface is small enough that a thin typed client in your own codebase is an afternoon's work.
• The wallet PWA as reference implementation. posternlabs.com/apps/wallet/ signs entirely client-side; study it for the transaction-building and signing flow.
• Contributing a Genesis-4 typed client is the natural community contribution: the frozen method registry in the node source (src/rpc/method_registry.rs, with tests/rpc_method_registry.rs pinning it) is the surface to generate from.

Other tooling: the explorer at blochl1.com (blocks, validators, epochs, analytics, transactions).

Integration reference documents for exchanges and partners exist and are provided on request via Postern Labs — they are not published here.

EVM roadmap & status

What is true, precisely:

• The Genesis-4 L1 is an eUTXO chain. Smart-contract execution is roadmap, not product.
• Chain id 8400 (0x20d0) is reserved, but it refers to a legacy Genesis-3-era L2 scaffold that is retired, not extended. Please do not deploy against chain id 8400 expecting a current network — nothing is listening on the other end that you should build on.
• The successor plan — EVM at L1 — is an explicit draft with no code on either track yet.

If you need EVM execution for your use case, the honest advice is: not here, not yet. Watch this page and the repository for the flag-day announcement when an execution layer ships; this section will change from a warning into documentation on that day.

Security & disclosure

Coordinated disclosure

• Report via the repository's security advisory flow, or encrypted contact, with the subject tag [bloch-security].
• Acknowledgement target: ≤ 2 days.
• In scope: Genesis-4 consensus, P2P/RPC surfaces, hybrid signature verification, privacy findings.

Audit status — stated plainly

No external third-party audit of the post-quantum stack has been contracted to date. Internal tool-assisted audits are continuous. If your risk model requires an external audit, that requirement is not yet met — factor it in.

Decentralization — stated plainly

The chain is young and run by a small operator set today; the validator-opening program is staged. Do not build assumptions of a large independent validator set into your threat model yet — the crediting rule's margins exist precisely because of this.