Contract Administration

Contracts with an admin address can be migrated to new code versions and have their admin transferred or cleared. These operations are central to the CosmWasm upgrade lifecycle.

Migrating a Contract

Migrate moves a contract to a new code ID while preserving its address and state. The contract must have an admin, and the migration message is passed to the new code’s migrate entry point.

Upload the new code

const newWasmCode = readFileSync("./my_contract_v2.wasm");
const { codeId: newCodeId } = await client.upload(address, newWasmCode, "auto");

Migrate the contract

const migrateResult = await client.migrate(
  address,
  contractAddress,
  newCodeId,
  { new_field: "default_value" },
  "auto",
);

The migrate message (fourth argument) is contract-defined. It typically handles schema changes, data migrations, or field initialization for the new version.

Only the contract’s admin address can call migrate. The sender must match the admin set during instantiation (or a subsequent updateAdmin call).

Updating the Admin

Transfer admin privileges to a different address:

await client.updateAdmin(address, contractAddress, "osmo1newadmin...", "auto");

After this call, only osmo1newadmin... can migrate the contract or change the admin again. The original admin loses all privileges.

Clearing the Admin

Remove the admin entirely, making the contract permanently non-upgradeable:

await client.clearAdmin(address, contractAddress, "auto");

Clearing the admin is irreversible. The contract can never be migrated or have its admin updated again. Only do this when you are certain the contract should be immutable.

Contract Lifecycle Summary

State	Can Migrate	Can Change Admin	How to Reach
Admin set	Yes	Yes	`instantiate` with `admin` option
Admin transferred	Yes	Yes	`updateAdmin`
Admin cleared	No	No	`clearAdmin`
No admin (from init)	No	No	`instantiate` without `admin` option

CosmJS

Concepts

Guides

API Reference

Contract Administration

Migrating a Contract

Updating the Admin

Clearing the Admin

Contract Lifecycle Summary

Next Steps

Querying Contracts

Gas and Advanced Usage

​Migrating a Contract

​Updating the Admin

​Clearing the Admin

​Contract Lifecycle Summary

​Next Steps

Querying Contracts

Gas and Advanced Usage

Migrating a Contract

Updating the Admin

Clearing the Admin

Contract Lifecycle Summary

Next Steps