Manifests: Migrations

The migrations section declares contract-defined migration entrypoints. Use it when a target contract version needs WASM code to transform state during an upgrade.

Migration declarations do not run by themselves. They are referenced by contract migration jobs and executed through the same deterministic Wasmtime runtime and fuel model as normal calls, with migration-specific restrictions on accepted effects.

Shape

{
  "migrations": [
    {
      "id": "report-v1-to-v2",
      "entrypoint": "migrateReportV1ToV2",
      "fromVersion": "0.1.0",
      "toVersion": "0.2.0",
      "input": {
        "type": "object",
        "properties": {
          "batchId": { "type": "string" }
        },
        "required": ["batchId"]
      },
      "output": {
        "type": "object",
        "properties": {
          "migrated": { "type": "integer" }
        },
        "required": ["migrated"]
      },
      "maxFuel": 5000000,
      "maxBatchSize": 50,
      "description": "Transforms v1 report state rows into the v2 layout."
    }
  ]
}

An empty migrations array means the contract does not expose contract-defined migration entrypoints.

Fields

Field	Required	Meaning
id	Yes	Stable migration id referenced by migration jobs.
entrypoint	Yes	WASM export that performs the migration batch.
fromVersion	No	Source contract version label.
toVersion	No	Target contract version label.
input	No	ABI schema for migration input.
output	No	ABI schema for migration output.
maxFuel	No	Migration-specific fuel ceiling.
maxBatchSize	No	Maximum batch size, capped by schema at 500.
description	No	Human-readable explanation for reviewers and tooling.

id

id is the stable migration identifier:

{ "id": "report-v1-to-v2" }

Migration jobs reference this id. Do not reuse an id for different behavior. If the transform changes, publish a new target contract manifest with a new migration id or version.

entrypoint

entrypoint is the WASM export that performs the migration batch:

{ "entrypoint": "migrateReportV1ToV2" }

The export must exist in the target contract WASM. If the migration job references a declared migration whose export is missing, execution fails before the transform can run.

fromVersion And toVersion

fromVersion and toVersion are optional labels for reviewers and tooling:

{
  "fromVersion": "0.1.0",
  "toVersion": "0.2.0"
}

They should match the contract generation being migrated, but the authoritative safety pins are still source/target contract ids plus expected code hashes and manifest hashes in the migration workflow.

input And output

input and output use the same compact ABI value schema as method ABI:

{
  "input": {
    "type": "object",
    "properties": {
      "batchId": { "type": "string" }
    },
    "required": ["batchId"]
  },
  "output": {
    "type": "object",
    "properties": {
      "migrated": { "type": "integer" }
    },
    "required": ["migrated"]
  }
}

Use these fields so migration planners, reviewers, and tests can understand the expected payloads and results.

maxFuel

maxFuel is a migration-specific ceiling:

{ "maxFuel": 5000000 }

Use it to prevent a migration batch from consuming more fuel than expected. The effective limit is still bounded by protocol limits.

maxBatchSize

maxBatchSize limits the number of rows or keys a migration batch should process:

{ "maxBatchSize": 50 }

The schema caps this value at 500. Keep batches small enough for fuel, write-effect, and operational rollback expectations.

description

description is reviewer-facing:

{
  "description": "Transforms v1 report state rows into the v2 layout."
}

Use it to explain why the migration exists and what state shape it creates.

Relationship To Migration Jobs

A contract-defined migration normally follows this path:

1. Publish and instantiate the target contract version.
2. Declare the migration entrypoint in the target manifest.
3. Plan the migration against source and target contracts.
4. Pin expected source and target code hashes and manifest hashes.
5. Create or approve the migration proposal/job.
6. Execute batches through the target migration entrypoint.
7. Finalize the job after all batches succeed.

For the full workflow, see the migration sections in Publishing.

Deterministic Failure Behavior

Common failures include:

• migration id is absent from the target manifest;
• migration entrypoint export is missing;
• batch input does not match the expected shape;
• WASM traps or exceeds fuel;
• migration return value is malformed;
• direct storage or encrypted-record writes are attempted where the migration job does not accept them;
• delete/write requests target rows outside the current batch;
• source or target code/manifest hash pins do not match.

Failed batches do not advance the migration cursor or apply partial writes.

Migration Checklist

• [ ] Migration id is stable and unique for this transform.
• [ ] Entrypoint exists in the target WASM.
• [ ] fromVersion and toVersion are meaningful for reviewers.
• [ ] Input and output schemas are documented.
• [ ] maxFuel and maxBatchSize are conservative.
• [ ] Source and target code hashes are pinned in the migration workflow.
• [ ] Source and target manifest hashes are pinned in the migration workflow.
• [ ] The migration has success, failure, replay, and batch-resume tests.

Next Steps

• General Info
• Methods
• Calls
• Publishing