Skip to main content

Updating Contracts

Learn how to update NEAR smart contracts, both through tools like NEAR CLI and programmatically. Understand the implications of state migration when changing contract logic.

NEAR accounts separate their logic (contract's code) from their state (storage), allowing the code to be changed.

Contract's can be updated in two ways:

  1. Through tools such as NEAR CLI or the NEAR API (if you hold the account's full access key).
  2. Programmatically, by implementing a method that takes the new code and deploys it.

Updating Through Tools​

Simply re-deploy another contract using your preferred tool, for example, using NEAR CLI:

# (optional) If you don't have an account, create one
near create-account <account-id> --useFaucet

# Deploy the contract
near deploy <account-id> <wasm-file>

Programmatic Update​

A smart contract can also update itself by implementing a method that:

  1. Takes the new wasm contract as input
  2. Creates a Promise to deploy it on itself

How to Invoke Such Method?​

# Load the contract's raw bytes
CONTRACT_BYTES=`cat ./path/to/wasm.wasm | base64`

# Call the update_contract method
near call <contract-account> update_contract "$CONTRACT_BYTES" --base64 --accountId <manager-account> --gas 300000000000000
DAO Factories

This is how DAO factories update their contracts

Migrating the State​

Since the account's logic (smart contract) is separated from the account's state (storage), the account's state persists when re-deploying a contract.

Because of this, adding methods or modifying existing ones will yield no problems.

However, deploying a contract that modifies or removes structures stored in the state will raise an error: Cannot deserialize the contract state, in which case you can choose to:

  1. Use a different account
  2. Rollback to the previous contract code
  3. Add a method to migrate the contract's state

The Migration Method​

If you have no option but to migrate the state, then you need to implement a method that:

  1. Reads the current state of the contract
  2. Applies different functions to transform it into the new state
  3. Returns the new state
DAO Update

This is how DAOs update themselves

Example: Guest Book Migration​

Imagine you have a Guest Book where you store messages, and the users can pay for such messages to be "premium". You keep track of the messages and payments using the following state:

Update Contract​

At some point you realize that you could keep track of the payments inside of the PostedMessage itself, so you change the contract to:

Incompatible States​

If you deploy the update into an initialized account the contract will fail to deserialize the account's state, because:

  1. There is an extra payments vector saved in the state (from the previous contract)
  2. The stored PostedMessages are missing the payment field (as in the previous contract)

Migrating the State​

To fix the problem, you need to implement a method that goes through the old state, removes the payments vector and adds the information to the PostedMessages:

Notice that migrate is actually an initialization method that ignores the existing state ([#init(ignore_state)]), thus being able to execute and rewrite the state.

Why we should remove old structures from the state?

To understand why we should remove old structures from the state let's take a look to how the data is stored.

For example, if the old version of the contract stores two messages with payments according methods get_messages and get_payments will return the following results:

get_messags result
INFO --- Result -------------------------
|    [
|      {
|        "premium": false,
|        "sender": "test-ac-1719933221123-3.testnet",
|        "text": "Hello"
|      },
|      {
|        "premium": false,
|        "sender": "test-ac-1719933221123-3.testnet",
|        "text": "Hello"
|      }
|    ]
|    ------------------------------------
get_payments result
INFO --- Result -------------------------
 |    [
 |      "10000000000000000000000",
 |      "10000000000000000000000"
 |    ]
 |    ------------------------------------

But if we take a look at the storage as text using following command, we will see that each payment is stored under its own key started with p\ prefix.

near contract view-storage <CONTRACT_ID> all as-text network-config testnet now
Storage as text result
INFO Contract state (values):
 |      key:   STATE
 |      value: \x02\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00m\x02\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00p
 |      --------------------------------
 |      key:   m\x00\x00\x00\x00\x00\x00\x00\x00
 |      value: \x00\x1f\x00\x00\x00test-ac-1719933221123-3.testnet\x05\x00\x00\x00Hello
 |      --------------------------------
 |      key:   m\x01\x00\x00\x00\x00\x00\x00\x00
 |      value: \x00\x1f\x00\x00\x00test-ac-1719933221123-3.testnet\x05\x00\x00\x00Hello
 |      --------------------------------
 |      key:   p\x00\x00\x00\x00\x00\x00\x00\x00
 |      value: \x00\x00@\xb2\xba\xc9\xe0\x19\x1e\x02\x00\x00\x00\x00\x00\x00
 |      --------------------------------
 |      key:   p\x01\x00\x00\x00\x00\x00\x00\x00
 |      value: \x00\x00@\xb2\xba\xc9\xe0\x19\x1e\x02\x00\x00\x00\x00\x00\x00
 |      --------------------------------

That means that while migrating the state to a new version we need not only change the messages structure, but also remove all payments related keys from the state. Otherwise, the old keys will simply stay behind being orphan, still occupying space.

To remove them in migrate method, we call clear() method on payments vector in mutable old_state struct. This method removes all elements from the collection.

tip

You can follow a migration step by step in the official migration example Javascript migration example testfile can be found on here: test-basic-updates.ava.js, run by this command: pnpm run test:basic-update in examples directory.