Upgrading Smart Contracts

NEAR accounts separate their logic (contract code) from their state (storage), allowing the code to be changed without losing data. Contracts can be updated in two ways:

Via Tools

Using NEAR CLI or API if you hold the account’s full access key

Programmatically

Implementing a method that takes new code and deploys it

Updating via NEAR CLI

The simplest way to update a contract is to re-deploy using NEAR CLI:

# Compile your updated contract
cargo near build  # or npm run build

# Deploy the new version
near deploy <your-account.testnet> <path-to-new-wasm>

The account’s state persists - only the code changes.

Programmatic Updates

A contract can update itself by implementing an update method:

Rust
JavaScript

use near_sdk::{near, env, Promise};

#[near]
impl Contract {
    /// Update the contract code
    /// Only callable by the contract owner
    pub fn update_contract(&self) -> Promise {
        // Check authorization
        self.assert_owner();

        // Get new contract code from input
        let code = env::input().expect("No input");

        // Deploy the new code
        Promise::new(env::current_account_id())
            .deploy_contract(code.to_vec())
    }

    fn assert_owner(&self) {
        assert_eq!(
            env::predecessor_account_id(),
            self.owner,
            "Only owner can update"
        );
    }
}

import { NearBindgen, call, near, bytes } from 'near-sdk-js';

@NearBindgen({})
class Contract {
  owner = '';

  @call({})
  update_contract({ code }) {
    // Check authorization
    this.assert_owner();

    // Deploy new code
    const promise = near.promiseBatchCreate(near.currentAccountId());
    near.promiseBatchActionDeployContract(promise, code);
    return promise;
  }

  assert_owner() {
    if (near.predecessorAccountId() !== this.owner) {
      throw new Error('Only owner can update');
    }
  }
}

Calling the Update Method

CLI
JavaScript (NEAR API)

# Read the contract code
CONTRACT_CODE=$(cat path/to/new-contract.wasm | base64)

# Call update method
near call <contract-account> update_contract \
  file-args <path/to/wasm> \
  --gas 300000000000000 \
  --useAccount <owner-account>

const fs = require('fs');
const { connect, keyStores } = require('near-api-js');

// Read contract code
const code = fs.readFileSync('./path/to/contract.wasm');

// Connect to NEAR
const near = await connect({
  networkId: 'testnet',
  keyStore: new keyStores.UnencryptedFileSystemKeyStore(),
  nodeUrl: 'https://rpc.testnet.near.org',
});

const account = await near.account('owner-account.testnet');

// Update contract
await account.functionCall({
  contractId: 'contract-account.testnet',
  methodName: 'update_contract',
  args: code,
  gas: '300000000000000',
});

DAO FactoriesThis is how DAO factories update their contracts.

State Migration

Since the account’s state persists when updating the contract, changes to the state structure require migration.

Safe Changes

When Migration is Needed

If you modify or remove structures stored in state, you’ll see:

Error: Cannot deserialize the contract state

You have three options:

Use a different account (fresh start)
Rollback to previous contract code
Migrate the state (recommended for production)

State Migration Example

Original Contract

Suppose you have a guest book contract:

Rust
JavaScript

use near_sdk::{near, store::Vector};

#[near(serializers=[borsh])]
pub struct PostedMessage {
    pub premium: bool,
    pub sender: AccountId,
    pub text: String,
}

#[near(contract_state)]
pub struct Contract {
    messages: Vector<PostedMessage>,
    payments: Vector<u128>,
}

@NearBindgen({})
class Contract {
  messages = [];
  payments = [];
  
  schema = {
    messages: [{ premium: 'boolean', sender: 'string', text: 'string' }],
    payments: ['string'],
  };
}

Updated Contract

You decide to store payments inside messages:

Rust
JavaScript

#[near(serializers=[borsh])]
pub struct PostedMessage {
    pub premium: bool,
    pub sender: AccountId,
    pub text: String,
    pub payment: u128,  // NEW FIELD
}

#[near(contract_state)]
pub struct Contract {
    messages: Vector<PostedMessage>,
    // payments vector removed
}

@NearBindgen({})
class Contract {
  messages = [];
  
  schema = {
    messages: [{
      premium: 'boolean',
      sender: 'string',
      text: 'string',
      payment: 'string'  // NEW FIELD
    }],
  };
}

The Problem

If you deploy this directly:

Extra payments vector still in storage
Existing PostedMessages missing the payment field
Contract fails to deserialize state

The Solution: Migration Method

Implement a migration function:

Rust
JavaScript

use near_sdk::{near, env, store::Vector};

// Old state structure
#[near(serializers=[borsh])]
struct OldPostedMessage {
    premium: bool,
    sender: AccountId,
    text: String,
}

#[near(serializers=[borsh])]
struct OldState {
    messages: Vector<OldPostedMessage>,
    payments: Vector<u128>,
}

// New state structure
#[near(serializers=[borsh])]
pub struct PostedMessage {
    pub premium: bool,
    pub sender: AccountId,
    pub text: String,
    pub payment: u128,
}

#[near(contract_state)]
pub struct Contract {
    messages: Vector<PostedMessage>,
}

