From e6b571d234bc05231d332b200283177c14dbbacf Mon Sep 17 00:00:00 2001 From: ghimire007 <69514062+ghimire007@users.noreply.github.com> Date: Sat, 30 Sep 2023 06:18:42 +1000 Subject: [PATCH] Added Tabs for both near-cli-rs and near-cli commands (#1480) * Update deploy.md * Update lock.md * Update upgrade.md * Update prototyping.md * Update token-tx.md * Update prototyping.md * Update serialization-interface.md * Update token-tx.md --------- Co-authored-by: gagdiez --- docs/2.develop/deploy.md | 92 +++++++++++++++++++ docs/2.develop/lock.md | 30 ++++++ docs/2.develop/upgrade.md | 45 ++++++++- docs/sdk/js/building/prototyping.md | 91 +++++++++++++++++- docs/sdk/js/promises/token-tx.md | 28 +++++- docs/sdk/rust/building/prototyping.md | 68 ++++++++++++++ .../serialization-interface.md | 25 ++++- docs/sdk/rust/promises/token-tx.md | 29 +++++- 8 files changed, 398 insertions(+), 10 deletions(-) diff --git a/docs/2.develop/deploy.md b/docs/2.develop/deploy.md index 62db2081917..ec4cb2d1f0d 100644 --- a/docs/2.develop/deploy.md +++ b/docs/2.develop/deploy.md @@ -3,6 +3,8 @@ id: deploy title: NEAR CLI - Basics sidebar_label: Deploying and Using --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; After your contract is ready you can deploy it in the NEAR network for everyone to use it. @@ -24,6 +26,11 @@ Thanks to the `NEAR CLI` deploying a contract is as simple as: 2. Deploy it into the desired account using the [NEAR CLI](../4.tools/cli.md#near-deploy): #### Create an Account and Deploy + + + + + ```bash # Automatically deploy the wasm in a new account near dev-deploy @@ -32,7 +39,27 @@ near dev-deploy cat ./neardev/dev-account ``` + + + +```bash +# Automatically deploy the wasm in a new account +near account create-account sponsor-by-faucet-service .testnet autogenerate-new-keypair save-to-keychain network-config testnet create + + +near contract deploy .testnet use-file without-init-call network-config testnet sign-with-keychain +``` + + + + + + #### Deploy in an Existing Account + + + + ```bash # login into your account near login @@ -41,6 +68,21 @@ near login near deploy ``` + + + +```bash +# login into your account +near account import-account using-web-wallet network-config testnet + +# deploy the contract +near contract deploy use-file without-init-call network-config testnet sign-with-keychain send + +``` + + + + :::tip You can overwrite a contract by deploying another on top of it. In this case, the account's logic will change, but the state will persist @@ -62,10 +104,29 @@ Considering this, we advise to name methods using `snake_case` in all SDKs as th If your contract has an [initialization method](./contracts/anatomy.md#initialization-functions) you can call it to initialize the state. This is not necessary if your contract implements `default` values for the state. + + + + + ```bash # Call the initialization method (`init` in our examples) near call [] --accountId ``` + + + + +```bash +# Call the initialization method (`init` in our examples) +near contract call-function as-transaction json-args [] prepaid-gas '30 TeraGas' attached-deposit '0 NEAR' sign-as network-config testnet sign-with-keychain send +``` + + + + + + :::info You can initialize your contract [during deployment](#deploying-the-contract) using the `--initFunction` & `--initArgs` arguments. @@ -81,9 +142,24 @@ Once your contract is deployed you can interact with it right away using [NEAR C ### View methods View methods are those that perform **read-only** operations. Calling these methods is free, and do not require to specify which account is being used to make the call: + + + + + + ```bash near view ``` + + + + +```bash +near contract call-function as-read-only text-args '' network-config testnet now +``` + + :::tip View methods have by default 200 TGAS for execution @@ -95,6 +171,22 @@ View methods have by default 200 TGAS for execution Change methods are those that perform both read and write operations. For these methods we do need to specify the account being used to make the call, since that account will expend GAS in the call. + + + + ```bash near call --accountId [--deposit ] [--gas ] ``` + + + + + +```bash + +near contract call-function as-transaction json-args prepaid-gas attached-deposit sign-as network-config testnet sign-with-keychain send +``` + + + diff --git a/docs/2.develop/lock.md b/docs/2.develop/lock.md index ed5899d2392..a08bb12a06a 100644 --- a/docs/2.develop/lock.md +++ b/docs/2.develop/lock.md @@ -3,17 +3,47 @@ id: lock title: Locking Accounts --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + Removing all [full access keys](../4.tools/cli.md#near-delete-key-near-delete-key) from an account will effectively **lock it**. When an account is locked nobody can perform transactions in the account's name (e.g. update the code or transfer money). #### How to Lock an Account + + + ```bash near keys # result: [access_key: {"nonce": ..., "public_key": ''}] near delete-key '' ``` + + + +```bash +near account list-keys network-config testnet now +# result: + ++---+------------+-------+-------------+ +| # | Public Key | Nonce | Permissions | ++---+------------+-------+-------------+ + .. '' ... ... ++---+------------+-------+-------------+ + +near account delete-key '' network-config testnet sign-with-keychain send + +``` + + + + + + + + #### Why Locking an Account Locking an account brings more reassurance to end-users, since they know no external actor will be able to manipulate the account's diff --git a/docs/2.develop/upgrade.md b/docs/2.develop/upgrade.md index 59255c44dd8..b17a37480d2 100644 --- a/docs/2.develop/upgrade.md +++ b/docs/2.develop/upgrade.md @@ -20,6 +20,10 @@ Contract's can be updated in two ways: ## Updating Through Tools Simply re-deploy another contract using your preferred tool, for example, using [NEAR CLI](../4.tools/cli.md): + + + + ```bash # If you already used dev-deploy the same account will be used near dev-deploy --wasmFile @@ -28,6 +32,28 @@ near dev-deploy --wasmFile near deploy --wasmFile ``` + + + + + + +```bash +# If you already used dev-deploy the same account will be used +near contract deploy .testnet use-file without-init-call network-config testnet sign-with-keychain + + +# If you logged in +near contract deploy use-file without-init-call network-config testnet sign-with-keychain send + +``` + + + + + + + --- ## Programmatic Update @@ -45,7 +71,7 @@ A smart contract can also update itself by implementing a method that: #### How to Invoke Such Method? - + ```bash # Load the contract's raw bytes @@ -56,7 +82,20 @@ near call update_contract "$CONTRACT_BYTES" --base64 --accoun ``` - + + + +```bash +# Load the contract's raw bytes +CONTRACT_BYTES=`cat ./path/to/wasm.wasm | base64` + +# Call the update_contract method +near contract call-function as-transaction update_contract base64-args "$CONTRACT_BYTES" prepaid-gas '300 TeraGas' attached-deposit '0 NEAR' sign-as network-config testnet sign-with-keychain send + +``` + + + ```js // Load the contract's raw bytes @@ -151,4 +190,4 @@ Notice that `migrate` is actually an [initialization method](./contracts/anatomy :::tip You can follow a migration step by step in the [official migration example](https://github.com/near-examples/update-migrate-rust/tree/main/contracts/basic-updates/base) -::: \ No newline at end of file +::: diff --git a/docs/sdk/js/building/prototyping.md b/docs/sdk/js/building/prototyping.md index 3c049ee27fa..140e7aa3525 100644 --- a/docs/sdk/js/building/prototyping.md +++ b/docs/sdk/js/building/prototyping.md @@ -4,6 +4,9 @@ sidebar_label: Rapid Prototyping title: "Upgrading Contracts: Rapid Prototyping" --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Rapid Prototyping When you change the interface of a contract and re-deploy it, you may see this error: @@ -32,10 +35,32 @@ For both cases, let's consider the following example. Let's say you deploy [a JS status message contract](https://github.com/near/near-sdk-js/blob/263c9695ab7bb853ced12886c4b3f8663070d900/examples/src/status-message-collections.js#L10-L42) contract to testnet, then call it with: + + + ```bash near call [contract] set_status '{"message": "lol"}' --accountId you.testnet near view [contract] get_status '{"account_id": "you.testnet"}' ``` + + + +```bash +near contract call-function as-transaction [contract] set_status json-args '{"message": "lol"}' prepaid-gas '30 TeraGas' attached-deposit '0 NEAR' sign-as you.testnet network-config testnet sign-with-keychain send + +near contract call-function as-read-only [contract] get_status text-args '{"account_id": "you.testnet"}' network-config testnet now +``` + + + + + + + + + + + This will return the message that you set with the call to `set_status`, in this case `"lol"`. @@ -49,9 +74,34 @@ You build & deploy the contract again, thinking that maybe because the new `tagl When first getting started with a new project, the fastest way to deploy a contract is [`dev-deploy`](/concepts/basics/accounts/creating-accounts): + + + + ```bash near dev-deploy [--wasmFile ./path/to/compiled.wasm] ``` + + + +```bash +near account create-account sponsor-by-faucet-service .testnet autogenerate-new-keypair save-to-keychain network-config testnet create + +near contract deploy .testnet use-file without-init-call network-config testnet sign-with-keychain + +``` + + + + + + + + + + + + This does a few things: @@ -69,23 +119,62 @@ The easiest way is just to delete the `neardev` folder, then run `near dev-deplo ### 2. Deleting & recreating contract account If you want to have a predictable account name rather than an ever-changing `dev-*` account, the best way is probably to create a sub-account: + + ```bash title="Create sub-account" near create-account app-name.you.testnet --masterAccount you.testnet ``` + + + +```bash title="Create sub-account" +near account create-account fund-myself app-name.you.testnet '100 NEAR' autogenerate-new-keypair save-to-keychain sign-as you.testnet network-config testnet sign-with-keychain send +``` + + + + + + Then deploy your contract to it: + + + ```bash title="Deploy to sub-account" near deploy --accountId app-name.you.testnet [--wasmFile ./path/to/compiled.wasm] ``` + + + +```bash title="Deploy to sub-account" +near contract deploy app-name.you.testnet use-file <./path/to/compiled.wasm> without-init-call network-config testnet sign-with-keychain send +``` + + + + + In this case, how do you delete all contract state and start again? Delete the sub-account and recreate it. + + + ```bash title="Delete sub-account" near delete app-name.you.testnet you.testnet ``` + + + +```bash title="Delete sub-account" +near account delete-account app-name.you.testnet beneficiary you.testnet network-config testnet sign-with-keychain send +``` + + This sends all funds still on the `app-name.you.testnet` account to `you.testnet` and deletes the contract that had been deployed to it, including all contract state. -Now you create the sub-account and deploy to it again using the commands above, and it will have empty state like it did the first time you deployed it. \ No newline at end of file +Now you create the sub-account and deploy to it again using the commands above, and it will have empty state like it did the first time you deployed it. diff --git a/docs/sdk/js/promises/token-tx.md b/docs/sdk/js/promises/token-tx.md index ae23100e9f7..c87b09eb735 100644 --- a/docs/sdk/js/promises/token-tx.md +++ b/docs/sdk/js/promises/token-tx.md @@ -3,6 +3,9 @@ sidebar_position: 2 title: Sending Native Tokens --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Sending $NEAR You might want to send tokens from a contract for many reasons. @@ -41,6 +44,27 @@ Most of this is boilerplate you're probably familiar with by now – imports, s - Returning the `NearPromise`: This allows NEAR Explorer, near-cli, near-api-js, and other tooling to correctly determine if a whole chain of transactions is successful. If your function does not return `Promise`, tools like near-cli will return immediately after your function call. And then even if the `transfer` fails, your function call will be considered successful. -Using near-cli, someone could invoke this function with a call like: +Using near-cli or near-cli-rs, someone could invoke this function with a call like: + + + + + +```bash +near call pay '{"amount": "1000000000000000000000000", "to": "example.near"}' --accountId benjiman.near +``` + + + + + + +```bash +near contract call-function as-transaction pay json-args '{"amount": "1000000000000000000000000", "to": "example.near"}' prepaid-gas '30 TeraGas' attached-deposit '0 NEAR' sign-as benjiman.near network-config testnet sign-with-keychain send +``` + + + + + - near call $CONTRACT pay '{"amount": "1000000000000000000000000", "to": "example.near"}' --accountId root.near diff --git a/docs/sdk/rust/building/prototyping.md b/docs/sdk/rust/building/prototyping.md index 1a874358f65..1cc42422d21 100644 --- a/docs/sdk/rust/building/prototyping.md +++ b/docs/sdk/rust/building/prototyping.md @@ -4,6 +4,8 @@ sidebar_label: Rapid Prototyping title: "Upgrading Contracts: Rapid Prototyping" --- import {CodeTabs, Language, Github} from "@site/components/codetabs"; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Rapid Prototyping @@ -42,11 +44,24 @@ The [rust-status-message](https://github.com/near-examples/rust-status-message) Let's say you deploy this contract to testnet, then call it with: + + + ```bash near call [contract] set_status '{"message": "lol"}' --accountId you.testnet near view [contract] get_status '{"account_id": "you.testnet"}' ``` + + + +```bash +near contract call-function as-transaction [contract] set_status json-args '{"message": "lol"}' prepaid-gas '30 TeraGas' attached-deposit '0 NEAR' sign-as you.testnet network-config testnet sign-with-keychain send + +near contract call-function as-read-only [contract] get_status text-args '{"account_id": "you.testnet"}' network-config testnet now +``` + + This will return the message that you set with the call to `set_status`, in this case `"lol"`. At this point the contract is deployed and has some state. @@ -97,10 +112,26 @@ You build & deploy the contract again, thinking that maybe because the new `tagl ### 1. `rm -rf neardev && near dev-deploy` When first getting started with a new project, the fastest way to deploy a contract is [`dev-deploy`](/concepts/basics/accounts/creating-accounts): + + ```bash near dev-deploy [--wasmFile ./path/to/compiled.wasm] ``` + + + +```bash +near account create-account sponsor-by-faucet-service .testnet autogenerate-new-keypair save-to-keychain network-config testnet create + +near contract deploy .testnet use-file without-init-call network-config testnet sign-with-keychain + +``` + + + + + This does a few things: @@ -119,21 +150,58 @@ The easiest way is just to delete the `neardev` folder, then run `near dev-deplo If you want to have a predictable account name rather than an ever-changing `dev-*` account, the best way is probably to create a sub-account: + + + ```bash title="Create sub-account" near create-account app-name.you.testnet --masterAccount you.testnet ``` + + + +```bash title="Create sub-account" +near account create-account fund-myself app-name.you.testnet '100 NEAR' autogenerate-new-keypair save-to-keychain sign-as you.testnet network-config testnet sign-with-keychain send +``` + + + Then deploy your contract to it: + + + ```bash title="Deploy to sub-account" near deploy --accountId app-name.you.testnet [--wasmFile ./path/to/compiled.wasm] ``` + + + +```bash title="Deploy to sub-account" +near contract deploy app-name.you.testnet use-file <./path/to/compiled.wasm> without-init-call network-config testnet sign-with-keychain send +``` + + + + In this case, how do you delete all contract state and start again? Delete the sub-account and recreate it. + + + + ```bash title="Delete sub-account" near delete app-name.you.testnet you.testnet ``` + + + +```bash title="Delete sub-account" +near account delete-account app-name.you.testnet beneficiary you.testnet network-config testnet sign-with-keychain send +``` + + This sends all funds still on the `app-name.you.testnet` account to `you.testnet` and deletes the contract that had been deployed to it, including all contract state. diff --git a/docs/sdk/rust/contract-interface/serialization-interface.md b/docs/sdk/rust/contract-interface/serialization-interface.md index 4c10632001e..97e7f49c9e5 100644 --- a/docs/sdk/rust/contract-interface/serialization-interface.md +++ b/docs/sdk/rust/contract-interface/serialization-interface.md @@ -1,6 +1,8 @@ --- sidebar_position: 5 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; # Serialization Protocols @@ -57,7 +59,26 @@ https://github.com/mikedotexe/rust-status-message/blob/b83c5126fdbe0f19bc904e547 To call this with NEAR CLI, use a command similar to this: - near call rust-status-message.demo.testnet set_status_borsh --base64 'DAAAAEFsb2hhIGhvbnVhIQ==' --accountId demo.testnet + + + +```bash +near call rust-status-message.demo.testnet set_status_borsh --base64 'DAAAAEFsb2hhIGhvbnVhIQ==' --accountId demo.testnet +``` + + + + + + + +```bash +near contract call-function as-transaction rust-status-message.demo.testnet set_status_borsh base64-args 'DAAAAEFsb2hhIGhvbnVhIQ==' prepaid-gas '30 TeraGas' attached-deposit '0 NEAR' sign-as demo.testnet network-config testnet sign-with-keychain send +``` + + + + See more details in [this GitHub gist](https://gist.github.com/mfornet/d8a94af333a68d67affd8cb78464c7c0) from [Marcelo](https://gist.github.com/mfornet). @@ -150,4 +171,4 @@ impl Contract { self.data.into() } } -``` \ No newline at end of file +``` diff --git a/docs/sdk/rust/promises/token-tx.md b/docs/sdk/rust/promises/token-tx.md index ac4fc193a3f..4f3f74b463e 100644 --- a/docs/sdk/rust/promises/token-tx.md +++ b/docs/sdk/rust/promises/token-tx.md @@ -2,6 +2,9 @@ sidebar_position: 2 --- +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + # Sending $NEAR You might want to send tokens from a contract for many reasons. @@ -47,7 +50,29 @@ Most of this is boilerplate you're probably familiar with by now – imports, s * Returning `Promise`: This allows NEAR Explorer, near-cli, near-api-js, and other tooling to correctly determine if a whole chain of transactions is successful. If your function does not return `Promise`, tools like near-cli will return immediately after your function call. And then even if the `transfer` fails, your function call will be considered successful. You can see an example of this behavior [here](https://github.com/near-examples/xcc-advanced). -Using near-cli, someone could invoke this function with a call like: +Using near-cli or near-cli-rs, someone could invoke this function with a call like: + + + + + +```bash +near call pay '{"amount": "1000000000000000000000000", "to": "example.near"}' --accountId benjiman.near +``` + + + + + + +```bash +near contract call-function as-transaction pay json-args '{"amount": "1000000000000000000000000", "to": "example.near"}' prepaid-gas '30 TeraGas' attached-deposit '0 NEAR' sign-as benjiman.near network-config testnet sign-with-keychain send +``` + + + + + + - near call $CONTRACT pay '{"amount": "1000000000000000000000000", "to": "example.near"}' --accountId benjiman.near