Consensus v0.6 Migration

Consensus v0.6 Migration

Consensus v0.6 introduces the complete fee-funded transaction lifecycle used by Studio v0.123. Applications should upgrade Studio, node, SDK, CLI, and fee-profile tooling as one compatible release family rather than mixing release-candidate and stable components.

Compatible release lines

Componentv0.6 release family
Consensus contracts and GenLayer Nodev0.6 RC
GenLayer Studiov0.123 RC
genlayer-jsv2.0 RC
genlayer-pyv0.19 RC
GenLayer CLIv0.40 RC
Transaction Kit and gltest fee profilesmatching v0.6-compatible prerelease

Use the exact versions published in the release notes. Prerelease package tags must be installed explicitly; do not assume an npm or container latest tag resolves to the RC.

Test on Studio-dev first

The release-candidate stack is deployed at studio-dev.genlayer.com (opens in a new tab), with canonical RPC https://studio-dev.genlayer.com/api and chain ID 61997. It is separate from stable Studionet (61999).

Use the JavaScript studioDevnet definition or CLI studio-dev alias supplied by the matching RC. Do not point the stable studionet chain object at the preview RPC: chain identity and consensus contract addresses must move together.

Switch SDK versions at the upgrade

A hosted Studio moves from v0.121 to v0.123 in one step, and the two versions need different SDK lines: the v0.6 SDKs do not deploy against v0.121, and on a fee-charging v0.123 Studio the earlier SDKs have every deploy and write rejected because they send no fees. If your app cannot be down in between, ship one build that carries both SDK lines and picks one at runtime.

Detect the Studio version

Call the sim_getFeeConfig RPC method. Only Studio v0.123 and later implement it.

ResponseMeaningWhat to do
A result objectStudio is on v0.123Use the v0.6 SDK line
Error code -32601 (method not found)Studio is still on v0.121Keep using your current SDK
Network error, timeout, HTTP error, or any other RPC errorUnknownDo not switch. Retry, and fail the write if it keeps happening

Decide on whether the method exists, not on the enabled field of the result. enabled only says whether that Studio charges fees. The v0.6 SDK line works against both gasless and fee-charging v0.123 Studios, so use it whenever the method exists.

⚠️

Treat network failures as "unknown", never as "old Studio". During the upgrade the RPC can be unreachable for a few minutes; an app that falls back to the old SDK on any failure sends writes the upgraded Studio rejects.

Example

Install the v0.6 SDK next to the one you already use, under an alias:

npm install genlayer-js-v2@npm:genlayer-js@2

While v2 is still a release candidate, name the exact version instead of 2, for example genlayer-js@2.0.0-rc.3.

Then probe before each deploy or write:

type StudioLine = "v0.6" | "legacy";
 
let cached: StudioLine | undefined;
 
export async function detectStudioLine(rpcUrl: string): Promise<StudioLine> {
  // An upgraded Studio never goes back, so only the "v0.6" answer is cached.
  if (cached === "v0.6") return cached;
 
  const response = await fetch(rpcUrl, {
    method: "POST",
    headers: { "content-type": "application/json" },
    body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "sim_getFeeConfig", params: [] }),
    signal: AbortSignal.timeout(10_000),
  });
  if (!response.ok) {
    throw new Error(`Studio RPC returned HTTP ${response.status}`);
  }
 
  const body = await response.json();
  if (body.result) {
    cached = "v0.6";
    return cached;
  }
  if (body.error?.code === -32601) return "legacy";
  throw new Error(`Unexpected sim_getFeeConfig response: ${JSON.stringify(body.error)}`);
}
const line = await detectStudioLine("https://studio.genlayer.com/api");
 
if (line === "v0.6") {
  const { createClient } = await import("genlayer-js-v2");
  // v0.6 path: estimate fees and submit them with the transaction
} else {
  const { createClient } = await import("genlayer-js");
  // current path, unchanged
}

detectStudioLine throws when it cannot tell. Let that error stop the write, or retry it with a delay; do not catch it and continue on either path.

Python

One Python environment cannot hold two versions of genlayer-py. Run the same probe with any HTTP client, and either keep the two paths in separate environments or deploy the build pinned to genlayer-py v0.19 as soon as the probe returns a result.

After the upgrade

Once every Studio your app talks to answers sim_getFeeConfig, remove the old SDK and the probe. The v0.6 path then follows the rest of this guide, starting with fee submission below.

Migrate fee submission

On a fee-charging deployment, every deploy and write must carry a FeesDistribution and its quoted fee value. The recommended path is:

  1. exercise representative contract branches in tests;
  2. generate and commit a fee-profile.json with gltest --fee-profile;
  3. convert the selected profile entry into live estimate options;
  4. read current network prices and caps through the SDK estimate; and
  5. submit the returned distribution and feeValue unchanged.

The deposit covers consensus time units, execution, child messages, and the chosen appeal/rotation posture. Unused fee budget is refunded at finalization. A Studio deployment can be gasless; detect that from the estimate result rather than from its network name.

See Fees & Transaction Policy and Fee Profiling & Estimation.

Migrate appeals

The authoritative appeal quote contains both the bond and funding for the work induced by the next round. Use the high-level appeal operation and let it bind the active decision:

const charge = await client.getAppealCharge({ txId });
await client.appealTransaction({ txId, value: charge });
charge = client.get_appeal_charge(tx_id)
client.appeal_transaction(tx_id, value=charge)

Both public operations use topUpAndSubmitAppeal. Direct submitAppeal is only suitable for explicit low-level conformance against a next round that is already funded; an ordinary unfunded appeal can otherwise revert with AppealRoundNotPermitted.

A successful appeal returns the bond principal plus profit equal to 1.5× the bond, for 2.5× the bond in total. The induced-work funding is not part of the multiplied reward.

Read status and execution together

An accepted or finalized status does not by itself prove successful contract execution. Treat a transaction as successful only when:

  • its status is ACCEPTED or FINALIZED; and
  • its execution result is FINISHED_WITH_RETURN.

Use the SDK's isSuccessful helper or Transaction Kit's normalized outcome. Track until finalization when the UI needs exact fee consumption and refunds.

Other protocol-visible changes

  • Randomness: validator seed advances use ECVRF proofs bound to the registered operator public key and a per-recipient domain-separated seed chain.
  • Tribunals: the electorate and quorum are frozen at creation, consequence processing is bounded and retryable, and a majority-disagree verdict wires the convicted leader into the staking judicial restriction.
  • Developer rewards: the first deployment mints one Developer NFT, and later contracts from the same developer are attached to it. One claim processes at most 50 inflation epochs.
  • Error decoding: the v0.6 snapshot exposes 363 unique custom-error selectors; use the Error & Revert Reference with the ABI from the deployment you are calling.

Application checklist

  • Install one coherent RC set and lock it in the package and deployment manifests.
  • Use studioDevnet / studio-dev for the preview and studionet only for stable Studio.
  • Replace hand-built fee arithmetic with an SDK estimate generated from a measured profile.
  • Cover every message-emitting and materially expensive branch in profile tests.
  • Replace direct public submitAppeal calls with appealTransaction / appeal_transaction.
  • Display deposit, consumed fees, and final refund as different values.
  • Require both successful status and execution result before showing an application action as complete.
  • Re-run profile tests whenever contract code, GenVM, Studio, or the fee policy changes.
⚠️

Studio-dev is a release-candidate environment and may reset. Move durable production-like testing to Bradbury only after the compatible v0.6 stack has been promoted there.