#[near]
impl Contract {
    /// Migration method
    #[init(ignore_state)]
    #[private]
    pub fn migrate() -> Self {
        // Read old state
        let old_state: OldState = env::state_read()
            .expect("Failed to read state");

        // Create new messages with payments
        let mut new_messages = Vector::new(b"m");
        
        for i in 0..old_state.messages.len() {
            let old_msg = old_state.messages.get(i).unwrap();
            let payment = old_state.payments.get(i).unwrap_or(0);
            
            new_messages.push(PostedMessage {
                premium: old_msg.premium,
                sender: old_msg.sender,
                text: old_msg.text,
                payment,
            });
        }

        // Return new state
        Self {
            messages: new_messages,
        }
    }
}

@NearBindgen({})
class Contract {
  messages = [];

  @initialize({})
  migrate() {
    // Read old state directly from storage
    const oldMessages = this.messages || [];
    const oldPayments = this.payments || [];

    // Transform to new structure
    this.messages = oldMessages.map((msg, index) => ({
      premium: msg.premium,
      sender: msg.sender,
      text: msg.text,
      payment: oldPayments[index] || '0',
    }));

    // Clear old payments field
    delete this.payments;

    near.log('Migration completed');
  }
}

Important:The migration function is an initialization method that ignores the existing state (#[init(ignore_state)] or @initialize), allowing it to execute and rewrite the state.

Running the Migration

# 1. Deploy the new contract
near deploy <contract-account> <new-wasm>

# 2. Call the migration method
near call <contract-account> migrate '{}' --useAccount <contract-account>

Why Remove Old Structures?Old data remains in storage even after migration, occupying space and costing NEAR. Always clean up by calling methods like clear() on removed collections.

Best Practices

1. Test Migrations on Testnet

Always test state migrations on testnet first:

Deploy old version
Add test data
Deploy new version
Run migration
Verify all data migrated correctly

2. Version Your State

Include a version field in your contract state:

#[near(contract_state)]
pub struct Contract {
    version: u32,
    // other fields
}

This makes it easier to handle multiple migration paths.

3. Plan for Upgrades

Design your contract with upgrades in mind:

Use collections instead of fixed structures
Keep state structure simple
Document state schema
Plan migration strategy early

4. Limit Update Permissions

Restrict who can update the contract:

pub fn update_contract(&self) {
    // Only specific accounts can update
    assert_eq!(
        env::predecessor_account_id(),
        self.owner,
        "Unauthorized"
    );
}

5. Use DAO for Governance

For important contracts, use a DAO to govern updates:

Community votes on upgrades
Timelock for updates
Emergency pause mechanism

6. Back Up Contract State

Before major updates:

Export contract state
Save locally
Verify export is complete
Then proceed with update

Common Migration Patterns

Adding Optional Fields

Rust
JavaScript

// Before
pub struct User {
    pub name: String,
    pub balance: u128,
}

// After - no migration needed if using Option
pub struct User {
    pub name: String,
    pub balance: u128,
    pub email: Option<String>,  // Optional field
}

// Fields can be undefined without migration
class User {
  name = '';
  balance = '0';
  email = null;  // Optional field
}

Renaming Fields

Requires migration to copy data:

#[init(ignore_state)]
pub fn migrate() -> Self {
    let old: OldContract = env::state_read().unwrap();
    Self {
        new_field_name: old.old_field_name,
        // ... other fields
    }
}

Changing Field Types

Requires migration with type conversion:

#[init(ignore_state)]
pub fn migrate() -> Self {
    let old: OldContract = env::state_read().unwrap();
    Self {
        // Convert String to AccountId
        account: old.account_string.parse().unwrap(),
        // ... other fields
    }
}

Emergency Procedures

Rollback

If an update goes wrong, rollback immediately:

# Redeploy previous version
near deploy <account> <old-contract.wasm>

Pause Contract

Implement a pause mechanism for emergencies:

#[near]
impl Contract {
    pub fn pause(&mut self) {
        self.assert_owner();
        self.paused = true;
    }

    pub fn unpause(&mut self) {
        self.assert_owner();
        self.paused = false;
    }

    fn assert_not_paused(&self) {
        assert!(!self.paused, "Contract is paused");
    }
}

Migration Checklist

Resources

Migration Example

Complete migration example project

DAO Updates

How DAOs handle contract updates

Testing

Test your migrations thoroughly

Security

Security considerations for updates

Next Steps

Monitor Contract

Track your contract after updates

Build Frontend

Update your frontend for new features

Security Audit

Audit after major changes

Documentation

Update your documentation

Getting Started

Protocol

Smart Contracts

Web3 Applications

AI and Agents

Chain Abstraction

Primitives

Data Infrastructure

Via Tools

Programmatically

​Updating via NEAR CLI

​Programmatic Updates

​Calling the Update Method

​State Migration

​Safe Changes

​When Migration is Needed

​State Migration Example

​Original Contract

​Updated Contract

​The Problem

​The Solution: Migration Method

​Running the Migration

​Best Practices

​Common Migration Patterns

​Adding Optional Fields

​Renaming Fields

​Changing Field Types

​Emergency Procedures

​Rollback

​Pause Contract

​Migration Checklist

​Resources

Migration Example

DAO Updates

Testing

Security

​Next Steps

Monitor Contract

Build Frontend

Security Audit

Documentation

Build docs developers (and LLMs) love

Updating via NEAR CLI

Programmatic Updates

Calling the Update Method

State Migration

Safe Changes

When Migration is Needed

State Migration Example

Original Contract

Updated Contract

The Problem

The Solution: Migration Method

Running the Migration

Best Practices

Common Migration Patterns

Adding Optional Fields

Renaming Fields

Changing Field Types

Emergency Procedures

Rollback

Pause Contract

Migration Checklist

Resources

Next Steps