NEAR: Creating & U=upgrading a simple message contract
NEAR support is deprecated
Chainstack deprecated support for NEAR nodes. This page here is for legacy and in case you may find it useful. Aurora nodes are still supported.
This tutorial guides you through creating a simple message contract, deploying the contract, interacting with it, and upgrading it.
In short, you will do the following:
- Create a simple message contract in Rust.
- Deploy the contract using NEAR CLI.
- Change the contract state by interacting with it using NEAR CLI.
- Upgrade the contract with new functionality and redeploy the contract while migrating the contract state.
- Retrieve the old contract state and set a new state.
In the process, you will gain first-hand knowledge of how to create metamorphic smart contracts on NEAR.
Prerequisites
- A NEAR node endpoint.
- Rust to create the contract.
- NEAR CLI to work with accounts, deploy contracts, and interact with the network.
Overview
To get from zero to an upgraded contract on the NEAR testnet, do the following:
Get a testnet NEAR node endpoint.
Set up the NEAR CLI.
Create an account on the NEAR testnet using the NEAR wallet.
Set up the project.
Deploy an initial version of the contract.
Change the contract state by interacting with it.
Deploy an upgraded version of the contract and migrate the contract state.
Retrieve the old contract state and set the new state.
Create an account on the NEAR testnet
Go to the NEAR testnet wallet.
Click Create Account.
Provide any account name that is not taken. Example: upgradablecontract.testnet
.
Click Reserve My Account ID and secure your account as prompted.
This will initiate your account on the NEAR testnet with testnet NEAR.
You can also additionally fund your account on the testnet with the NEAR faucet.
Set up your project
Add the WebAssembly target to your environment:
Initialize your project by running in your project directory:
Edit the generated Cargo.toml
file to provide your project details and setup:
Create the initial contract
This is a simple contract that lets you record a message and then retrieve the recorded message.
In the src/lib.rs
file, provide your smart contract:
Compile the contract
Run:
Create a contract account
Log in to your account that you created earlier:
- Run
near login
. - Use the generated link to authorize the account in your browser.
Once logged in NEAR CLI, run:
where:
simplemessage
— any name to give to the contract that you will deploy.upgradablecontract
— the name of the account on the NEAR testnet that you created earlier.--initialBalance
— providing this flag will fund the created contract with 20 testnet NEAR.- NEAR_ENDPOINT — your NEAR node HTTPS endpoint.
Deploy the initial contract
At this point, you have the following:
- NEAR CLI is set up to work through a NEAR node.
- A compiled simple message contract.
- A funded contract account.
You can now deploy the contract on the NEAR testnet.
To deploy, run:
where:
simple_message.wasm
— the name of the contract that you compiled to.simplemessage
— the name of the contract account that you created earlier.upgradablecontract
— the name of the account on the NEAR testnet that you created earlier.- NEAR_ENDPOINT — your NEAR node HTTPS endpoint.
Example of the deployed contract: 997VvZ2EAss2NjdoGMJkZwJCMTNLZmKbXP3ZnFGkCMAh.
Interact with the contract
Set the contract status message:
where:
simplemessage
— the name of the contract account that you deployed the compiled contract to.upgradablecontract
— the name of the account on the NEAR testnet that you created earlier.- NEAR_ENDPOINT — your NEAR node HTTPS endpoint.
Retrieve the contract status message:
Change the contract source code
You are now going to upgrade the contract by changing the following:
- Change the key-value pair name
records
totaglines
and the corresponding state changing functionset_status
toset_tagline
. - Add the new callable key-value pair
bios
. - Provide a way to retrieve with the new contract code the original state on the chain set through the
records
key-value pair. This is done through themigrate
function.
Edit the src/lib.rs
file to provide the upgraded version of the contract:
Compile the upgraded contract
Run:
Deploy the upgraded contract
You will now deploy the upgraded contract code on the same contract account where the initial contract is running.
Since you interacted with the original contract, you have changed the chain state. Deploying an upgraded version of the contract does not purge the changed state. This means that you must have a way to retrieve the changed state through the upgraded contract interface. In our simple message contract, this is done through the migrate
function.
You will migrate the original state at the upgraded contract deployment.
Run:
where:
simple_message.wasm
— the name of the upgraded contract that you compiled to.simplemessage
— the name of the contract account where the original contract is running.upgradablecontract
— the name of the account on the NEAR testnet that you used to deploy the original contract.- NEAR_ENDPOINT — your NEAR node HTTPS endpoint.
Example of the upgraded contract deployment: 997VvZ2EAss2NjdoGMJkZwJCMTNLZmKbXP3ZnFGkCMAh.
Interact with the upgraded contract
Retrieve the original state message:
where:
- simplemessage — the name of the contract account that you deployed the upgraded contract to.
- upgradablecontract — the name of the account on the NEAR testnet that you used to set the original message.
- NEAR_ENDPOINT — your NEAR node HTTPS endpoint.
Note that since this is an upgraded contract, you are retrieving the original message through the new interface: through get_tagline
instead of get_status
.
You can also change the state with the new function that you added to the contract: set_bio
.
Example:
And retrieve the new state:
Conclusion
This tutorial guided you through the basics of creating a simple NEAR contract, deploying the initial contract on the NEAR network, interacting with the contract, and upgrading the contract.
This tutorial uses the testnet, however, the exact same instructions and sequence will work on the mainnet as well.