---
title: "Consensus v0.6 Migration"
description: "Migrate applications and tooling to the Consensus v0.6 and Studio v0.123 release family."
source: https://docs.genlayer.com/developers/consensus-v06-migration
last_updated: 2026-11-18
---

# 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

| Component | v0.6 release family |
|:--|:--|
| Consensus contracts and GenLayer Node | v0.6 RC |
| GenLayer Studio | v0.123 RC |
| `genlayer-js` | v2.0 RC |
| `genlayer-py` | v0.19 RC |
| GenLayer CLI | v0.40 RC |
| Transaction Kit and `gltest` fee profiles | matching 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](https://studio-dev.genlayer.com), 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.

| Response | Meaning | What to do |
|:--|:--|:--|
| A `result` object | Studio is on v0.123 | Use the v0.6 SDK line |
| Error code `-32601` (method not found) | Studio is still on v0.121 | Keep using your current SDK |
| Network error, timeout, HTTP error, or any other RPC error | Unknown | Do 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.

> **Warning:**
> 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:

```bash
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:

```ts
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)}`);
}
```

```ts
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](https://docs.genlayer.com/developers/decentralized-applications/fees-and-transaction-kit) and [Fee Profiling & Estimation](https://docs.genlayer.com/developers/decentralized-applications/fee-profiling-and-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:

```typescript
const charge = await client.getAppealCharge({ txId });
await client.appealTransaction({ txId, value: charge });
```

```python
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](https://docs.genlayer.com/developers/error-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.

> **Warning:**
> 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.
