> ## Documentation Index
> Fetch the complete documentation index at: https://docs.near.org/llms.txt
> Use this file to discover all available pages before exploring further.
# Updating Contracts
> Learn how to upgrade NEAR smart contracts safely, including programmatic updates, migration strategies, and best practices for contract versioning.
export const Github = ({url, start, end, fname, withSourceLink = true}) => {
const [code, setCode] = useState(null);
function toRaw(ref) {
const fullUrl = ref.slice(ref.indexOf('https'));
const [url] = fullUrl.split('#');
const [org, repo, , branch, ...pathSeg] = new URL(url).pathname.split('/').slice(1);
return `https://raw.githubusercontent.com/${org}/${repo}/${branch}/${pathSeg.join('/')}`;
}
async function fetchCode(url, fromLine, toLine) {
let res;
if (typeof window !== 'undefined') {
const validUntil = localStorage.getItem(`${url}-until`);
if (validUntil && Number(validUntil) > Date.now()) {
res = localStorage.getItem(url);
}
}
if (!res) {
try {
res = await (await fetch(url)).text();
if (typeof window !== 'undefined') {
localStorage.setItem(url, res);
localStorage.setItem(`${url}-until`, String(Date.now() + 60000));
}
} catch {
return 'Error fetching code, please try reloading';
}
}
let body = res.split('\n');
const from = fromLine ? Number(fromLine) - 1 : 0;
const to = toLine ? Number(toLine) : body.length;
body = body.slice(from, to);
const precedingSpace = body.reduce((prev, line) => {
if (line.length === 0) return prev;
const spaces = line.match(/^\s+/);
if (spaces) return Math.min(prev, spaces[0].length);
return 0;
}, Infinity);
return body.map(line => line.slice(precedingSpace === Infinity ? 0 : precedingSpace)).join('\n');
}
function buildSourceUrl(url, start, end) {
const base = url.split('#')[0];
if (start && end) return `${base}#L${start}-L${end}`;
if (start) return `${base}#L${start}`;
return base;
}
useEffect(() => {
const rawUrl = toRaw(url);
fetchCode(rawUrl, start, end).then(res => setCode(res));
}, [url, start, end]);
const sourceUrl = buildSourceUrl(url, start, end);
const startLine = start ? Number(start) : 1;
const fileName = fname ?? sourceUrl.split('/').pop();
return
{}
{start && end &&
Lines {start}–{end}
}
{}
{code === null ?
Loading...
:
{code.split('\n').map((line, i) =>
|
{startLine + i}
|
{line || ' '}
|
)}
}
{}
{withSourceLink &&
}
### 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](https://github.com/near-daos/sputnik-dao-contract/blob/main/sputnikdao2/src/upgrade.rs#L59)
### 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 in Rust/JS, `migrate` is actually an [initialization method](../anatomy/storage) that **ignores** the existing state (`[#init(ignore_state)]`), thus being able to execute and rewrite the state.
In Go, `Migrate()` is a regular `@contract:mutating` method that reads the old state manually using `env.StateRead()`, transforms it, and writes the new state back — no special init directive is needed.
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:
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
INFO --- Result -------------------------
| [
| {
| "premium": false,
| "sender": "test-ac-1719933221123-3.testnet",
| "text": "Hello"
| },
| {
| "premium": false,
| "sender": "test-ac-1719933221123-3.testnet",
| "text": "Hello"
| }
| ]
| ------------------------------------
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
near contract view-storage all as-text network-config testnet now
```
```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.
You can follow a migration step by step in the
[official migration example](https://github.com/near-examples/update-migrate-rust/tree/main/basic-updates/base)
Javascript migration example testfile can be found on here:
[test-basic-updates.ava.js](https://github.com/near/near-sdk-js/blob/develop/examples/__tests__/test-basic-updates.ava.js),
run by this command: `pnpm run test:basic-update` in examples directory.