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.

Per-method cache TTLs at the proxy:

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 are refused with -32600 — one JSON-RPC call per request.

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.

Build

git clone https://github.com/tiagobeltraoacioli-sketch/bloch-sis-pow
cd bloch-sis-pow

# genesis artifacts: verify the carryover checksum BEFORE unpacking
shasum -a 256 -c carryover.tsv.gz.sha256
gunzip -k carryover.tsv.gz          # -> carryover.tsv (~55 MB, 452,726 opening outputs)

# build FROM THE CRATE DIRECTORY — rust-toolchain.toml lives inside it;
# the workspace root resolves a different pinned toolchain
cd crates/bloch-pos-node
cargo build --locked --release
# binary: target/release/bloch-pos

• genesis/mainnet.manifest ships in the repo; carryover.tsv.gz + its .sha256 sit at the repository root and must be verified and decompressed as above — the node wants the plain .tsv.
• The node refuses to start on a carryover/manifest mismatch (four manifest-committed fields are checked), so a corrupted or wrong-version .tsv fails loudly, not silently.

Run (observer posture)

# stage the genesis artifacts wherever you keep node data
mkdir -p /var/lib/bloch
cp genesis/mainnet.manifest carryover.tsv /var/lib/bloch/

./target/release/bloch-pos run \
  --data-dir /var/lib/bloch/data \
  --genesis /var/lib/bloch/mainnet.manifest \
  --carryover /var/lib/bloch/carryover.tsv \
  --transport devnet \
  --listen 19100 --listen-addr 127.0.0.1 \
  --peers 139.180.166.5:19100,139.180.173.231:19100 \
  --rpc-port 16310 --rpc-bind 127.0.0.1

• Bootnodes (devnet transport — plain host:port, not libp2p multiaddrs): 139.180.166.5:19100, 139.180.173.231:19100.
• RPC defaults to 127.0.0.1:16310. Never widen --rpc-bind — front the node with your own authenticated proxy instead. On newer builds, the env var BLOCH_RPC_HOST_ALLOWLIST widens the HTTP Host allowlist when your proxy needs it.
• Observer nodes carry no validator.key and can be restarted freely.

Observability next release

/health and /metrics (Prometheus, bloch_pos_* series — behind_by_slots, finalized_epoch, peer_count, equivocations_observed_total, …) exist on next-release builds, behind --metrics-port, off by default. On today's fleet binary, monitor via the RPC surface (getchaininfo.behind_by_slots and transport.peers).

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.