diff --git a/docs/2.build/2.smart-contracts/release/upgrade.md b/docs/2.build/2.smart-contracts/release/upgrade.md index 28b3db0c8b2..ece58a4914a 100644 --- a/docs/2.build/2.smart-contracts/release/upgrade.md +++ b/docs/2.build/2.smart-contracts/release/upgrade.md @@ -11,8 +11,8 @@ allowing the code to be changed. Contract's can be updated in two ways: -1. **Through tools** such as [NEAR CLI](../../../4.tools/cli.md) or - [near-api-js](../../../4.tools/near-api-js/quick-reference.md) (if you hold +1. **Through tools** such as [NEAR CLI](../../../4.tools/cli.md) or the + [NEAR API](../../../4.tools/near-api.md) (if you hold the account's [full access key](../../../1.concepts/protocol/access-keys.md)). 2. **Programmatically**, by implementing a method that diff --git a/docs/2.build/4.web3-apps/frontend.md b/docs/2.build/4.web3-apps/frontend.md index b4e27a0ea33..2fae10c11cc 100644 --- a/docs/2.build/4.web3-apps/frontend.md +++ b/docs/2.build/4.web3-apps/frontend.md @@ -29,12 +29,12 @@ While your user interface layer will remain centralized, the backend layer—inc When building a frontend that can connect with the NEAR blockchain using standard web2 tooling will require you to import two dependencies: -- [NEAR API JS](../../4.tools/near-api-js/quick-reference.md) - A JavaScript API tool that allows frontend clients the ability to view and retrieve data directly from the blockchain. +- [NEAR API JS](../../4.tools/near-api.md) - A JavaScript API tool that allows frontend clients the ability to view and retrieve data directly from the blockchain. - [Wallet Selector](../../4.tools/wallet-selector.md) - Wallet integration tool allowing developers to choose which wallets are supported and allows users to choose which wallet they would like to connect with. :::tip -[Checkout this article](integrate-contracts.md) to learn how to integrate smart contracts to your frontend, using [Wallet Selector](../../4.tools/wallet-selector.md) and [NEAR API JS](../../4.tools/near-api-js/quick-reference.md). +[Checkout this article](integrate-contracts.md) to learn how to integrate smart contracts to your frontend, using [Wallet Selector](../../4.tools/wallet-selector.md) and [NEAR API JS](../../4.tools/near-api.md). ::: diff --git a/docs/4.tools/near-api-js/cookbook.md b/docs/4.tools/near-api-js/cookbook.md deleted file mode 100644 index b13a4c7e1c7..00000000000 --- a/docs/4.tools/near-api-js/cookbook.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -id: cookbook -title: Common Use Cases -sidebar_label: Cookbook ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -The repository contains [many recipes](https://github.com/near/near-api-js/blob/master/packages/cookbook) that you can readily use to solve common case scenarios. - -| Name | Description | -|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| ----------------------------------------------------------------------------------------------------------- | -| **ACCOUNTS** | | -| [Create Account](https://github.com/near/near-api-js/blob/master/packages/cookbook/accounts/create-testnet-account.js) | Create [NEAR accounts](/concepts/protocol/account-model) without using NEAR Wallet. | -| [Access Key Rotation](https://github.com/near/near-api-js/tree/master/packages/cookbook/accounts/access-keys) | Create and delete [access keys](/concepts/protocol/access-keys) for added security. | -| **TRANSACTIONS** | | -| [Get Transaction Status](https://github.com/near/near-api-js/blob/master/packages/cookbook/transactions/get-tx-status.ts) | Gets transaction status using a tx hash and associated account/contract ID. | -| [Recent Transaction Details](https://github.com/near/near-api-js/blob/master/packages/cookbook/transactions/get-tx-detail.js) | Get recent transaction details without using an [indexing](/concepts/advanced/near-indexer-framework) service. | -| [Batch Transactions](https://github.com/near/near-api-js/blob/master/packages/cookbook/transactions/batch-transactions.js) | Sign and send multiple [transactions](/concepts/protocol/transactions). | -| **UTILS** | | -| [Deploy Contract](https://github.com/near/near-api-js/blob/master/packages/cookbook/utils/deploy-contract.js) | Deploys a smart contract using a pre-compiled WASM file. | -| [Calculate Gas](https://github.com/near/near-api-js/blob/master/packages/cookbook/utils/calculate-gas.js) | Calculate [gas burnt](/concepts/protocol/gas) from any contract call. | -| [Read State w/o Account](https://github.com/near/near-api-js/blob/master/packages/cookbook/utils/get-state.js) | Read state of a contract without instantiating an account. | -| [Wrap](https://github.com/near/near-api-js/blob/master/packages/cookbook/utils/wrap-near.js) & [Unwrap](https://github.com/near/near-api-js/blob/master/packages/cookbook/utils/unwrap-near.js) NEAR | Wrap and unwrap NEAR using the `wrap.near` smart contract. | -| [Verify Signature](https://github.com/near/near-api-js/blob/master/packages/cookbook/utils/verify-signature.js) | Verify a key pair signature. | diff --git a/docs/4.tools/near-api-js/faq.md b/docs/4.tools/near-api-js/faq.md deleted file mode 100644 index 55647966db9..00000000000 --- a/docs/4.tools/near-api-js/faq.md +++ /dev/null @@ -1,434 +0,0 @@ ---- -id: faq -title: FAQ for NEAR JavaScript API -sidebar_label: FAQ ---- - -A collection of Frequently Asked Questions by the community. - - -## General {#general} - -### Can I use `near-api-js` on a static html page? {#can-i-use-near-api-js-on-a-static-html-page} - -You can load the script from a CDN. - -```html - -``` - -:::note -Make sure you load the latest version. - -Versions list is on [npmjs.com](https://www.npmjs.com/package/near-api-js) -::: - -
-Example Implementation -

- -```html - - - - - - - - Document - - - -

- - - - - - - -``` - -

-
- ---- - -### What front-end frameworks can I use the JavaScript API with? - -The JavaScript API is framework-agnostic. You can include it in any front-end framework, such as React, Vue, Angular, and others. - -You can use [`create-near-app`](https://github.com/near/create-near-app) to quickly bootstrap projects with different templates: - - npx create-near-app - -### Can I use the JavaScript API with mobile JavaScript frameworks such as React Native? - -The JavaScript API can be used in most JavaScript runtimes, and under the hood, it’s an abstraction over NEAR’s [RPC API](/api/rpc/introduction). However, notice that the Wallet can’t be used everywhere. For example, in React Native apps you’ll be able to use the Wallet in web versions of the apps, but it won’t work in the native app deployments. - -You can use the Wallet in `WebView` components in iOS or Android, however be aware that it uses `LocalStorage` for `KeyStore`, and it’s your responsibility to persist the storage when you manage loading of `WebView` components. - ---- - -## Transactions {#transactions} - -### How to check the status of transaction - -Please refer to examples about transactions in the [Cookbook](/tools/near-api-js/cookbook). - -### How transactions are signed and sent by near-api-js - -There are a few steps involved before transaction data is communicated to the network and eventually included in a block. The following steps are taken when creating, signing and ultimately a transaction from a user's account: - -1. The user creates a transaction object using the [`account.signAndSendTransaction` method](https://github.com/near/near-api-js/blob/f78616480ba84c73f681211fe6266bd2ed2b9da1/packages/near-api-js/src/account.ts#L200). This method accepts an array of actions and returns an object for the outcome of the transaction. -2. The transaction is signed using the [`account.signTransaction` method](https://github.com/near/near-api-js/blob/f78616480ba84c73f681211fe6266bd2ed2b9da1/packages/near-api-js/src/account.ts#L204). This method accepts an array of actions and returns a signed transaction object. -3. The signed transaction object is sent to the network using the [`account.connection.provider.sendTransaction` method](https://github.com/near/near-api-js/blob/f78616480ba84c73f681211fe6266bd2ed2b9da1/packages/near-api-js/src/account.ts#L208). This method accepts a signed transaction object and returns a transaction hash. This step [performs the borsh serialization of the transaction object](https://github.com/near/near-api-js/blob/f78616480ba84c73f681211fe6266bd2ed2b9da1/packages/near-api-js/src/providers/json-rpc-provider.ts#L80) and calls the [`broadcast_tx_commit` JSON RPC method with the serialized transaction object encoded in base64](https://github.com/near/near-api-js/blob/f78616480ba84c73f681211fe6266bd2ed2b9da1/packages/near-api-js/src/providers/json-rpc-provider.ts#L81). - -### How to send batch transactions - -You may batch send transactions by using the `signAndSendTransaction({})` method from `account`. This method takes an array of transaction actions, and if one fails, the entire operation will fail. Here's a simple example: - -```js -const { connect, transactions, keyStores } = require("near-api-js"); -const fs = require("fs"); -const path = require("path"); -const homedir = require("os").homedir(); - -const CREDENTIALS_DIR = ".near-credentials"; -const CONTRACT_NAME = "spf.idea404.testnet"; -const WASM_PATH = path.join(__dirname, "../build/uninitialized_nft.wasm"); - -const credentialsPath = path.join(homedir, CREDENTIALS_DIR); -const keyStore = new keyStores.UnencryptedFileSystemKeyStore(credentialsPath); - -const config = { - keyStore, - networkId: "testnet", - nodeUrl: "https://rpc.testnet.near.org", -}; - -sendTransactions(); - -async function sendTransactions() { - const near = await connect({ ...config, keyStore }); - const account = await near.account(CONTRACT_NAME); - const args = { some_field: 1, another_field: "hello" }; - - const balanceBefore = await account.getAccountBalance(); - console.log("Balance before:", balanceBefore); - - try { - const result = await account.signAndSendTransaction({ - receiverId: CONTRACT_NAME, - actions: [ - transactions.deployContract(fs.readFileSync(WASM_PATH)), // Contract does not get deployed - transactions.functionCall("new", Buffer.from(JSON.stringify(args)), 10000000000000, "0"), // this call fails - transactions.transfer("1" + "0".repeat(24)), // 1 NEAR is not transferred either - ], - }); - console.log(result); - } catch (e) { - console.log("Error:", e); - } - - const balanceAfter = await account.getAccountBalance(); - console.log("Balance after:", balanceAfter); -} -``` - -``` -Balance before: { - total: '49987878054959838200000000', - stateStaked: '4555390000000000000000000', - staked: '0', - available: '45432488054959838200000000' -} -Receipts: 2PPueY6gnA4YmmQUzc8DytNBp4PUpgTDhmEjRSHHVHBd, 3isLCW9SBH1MrPjeEPAmG9saHLj9Z2g7HxzfBdHmaSaG - Failure [spf.idea404.testnet]: Error: {"index":1,"kind":{"ExecutionError":"Smart contract panicked: panicked at 'Failed to deserialize input from JSON.: Error(\"missing field `owner_id`\", line: 1, column: 40)', nft/src/lib.rs:47:1"}} -Error: ServerTransactionError: {"index":1,"kind":{"ExecutionError":"Smart contract panicked: panicked at 'Failed to deserialize input from JSON.: Error(\"missing field `owner_id`\", line: 1, column: 40)', nft/src/lib.rs:47:1"}} - at parseResultError (/Users/dennis/Code/naj-test/node_modules/near-api-js/lib/utils/rpc_errors.js:31:29) - at Account. (/Users/dennis/Code/naj-test/node_modules/near-api-js/lib/account.js:156:61) - at Generator.next () - at fulfilled (/Users/dennis/Code/naj-test/node_modules/near-api-js/lib/account.js:5:58) - at processTicksAndRejections (node:internal/process/task_queues:96:5) { - type: 'FunctionCallError', - context: undefined, - index: 1, - kind: { - ExecutionError: 'Smart contract panicked: panicked at \'Failed to deserialize input from JSON.: Error("missing field `owner_id`", line: 1, column: 40)\', nft/src/lib.rs:47:1' - }, - transaction_outcome: { - block_hash: '5SUhYcXjXR1svCxL5BhCuw88XNdEjKXqWgA9X4XZW1dW', - id: 'SKQqAgnSN27fyHpncaX3fCUxWknBrMtxxytWLRDQfT3', - outcome: { - executor_id: 'spf.idea404.testnet', - gas_burnt: 4839199843770, - logs: [], - metadata: [Object], - receipt_ids: [Array], - status: [Object], - tokens_burnt: '483919984377000000000' - }, - proof: [ [Object], [Object], [Object], [Object], [Object] ] - } -} -Balance after: { - total: '49985119959346682700000000', - stateStaked: '4555390000000000000000000', - staked: '0', - available: '45429729959346682700000000' -} - -``` - -You may also find an example of batch transactions in the [Cookbook](/tools/near-api-js/cookbook). - ---- - -## Accounts {#accounts} - -### What’s the difference between `Account` and `ConnectedWalletAccount`? - -Interaction with the wallet is only possible in a web-browser environment because NEAR’s Wallet is web-based. -The difference between `Account` and `ConnectedWalletAccount` is mostly about the way it signs transactions. The `ConnectedWalletAccount` uses the wallet to approve transactions. -Under the hood the `ConnectedWalletAccount` inherits and overrides some methods of `Account`. - -### How to create implicit accounts? - -You can read about it in the article about [Implicit Accounts](https://docs.near.org/integrations/implicit-accounts). - ---- - -## Contracts {#contracts} - -### How do I attach gas / a deposit? {#how-do-i-attach-gas--a-deposit} - -After [contract is instantiated](/tools/near-api-js/contract#load-contract) you can then call the contract and specify the amount of attached gas. - -```js -await contract.method_name( - { - arg_name: "value", // argument name and value - pass empty object if no args required - }, - "300000000000000", // attached GAS (optional) - "1000000000000000000000000" // attached deposit in yoctoNEAR (optional) -); -``` - ---- - -## Common Errors {#common-errors} - -### RPC Errors - -Refer to the exhaustive [list of error messages](https://github.com/near/near-api-js/blob/16ba17251ff7d9c8454261001cd6b87e9a994789/packages/near-api-js/src/res/error_messages.json) -that RPC endpoints throws and JavaScript API propagates. - -### Missing contract methods {#missing-contract-method} - -When constructing a `Contract` instance on the client-side, you need to specify -the contract's methods. If you misspell, mismatch, or miss method names - you'll -receive errors about missing methods. - -There are a few cases of missing or wrong methods: -- When you call a method you didn't specify in the constructor. -- When you call a method that doesn't exist on the blockchain's contract (but you did specify it in the client-side constructor). -- When you mismatch between `viewMethods` and `changeMethods`. - -For example, let's look at the following contract code. -It contains one `view` and one `call` method: - -```js -@NearBindgen -class MyContract extends NearContract { - constructor() { super(); } - - @view - method_A_view(): string { - return 'Hi'; - } - - @call - method_B_call(): void {} -} -``` - -#### Client-side errors for missing methods - -##### `TypeError: contract.METHOD_NAME is not a function` - -The following contract constructor declares only `method_A_view`, it doesn't declare `method_B_call` -```js -const contract = await new nearAPI.Contract( - walletConnection.account(), 'guest-book.testnet', - { - viewMethods: ['method_A_view'], // <=== Notice this - changeMethods: [], // <=== Notice this - sender: walletConnection.getAccountId(), - } -); - -// This will work because we declared `method_A_view` in constructor -await contract.method_A_view(); - -// This will throw `TypeError: contract.method_B_call is not a function` -// because we didn't declare `method_B_call` in constructor, -// even if it exists in the real contract. -await contract.method_B_call(); - -// This will also throw `TypeError: contract.method_C is not a function`, -// not because `method_C` doesn't exist on the contract, but because we didn't declare it -// in the client-side constructor. -await contract.method_C(); -``` - -#### RPC errors for missing methods - -##### `wasm execution failed with error: FunctionCallError(MethodResolveError(MethodNotFound))` - -In this example we specify and call a method, but this method doesn't exist on the blockchain: -```js -const contract = await new nearAPI.Contract( - // ... - { - viewMethods: ["method_C"], // <=== method_C doesn't exist on the contract above - changeMethods: [], - // ... - } -); -// We did specify `method_C` name in constructor, so this function exists on client-side `contract` instance, -// but a method with this name does not exist on the actual contract on the blockchain. -// This will return an error from RPC call `FunctionCallError(MethodResolveError(MethodNotFound))` -// and will throw it on the client-side -await contract.method_C(); - -// Notice: if we call `method_A_view` we get `TypeError: contract.method_A_view is not a function`. -// Even though the method exists on the actual blockchain contract, -// we didn't specify `method_A_view` in the contract's client-side constructor. -await contract.method_A_view(); -``` - -##### `wasm execution failed with error: FunctionCallError(HostError(ProhibitedInView { method_name: "storage_write" }))` - -Last case is when you mismatch `viewMethods` and `changeMethods`. - -In the contract above we declared: -- A `@view` method named `method_A_view` -- A `@call` method named `method_B_call` - -In a client-side constructor, the contract's `@view` method names must be specified under `viewMethods`, -and the contract's `@call` method names must be specified under `changeMethods`. -If we mismatch between the types we will receive errors. - -For example: -```js -const contract = await new nearAPI.Contract( - // ... - { - viewMethods: ['method_B_call'], // <=== here should be `method_A_view` - changeMethods: ['method_A_view'], // <=== and here should be `method_B_call` - // ... - } -); - -// This will return an error from RPC call and throw: -// `wasm execution failed with error: FunctionCallError(HostError(ProhibitedInView { method_name: "storage_write" }))` -// This error indicates that we are trying to call a state-changing method but declare it as a read-only method in client-side. -await contract.method_B_call(); - -// The following behavior is undefined and might not work as expected. -// `method_A_veiw` should be declared under `viewMethods` and in our example here we declare it under `changeMethods`. -await contract.method_A_view(); -``` - -### Class `{X}` is missing in schema: publicKey - -There is currently a known issue with the JavaScript API library, when you `import` it more than once -it might cause a namespace collision. - -A temporary workaround: make sure you don't re-import it, for example when running tests. - ---- - -### `regeneratorRuntime` is not defined {#regeneratorruntime-is-not-defined} - -You are probably using [Parcel](https://parceljs.org/) like we do in [other examples](https://github.com/near-examples). Please make sure you have this line at the top of your main JS file. (Most likely `index.js`): - -```js -import "regenerator-runtime/runtime"; -``` - -- Also, ensure the dependencies for this are added to the project by checking the dev dependencies in your `package.json`. If not found you can install this by running the following in your terminal: - -```bash -npm install regenerator-runtime --save-dev -``` - ---- - -### Window error using `Node.js` {#window-error-using-nodejs} - -You're maybe using a KeyStore that's for the browser. Instead, use a [filesystem key](/tools/near-api-js/quick-reference#key-store) or private key string. - -**Browser KeyStore:** - -```js -const { keyStores } = require("near-api-js"); -const keyStore = new keyStores.BrowserLocalStorageKeyStore(); -``` - -**FileSystem KeyStore:** - -```js -const { keyStores } = require("near-api-js"); -const KEY_PATH = "~./near-credentials/testnet/example-account.json"; -const keyStore = new keyStores.UnencryptedFileSystemKeyStore(KEY_PATH); -``` diff --git a/docs/4.tools/near-api-js/naj-account.md b/docs/4.tools/near-api-js/naj-account.md deleted file mode 100644 index 8c762fcb23b..00000000000 --- a/docs/4.tools/near-api-js/naj-account.md +++ /dev/null @@ -1,160 +0,0 @@ ---- -id: account -title: Account -sidebar_label: Account ---- - -You can interact with, create or delete NEAR accounts. - -### Load Account {#load-account} - -This will return an Account object for you to interact with. - -```js -const account = await nearConnection.account("example-account.testnet"); -``` - -[ Class `Account`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html) - -### Create Account {#create-account} - -Create a sub-account. - -```js -// creates a sub-account using funds from the account used to create it. -const account = await nearConnection.account("example-account.testnet"); -await account.createAccount( - "sub.example-account.testnet", // sub-account name - "8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc", // public key for sub account - "10000000000000000000" // initial balance for new account in yoctoNEAR -); -``` - -[ Method `Account.createAccount`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#createAccount) - -For creating .near or .testnet accounts please refer to the [cookbook](https://github.com/near/near-api-js/tree/master/packages/cookbook/accounts). - -### Delete Account {#delete-account} - -```js -// deletes account found in the `account` object -// transfers remaining account balance to the accountId passed as an argument -const account = await nearConnection.account("example-account.testnet"); -await account.deleteAccount("beneficiary-account.testnet"); -``` - -[ Method `Account.deleteAccount`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#deleteAccount) - -### Get Account Balance {#get-account-balance} - -```js -// gets account balance -const account = await nearConnection.account("example-account.testnet"); -await account.getAccountBalance(); -``` - -[ Method `Account.getAccountBalance`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#getAccountBalance) - -### Get Account details {#get-account-details} - -Returns information about an account, such as authorized apps. - -```js -// gets account details in terms of authorized apps and transactions -const account = await nearConnection.account("example-account.testnet"); -await account.getAccountDetails(); -``` - -[ Method `Account.getAccountDetails`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#getAccountDetails) - -### Deploy a Contract {#deploy-a-contract} - -You can deploy a contract from a compiled WASM file. This returns an object with transaction and receipts outcomes and status. - -```js -const account = await nearConnection.account("example-account.testnet"); -const transactionOutcome = await account.deployContract( - fs.readFileSync("example-file.wasm") -); -``` - -[ Method `Account.deployContract`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#deployContract) -    -[ Interface `FinalExecutionOutcome`](https://near.github.io/near-api-js/interfaces/_near_js_types.provider_response.FinalExecutionOutcome.html) - -### Send Tokens {#send-tokens} - -Transfer NEAR tokens between accounts. This returns an object with transaction and receipts outcomes and status. - -```js -const account = await nearConnection.account("sender-account.testnet"); -await account.sendMoney( - "receiver-account.testnet", // receiver account - "1000000000000000000000000" // amount in yoctoNEAR -); -``` - -[ Method `Account.sendMoney`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#sendMoney) -    -[ Interface `FinalExecutionOutcome`](https://near.github.io/near-api-js/interfaces/_near_js_types.provider_response.FinalExecutionOutcome.html) - -### State {#state} - -Get basic account information, such as amount of tokens the account has or the amount of storage it uses. - -```js -const account = await nearConnection.account("example-account.testnet"); -const accountState = await account.state(); -``` - -[ Method `Account.state`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#state) -    -[ Interface `AccountView`](https://near.github.io/near-api-js/interfaces/near_api_js.providers_provider.AccountView.html) - -### Access Keys {#access-keys} - -You can get and manage keys for an account. - -#### Add Full Access Key {#add-full-access-key} - -```js -// takes public key as string for argument -const account = await nearConnection.account("example-account.testnet"); -await account.addKey("8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc"); -``` - -[ Method `Account.addKey`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#addKey) - -#### Add Function Access Key {#add-function-access-key} - -```js -const account = await nearConnection.account("example-account.testnet"); -await account.addKey( - "8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc", // public key for new account - "example-account.testnet", // contract this key is allowed to call (optional) - "example_method", // methods this key is allowed to call (optional) - "2500000000000" // allowance key can use to call methods (optional) -); -``` - -[ Method `Account.addKey`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#addKey) - -#### Get All Access Keys {#get-all-access-keys} - -```js -const account = await nearConnection.account("example-account.testnet"); -await account.getAccessKeys(); -``` - -[ Method `Account.getAccessKeys`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#getAccessKeys) -    -[ Interface `AccessKeyInfoView`](https://near.github.io/near-api-js/interfaces/near_api_js.providers_provider.AccessKeyInfoView.html) - -#### Delete Access Key {#delete-access-key} - -```js -const account = await nearConnection.account("example-account.testnet"); -await account.deleteKey("8hSHprDq2StXwMtNd43wDTXQYsjXcD4MJTXQYsjXcc"); -``` - -[ Method `Account.deleteKey`](https://near.github.io/near-api-js/classes/near_api_js.account.Account.html#deleteKey) diff --git a/docs/4.tools/near-api-js/naj-contract.md b/docs/4.tools/near-api-js/naj-contract.md deleted file mode 100644 index 60b2af055dc..00000000000 --- a/docs/4.tools/near-api-js/naj-contract.md +++ /dev/null @@ -1,128 +0,0 @@ ---- -id: contract -title: Contract -sidebar_label: Contract ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -When you instantiate an instance of `Contract` you need to specify the names of the functions you have on your smart contract. -Then the new instance of `Contract` will have methods with the same names as your smart contract functions. -For example if you deployed a contract with `my_smart_contract_function` function on it, then this will work: - -```js -const contract = new Contract(account, "example-contract.testnet", { - changeMethods: ["my_smart_contract_function"], // your smart-contract has a function `my_smart_contract_function` -}); -// `contract` object has `my_smart_contract_function` function on it: -contract.my_smart_contract_function(); -``` - -### Load Contract {#load-contract} - - - - -```js -const { Contract } = nearAPI; - -const contract = new Contract( - account, // the account object that is connecting - "example-contract.testnet", - { - // name of contract you're connecting to - viewMethods: ["getMessages"], // view methods do not change state but usually return a value - changeMethods: ["addMessage"], // change methods modify state - } -); -``` - -[ Class `Contract`](https://near.github.io/near-api-js/classes/_near_js_accounts.contract.Contract.html) - - - - -```js -const { Contract } = nearAPI; - -const contract = new Contract( - wallet.account(), // the account object that is connecting - "example-contract.testnet", - { - // name of contract you're connecting to - viewMethods: ["getMessages"], // view methods do not change state but usually return a value - changeMethods: ["addMessage"], // change methods modify state - } -); -``` - -[ Class `Contract`](https://near.github.io/near-api-js/classes/_near_js_accounts.contract.Contract.html) - - - - -### Call Contract {#call-contract} - - - - -```js -const contract = new Contract(account, "example-contract.testnet", { - changeMethods: ["method_name"], -}); -await contract.method_name( - { - arg_name: "value", // argument name and value - pass empty object if no args required - }, - "300000000000000", // attached GAS (optional) - "1000000000000000000000000" // attached deposit in yoctoNEAR (optional) -); -``` - - - - -```js -const contract = new Contract(account, "example-contract.testnet", { - changeMethods: ["method_name"], -}); -await contract.method_name({ - callbackUrl: "https://example.com/callback", // callbackUrl after the transaction approved (optional) - meta: "some info", // meta information NEAR Wallet will send back to the application. `meta` will be attached to the `callbackUrl` as a url param - args: { - arg_name: "value", // argument name and value - pass empty object if no args required - }, - gas: 300000000000000, // attached GAS (optional) - amount: 1000000000000000000000000, // attached deposit in yoctoNEAR (optional) -}); -``` - - - - -```js -const contract = new Contract(account, "example-contract.testnet", { - viewMethods: ["view_method_name"], -}); -const response = await contract.view_method_name(); -``` - - - - -```js -const contract = new Contract(account, "example-contract.testnet", { - viewMethods: ["view_method_name"], -}); -const response = await contract.view_method_name({ arg_name: "arg_value" }); -``` - - - - -[ Class `Contract`](https://near.github.io/near-api-js/classes/_near_js_accounts.contract.Contract.html) - -[//]: # "## Transactions {#transactions}" -[//]: # "A [Transaction](/concepts/protocol/transactions) is a collection of Actions, and there are few types of Actions." -[//]: # "For every type of Action there is a function on Account that you can use to invoke the Action, but Account also exposes `signAndSendTransaction` function which you can use to build and invoke a batch transaction." diff --git a/docs/4.tools/near-api-js/naj-utils.md b/docs/4.tools/near-api-js/naj-utils.md deleted file mode 100644 index e20f3a95177..00000000000 --- a/docs/4.tools/near-api-js/naj-utils.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -id: utils -title: Utilities -sidebar_label: Utilities ---- - -### NEAR => yoctoNEAR {#near--yoctonear} - -```js -// converts NEAR amount into yoctoNEAR (10^-24) - -const { utils } = nearAPI; -const amountInYocto = utils.format.parseNearAmount("1"); -``` - -[ Function `parseNearAmount`](https://near.github.io/near-api-js/functions/_near_js_utils.format.parseNearAmount.html) - -### YoctoNEAR => NEAR {#yoctonear--near} - -```js -// converts yoctoNEAR (10^-24) amount into NEAR - -const { utils } = nearAPI; -const amountInNEAR = utils.format.formatNearAmount("1000000000000000000000000"); -``` - -[ Function `formatNearAmount`](https://near.github.io/near-api-js/functions/_near_js_utils.format.formatNearAmount.html) diff --git a/docs/4.tools/near-api-js/naj-wallet.md b/docs/4.tools/near-api-js/naj-wallet.md deleted file mode 100644 index 47355d83e88..00000000000 --- a/docs/4.tools/near-api-js/naj-wallet.md +++ /dev/null @@ -1,140 +0,0 @@ ---- -id: wallet -title: Interacting with the Wallet -sidebar_label: Wallet ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -Wallet interaction is possible only in the browser, because NEAR's Wallet is web-based. - -Most frequent action is Sign In. Your user is redirected to the Wallet page to authorize your application. -Once the user has Signed In, an access key is saved in browser's LocalStorage. -All following actions that require the access key will be allowed. -In case a user needs to authorize a transaction that has a deposit attached, your user will be automatically redirected to the Wallet again. - -### Creating Wallet Connection {#wallet-connection} - -In Wallet connection you use a LocalStorage [`KeyStore`](/tools/near-api-js/quick-reference#key-store). - - - - -```js -const { connect, keyStores, WalletConnection } = nearAPI; - -const connectionConfig = { - networkId: "testnet", - keyStore: new keyStores.BrowserLocalStorageKeyStore(), - nodeUrl: "https://rpc.testnet.near.org", - walletUrl: "https://testnet.mynearwallet.com/", - helperUrl: "https://helper.testnet.near.org", - explorerUrl: "https://testnet.nearblocks.io", -}; - -// connect to NEAR -const nearConnection = await connect(connectionConfig); - -// create wallet connection -// provide a prefix for the key -const walletConnection = new WalletConnection(nearConnection, "example-prefix"); -``` - - - - -```js -const { connect, keyStores, WalletConnection } = nearAPI; - -const connectionConfig = { - networkId: "mainnet", - keyStore: new keyStores.BrowserLocalStorageKeyStore(), - nodeUrl: "https://rpc.mainnet.near.org", - walletUrl: "https://wallet.mainnet.near.org", - helperUrl: "https://helper.mainnet.near.org", - explorerUrl: "https://nearblocks.io", -}; - -// connect to NEAR -const nearConnection = await connect(connectionConfig); - -// create wallet connection -const walletConnection = new WalletConnection(nearConnection); -``` - - - - - -[ Module `browserConnect`](https://near.github.io/near-api-js/modules/near_api_js.browserConnect.html) -    -[ Class `WalletConnection`](https://near.github.io/near-api-js/classes/_near_js_wallet_account.walletAccount.WalletConnection.html) - -### Ask your user to Sign In {#sign-in} - -You first create a [WalletConnection](#wallet-connection), and then call `requestSignIn`. -This will redirect the current page to the Wallet authentication page. You can optionally configure success and failure redirect URLs. - -When you create a wallet connection you have the option to create a [function call access key](/concepts/protocol/access-keys#function-call-keys) for a specific contract to be used by your application. This allows the app to automatically sign `non-payable methods` for the user without having to sign each transaction manually in the wallet. You can also decide to specify a list of `methodNames` that will restrict the key to sign only certain methods on the specified contract. Passing an empty array will allow all methods to be signed. - -```js -// const walletConnection = new WalletConnection(nearConnection); -// all parameters are optional -walletConnection.requestSignIn({ - contractId: "example-contract.testnet.REPLACE_ME", // optional - methodNames: [], // optional - successUrl: "REPLACE_ME://.com/success", // optional redirect URL on success - failureUrl: "REPLACE_ME://.com/failure", // optional redirect URL on failure -}); -``` - -[ Method `WalletConnection.requestSignIn`](https://near.github.io/near-api-js/classes/_near_js_wallet_account.walletAccount.WalletConnection.html#requestSignIn) - -:::tip -Sign In is **_not required_** if you are using an alternative key store to local storage, or you are not signing transactions (meaning - you are only calling read-only _view_ methods on a contract) -::: - -### Sign Out your user {#sign-out} - -```js -// const walletConnection = new WalletConnection(nearConnection); -walletConnection.signOut(); -``` - -[ Method `WalletConnection.signOut`](https://near.github.io/near-api-js/classes/_near_js_wallet_account.walletAccount.WalletConnection.html#signOut) - -### Check if Signed In {#check-if-signed-in} - -```js -// const walletConnection = new WalletConnection(nearConnection); -if (walletConnection.isSignedIn()) { - // user is signed in -} -``` - -[ Method `WalletConnection.isSignedId`](https://near.github.io/near-api-js/classes/_near_js_wallet_account.walletAccount.WalletConnection.html#isSignedIn) - -### Get Wallet Account {#get-authorized-account} - -Get the [Account](naj-account.md) your user has signed in with in the Wallet. - -#### Get Account ID (as string) {#get-authorized-account-id} - -```js -// const walletConnection = new WalletConnection(nearConnection); -const walletAccountId = walletConnection.getAccountId(); -``` - -[ Method `WalletConnection.getAccountId`](https://near.github.io/near-api-js/classes/_near_js_wallet_account.walletAccount.WalletConnection.html#getAccountId) - -#### Get Account Object {#get-authorized-account-object} - -```js -// const walletConnection = new WalletConnection(nearConnection); -const walletAccountObj = walletConnection.account(); -``` - -[ Method `WalletConnection.account`](https://near.github.io/near-api-js/classes/_near_js_wallet_account.walletAccount.WalletConnection.html#account) -    -[ Class `ConnectedWalletAccount`](https://near.github.io/near-api-js/classes/_near_js_wallet_account.walletAccount.ConnectedWalletAccount.html) diff --git a/docs/4.tools/near-api-js/quick-reference.md b/docs/4.tools/near-api-js/quick-reference.md deleted file mode 100644 index d8de49d4789..00000000000 --- a/docs/4.tools/near-api-js/quick-reference.md +++ /dev/null @@ -1,258 +0,0 @@ ---- -id: quick-reference -title: Using JavaScript API to interact with NEAR -sidebar_label: Using JavaScript API ---- - -import Tabs from '@theme/Tabs'; -import TabItem from '@theme/TabItem'; - -## Quick Reference - -- [Installation](#install) -- [Interacting with the Wallet](naj-wallet.md) -- [Accounts](naj-account.md) -- [Contracts](naj-contract.md) -- [Utilities](naj-utils.md) - -## What is `near-api-js` - -`near-api-js` is a complete library to interact with the NEAR blockchain. You can use it in the browser, or in Node.js runtime. - -You'll typically first create a connection to NEAR with [`connect`](#connect) using a [`KeyStore`](#key-store). -With the connection object you now can: - -- Interact with the [Wallet](naj-wallet.md) in a browser. -- Instantiate an [Account](naj-account.md) object to: - - Send tokens - - Deploy contracts - - Inspect, create or delete accounts - - Manage keys for accounts. -- Instantiate a [Contract](naj-contract.md) object to call smart contract methods. - -The library also contains some [utility functions](naj-utils.md). - -:::tip -To quickly get started with integrating NEAR in a web browser, read our [Web Frontend integration](/build/web3-apps/integrate-contracts) article. -::: - -:::info -Note the difference between `near-api-js` and `near-sdk-js`: - -The JavaScript _SDK_ is a library for developing smart contracts. It contains classes and functions you use to write your smart contract code. - -The JavaScript _API_ is a complete library for all possible commands to interact with NEAR. It’s a wrapper for the RPC endpoints, a library to interact with NEAR Wallet in the browser, and a tool for keys management. -::: - ---- - -## Install {#install} - -Include `near-api-js` as a dependency in your package. - -```bash -npm i --save near-api-js -``` - -## Import {#import} - -You can use the API library in the browser, or in Node.js runtime. Some features are available only in one of the environments. -For example, the `WalletConnection` is only for the browser, and there are different `KeyStore` providers for each environment. - - - - -```js -import * as nearAPI from "near-api-js"; -``` - - - - -```js -const nearAPI = require("near-api-js"); -``` - - - - -## Key Store {#key-store} - -If you sign transactions, you need to create a _Key Store_. In the browser, the LocalStorage KeyStore will be used once you ask your user to Sign In with the Wallet. - - - - -```js -// creates keyStore using private key in local storage - -const { keyStores } = nearAPI; -const myKeyStore = new keyStores.BrowserLocalStorageKeyStore(); -``` - -[ Class `BrowserLocalStorageKeyStore`](https://near.github.io/near-api-js/classes/_near_js_keystores_browser.browser_local_storage_key_store.BrowserLocalStorageKeyStore.html) - - - - -```js -// creates a keyStore that searches for keys in .near-credentials -// requires credentials stored locally by using a NEAR-CLI command: `near login` -// https://docs.near.org/tools/cli#near-login - -const { keyStores } = nearAPI; -const homedir = require("os").homedir(); -const CREDENTIALS_DIR = ".near-credentials"; -const credentialsPath = require("path").join(homedir, CREDENTIALS_DIR); -const myKeyStore = new keyStores.UnencryptedFileSystemKeyStore(credentialsPath); -``` - -[ Class `UnencryptedFileSystemKeyStore`](https://near.github.io/near-api-js/classes/_near_js_keystores_node.unencrypted_file_system_keystore.UnencryptedFileSystemKeyStore.html) - - - - -```js -// creates keyStore from a provided file -// you will need to pass the location of the .json key pair - -const { KeyPair, keyStores } = require("near-api-js"); -const fs = require("fs"); -const homedir = require("os").homedir(); - -const ACCOUNT_ID = "near-example.testnet"; // NEAR account tied to the keyPair -const NETWORK_ID = "testnet"; -// path to your custom keyPair location (ex. function access key for example account) -const KEY_PATH = "/.near-credentials/near-example-testnet/get_token_price.json"; - -const credentials = JSON.parse(fs.readFileSync(homedir + KEY_PATH)); -const myKeyStore = new keyStores.InMemoryKeyStore(); -myKeyStore.setKey( - NETWORK_ID, - ACCOUNT_ID, - KeyPair.fromString(credentials.private_key) -); -``` - -[ Class `InMemoryKeyStore`](https://near.github.io/near-api-js/classes/_near_js_keystores.in_memory_key_store.InMemoryKeyStore.html) -    -[ Class `KeyPair`](https://near.github.io/near-api-js/classes/_near_js_crypto.key_pair.KeyPair.html) - - - - -```js -// creates keyStore from a private key string -// you can define your key here or use an environment variable - -const { keyStores, KeyPair } = nearAPI; -const myKeyStore = new keyStores.InMemoryKeyStore(); -const PRIVATE_KEY = - "by8kdJoJHu7uUkKfoaLd2J2Dp1q1TigeWMG123pHdu9UREqPcshCM223kWadm"; -// creates a public / private key pair using the provided private key -const keyPair = KeyPair.fromString(PRIVATE_KEY); -// adds the keyPair you created to keyStore -await myKeyStore.setKey("testnet", "example-account.testnet", keyPair); -``` - -[ Class `InMemoryKeyStore`](https://near.github.io/near-api-js/classes/_near_js_keystores.in_memory_key_store.InMemoryKeyStore.html) -    -[ Class `KeyPair`](https://near.github.io/near-api-js/classes/_near_js_crypto.key_pair.KeyPair.html) - - - - -## Connecting to NEAR {#connect} - -The object returned from `connect` is your entry-point for all commands in the API. -To sign a transaction you'll need a [`KeyStore`](#key-store) to create a connection. - - - - -```js -const { connect } = nearAPI; - -const connectionConfig = { - networkId: "testnet", - keyStore: myKeyStore, // first create a key store - nodeUrl: "https://rpc.testnet.near.org", - walletUrl: "https://testnet.mynearwallet.com/", - helperUrl: "https://helper.testnet.near.org", - explorerUrl: "https://testnet.nearblocks.io", -}; -const nearConnection = await connect(connectionConfig); -``` - - - - -```js -const { connect } = nearAPI; - -const connectionConfig = { - networkId: "mainnet", - keyStore: myKeyStore, // first create a key store - nodeUrl: "https://rpc.mainnet.near.org", - walletUrl: "https://wallet.mainnet.near.org", - helperUrl: "https://helper.mainnet.near.org", - explorerUrl: "https://nearblocks.io", -}; -const nearConnection = await connect(connectionConfig); -``` - - - - - -```js -const { connect } = nearAPI; -const connectionConfig = { - networkId: "local", - nodeUrl: "http://localhost:3030", - walletUrl: "http://localhost:4000/wallet", -}; -const nearConnection = await connect(connectionConfig); -``` - - - - -[ Module `connect`](https://near.github.io/near-api-js/modules/near_api_js.connect.html) - -## RPC Failover - -RPC providers can experience intermittent downtime, connectivity issues, or rate limits that cause client transactions to fail. This can be prevented by using the `FailoverRpcProvider` that supports multiple RPC providers. - - - - -```js -const jsonProviders = [ - new JsonRpcProvider({ - url: 'https://rpc.mainnet.near.org', - }), - new JsonRpcProvider( - { - url: 'https://another-rpc.cloud.com', - headers: { 'X-Api-Key': 'some string' }, - }, - { retries: 3, backoff: 2, wait: 500 } - ), -]; -const provider = new FailoverRpcProvider(jsonProviders); - -await connect({ - networkId: 'mainnet', - provider: provider, - // this isn't used if `provider` is specified, but is still required for backward compatibility - nodeUrl: 'https://rpc.mainnet.near.org', -}); -``` - - - - - - -[ Class `FailoverRpcProvider `](https://near.github.io/near-api-js/classes/near_api_js.providers_failover_rpc_provider.FailoverRpcProvider.html) diff --git a/docs/4.tools/near-api.md b/docs/4.tools/near-api.md new file mode 100644 index 00000000000..ecac66fd6fc --- /dev/null +++ b/docs/4.tools/near-api.md @@ -0,0 +1,990 @@ +--- +id: near-api +title: NEAR API +sidebar_label: NEAR API +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import {Github, Language} from "@site/src/components/codetabs" + +The NEAR API is a set of libraries that allow you to interact with the NEAR blockchain. You can use it to create accounts, send tokens, deploy contracts, and more. + +The API is available in multiple languages, including: +- JavaScript: [`near-api-js`](https://github.com/near/near-api-js) +- Rust: [`near-api-rs`](https://github.com/near/near-api-rs) +- Python: [`py-near`](https://github.com/pvolnov/py-near) + +For example, you could use [`near-api-js`](https://github.com/near/near-api-js) to create web applications or backend services written in node.js servers. + +:::tip Wallet Integration +To allow users to login into your web application using a wallet you will need the `wallet-selector`. Read more in our [Web Frontend integration](/build/web3-apps/integrate-contracts) article +::: + +These examples are references to code snippets, feel free to explore the full code examples in context by clicking `See full example on GitHub` below each example. + +--- + +## Install + + + + Include `near-api-js` as a dependency in your package. + + ```bash + npm i near-api-js + ``` + + :::tip Static HTML + If you are building a site without using `npm`, you can include the library directly in your HTML file through a CDN. + + ```html + + ``` + ::: + + + + + ```bash + cargo add near-api + ``` + + + + ```shell + pip install py-near + ``` + + + +
+ +### Import {#import} + + + + You can use the API library in the browser, or in Node.js runtime. + + + +
+ Using the API in Node.js + + All these examples are written for the browser, to use these examples in Node.js you should convert the project to an ES module. To do this, add the following to your `package.json`: + + + +
+ + + + + The methods to interact with the NEAR API are available through the `prelude` module. + + + + + + + You can use the NEAR API by importing the `py_near` package, either entirely + ```python + import py_near + ``` + + or only the parts you need, for example: + ```python + from py_near.account import Account + from py_near.providers import JsonProvider + ``` + + + +
+ +### Connecting to NEAR {#connect} + + + + + The object returned from `connect` is your entry-point for all commands in the API. + To transactions you'll need a [`KeyStore`](#signers). + + + +
+ Mainnet/Localnet connection + + ```js + // Mainnet config example + const connectionConfig = { + networkId: "mainnet", + keyStore: myKeyStore, + nodeUrl: "https://rpc.mainnet.near.org", + }; + + // Localnet config example + const connectionConfig = { + networkId: "local", + nodeUrl: "http://localhost:3030", + }; + ``` +
+ + + + + To interact with the blockchain you'll need to create a `NetworkConfig` object. + + Preset connections `mainnet` and `testnet` are available that come with standard configurations for each network. + + + + You can also create your own custom connection. + + + + + + +
+ +### Key Handlers: Stores & Signers + + + + + To sign transactions you'll need to a `KeyStore` with valid keypairs. + + + + + `BrowserLocalStorageKeyStore` can only be used in the browser, it uses the browser's local storage to store the keys. + + ```js + // Creates keyStore using private key in local storage + + const { keyStores } = nearAPI; + const myKeyStore = new keyStores.BrowserLocalStorageKeyStore(); + ``` + + + + + `UnencryptedFileSystemKeyStore` can be used is used to load keys from the legacy credentials directory used by the NEAR CLI. + + + + + + + Keystores can be created by loading a private key from a json file. + + + + + + + Keystores can be created by using a private key string. + + Private keys have the format "ed25519:5Fg2...". + + + + + + + Keystores can be created by using a seed phrase. To parse the seed phrase into a private key, the `near-seed-phrase` library is needed. + + ```bash + npm i near-seed-phrase + ``` + + Seed phrases have the format "shoe three gate ..." and are usually 12 words long. + + + + + + + + + + To sign transactions you'll need to create a `Signer` that holds a valid keypair. + + + + + Signers can be created using the Keystore that is also used as the standard for saving keys with the NEAR CLI. + + + + + + + Signers can be created using the credentials directory which is the legacy option for saving keys with the NEAR CLI. + + + + + + + Signers can be created by loading a public and private key from a file. + + + + + + + Signers can be created by using a private key string. + + Private keys have the format "ed25519:5Fg2...". + + + + + + + Signers can be created by using a seed phrase. + + Seed phrases have the format "shoe three gate ..." and are usually 12 words long. + + + + + + + + + TODO: not exactly the same in Python, it's more and account + RPC URL, or a JSON RPC provider + + + + +
+ + ### RPC Failover + + RPC providers can experience intermittent downtime, connectivity issues, or rate limits that cause client transactions to fail. This can be prevented by using the `FailoverRpcProvider` that supports multiple RPC providers. + + + + + + + + + You can pass multiple RPC providers to `JsonRpcProvider` + + ```python + from py_near.providers import JsonProvider + + provider = JsonProvider(["https://test.rpc.fastnear.com", "https://rpc.testnet.pagoda.co"]) + ``` + + + +--- + +## Account + +### Instantiate Account {#instantiate-account} + +This will return an Account object for you to interact with. + + + + + + + + + + + + + + You can instantiate any account with the following code: + + ```python + from py_near.account import Account + + account = Account(account_id="example-account.testnet", rpc_addr="https://rpc.testnet.pagoda.co") + await account.startup() + ``` + + If you want to use it to submit transactions later, you need to also pass the `private_key` param: + + ```python + account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co") + ``` + + + +
+ +### Get Balance {#get-balance} + +Gets the available and staked balance of an account in yoctoNEAR. + + + + + + + + + + + + + + + ```python + from py_near.account import Account + + account = Account(account_id="example-account.testnet", rpc_addr="https://rpc.testnet.pagoda.co") + await account.startup() + + account_balance = account.get_balance() + ``` + + + +
+ +### Get State {#get-state} + +Get basic account information, such as its code hash and storage usage. + + + + + + + + + + + + + + + ```python + from py_near.account import Account + + account = Account(account_id="example-account.testnet", rpc_addr="https://rpc.testnet.pagoda.co") + await account.startup() + + account_state = account.fetch_state() + ``` + + + +
+ +### Get Details {#get-details} + +Returns the authorized apps of an account. This is a list of contracts that the account has function call access keys for. + + + + + + + + + +
+ +### Create an Account {#create-account} + +In order to create .near or .testnet accounts, you need to make a function call to the top-level-domain account (i.e. `near` or `testnet`), calling `create_account`. In this example we generate a new public key for the account by generating a random private key. + +The deposit determines the initial balance of the account. + + + + + + +
+ Creating an account from a seed phrase + + You can also create an account with a public key that is derived from a randomly generated seed phrase. + + + +
+ + + + + + +
+ Creating an account from a seed phrase + + You can also create an account via a randomly generated seed phrase. + + + +
+ + + + + ```python + await account.function_call("testnet", "create_account", {"new_account_id": "example-account.testnet", "new_public_key": "ed25519:..."}, "30000000000000", 1 * NEAR) + ``` + + + + + +
+ +### Create a Sub-Account {#create-sub-account} + +Accounts can create sub-accounts of themselves, which are useful for creating separate accounts for different purposes. It is important to remark that the parent account has no control over any of its sub-accounts. + +The deposit determines the initial balance of the account. + + + + + + + + + + + + + + + Create a sub-account and fund it with your main account: + + ```python + from py_near.account import Account + from py_near.dapps.core import NEAR + + account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co") + await account.startup() + + res = account.create_account(account_id="sub.example-account.testnet", public_key="...", initial_balance=1 * NEAR)) + ``` + + + +
+ +### Delete Account {#delete-account} + +When deleting an account, you need to specify a beneficiary account id. This is the account that will receive the remaining NEAR balance of the account being deleted. + + + + + + + + + + + + + + +:::warning + +Only NEAR tokens will be transferred to the beneficiary, so you should transfer all your FTs, NFTs, etc. to another account before deleting. + +::: + +:::danger + +If the beneficiary account does not exist, the NEAR tokens will be burned + +::: + +--- + +## Transactions + +### Send Tokens {#send-tokens} + +Transfer NEAR tokens between accounts. + + + + + + + + + + + + + + + ```python + from py_near.account import Account + from py_near.dapps.core import NEAR + + account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co") + await account.startup() + + await account.send_money("receiver-account.testnet", 1 * NEAR)) + ``` + + + +
+ +### Call Function + +A call function changes the contract's state and requires a signer/keypair. + + + + + + + + + + + + + + + + + + ```python + await account.function_call("usn.near", "ft_transfer", {"receiver_id": "bob.near", "amount": "1000000000000000000000000"}) + ``` + + + +
+ +### Batch Actions + +You can send multiple [actions](../1.concepts/protocol/transaction-anatomy.md#actions) in a batch to a single receiver. If one action fails then the entire batch of actions will be reverted. + + + + + + + + + + + + + + +
+ +### Simultaneous Transactions + +Transactions can be sent in parallel to the network, so you don't have to wait for one transaction to complete before sending the next one. Note that these one transaction could be successful and the other one could fail. + + + + + + + + + + + + + + + ```python + import asyncio + from py_near.account import Account + + account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co") + await account.startup() + + # Prepare the transactions + tx1 = account.function_call("guestbook.near-examples.testnet", "add_message", { "text": "Hello, world!" }) + tx2 = account.function_call("counter.near-examples.testnet", "increment", {}) + + # Send the transactions simultaneously + const transactionsResults = await asyncio.gather(tx1, tx2) + ``` + + + + +
+ +### Deploy a Contract {#deploy-a-contract} + +You can deploy a contract from a compiled WASM file. + + + + + + + + + + Note that the `signer` here needs to be a signer for the same `account_id` as the one used to construct the `Contract` object. + + + + + + + ```python + import asyncio + from py_near.account import Account + + account = Account(account_id="example-account.testnet", private_key="ed25519:...", rpc_addr="https://rpc.testnet.pagoda.co") + await account.startup() + + with open("contract.wasm", "rb") as f: + contract_code = f.read() + await account.deploy_contract(contract_code) + ``` + + + +--- + +## View Function + +View functions are read-only functions that don't change the state of the contract. We can call these functions without a signer / keypair or any gas. + + + + + + + + + + + + + + + ```python + view_call_result = await account.view_function("guestbook.near-examples.testnet", "total_messages", {}) + # If args are required, they can be passed in like this in the 3rd argument: + # { + # "from_index": "0", + # "limit": "10" + # } + print(view_call_result) + ``` + + + +--- + +## Keys + +### Get All Access Keys {#get-all-access-keys} + +List all the access keys for an account. + + + + + + + + + + + + + + + ```python + keys = await account.get_access_key_list() + ``` + + + +
+ +### Add Full Access Key {#add-full-access-key} + +Add a new [full access key](../1.concepts/protocol/access-keys.md#full-access-keys) to an account. Here we generate a random keypair, alternatively you can use a keypair from a seed phrase. + + + + + + + + + + + + + + + ```python + keys = await account.add_full_access_public_key("5X9WvUbRV3aSd9Py1LK7HAndqoktZtcgYdRjMt86SxMj") + ``` + + + +
+ +### Add Function Call Key {#add-function-call-key} + +Add a new [function call key](../1.concepts/protocol/access-keys.md#function-call-keys) to an account. When adding the key you should specify the contract id the key can call, an array of methods the key is allowed to call, and the allowance in gas for the key. + + + + + + + + + + + + + + + ```python + await account.add_public_key( + "5X9WvUbRV3aSd9Py1LK7HAndqoktZtcgYdRjMt86SxMj", + "example-contract.testnet", # Contract this key is allowed to call + ["example_method"], # Methods this key is allowed to call (optional) + 0.25 * NEAR # Gas allowance key can use to call methods (optional) + ) + ``` + + + + +
+ +### Delete Access Key {#delete-access-key} + +When deleting an access key, you need to specify the public key of the key you want to delete. + + + + + + + + + + + + + + + ```python + await account.delete_public_key("5X9WvUbRV3aSd9Py1LK7HAndqoktZtcgYdRjMt86SxMj") + ``` + + + +--- + +## Utilities + +### NEAR to yoctoNEAR {#near-to-yoctonear} + +Convert an amount in NEAR to an amount in yoctoNEAR. + + + + + + + + + + + + + + + ```python + from py_near.dapps.core import NEAR + + amount_in_yocto = 1 * NEAR + ``` + + + + +
+ +### Format Amount {#format-amount} + + + + + Format an amount in yoctoNEAR to an amount in NEAR. + + + + + + + Format an amount of NEAR into a string of NEAR or yoctoNEAR depending on the amount. + + + + + + +--- + +## Additional resources + + + + + - [Documentation](https://near.github.io/near-api-js) + - [Github](https://github.com/near/near-api-js) + - [Full Examples](https://github.com/PiVortex/near-api-examples/tree/main/javascript) + - [Cookbook](https://github.com/near/near-api-js/tree/master/packages/cookbook) which contains examples using the near-js/client package, a wrapper tree shakable package for near-api-js. + + + + + - [Documentation](https://docs.rs/near-api/latest/near_api/) + - [Github](https://github.com/near/near-api-rs) + - [Full Examples](https://github.com/PiVortex/near-api-examples/tree/main/rust) + + + + + - [Phone number transfer](https://py-near.readthedocs.io/en/latest/clients/phone.html) + + + diff --git a/docs/5.api/rpc/providers.md b/docs/5.api/rpc/providers.md index 59f8b6e6ca2..4b00449033e 100644 --- a/docs/5.api/rpc/providers.md +++ b/docs/5.api/rpc/providers.md @@ -45,7 +45,7 @@ If you want to use a custom RPC provider with NEAR Wallet Selector, [check this ## RPC Failover -In `near-api-js` you can use [`FailoverRpcProvider`](../../4.tools/near-api-js/quick-reference.md#rpc-failover) to automatically switch RPC providers when one provider is experiencing downtime, or implement an RPC selection widget that allows users to add their own RPC provider. +In `near-api-js` you can use [`FailoverRpcProvider`](../../4.tools/near-api.md#rpc-failover) to automatically switch RPC providers when one provider is experiencing downtime, or implement an RPC selection widget that allows users to add their own RPC provider. As a user, if a dApp or wallet doesn't support RPC failover and the primary provider is down, you can use an RPC Selector browser extension to redirect all requests to an RPC provider of your choice. diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 565bd570106..17978313b09 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -148,7 +148,7 @@ const config = { type: 'html', value: '
Essentials ', }, - { label: 'NEAR API', to: '/tools/near-api-js/quick-reference' }, + { label: 'NEAR API', to: '/tools/near-api' }, { label: 'NEAR SDK', to: '/tools/sdk' }, { label: 'NEAR CLI', to: '/tools/near-cli' }, { diff --git a/website/sidebars.js b/website/sidebars.js index 5a3bf381326..69a328599c6 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -516,28 +516,7 @@ const sidebar = { "type": "html", "value": " Developer Tools " }, - { - "type": "category", - "label": "JavaScript API", - "items": [ - "tools/near-api-js/quick-reference", - "tools/near-api-js/wallet", - "tools/near-api-js/account", - "tools/near-api-js/contract", - "tools/near-api-js/utils", - "tools/near-api-js/faq", - { - "type": "link", - "label": "Handling Passphrases", - "href": "https://github.com/near/near-seed-phrase" - }, - { - "type": "link", - "label": "Type Docs", - "href": "https://near.github.io/near-api-js" - } - ] - }, + "tools/near-api", "tools/sdk", "tools/near-cli", {