migrate
Call v334 → current #9Runs migration logic for contracts after a runtime upgrade.
View calls on chainCall Workflow
Click items to navigate. Pan and zoom to explore.
The Big Picture
When the Contracts pallet itself upgrades, existing contract data may need transformation. This call runs that migration incrementally. Usually automated by the runtime, but can be called manually to control migration pacing or complete stuck migrations.
Why This Matters
Runtime upgrades may change how contract data is stored. Without migration, old contracts could malfunction. This ensures backward compatibility by transforming data to the new format.
Example Scenario
Chain upgraded from Contracts v8 to v9 with new storage layout. Query MigrationInProgress - returns Some(cursor). Contracts may fail until migrated. Call migrate(weight_limit=1000000). Repeat until MigrationInProgress returns None. All contracts now work correctly.
Common Questions
- Is migration automatic?
- Usually yes - runtime hooks run migration. Manual calls are for edge cases or controlling migration pace on resource-constrained chains.
- What if I don't migrate?
- Contracts may return errors or wrong data. Some calls may panic. Always complete migrations before expecting normal operation.
- How do I know migration is needed?
- Check MigrationInProgress storage. Some(cursor) = migration pending. None = no migration needed or migration complete.
Use Cases
- Complete pending contract pallet migrations
- Ensure contracts work after runtime upgrades
- Administrative maintenance after chain upgrades
From Chain Metadata
When a migration is in progress, this dispatchable can be used to run migration steps. Calls that contribute to advancing the migration have their fees waived, as it's helpful for the chain. Note that while the migration is in progress, the pallet will also leverage the `on_idle` hooks to run migration steps.
Input Parameters
| # | Name | Type | Description |
|---|---|---|---|
| 0 | weight_limit | Weight | weight_limit: Substrate dispatch weight (computational cost) |
Permissions
Permission data inferred from metadata. May be incomplete.
Requirements
- Runtime upgrade changed contract storage format
- Migration is pending (MigrationInProgress is Some)
- Caller has appropriate privileges
- Weight limit sufficient for migration step
Effects
Storage Modified
Postconditions
- Contract storage migrated to new format
- MigrationInProgress updated or cleared
- Migrated contracts functional under new runtime
Side Effects
- May need multiple calls to complete full migration
- Contracts may be unusable until migration completes
Code Examples
// ----------------------------------------------------------------------
// HEADS UP: 1 arg below has a complex type with no usable default.
// Look for `undefined as any` and replace it with real value
// before running — the snippet compiles, but will fail at runtime as-is.
// ----------------------------------------------------------------------
import { createClient, Binary } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws";
import { sub } from "@polkadot-api/descriptors"; // generated by: npx papi add sub -w wss://entrypoint-finney.opentensor.ai:443
const client = createClient(getWsProvider("wss://entrypoint-finney.opentensor.ai:443"));
const api = client.getTypedApi(sub);
// Build migrate call (typed, named args)
const weight_limit = undefined as any /* Weight — replace with real value */;
const tx = api.tx.Contracts.migrate({
weight_limit,
});Runtime Info
- Pallet Index
- 29
- Call Index
- 9
- First Version
- v334
- Current Version
- v411