{!signedAccountId && (
Welcome! Login to Play
)}What do you think is coming next?
Status: {status}
Animation by iambon.near
Rust has an interesting feature where enums can contain additional data. You can see [examples of that here](https://doc.rust-lang.org/rust-by-example/custom_types/enum.html). ## Using structs ### Storing contract state We're going to introduce several structs all at once. These structs are addressing a need from the previous chapter, where the puzzle itself was hardcoded and looked like this:
We've already used Actions in the [previous chapter](/tutorials/crosswords/basics/hashing-and-unit-tests#first-use-of-batch-actions), when we deployed and initialized the contract, which used the `DeployContract` and `FunctionCall` Action, respectively. The full list of Actions are available at the [NEAR specification site](https://nomicon.io/RuntimeSpec/Actions.html). By the end of this entire tutorial we'll have used all the Actions highlighted below:
From the perspective of a contract on cucumber.near, we see a list of the predecessor, signer, and current account.
Art by yasuoarts.near
1. [predecessor account](https://docs.rs/near-sdk/latest/near_sdk/env/fn.predecessor_account_id.html) — `env::predecessor_account_id()` This is the account that was the immediate caller to the smart contract. If this is a simple transaction (no cross-contract calls) from **alice.near** to **banana.near**, the smart contract at **banana.near** considers Alice the predecessor. In this case, Alice would *also* be the signer. :::tip When in doubt, use predecessor As we explore the differences between predecessor and signer, know that it's a more common **best practice to choose the predecessor**. Using the predecessor guards against a potentially malicious contract trying to "fool" another contract that only checks the signer. ::: 2. [signer account](https://docs.rs/near-sdk/latest/near_sdk/env/fn.signer_account_id.html) — `env::signer_account_id()` The signer is the account that originally *signed* the transaction that began the blockchain activity, which may or may not include cross-contract calls. If a function calls results in several cross-contract calls, think of the signer as the account that pushed over the first domino in that chain reaction. :::caution Beware of middlemen If your smart contract is checking the ownership over some assets (fungible token, NFTs, etc.) it's probably a bad idea to use the signer account. A confused or malicious contract might act as a middleman and cause unexpected behavior. If **alice.near** accidentally calls **evil.near**, the contract at that account might do a cross-contract call to **vulnerable-nft.near**, instructing it to transfer an NFT. If **vulnerable-nft.near** only checks the signer account to determine ownership of the NFT, it might unwittingly give away Alice's property. Checking the predecessor account eliminates this problem. ::: 3. [current account](https://docs.rs/near-sdk/latest/near_sdk/env/fn.current_account_id.html) — `env::current_account_id()` The current account is "me" from the perspective of a smart contract. :::tip Why would I use that? There might be various reasons to use the current account, but a common use case is checking ownership or handling callbacks to cross-contract calls. Many smart contracts will want to implement some sort of permission system. A common, rudimentary permission allows certain functions to only be called by the contract owner, AKA the person who owns a private key to the account for this contract. The contract can check that the predecessor and current account are the same, and trust offer more permissions like changing contract settings, upgrading the contract, or other privileged modifications. ::: --- # Source: https://docs.near.org/tutorials/crosswords/01-basics/03-hashing-and-unit-tests.md --- sidebar_position: 4 sidebar_label: Hash the solution, unit tests, and an init method title: Introduction to basic hashing and adding unit tests description: "Hash the crossword solution, add unit tests, and initialize the smart contract securely." --- In the previous section, we stored the crossword solution as plain text as a `String` type on the smart contract. If we're trying to hide the solution from the users, this isn't a great approach as it'll be public to anyone looking at the state. Let's instead hash our crossword solution and store that instead. There are different ways to hash data, but let's use `sha256` which is one of the hashing algorithms available in [the Rust SDK](https://docs.rs/near-sdk/latest/near_sdk/env/fn.sha256.html). :::info Remind me about hashing Without getting into much detail, hashing is a "one-way" function that will output a result from a given input. If you have input (in our case, the crossword puzzle solution) you can get a hash, but if you have a hash you cannot get the input. This basic idea is foundational to information theory and security. Later on in this tutorial, we'll switch from using `sha256` to using cryptographic key pairs to illustrate additional NEAR concepts. Learn more about hashing from [Evgeny Kapun](https://github.com/abacabadabacaba)'s presentation on the subject. You may find other NEAR-related videos from the channel linked in the screenshot below. [](https://youtu.be/PfabikgnD08) ::: ## Helper unit test during rapid iteration As mentioned in the first section of this **Basics** chapter, our smart contract is technically a library as defined in the manifest file. For our purposes, a consequence of writing a library in Rust is not having a "main" function that runs. You may find many online tutorials where the command `cargo run` is used during development. We don't have this luxury, but we can use unit tests to interact with our smart contract. This is likely more convenient than building the contract, deploying to a blockchain network, and calling a method. We'll add a dependency to the [hex crate](https://crates.io/crates/hex) to make things easier. As you may remember, dependencies live in the manifest file. ``` [dependencies] near-sdk = { version = "5.1.0", features = ["legacy"] } hex = "0.4.3" ``` Let's write a unit test that acts as a helper during development. This unit test will sha256 hash the input **"near nomicon ref finance"** and print it in a human-readable, hex format. (We'll typically put unit tests at the bottom of the `lib.rs` file.) ``` // use the attribute below for unit tests #[cfg(test)] mod tests { use super::*; use near_sdk::test_utils::{get_logs, VMContextBuilder}; use near_sdk::{testing_env, AccountId}; #[test] fn debug_get_hash() { // Basic set up for a unit test testing_env!(VMContextBuilder::new().build()); // Using a unit test to rapidly debug and iterate let debug_solution = "near nomicon ref finance"; let debug_hash_bytes = env::sha256(debug_solution.as_bytes()); let debug_hash_string = hex::encode(debug_hash_bytes); println!("Let's debug: {:?}", debug_hash_string); } ``` :::info What is that `{:?}` thing? Take a look at different formatting traits that are covered in the [`std` Rust docs](https://doc.rust-lang.org/std/fmt/index.html#formatting-traits) regarding this. This is a `Debug` formatting trait and can prove to be useful during development. ::: Run the unit tests with the command: ``` cargo test -- --nocapture ``` You'll see this output: ``` … running 1 test Let's debug: "69c2feb084439956193f4c21936025f14a5a5a78979d67ae34762e18a7206a0f" test tests::debug_get_hash ... ok test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s ``` This means when you sha256 the input **"near nomicon ref finance"** it produces the hash: `69c2feb084439956193f4c21936025f14a5a5a78979d67ae34762e18a7206a0f` :::tip Note on the test flags You may also run tests using: ``` cargo test ``` Note that the test command we ran had additional flags. Those flags told Rust **not to hide the output** from the tests. You can read more about this in [the cargo docs](https://doc.rust-lang.org/cargo/commands/cargo-test.html#display-options). Go ahead and try running the tests using the command above, without the additional flags, and note that we won't see the debug message. ::: The unit test above is meant for debugging and quickly running snippets of code. Some may find this a useful technique when getting familiar with Rust and writing smart contracts. Next we'll write a real unit test that applies to this early version of our crossword puzzle contract. ## Write a regular unit test Let's add this unit test (inside the `mod tests {}` block, under our previous unit test) and analyze it: ``` // part of writing unit tests is setting up a mock context // provide a `predecessor` here, it'll modify the default context fn get_context(predecessor: AccountId) -> VMContextBuilder { let mut builder = VMContextBuilder::new(); builder.predecessor_account_id(predecessor); builder } #[test] fn check_guess_solution() { // Get Alice as an account ID let alice: AccountId = "alice.testnet".parse().unwrap(); // Set up the testing context and unit test environment let context = get_context(alice); testing_env!(context.build()); // Set up contract object and call the new method let contract = Contract::new( "69c2feb084439956193f4c21936025f14a5a5a78979d67ae34762e18a7206a0f".to_string(), ); let mut guess_result = contract.guess_solution("wrong answer here".to_string()); assert!(!guess_result, "Expected a failure from the wrong guess"); assert_eq!(get_logs(), ["Try again."], "Expected a failure log."); guess_result = contract.guess_solution("near nomicon ref finance".to_string()); assert!(guess_result, "Expected the correct answer to return true."); assert_eq!( get_logs(), ["Try again.", "You guessed right!"], "Expected a successful log after the previous failed log." ); } } ``` The first few lines of code will be used commonly when writing unit tests. It uses the `VMContextBuilder` to create some basic context for a transaction, then sets up the testing environment. Next, an object is created representing the contract and the `set_solution` function is called. After that, the `guess_solution` function is called twice: first with the incorrect solution and then the correct one. We can check the logs to determine that the function is acting as expected. :::info Note on assertions This unit test uses the [`assert_eq!`](https://doc.rust-lang.org/std/macro.assert_eq.html) macro. Similar macros like [`assert!`](https://doc.rust-lang.org/std/macro.assert.html) and [`assert_ne!`](https://doc.rust-lang.org/std/macro.assert_ne.html) are commonly used in Rust. These are great to use in unit tests. However, these will add unnecessary overhead when added to contract logic, and it's recommended to use the [`require!` macro](https://docs.rs/near-sdk/4.0.0-pre.2/near_sdk/macro.require.html). See more information on this and [other efficiency tips here](../../../smart-contracts/anatomy/reduce-size.md). ::: Again, we can run all the unit tests with: ``` cargo test -- --nocapture ``` :::tip Run only one test To only run this latest test, use the command: ``` cargo test check_guess_solution -- --nocapture ``` ::: ## Modifying `set_solution` The [overview section](00-overview.md) of this chapter tells us we want to have a single crossword puzzle and the user solving the puzzle should not be able to know the solution. Using a hash addresses this, and we can keep `crossword_solution`'s field type, as `String` will work just fine. The overview also indicates we only want the author of the crossword puzzle to be able to set the solution. As it stands, our function `set_solution` can be called by anyone with a full-access key. It's trivial for someone to create a NEAR account and call this function, changing the solution. Let's fix that. Let's have the solution be set once, right after deploying the smart contract. Here we'll use the [`#[near]` macro](https://docs.rs/near-sdk/latest/near_sdk/attr.near.html) on a function called `new`, which is a common pattern. ``` #[near] impl Contract { #[init] pub fn new(solution: String) -> Self { Self { crossword_solution: solution, } } pub fn get_solution(&self) -> String { ``` Let's call this method on a fresh contract. Go into the directory containing the Rust smart contract and build it: ```bash cd contract # Build cargo near build ``` Create fresh account if you wish, which is good practice:
:::info Batch Actions in use Batch Actions are common in this instance, where we want to deploy and call an initialization function. They're also common when using a factory pattern, where a subaccount is created, a smart contract is deployed to it, a key is added, and a function is called. Here's a truncated snippet from a useful (though somewhat advanced) repository with a wealth of useful code: ``` Promise::new(staking_pool_account_id.clone()) .create_account() .transfer(env::attached_deposit()) .deploy_contract(include_bytes!("../../staking-pool/res/staking_pool.wasm").to_vec()) .function_call( b"new".to_vec(), near_sdk::serde_json::to_vec(&StakingPoolArgs { ``` We'll get into Actions later in this tutorial, but in the meantime here's a handy [reference from the spec](https://nomicon.io/RuntimeSpec/Actions.html). ::: As you can from the info bubble above, we can batch [Deploy](https://docs.rs/near-sdk/3.1.0/near_sdk/struct.Promise.html#method.deploy_contract) and [FunctionCall](https://docs.rs/near-sdk/3.1.0/near_sdk/struct.Promise.html#method.function_call) Actions. This is exactly what we want to do for our crossword puzzle, and luckily, NEAR CLI has a [flag especially for this](/tools/near-cli#deploy). Let's run this again with the handy `--initFunction` and `--initArgs` flags: Create fresh account if you wish, which is good practice:
Valid Account IDs
In NEAR, accounts can actually be any string as long as they meet the following criteria: - It must have at least 2 characters and can go up to 64 characters - It can only use lowercase letters (`a-z`), digits (`0-9`), and separators (`.`, `-`, `_`) This means that all `root`, `some-unique-string`, `something-to-remember-later`, `0x85f17....`, `fb9243ce` and `user.name` are **all valid account IDs**. However, users can only create accounts that are either a `named address`, an `implicit address`, or an `ethereum-like address`🧑💻 Technical: How to obtain a key-pair
The simplest way to obtain a public / private key that represents an account is using the [NEAR CLI](../tools/cli.md) ```bash near account create-account fund-later use-auto-generation save-to-folder ~/.near-credentials/implicit # The file "~/.near-credentials/implicit/8bca86065be487de45e795b2c3154fe834d53ffa07e0a44f29e76a2a5f075df8.json" was saved successfully cat ~/.near-credentials/implicit/8bca86065be487de45e795b2c3154fe834d53ffa07e0a44f29e76a2a5f075df8.json ``` or using the `near-seed-phrase` library: ```js const { seedPhrase, publicKey, secretKey } = generateSeedPhrase(); ```🧑💻 Technical: How to derive an implicit account from a public key
You can derive the implicit account address from a public key by removing the `ed25519:` prefix, decoding the resulting Base58 string into bytes, and then converting those bytes into a hexadecimal string. ```js // vanilla js Buffer.from(decode(publicKey.replace('ed25519:', ''))).toString('hex') // or using near-api-js utils.keyToImplicitAddress(publicKey); ```🧑💻 Technical: How Are Named Accounts Created?
In NEAR, named accounts are created using the [`CreateAccount`](./transaction-anatomy.md#actions) action. Both `testnet` and `near` accounts expose the function `create_account`, which triggers `CreateAccount` to create sub-accounts of themselves. For example, if we want to create the account `alice.testnet` with `0.1 NEAR`, we would need to call the `create_account` method of `testnet` using an existing account (e.g. `funding-account.testnet`): ```bash near call testnet create_account '{"new_account_id": "alice.testnet", "new_public_key": "ed25519:"}' --useAccount funding-account.testnet --networkId testnet ``` If we then want to create a sub-account of `alice.testnet` - which we control - we can simply trigger the `CreateAccount` action ourselves: ```bash near create-account sub-acc.new-acc.testnet --useAccount new-acc.testnet ``` > Note: if you want the accounts to have some initial balance, you can add the `--deposit### [Multiple Keys](access-keys.md) NEAR accounts can have multiple [keys](access-keys.md), each with their own set of permissions: - You can easily swap keys if one gets compromised - You can use keys as authorization tokens for third-party applications
### [Smart Contracts](../smart-contracts/what-is.md) NEAR accounts can optionally hold an application - known as a [smart contract](../smart-contracts/what-is.md) - which can be written in Javascript or Rust. --- ## Comparison With Ethereum {#compared-to-ethereum} If you're familiar with development on Ethereum, it's worth making a quick note about how accounts are different. The table below summarizes some key differences: | | Ethereum Account | NEAR Account | |-----------------|--------------------------|----------------------------------------------------------------------------------------| | Account ID | Public Key (`0x123...`) | - Native named accounts (`alice.near`)
- Implicit accounts (`0x123...`) | | Secret Key | Private Key (`0x456...`) | Multiple key-pairs with permissions:
- `FullAccess` key
- `FunctionCall` key | | Smart Contracts | Synchronous execution | Asynchronous execution | | Gas Fees | In the order of dollars | In the order of tenths of a cent | | Block Time | ~12 seconds | ~600 milliseconds | --- # Source: https://docs.near.org/integrations/accounts.md --- id: accounts title: Accounts sidebar_label: Accounts description: "Learn about NEAR account management for exchanges and integrations, including account creation, key management, and balance tracking." --- This document provides relevant information about NEAR accounts for exchanges looking forward to integrate the NEAR token Please see the [documentation for accounts](/protocol/account-model) for basic information. - For exchanges, NEAR supports [implicit account](https://nomicon.io/DataStructures/Account.html#implicit-account-ids) creation which allows the creation of accounts without paying for transactions. - You can create an implicit account by following the steps in [this guide](/integrations/implicit-accounts). - Accounts must have enough tokens to cover its storage which currently costs `0.0001 NEAR` per byte. This equates to a minimum balance of `0.00182 NEAR` for an account with one access key. You can query the live storage price using the [`protocol-config`](/api/rpc/protocol#protocol-config) RPC endpoint. For more details on storage fees see [this section of the economics paper](https://pages.near.org/papers/economics-in-sharded-blockchain/#transaction-and-storage-fees). ## Transfer from Function Call {#transfer-from-function-call} NEAR allows transfers to happen within a function call. More importantly, when an account is deployed with some contract, it is possible that the only way to transfer tokens from that account is through a function call. Therefore, exchanges need to support transfers through function calls as well. We recommend the following approach: Exchange can [query block by height](/api/rpc/block-chunk#block-details) to get blocks on each height, and for every block, [query its chunk](/api/rpc/block-chunk#chunk-details) to obtain the transactions included in the block. For each transaction, [query its status](/api/rpc/transactions#transaction-status-with-receipts) to see the receipts generated from transactions. Since exchanges are only interested in transfers to their addresses, they only need to filter receipts that only contain `Transfer` action and whose `predecessor_id` is not `system` (receipts with `predecessor_id` equal to `system` are [refunds](https://nomicon.io/RuntimeSpec/Refunds.html)). Then, to check whether the receipt succeeds, it is sufficient to look for the `receipt_id` in `receipts_outcome` and see if its status is `SuccessValue`. Alternatively, exchange can use [the indexer framework](https://github.com/near/nearcore/tree/master/chain/indexer) to help index on-chain data which include receipts. An example usage of the indexer can be found [here](https://github.com/near/nearcore/tree/master/tools/indexer/example). Below we include examples from the contracts that are likely to be used to perform transfers through function calls. **Example of transfer from a lockup contract** A contract `evgeny.lockup.near` is deployed and we can check its owner by ```bash near contract call-function as-read-only evgeny.lockup.near get_owner_account_id json-args '{}' network-config testnet now # View call: evgeny.lockup.near.get_owner_account_id() # 'evgeny.near' ``` Now we want to transfer some unlocked tokens (1 NEAR) with the following call ```bash near contract call-function as-transaction evgeny.lockup.near transfer json-args '{"amount":"1000000000000000000000000", "receiver_id": "evgeny.near"}' prepaid-gas '100.0 Tgas' attached-deposit '0 NEAR' sign-as evgeny.near network-config testnet sign-with-keychain send ``` **Note**: the response below can be obtained by hitting the RPC with the transaction hash and NEAR account like this: ```bash http post https://rpc.testnet.near.org jsonrpc=2.0 id=txstatus method=EXPERIMENTAL_tx_status \ params:='[ "GXP8YaSonoN2eBY6dB3FbMN2NyYD2JeJJvKdvbL4Jmb2", "evgeny.near"]' ```
**Example Response:**
```json { "id": "123", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "evgeny.near", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "eyJhbW91bnQiOiIxMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIiwicmVjZWl2ZXJfaWQiOiJldmdlbnkubmVhciJ9", "deposit": "0", "gas": 100000000000000, "method_name": "transfer" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "evgeny.near", "signer_public_key": "ed25519:BVRTxEEMx3gFceSgJtnvPFbSnPDwwUzHe6KGduRh5Byq" } }, "receipt_id": "CyJL22SYqt26qgh2XVnk9MGfvzgyiiq5Lny7DdbTdTWU", "receiver_id": "evgeny.lockup.near" }, { "predecessor_id": "evgeny.lockup.near", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "1000000000000000000000000" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "evgeny.near", "signer_public_key": "ed25519:BVRTxEEMx3gFceSgJtnvPFbSnPDwwUzHe6KGduRh5Byq" } }, "receipt_id": "EvHfj4fUyVuLBRKNdCZmFGr4WfqwYf7YCbzFsRGFTFJC", "receiver_id": "evgeny.near" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "19200274886926125000" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "evgeny.near", "signer_public_key": "ed25519:BVRTxEEMx3gFceSgJtnvPFbSnPDwwUzHe6KGduRh5Byq" } }, "receipt_id": "J1bBKH43nXHYg4NuS97R1PFzdZchrJboVAdRsK5NRrAv", "receiver_id": "evgeny.near" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "18655658845681462514128" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "evgeny.near", "signer_public_key": "ed25519:BVRTxEEMx3gFceSgJtnvPFbSnPDwwUzHe6KGduRh5Byq" } }, "receipt_id": "6PFaxnNvK5r6qxBq5WfV9uGjoNM6qjhHwLehLP1qak9d", "receiver_id": "evgeny.near" } ], "receipts_outcome": [ { "block_hash": "9boEKq9G1UFsEuzmuQrxh5dkRc8xsv8PSPGEkYiTyRLj", "id": "CyJL22SYqt26qgh2XVnk9MGfvzgyiiq5Lny7DdbTdTWU", "outcome": { "executor_id": "evgeny.lockup.near", "gas_burnt": 3574640311481, "logs": [ "Transferring 1000000000000000000000000 to account @evgeny.near" ], "receipt_ids": [ "EvHfj4fUyVuLBRKNdCZmFGr4WfqwYf7YCbzFsRGFTFJC", "6PFaxnNvK5r6qxBq5WfV9uGjoNM6qjhHwLehLP1qak9d" ], "status": { "SuccessReceiptId": "EvHfj4fUyVuLBRKNdCZmFGr4WfqwYf7YCbzFsRGFTFJC" }, "tokens_burnt": "357464031148100000000" }, "proof": [] }, { "block_hash": "7qn4BjmMD4QbyVvMa8QEzm7h5YuhoGTFTgLeNMUp85UQ", "id": "EvHfj4fUyVuLBRKNdCZmFGr4WfqwYf7YCbzFsRGFTFJC", "outcome": { "executor_id": "evgeny.near", "gas_burnt": 223182562500, "logs": [], "receipt_ids": ["J1bBKH43nXHYg4NuS97R1PFzdZchrJboVAdRsK5NRrAv"], "status": { "SuccessValue": "" }, "tokens_burnt": "22318256250000000000" }, "proof": [ { "direction": "Right", "hash": "AwHdk5dushTSXHFBt3R5MiexjiXybwdnEaB7L9iJ5F6t" } ] }, { "block_hash": "46788Ay85YGnQaH5tfbboQNWJs3gyXsPbcWzRyxqw56K", "id": "J1bBKH43nXHYg4NuS97R1PFzdZchrJboVAdRsK5NRrAv", "outcome": { "executor_id": "evgeny.near", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [] }, { "block_hash": "7qn4BjmMD4QbyVvMa8QEzm7h5YuhoGTFTgLeNMUp85UQ", "id": "6PFaxnNvK5r6qxBq5WfV9uGjoNM6qjhHwLehLP1qak9d", "outcome": { "executor_id": "evgeny.near", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Left", "hash": "9RRJpH5VdDxsHpp323EshcAauV5wUNDyW9FpEJBRXXq8" } ] } ], "status": { "SuccessValue": "" }, "transaction": { "actions": [ { "FunctionCall": { "args": "eyJhbW91bnQiOiIxMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIiwicmVjZWl2ZXJfaWQiOiJldmdlbnkubmVhciJ9", "deposit": "0", "gas": 100000000000000, "method_name": "transfer" } } ], "hash": "GXP8YaSonoN2eBY6dB3FbMN2NyYD2JeJJvKdvbL4Jmb2", "nonce": 6, "public_key": "ed25519:BVRTxEEMx3gFceSgJtnvPFbSnPDwwUzHe6KGduRh5Byq", "receiver_id": "evgeny.lockup.near", "signature": "ed25519:4nfzTMpQJKCY3KaqUTFig4Xy9uxwbMeQpMJjtNKsXmwiVqgcVSWRguZEgZM8L2x1jvdpZHsYjLCxc9cSBamXuXPH", "signer_id": "evgeny.near" }, "transaction_outcome": { "block_hash": "4u7maz2U43W4DPxqQE8KoRNi5dTRHrAsKsFk2qDQsQEw", "id": "GXP8YaSonoN2eBY6dB3FbMN2NyYD2JeJJvKdvbL4Jmb2", "outcome": { "executor_id": "evgeny.near", "gas_burnt": 2428086459116, "logs": [], "receipt_ids": ["CyJL22SYqt26qgh2XVnk9MGfvzgyiiq5Lny7DdbTdTWU"], "status": { "SuccessReceiptId": "CyJL22SYqt26qgh2XVnk9MGfvzgyiiq5Lny7DdbTdTWU" }, "tokens_burnt": "242808645911600000000" }, "proof": [] } } } ```**Example Response:**
```json { "id": "123", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "3069687780141648922140" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "multisigtest.testnet", "signer_public_key": "ed25519:JDewsbE7nz6orFD4zJ3mVzqhfcaoSD6Hmi5as3AHHiTt" } }, "receipt_id": "4qgDptd7Wm6vswAhWMCsVpTjBEkmLJEUxSNVQS1wu3rD", "receiver_id": "multisigtest.testnet" } ], "receipts_outcome": [ { "block_hash": "6uJWHTvUrtFQAurUyfuAfy9EdoR9FhLodGh44aHJta6m", "id": "94LiYwKJEDherHMNg9fqLy9ShFTDiQiUN3nDaGmLZwth", "outcome": { "executor_id": "multisigtest.testnet", "gas_burnt": 8024094920263, "logs": [], "receipt_ids": ["4qgDptd7Wm6vswAhWMCsVpTjBEkmLJEUxSNVQS1wu3rD"], "status": { "SuccessValue": "OA==" }, "tokens_burnt": "802409492026300000000" }, "proof": [ { "direction": "Left", "hash": "GedzmwRkxA5VkT8GLBCnrPUmnEhWPXadPmiq4Ho1s9pH" }, { "direction": "Right", "hash": "GirkzdS9YpsAz5fXuL5T3rXd93aRcnXNAdXYi241qpWK" } ] }, { "block_hash": "4JyQ6guJKeWZxxXrKndLDuSa5URuirmBi6RzsbKYFsBE", "id": "4qgDptd7Wm6vswAhWMCsVpTjBEkmLJEUxSNVQS1wu3rD", "outcome": { "executor_id": "multisigtest.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [] } ], "status": { "SuccessValue": "OA==" }, "transaction": { "actions": [ { "FunctionCall": { "args": "eyJyZXF1ZXN0Ijp7InJlY2VpdmVyX2lkIjoiYm93ZW4iLCJhY3Rpb25zIjpbeyJ0eXBlIjoiVHJhbnNmZXIiLCJhbW91bnQiOiIxMDAwMDAwMDAwMDAwMDAwMDAwMDAwMDAwIn1dfX0=", "deposit": "0", "gas": 30000000000000, "method_name": "add_request_and_confirm" } } ], "hash": "FGREJkC1e8y95Rc35iD1LVRiDy1WcAZhAxxkSinfb2mL", "nonce": 10, "public_key": "ed25519:JDewsbE7nz6orFD4zJ3mVzqhfcaoSD6Hmi5as3AHHiTt", "receiver_id": "multisigtest.testnet", "signature": "ed25519:3NUKXd4uj2eEBqGQtRAxkTFW7UfG44tjvQNNHBDvN9ZswTTMRsDrMJSd1U3GqWF7QToqWQR9J8atNEVTemSWYw41", "signer_id": "multisigtest.testnet" }, "transaction_outcome": { "block_hash": "6uJWHTvUrtFQAurUyfuAfy9EdoR9FhLodGh44aHJta6m", "id": "FGREJkC1e8y95Rc35iD1LVRiDy1WcAZhAxxkSinfb2mL", "outcome": { "executor_id": "multisigtest.testnet", "gas_burnt": 2428204963618, "logs": [], "receipt_ids": ["94LiYwKJEDherHMNg9fqLy9ShFTDiQiUN3nDaGmLZwth"], "status": { "SuccessReceiptId": "94LiYwKJEDherHMNg9fqLy9ShFTDiQiUN3nDaGmLZwth" }, "tokens_burnt": "242820496361800000000" }, "proof": [ { "direction": "Right", "hash": "AsNAQabPFkmaugRGhCbzcEcR8Gnd22WXxPM2fb2cwHiv" }, { "direction": "Right", "hash": "GirkzdS9YpsAz5fXuL5T3rXd93aRcnXNAdXYi241qpWK" } ] } } } ```**Example Response:**
```json { "id": "123", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "multisigtest.testnet", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "1000000000000000000000000" } } ], "gas_price": "451542320", "input_data_ids": [], "output_data_receivers": [], "signer_id": "multisigtest.testnet", "signer_public_key": "ed25519:BmVX32jhvEd8d8outiQdjf66GGYV3pb7kaxrKTdNisCz" } }, "receipt_id": "DZbHTEf3i3XznK4oJHQfcrteoiCL6WykRiA8vsn4LmAy", "receiver_id": "bowen" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "78458115804795000000" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "multisigtest.testnet", "signer_public_key": "ed25519:BmVX32jhvEd8d8outiQdjf66GGYV3pb7kaxrKTdNisCz" } }, "receipt_id": "6SxC9GfYdjqm7Ao5EAw51XUAjgoN8Lj2X9xJfxjDQYXd", "receiver_id": "multisigtest.testnet" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "112870156274913516718240" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "multisigtest.testnet", "signer_public_key": "ed25519:BmVX32jhvEd8d8outiQdjf66GGYV3pb7kaxrKTdNisCz" } }, "receipt_id": "CHfzz6NLcQMyiLHBQoczhgm5BFjLVfv9B7eCyXKLhhcT", "receiver_id": "multisigtest.testnet" } ], "receipts_outcome": [ { "block_hash": "9JEiMrZ1SpAUEbQswde3Diptzwy35Vrvd41VZWG9hYVE", "id": "FfuhYhsgFL7sLC8pk1tuRnMHJdqycE6gEcfgZLW9fmFB", "outcome": { "executor_id": "multisigtest.testnet", "gas_burnt": 10109796553814, "logs": [], "receipt_ids": [ "DZbHTEf3i3XznK4oJHQfcrteoiCL6WykRiA8vsn4LmAy", "CHfzz6NLcQMyiLHBQoczhgm5BFjLVfv9B7eCyXKLhhcT" ], "status": { "SuccessReceiptId": "DZbHTEf3i3XznK4oJHQfcrteoiCL6WykRiA8vsn4LmAy" }, "tokens_burnt": "1010979655381400000000" }, "proof": [ { "direction": "Left", "hash": "9e2UcG6qBRahBh3V2Z8bGJLh5c4jXfZdP3WBJkCpJCfj" } ] }, { "block_hash": "4LkVfqyhhrxDdVFmow6NxLf1jTaj6XVr7CVcUxxySd1R", "id": "DZbHTEf3i3XznK4oJHQfcrteoiCL6WykRiA8vsn4LmAy", "outcome": { "executor_id": "bowen", "gas_burnt": 223182562500, "logs": [], "receipt_ids": ["6SxC9GfYdjqm7Ao5EAw51XUAjgoN8Lj2X9xJfxjDQYXd"], "status": { "SuccessValue": "" }, "tokens_burnt": "22318256250000000000" }, "proof": [ { "direction": "Right", "hash": "FFWaWUFt6sNx5XNHzGYsYBSYFWtGPoww5XQz1QmLVc8i" } ] }, { "block_hash": "G6LDdnAa2b38TB4KZ89HAyVgfgyiRPDDgSxoZypbUYpx", "id": "6SxC9GfYdjqm7Ao5EAw51XUAjgoN8Lj2X9xJfxjDQYXd", "outcome": { "executor_id": "multisigtest.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [] }, { "block_hash": "4LkVfqyhhrxDdVFmow6NxLf1jTaj6XVr7CVcUxxySd1R", "id": "CHfzz6NLcQMyiLHBQoczhgm5BFjLVfv9B7eCyXKLhhcT", "outcome": { "executor_id": "multisigtest.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Left", "hash": "DpDYAEKZTtSomgyeNcJ2i4qjvfqnCtf1CXa83Cz5wvEy" } ] } ], "status": { "SuccessValue": "" }, "transaction": { "actions": [ { "FunctionCall": { "args": "eyJyZXF1ZXN0X2lkIjo4fQ==", "deposit": "0", "gas": 250000000000000, "method_name": "confirm" } } ], "hash": "Fu39vwxC4mu9ks1DZA5Cib63RnBMHpFonk2DcbpioEYc", "nonce": 9, "public_key": "ed25519:BmVX32jhvEd8d8outiQdjf66GGYV3pb7kaxrKTdNisCz", "receiver_id": "multisigtest.testnet", "signature": "ed25519:2raQq7t3cmzSL2krE2xaNqXhAw7cKMoXrBjT2ZhAGfCVtGwzbbQ8zkB17vrCSFZDbFmPWSJpoqsw8qPZZiorwSzS", "signer_id": "multisigtest.testnet" }, "transaction_outcome": { "block_hash": "9JEiMrZ1SpAUEbQswde3Diptzwy35Vrvd41VZWG9hYVE", "id": "Fu39vwxC4mu9ks1DZA5Cib63RnBMHpFonk2DcbpioEYc", "outcome": { "executor_id": "multisigtest.testnet", "gas_burnt": 2427972426482, "logs": [], "receipt_ids": ["FfuhYhsgFL7sLC8pk1tuRnMHJdqycE6gEcfgZLW9fmFB"], "status": { "SuccessReceiptId": "FfuhYhsgFL7sLC8pk1tuRnMHJdqycE6gEcfgZLW9fmFB" }, "tokens_burnt": "242797242648200000000" }, "proof": [ { "direction": "Right", "hash": "B6hN48qeVP8J3hP8XGcANShM264QkNjgJAfMtsuknqex" } ] } } } ```#### Creating `.testnet` / `.near` Accounts Accounts can only create immediate sub-accounts of themselves. If your contract wants to create a `.mainnet` or `.testnet` account, then it needs to [call](#function-call) the `create_account` method of `near` or `testnet` root contracts.
### Deploying the Contract to the NEAR network In order to deploy the contract you will need to create a NEAR account.
### CLI: Interacting with the Contract To interact with the contract through the console, you can use the following commands:
Interaction with other macros
When `near` is built for the wasm32 target, it generates the external NEAR contract bindings. To achieve this it is actually generating another function with the signature `pub extern "C" fn function_name()` that first deserializes the contract struct from NEAR storage and then calls the `contract.function_name(parameter1, parameter2, ...)`. If you have annotated your function with any attribute-like macros, these are then executed _twice_. Specifically if the attribute like macro makes any modification to the function signature, or inserts any code that depends on the contract struct (in the form of `&self`, `&mut self`, or `self`) this will fail in the second invocation, because the externally exposed function does not have any concept of this struct. It is possible to detect this by checking which build target you are building for and limit the execution of the macro to operate only on the first pass.Response
For `Ecdsa`, the function returns the components of the signature as hex strings. Note that to get `r`, remove the first two hex characters from `big_r`. ```typescript { scheme: 'Secp256k1', big_r: { affine_point: '03D537AFFD52BE9AF0DA6CF41B573F4BE065434AEE2D25A500BC730C06E7EB2AF1' }, s: { scalar: '3470037EB46DC6D1921900B635785290184EC980CFEC7109EB103B5698D4F725' }, recovery_id: 0 } ``` For `Eddsa`, the function returns the whole signature as a 64-byte array. ```typescript { scheme: 'Ed25519', signature: [ 5, 105, 30, 208, 192, 39, 154, 105, 252, 20, 132, 64, 247, 207, 223, 127, 197, 43, 30, 145, 164, 224, 1, 45, 240, 28, 155, 218, 204, 5, 136, 111, 238, 40, 120, 122, 249, 166, 193, 174, 120, 94, 177, 39, 179, 193, 170, 117, 37, 36, 155, 38, 72, 24, 118, 235, 187, 110, 129, 26, 186, 7, 0, 8 ] } ``` If you're using the chainsig.js library, you don't need to worry about the format of these responses since the library handles it.Response
For `Ecdsa`, the function returns the components of the signature as hex strings. Note that to get `r`, remove the first two hex characters from `big_r`. ```python { 'scheme': 'Secp256k1', 'big_r': { 'affine_point': '03D537AFFD52BE9AF0DA6CF41B573F4BE065434AEE2D25A500BC730C06E7EB2AF1' }, 's': { 'scalar': '3470037EB46DC6D1921900B635785290184EC980CFEC7109EB103B5698D4F725' }, 'recovery_id': 0 } ``` For `Eddsa`, the function returns the whole signature as a 64-byte array. ```python { 'scheme': 'Ed25519', 'signature': [ 5, 105, 30, 208, 192, 39, 154, 105, 252, 20, 132, 64, 247, 207, 223, 127, 197, 43, 30, 145, 164, 224, 1, 45, 240, 28, 155, 218, 204, 5, 136, 111, 238, 40, 120, 122, 249, 166, 193, 174, 120, 94, 177, 39, 179, 193, 170, 117, 37, 36, 155, 38, 72, 24, 118, 235, 187, 110, 129, 26, 186, 7, 0, 8 ] } ```Response
For `Ecdsa`, the function returns the components of the signature as hex strings. Note that to get `r`, remove the first two hex characters from `big_r`. ```json { "scheme": "Secp256k1", "big_r": { "affine_point": "03D537AFFD52BE9AF0DA6CF41B573F4BE065434AEE2D25A500BC730C06E7EB2AF1" }, "s": { "scalar": "3470037EB46DC6D1921900B635785290184EC980CFEC7109EB103B5698D4F725" }, "recovery_id": 0 } ``` For `Eddsa`, the function returns the whole signature as a 64-byte array. ```json { "scheme": "Ed25519", "signature": [ 5, 105, 30, 208, 192, 39, 154, 105, 252, 20, 132, 64, 247, 207, 223, 127, 197, 43, 30, 145, 164, 224, 1, 45, 240, 28, 155, 218, 204, 5, 136, 111, 238, 40, 120, 122, 249, 166, 193, 174, 120, 94, 177, 39, 179, 193, 170, 117, 37, 36, 155, 38, 72, 24, 118, 235, 187, 110, 129, 26, 186, 7, 0, 8 ] } ```**Example Response:**
```json { "id": "dontcare", "jsonrpc": "2.0", "result": { "block_hash": "BRgE4bjmUo33jmiVBcZaWGkSLVeL7TTi4ZxYTvJdPbB9", "changes": [ { "cause": { "tx_hash": "4To336bYcoGc3LMucJPMk6fMk5suKfCrdNotrRtTxqDy", "type": "transaction_processing" }, "change": { "account_id": "sender.testnet", "amount": "11767430014412510000000000", "code_hash": "11111111111111111111111111111111", "locked": "0", "storage_paid_at": 0, "storage_usage": 806 }, "type": "account_update" } ] } } ```Handling Funds
When a user attaches tokens to a call, the tokens are deposited to the contract's account before the function is executed. However, if the function raises an error during its execution, the tokens are immediately refunded to the user.A simple smart contract that stores a `string` message on its state
A friendly counter that stores a number with methods to increment, decrement, and reset it
Users can sign the guest book, optionally paying `0.01 Ⓝ` to mark their messages as "premium
Forward NEAR tokens to a beneficiary while tracking all donations. Learn how contracts handle token transfers
Guess the outcome of a coin flip and earn points. Demonstrates how to handle randomness on the blockchain
### NEAR Connector Hooks All frontends use [`near-connect-hooks`](https://www.npmjs.com/package/near-connect-hooks), which wrap the functionality of [NEAR Connector](../../web3-apps/tutorials/wallet-login.md) to handle the connection between the web app and the NEAR blockchain. The `near-connect-hooks` expose a `NearProvider` that is used to wrap the entire application, usually in `pages/_app.js`: ```jsx export default function App({ Component, pageProps }: AppProps) { return (
We can then use the **`useNearWallet` hook** within any component to access all NEAR-related functionality, such as login/logout, view and call functions, and sign transactions: ```jsx export default function App() { // Login / Logout functionality const { loading, signIn, signOut, signedAccountId } = useNearWallet(); // To interact with the contract const { viewFunction, callFunction, signAndSendTransactions } = useNearWallet(); } ``` --- ## Smart Contract All repositories include the same smart contract implemented in different languages, including **Rust**, **Javascript**, and sometimes **Python**. The contracts are implemented following the latest versions of each SDK, and include sandbox tests showcasing how to properly test smart contracts in a realistic environment.
### Testing Each contract includes sandbox tests that simulate real user interactions. For example, in the `Guest Book` example, the tests cover scenarios like having multiple accounts signing the guest book, including premium messages.
### Creating an Account All smart contracts can be built and deployed using the `NEAR CLI`. A good first step is to always create a new NEAR account to deploy your contract: ```bash near create-account
### Building & Deploying Once you created an account to host the contract, you can build and deploy it:
### Interacting via CLI Once your contract is deployed, check the `README.md` of each repository to see the available methods you can call. As a general guide, the `NEAR CLI` has two main ways to interact with smart contracts: ```bash # Call a read-only (view) method near view
What do these Technical Terms mean?
In technical terms, NEAR is a [layer-one](https://coinmarketcap.com/academy/glossary/layer-1-blockchain), [sharded](https://near.org/blog/near-launches-nightshade-sharding-paving-the-way-for-mass-adoption), [proof-of-stake](https://en.wikipedia.org/wiki/Proof_of_stake) blockchain built with usability in mind. [Layer-1](https://coinmarketcap.com/academy/glossary/layer-1-blockchain) means NEAR is the foundation that supports everything else built on it. It keeps all the transaction records safe and unchangeable which keeps the network secure and trustworthy. [Sharded](https://near.org/blog/near-launches-nightshade-sharding-paving-the-way-for-mass-adoption) means the network is broken into pieces that work in parallel. This helps NEAR process transactions quickly and efficiently. [Proof-of-stake](https://en.wikipedia.org/wiki/Proof_of_stake) uses less electricity compared with other blockchains which use proof-of-work. Users show they own NEAR tokens to help run the network. This makes it cheaper and lets more people use it.What happens if the cross-contract call fails?
The first time this method is called the contract will try to send itself FTs. Most fungible token contracts don't allow one to send themselves FTs so the cross-contract call will fail. However, since cross-contract calls are asynchronous and independent and we are not checking the result of the call then the auction contract does not care that the call failed and ft_on_transfer will complete successfully. In the other cases, the call to the fungible token contract could only fail if the receiver does not exist, the FT contract does not exist, the auction contract doesn't have enough fungible tokens to cover the amount being sent, or the receiver is not registered in the FT contract. Our contract is set up such that these errors cannot occur, the receiver must exist since they placed the previous bid, the FT contract exists since it was used to place the bid, the auction contract has enough FTs to cover the amount since it was sent that amount by the previous bid, and the receiver must be registered in the FT contract since they needed to have held the token in the first place to make a bid.Example response:
```json { "jsonrpc": "2.0", "result": { "author": "node2", "chunks": [ { "balance_burnt": "0", "bandwidth_requests": null, "chunk_hash": "CzPafxtJmM1FnRoasKWAVhceJzZzkz9RKUBQQ4kY9V1v", "congestion_info": { "allowed_shard": 1, "buffered_receipts_gas": "0", "delayed_receipts_gas": "0", "receipt_bytes": 0 }, "encoded_length": 308, "encoded_merkle_root": "6z9JwwtVfS5nRKcKeJxgzThRRs2wCNvbH88T3cuARe6W", "gas_limit": 1000000000000000, "gas_used": 0, "height_created": 187310138, "height_included": 187310138, "outcome_root": "11111111111111111111111111111111", "outgoing_receipts_root": "AChfy3dXeJjgD2w5zXkUTFb6w8kg3AYGnyyjsvc7hXLv", "prev_block_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_state_root": "cRMk2zd2bWC1oBfGowgMTpqW9L5SNG2FeE72yT1wpQA", "rent_paid": "0", "shard_id": 0, "signature": "ed25519:L1iCopW8gY5rqwfuZT8Y3bHHXvuvWT87X9rwdY6LmFi8LGZdMhj2CkQCXLGrzdfYXD8B54wPTM9TqJAHcKfFDyW", "tx_root": "CMwUsP8q4DTBUYxXm12jVwC8xTD8L1T1n3jdKLQVh6bm", "validator_proposals": [], "validator_reward": "0" }, { "balance_burnt": "0", "bandwidth_requests": null, "chunk_hash": "44MZBWmPgXszAyojsffzozvNEdRsJcsq7RrdAV4Y7CLm", "congestion_info": { "allowed_shard": 2, "buffered_receipts_gas": "0", "delayed_receipts_gas": "0", "receipt_bytes": 0 }, "encoded_length": 8, "encoded_merkle_root": "5TxYudsfZd2FZoMyJEZAP19ASov2ZD43N8ZWv8mKzWgx", "gas_limit": 1000000000000000, "gas_used": 0, "height_created": 187310138, "height_included": 187310138, "outcome_root": "11111111111111111111111111111111", "outgoing_receipts_root": "AChfy3dXeJjgD2w5zXkUTFb6w8kg3AYGnyyjsvc7hXLv", "prev_block_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_state_root": "EQ5mcUAzJA4du33f9g9YzKvdte2ukyRHMMHbbqdazZvU", "rent_paid": "0", "shard_id": 1, "signature": "ed25519:4ktZTtEfxXSXPVj6Kii52d2T684HKKtEMzrd3dNc7UyxmgkKcLtxD1fawtbj8KsmjbZPGj8YMzanDeViEhxRJtDX", "tx_root": "11111111111111111111111111111111", "validator_proposals": [], "validator_reward": "0" }, { "balance_burnt": "38449649514500000000", "bandwidth_requests": null, "chunk_hash": "7eB8V8zMmNp9GxfRt3oHA3DS7YTgPvZ761pBzoziLay8", "congestion_info": { "allowed_shard": 3, "buffered_receipts_gas": "0", "delayed_receipts_gas": "0", "receipt_bytes": 0 }, "encoded_length": 1804, "encoded_merkle_root": "6aZKpB3jZbhAq3kDtXaM6s1hYRLYEM624yiKkKvd957m", "gas_limit": 1000000000000000, "gas_used": 384496495145, "height_created": 187310138, "height_included": 187310138, "outcome_root": "D7ojhJ8UAgWf8A51Ekcundn3Kzdc577p5LFxqxcZurdB", "outgoing_receipts_root": "3CK2q73iJmWa36EbaceqGcTz7pD7pia8BsUDE3gixwnF", "prev_block_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_state_root": "7bSk4ev8EhZFSjb8Zb6ftkEZAUYQdbyPPz2ZkrvjLPuK", "rent_paid": "0", "shard_id": 2, "signature": "ed25519:2sQ4JfYSMFcwpjbmonk67mMCMvuQyCNzvvk3iqCLMR7mnHauy3i7aTbySXwoqnrDjdmNjQ3gJMaA53LSRxYmoyAD", "tx_root": "11111111111111111111111111111111", "validator_proposals": [], "validator_reward": "0" }, { "balance_burnt": "0", "bandwidth_requests": null, "chunk_hash": "9pTjB74BgVSoP4Wb68BjkgnyABvZQUzAvv54YiVgse1B", "congestion_info": { "allowed_shard": 4, "buffered_receipts_gas": "0", "delayed_receipts_gas": "0", "receipt_bytes": 0 }, "encoded_length": 8, "encoded_merkle_root": "5TxYudsfZd2FZoMyJEZAP19ASov2ZD43N8ZWv8mKzWgx", "gas_limit": 1000000000000000, "gas_used": 0, "height_created": 187310138, "height_included": 187310138, "outcome_root": "11111111111111111111111111111111", "outgoing_receipts_root": "AChfy3dXeJjgD2w5zXkUTFb6w8kg3AYGnyyjsvc7hXLv", "prev_block_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_state_root": "JDHeuYmX4kvsTPKyJYtJTrm7UK3JHTf4rw7hcHXYEfCn", "rent_paid": "0", "shard_id": 3, "signature": "ed25519:5AejTPwZGWqdZjGCUbhLCcgasNDtsYKRJhS33uYR5Psu6NcCiaeLZnV8Q7dtWK4hLJ1iA48DA2WeqEeUyGhqWAGT", "tx_root": "11111111111111111111111111111111", "validator_proposals": [], "validator_reward": "0" }, { "balance_burnt": "32741908829000000000", "bandwidth_requests": null, "chunk_hash": "2xQwSvBiCb1mkoPxBJhSRg7pjmnrmKMEffatDz73Y8Jj", "congestion_info": { "allowed_shard": 5, "buffered_receipts_gas": "0", "delayed_receipts_gas": "0", "receipt_bytes": 0 }, "encoded_length": 1042, "encoded_merkle_root": "5XpktxfgMp6thB2nH3PxdSg3K84p2wmpihHxUCqeQA6c", "gas_limit": 1000000000000000, "gas_used": 327419088290, "height_created": 187310138, "height_included": 187310138, "outcome_root": "69ZXwcYi41NY6cx1rZog8YavBPQvN75pmkNHZsFjWfUW", "outgoing_receipts_root": "FqGVK8H8x2P3BbvuFMo7VCTy8cCNTzT1jd5JoLXfYRNG", "prev_block_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_state_root": "BJePbZUt8VzJBwKf1j1sRUJJJEx4D2fUu4SCHiWs331o", "rent_paid": "0", "shard_id": 4, "signature": "ed25519:2QSda4eMn25hmmTY31wN6RnBpBLjamSLrQRoVZ1yEoWyhtMhtg8rUv9Ko1tEdSftwhNEhL1ETixaAz4qcmvHUvD1", "tx_root": "6qbqA8B9oyeVG33JXH25xbA2DiqvHRnxipurYUBJ9D8B", "validator_proposals": [], "validator_reward": "0" }, { "balance_burnt": "0", "bandwidth_requests": null, "chunk_hash": "EVkgySRKpB9HrEJz8f18p9pWmJzhtL9WeYMwDSeY1827", "congestion_info": { "allowed_shard": 0, "buffered_receipts_gas": "0", "delayed_receipts_gas": "0", "receipt_bytes": 0 }, "encoded_length": 8, "encoded_merkle_root": "5TxYudsfZd2FZoMyJEZAP19ASov2ZD43N8ZWv8mKzWgx", "gas_limit": 1000000000000000, "gas_used": 0, "height_created": 187310138, "height_included": 187310138, "outcome_root": "11111111111111111111111111111111", "outgoing_receipts_root": "AChfy3dXeJjgD2w5zXkUTFb6w8kg3AYGnyyjsvc7hXLv", "prev_block_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_state_root": "GkcYxyvnet4nvL7LFdbKxiscFBpe5WSzy5g2pW58LSRs", "rent_paid": "0", "shard_id": 5, "signature": "ed25519:573WUDx8Sm4Fi16PFQkELXYq2SYezcbQP4CuhseqNizDtSTf2c2TKMWf2ZuACiWCSa8ARw8eWB2ZKWaY1uy7xd14", "tx_root": "11111111111111111111111111111111", "validator_proposals": [], "validator_reward": "0" } ], "header": { "approvals": [ null, "ed25519:5GhoQTPXsWpgGPq2ZHZCfP9iY9GSmHMNsnydzxBxnibGvC43PFUAD58aUSNyfepRY4dAMbjbf8CduMyQU83HBxAt", "ed25519:3Vc7sgrrgvpFXRr94mx3CD32Std1MRprR7igChZUisJvUm6f2yJmUGaXk38CYbh2wT1gfsKJ2UHf9icRome3jFYw", "ed25519:3DZqMDGrk3eNUcZ8FiTtdw2piMXVcmVDDs89kHdRdDDgTr88GnQPEym4kfX9FUE81MnbytmotPry2sXD6MvbVprp", "ed25519:5qtN8dU2iCtZxqPNszhPJ2Rgio88QL2wseLPhLH5Ev56WuxcNsmFZbNREvA6cKAKz4aDwQFFmmj888h6EEZuS2TV", "ed25519:3gKUWzXU7Am5xdZqgMN3TC5wGVrf1kp6WQoqqtLFaF9JtBQKqqpZ67CKBm6KfejHPhiRkp1PbDJbppiNCpN3spr6", "ed25519:3wgeF9tcjx1vX2bLpXfm8fYUQnai524XjTNb3Wt2LHMZnNoXzW4D2XBynj8sK41H5wtSbeVYpN3vGY1r23y56BaY", "ed25519:ek5uvofwn5ZJidjYwiqS8Xpd1Y521FAUWrPyU9w3F8UT9yhviWuzPBCJUyMFVKnYUW6k6tZSZxT3NZibGfrGWA4", "ed25519:4UcHZyKNzGDsMSNfQjLA9EE8yXiq3aroLUz4WJATzkKkUfMNVRkWxGc5tih2jDwzKfY3Ni5YiPoBbPzPCxNrusLf", "ed25519:2hXaGXtAxngCjEWvnUUEgnnPCsXYzPzDadGHdw9sz6ng5oDQDPhnTm1MCG37xvv7xgCVhj3tqRZy8v74uap7WFC5", "ed25519:kLuyqcTUynL1P77uMaaRs2MzxiaE1uyVGPjAVxpufK9A19G6LDUfK2GcbFXkqCgvKBJEGZKFPUbBqs7EmDdLPD7", "ed25519:5ebABgQGk7idMAQgiEgc9a78v6fsD1nKXfevdBRJPFCn8bRuuFpthzzCp3NQXcr2XgSpNo6HJp8EZzzZHkSLfTDc", "ed25519:4hTb2qFydXaiMKfv1pCxU4S9TQYQTHhqUPuGy8dejqxt2FFHD2sdFsYCv8Mf8qWRSob77QMuQbj37aQfEuJR2hH4", null, "ed25519:65jkXVzQ8pGsRDApBvVFx4xR7j4gruJaL2wumRHEHWib61M5Ztvtt7TTkz2DMN1nrRy6C7Pfhe3U3KpdSVEKKYAN", null, "ed25519:3kNRvMnpP8t4D9Dgs1YDAXyPNg7V3fpNa3GEWyCNNq5EvXxnyEoXRyPtbrZQM2FbapKsL2DnaNGvewHwBRQz5DbD", "ed25519:5JQugH24LahiK7sn85akbprCtpAWfnZ2ffazxQ61kt9f6pe8b8s2LrHVKV3Wf4Sg3xHuP7fuUZJRyA4MWz3EQ83i", "ed25519:2zXba2vAyGEq1fWauB3Kj6HbExTZG1S9KXKe6xcLxEpJHP9JHE6P3mJzpc765WpNsP21evNGj6mffJAwRHtwRny4", null ], "block_body_hash": "6oSbpNUWcAUuaKWx79qTwyRPDLukg9hZ1RCa2PS5rcGt", "block_merkle_root": "DWK6gpunDXHgxU1KJi3Dx8o2HcKqQmUQJEaisK4M3ovD", "block_ordinal": 139413603, "challenges_result": [], "challenges_root": "11111111111111111111111111111111", "chunk_endorsements": [ [255, 255], [251, 127], [255, 31], [255, 247], [255, 239, 1], [255, 63] ], "chunk_headers_root": "4MjChqi5JChDhaiU4zkhN1jeygZiMd66KeHe3Gz9Vs7s", "chunk_mask": [true, true, true, true, true, true], "chunk_receipts_root": "7nEtD9XsDbRJy7MwvUg4QX5zDUktiEVRP9nM6hHpsHmX", "chunk_tx_root": "44YKYmcG1JTocmPSMGpriLwN8CTi29sD8z5FcocMZAKo", "chunks_included": 6, "epoch_id": "HkFsp3sn9K3KDWVoWPCfUSQocgf5bH4icgjHijePc2aX", "epoch_sync_data_hash": null, "gas_price": "100000000", "hash": "6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w", "height": 187310138, "last_ds_final_block": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "last_final_block": "71qgTQCVFfjQkimSdnhxR8iWSP6o9jqumLcZ9k5g25mT", "latest_protocol_version": 73, "next_bp_hash": "AWcwcDPWUjcW9zGiAt7UEUZzZ5Ue77537turbvBLbsiB", "next_epoch_id": "FQBXgdi9oWKanYBXPP1sNUD93KMquocjT5mVrjQ4PH7E", "outcome_root": "7Qkowo41AoiMdNfyiT83DwvwyReMeqhrkpqTzGm4Z19T", "prev_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_height": 187310137, "prev_state_root": "AiApSbMNq9kPPEiLLWhFpSrX5HoPToaBXztM9fePX2ap", "random_value": "Br6a6tgEhNBZm9iPtxCLhwqwCr2eoEAGGMeVYZnU6fVF", "rent_paid": "0", "signature": "ed25519:YSuWifP5B3VBPuEVJppWt13AShXsWZ64Qus8uHmtddE2mY6u4jnZVv6Gz4tFvWXfBAkZDk5xtd95rUterEdQm5t", "timestamp": 1739254177539033760, "timestamp_nanosec": "1739254177539033760", "total_supply": "2515615267787707740507051994761921", "validator_proposals": [], "validator_reward": "0" } }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "6RWmTYhXCzjMjoY3Mz1rfFcnBm8E6XeDDbFEPUA4sv1w", "block_effects": [ { "account_id": "account.rpc-examples.testnet", "type": "account_touched" }, { "account_id": "dev2-nsp.testnet", "type": "account_touched" }, { "account_id": "ping-account.testnet", "type": "account_touched" }, { "account_id": "v1.signer-dev.testnet", "type": "account_touched" }, { "account_id": "account.rpc-examples.testnet", "type": "access_key_touched" }, { "account_id": "ping-account.testnet", "type": "access_key_touched" }, { "account_id": "dev2-nsp.testnet", "type": "data_touched" }, { "account_id": "dev2-nsp.testnet", "type": "data_touched" }, { "account_id": "v1.signer-dev.testnet", "type": "data_touched" } ] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "author": "kiln.pool.f863973.m0", "header": { "balance_burnt": "0", "bandwidth_requests": null, "chunk_hash": "CzPafxtJmM1FnRoasKWAVhceJzZzkz9RKUBQQ4kY9V1v", "congestion_info": { "allowed_shard": 1, "buffered_receipts_gas": "0", "delayed_receipts_gas": "0", "receipt_bytes": 0 }, "encoded_length": 308, "encoded_merkle_root": "6z9JwwtVfS5nRKcKeJxgzThRRs2wCNvbH88T3cuARe6W", "gas_limit": 1000000000000000, "gas_used": 0, "height_created": 187310138, "height_included": 187310138, "outcome_root": "11111111111111111111111111111111", "outgoing_receipts_root": "AChfy3dXeJjgD2w5zXkUTFb6w8kg3AYGnyyjsvc7hXLv", "prev_block_hash": "Wj6B3RTv73EWDNbSammRDeA9315RaPyRrJYmiP4nG4X", "prev_state_root": "cRMk2zd2bWC1oBfGowgMTpqW9L5SNG2FeE72yT1wpQA", "rent_paid": "0", "shard_id": 0, "signature": "ed25519:L1iCopW8gY5rqwfuZT8Y3bHHXvuvWT87X9rwdY6LmFi8LGZdMhj2CkQCXLGrzdfYXD8B54wPTM9TqJAHcKfFDyW", "tx_root": "CMwUsP8q4DTBUYxXm12jVwC8xTD8L1T1n3jdKLQVh6bm", "validator_proposals": [], "validator_reward": "0" }, "receipts": [], "transactions": [ { "actions": [ { "FunctionCall": { "args": "eyJyZWNvcmRfaWQiOjEsInJlY29yZCI6IkhlbGxvLCBOZWFyIFByb3RvY29sISJ9", "deposit": "0", "gas": 50000000000000, "method_name": "write_record" } } ], "hash": "J3KbUXF9YPu2eGnbDCACxGvmMDZMdP7acGYhVLHGu9y2", "nonce": 187309654000001, "priority_fee": 0, "public_key": "ed25519:EddTahJwZpJjYPPmat7DBm1m2vdrFBzVv7e3T4hzkENd", "receiver_id": "contract.rpc-examples.testnet", "signature": "ed25519:3opUQgg5eNQmE2LJ8zJiitBAVLDFR3svk8LC5VtVGorQuq8jWLocKAt7B4xb6n7DhH8zSVCWcRRrmVL9f1wHiVXa", "signer_id": "account.rpc-examples.testnet" } ] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Supported Networks
While you can sign transactions for any network using Eddsa or Ecdsa keys, each chain signs transactions differently. Our example [implementation](./chain-signatures/implementation) shows you how to sign transactions for: Bitcoin, Solana, Cosmos, XRP, Aptos, Sui and EVM networks (Ethereum, Base, BNB Chain, Avalanche, Polygon, Arbitrum, and more).### Derivation Paths: One Account, Multiple Chains Chain Signatures link NEAR accounts to addresses in other blockchain using [Additive Key Derivation](https://eprint.iacr.org/2021/1330) (a simple mechanism for deriving many subkeys from a single master key). These keys are generated using `derivation paths` (or `paths` for short). A `derivation path` is simply a string (e.g. `ethereum-1`, `ethereum-2`, etc) that in conjunction with the NEAR account derives a unique address on the target blockchain. For example, we can derive multiple Ethereum addresses from `example.near` by using different paths: 1. `example.near` + `ethereum-1` = `0x1b48b83a308ea4beb845db088180dc3389f8aa3b` 2. `example.near` + `ethereum-2` = `0x99c5d3025dc736541f2d97c3ef3c90de4d221315` 3. `example.near` + `...` = `0x...` It is important to note that this allows us to discover the **public address** of the foreign account that we can control. To actually control the foreign account, we need to request signatures from the MPC service. :::tip In practice, the external address is deterministically derived using the NEAR address (`example.near`), the path (`ethereum-1`) and the MPC service's public key :::
### Multichain Smart Contract A deployed multichain smart contract ([v1.signer](https://nearblocks.io/address/v1.signer)) is used to request signatures for transactions on other blockchains. This contract has [a `sign` method](https://github.com/near/mpc/blob/01f33ed0a2a2c4c24ef49a2f36df3b20aa400816/libs/chain-signatures/contract/src/lib.rs#L242) that takes these three parameters: 1. The `payload` (transaction or transaction hash) to be signed for the target blockchain. 2. The `path` that identifies the account to be used to sign the transaction. 3. The `domain_id` as an integer that identifies the signature scheme to be used for generating the signature. Currently this can be `0` for Secp256k1 or `1` for Ed25519. For example, a user could request a signature to `send 0.1 ETH to 0x060f1...` **(transaction)** using the `ethereum-1` account **(path)** with `0` (Secp256k1) as **domain ID**. After a request is made, the `sign` method will [yield execution](/blog/yield-resume) waiting while the [MPC signing service](#multi-party-computation-service) signs the transaction. Once the signature is ready, the contract resumes computation and returns it to the user. This signature is a valid signed transaction that can be readily sent to the target blockchain to be executed. :::tip The `sign` method currently supports both Secp256k1 and Ed25519 signature schemes which enables signing transactions for the vast majority of the well-known blockchains including Bitcoin, Ethereum, Solana, BNB chain, Ton, or Stellar. In the future, the MPC participants can add more signature schemes via the `vote_add_domains` method. :::
### Multi-Party Computation Service The essence of Multi-Party Computation (MPC) is to enable independent parties to perform shared computations on private information without revealing secrets to each other. In practice, this system can be used with blockchain platforms to safely sign a transaction on behalf of a user without ever having to expose a private key. NEAR's MPC service is comprised of several independent nodes, **none of which can sign by itself**, but instead create **signature-shares** that are **aggregated through multiple rounds** to **jointly** sign a transaction. Currently, the service is composed of 8 independent nodes. However the set of participating nodes can be extended with the `vote_new_parameters` method of the `v1.signer` smart contract if enough active nodes vote for it. This service continuously listens for signature requests (i.e. users calling the `sign` method on the `v1.signer` smart contract) and when a call is detected the MPC service: 1. Asks its nodes to jointly derive a signature for the `payload` using the account identified by the `path` 2. Once complete, call the `v1.signer` contract to store the resulting `Signature` :::info A Custom MPC Service Generally, MPC signing services work by sharing a master key, which needs to be re-created each time a node joins or leaves. NEAR's MPC service allows for nodes to safely join and leave, without needing to re-derive a master key. ::: :::tip Want to learn more about the mathematics that enable MPC? [**Check this awesome article**](https://www.zellic.io/blog/mpc-from-scratch/). ::: --- ## Concluding Remarks Chain Signatures are a powerful tool that allows NEAR accounts to control accounts on other blockchains. This is a fundamental step towards enabling true ownership of cross-chain data and assets. For the user, the process is made completely **on chain**, since they only need to make a call to a smart contract and wait for the response. Thanks to `derivation paths`, a single NEAR account can control **multiple accounts** on different blockchains, and thanks to the MPC service, the user can be sure that **nobody but themselves** can request signatures for those accounts. --- # Source: https://docs.near.org/smart-contracts/security/checklist.md --- id: checklist title: ✅ Checklist description: "Best practices for security and common safeguards." --- Once you finished developing your smart contract please go through the following list in order to ensure everything is safe for the end user. :::info Check our [security articles](./welcome.md) to understand how to improve the security of your contract. ::: --- ## Anatomy 1. All private methods are decorated as `private`. ## Environment 2. `predecessor` and `signer` are used correctly through the entire contract. ## Storage 3. Each time the state grows it is ensured that there is enough balance to cover it 4. All collections (i.e. Vector, Map, Tree, etc) have a unique id 5. Check for underflow and overflow!. In rust, you can do this by simply adding the `overflow-checks = true` flag in your `Cargo.toml`. ## Actions 6. When sending money, you leave enough in the contract to cover the storage cost 7. If you are tracking user's fund, you **deduct them before** sending them back to the user. ## Callbacks 8. All private callbacks are marked as `private` 9. All cross-contract calls have a callback 10. All callbacks check for errors and roll back the state if necessary 11. All callbacks return money to the `predecessor` if necessary 12. Callbacks are free of `panic!` 13. All the callbacks are given enough GAS to execute entirely 14. The contract is not left in an exploitable state between a cross-contract call and its callback --- # Source: https://docs.near.org/tools/clear-state.md --- id: clear-state title: Clear Contract State description: "Clean up a contract's state." --- This simple command-line tool allows you to clean up the state of a NEAR account without deleting it. ## How it works This JavaScript CLI tool deploys a [`state-cleanup.wasm`](https://github.com/near-examples/near-clear-state/blob/main/contractWasm/state_cleanup.wasm) contract replacing the current one, and then uses the new contract to clean up the account's state, so you can easily redeploy a new contract or use the account in any other way. Here's a quick snippet of the contract's main code: ``` let input = env::input().unwrap(); let args: Args = serde_json::from_slice(&input).unwrap(); for key in args.keys.iter() { env::storage_remove(&base64::decode(key).unwrap()); } ``` :::tip Want to check the smart contract? Check the GitHub repository and learn more about the [State Cleanup tool](https://github.com/near-examples/near-clear-state). ::: --- ## How to use ### Requirements You'll need [NEAR CLI](cli.md). You can install it by running: ```bash npm install -g near-cli-rs@latest ``` ### Clear your Account State To clear your Account state, follow these steps. #### 1. Login with NEAR CLI This will store a full access key locally on your machine. Select the account you wish to clear the state. ```bash near login ``` :::warning Legacy keychain Be sure to select `Store the access key in my legacy keychain (compatible with the old near CLI)` to store the access key on the legacy keychain. ::: #### 2. Clone the `near-clear-state` Repository ```sh git clone https://github.com/near-examples/near-clear-state.git ``` #### 3. Install dependencies ```bash cd near-clear-state && npm i ``` #### 4. Clear your State ```bash npx near-clear-state clear-state --account
| `https://github.com/near-examples/coin-flip-examples.git` |
If you choose Gitpod, a new browser window will open automatically with the code. Give it a minute, and the front-end will pop up (ensure the pop-up window is not blocked).
If you are running the app locally, you should build and deploy a contract (JavaScript or Rust version) and a client manually.
---
## Interacting With the Counter
Go ahead and log in with your NEAR account. If you don't have one, you can create one on the fly. Once logged in, use the `tails` and `heads` buttons to try to guess the next coin flip outcome.
*Frontend of the Game*
---
## Structure of a dApp
Now that you understand what the dApp does, let us take a closer look to its structure:
1. The frontend code lives in the `/frontend` folder.
2. The smart contract code in Rust is in the `/contract-rs` folder.
3. The smart contract code in JavaScript is in the `/contract-ts` folder.
:::note
Both Rust and JavaScript versions of the contract implement the same functionality.
:::
### Contract
The contract presents 2 methods: `flip_coin`, and `points_of`.
### Understanding the Frontend The frontend is a [Next.JS](https://nextjs.org/) project generated by [create-near-app](https://github.com/near/create-near-app). Check `_app.js` and `index.js` to understand how components are displayed and interacting with the contract.
Storage Cost
Your contract needs to lock a portion of their balance proportional to the amount of data they stored in the blockchain. This means that: - If more data is added the **storage increases ↑**, and your contract's **balance decreases ↓**. - If data is deleted the **storage decreases ↓**, and your contract's **balance increases ↑**. Currently, it costs approximately **1 Ⓝ** to store **100kb** of data.Storage Constraints on NEAR
For storing data on-chain it’s important to keep in mind the following: - There is a 4mb limit on how much you can upload at once Let’s say for example, someone wants to put an NFT purely on-chain (rather than IPFS or some other decentralized storage solution) you’ll have almost an unlimited amount of storage but will have to pay 1 $NEAR per 100kb of storage used. Users will be limited to 4MB per contract call upload due to MAX_GAS constraints. The maximum amount of gas one can attach to a given functionCall is 300TGas.Serialization & Storage Example
The array `[1,2,3,4]` will be serialized into the JSON string `"[1,2,3,4]"` in Javascript, and the Borsh byte-stream `[0,0,0,4,1,2,3,4]` in Rust before being storedSerialization & Storage Example
The sdk array `[1,2,3,4]` with prefix `"p"` will be stored as the string `"p"` in the contract's attribute, and create four entries in the contract's storage: `p-0:1`, `p-1:2`...SDK Collections' Features
| Type | Iterable | Clear All Values | Preserves Insertion Order | Range Selection | |----------------|:--------:|:----------------:|:-------------------------:|:---------------:| | `Vector` | ✅ | ✅ | ✅ | ✅ | | `LookupSet` | | | | | | `UnorderedSet` | ✅ | ✅ | | ✅ | | `IterableSet` | ✅ | ✅ | | ✅ | | `LookupMap` | | | | | | `UnorderedMap` | ✅ | ✅ | | ✅ | | `IterableMap` | ✅ | ✅ | | ✅ | | `TreeMap` | ✅ | ✅ | ✅ | ✅ |SDK Collections' Time Complexities
| Type | Access | Insert | Delete | Search | Traverse | Clear | |----------------|:------:|:--------:|:--------:|:--------:|:--------:|:-----:| | `Vector` | O(1) | O(1)\* | O(1)\*\* | O(n) | O(n) | O(n) | | `LookupSet` | O(1) | O(1) | O(1) | O(1) | N/A | N/A | | `UnorderedSet` | O(1) | O(1) | O(1) | O(1) | O(n) | O(n) | | `IterableSet` | O(1) | O(1) | O(1) | O(1) | O(n) | O(n) | | `LookupMap` | O(1) | O(1) | O(1) | O(1) | N/A | N/A | | `IterableMap` | O(1) | O(1) | O(1) | O(1) | O(n) | O(n) | | `TreeMap` | O(1) | O(log n) | O(log n) | O(log n) | O(n) | O(n) | _\* - to insert at the end of the vector using `push_back` (or `push_front` for deque)_ _\*\* - to delete from the end of the vector using `pop` (or `pop_front` for deque), or delete using `swap_remove` which swaps the element with the last element of the vector and then removes it._### Instantiation All structures need to be initialized using a **unique `prefix`**, which will be used to index the collection's values in the account's state
### Vector Implements a [vector/array](https://en.wikipedia.org/wiki/Array_data_structure) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
### LookupMap Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
### UnorderedMap / IterableMap Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
### LookupSet Implements a [set](https://en.wikipedia.org/wiki/Set_(abstract_data_type)) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
### UnorderedSet / IterableSet Implements a [map/dictionary](https://en.wikipedia.org/wiki/Associative_array) which persists in the contract's storage. Please refer to the Rust and JS SDK's for a full reference on their interfaces.
### Tree An ordered equivalent of Map. The underlying implementation is based on an [AVL](https://en.wikipedia.org/wiki/AVL_tree). You should use this structure when you need to: have a consistent order, or access the min/max keys.
Example response:
```json { "jsonrpc": "2.0", "result": { "amount": "999788200694421800000000", "block_hash": "56xEo2LorUFVNbkFhCncFSWNiobdp1kzm14nZ47b5JVW", "block_height": 187440904, "code_hash": "11111111111111111111111111111111", "locked": "0", "storage_paid_at": 0, "storage_usage": 410 }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "8woqfx6kyjgfgU1S2L6Kur27h5jpBtDTmG8vQ8vpAUut", "changes": [ { "cause": { "receipt_hash": "FseKd4rmjPSAuEz9zh9b5PfUS4jJV4rB6XkeHwVkyXkk", "type": "receipt_processing" }, "change": { "account_id": "contract.rpc-examples.testnet", "amount": "4999184472524996100000000", "code_hash": "GVvBFWDPNmomMwXH4LvQW2cRaZJ8N6gxsdBhbJ8ReVJf", "locked": "0", "storage_paid_at": 0, "storage_usage": 81621 }, "type": "account_update" }, { "cause": { "receipt_hash": "FseKd4rmjPSAuEz9zh9b5PfUS4jJV4rB6XkeHwVkyXkk", "type": "action_receipt_gas_reward" }, "change": { "account_id": "contract.rpc-examples.testnet", "amount": "4999212038891301300000000", "code_hash": "GVvBFWDPNmomMwXH4LvQW2cRaZJ8N6gxsdBhbJ8ReVJf", "locked": "0", "storage_paid_at": 0, "storage_usage": 81621 }, "type": "account_update" } ] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "bxucHpnP8VsiB3pLvA7DpBwri9x1DCZxVfBNkrdWbqn", "block_height": 187441984, "code_base64": "AGFzbQEAAAABugEbYAJ/fwF/YAN/f38Bf2ACf38AYAN/...", "hash": "GVvBFWDPNmomMwXH4LvQW2cRaZJ8N6gxsdBhbJ8ReVJf" }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "GN5R7S8mMTEkUT1njWu9jARV29G7izVDjdSNs976BJVw", "block_height": 187442491, "values": [ { "key": "U1RBVEU=", "value": "HQAAAEdyZWV0aW5ncyBmcm9tIE5FQVIgUHJvdG9jb2whAQAAAHI=" }, { "key": "cgEAAAAAAAAA", "value": "FQAAAEhlbGxvLCBOZWFyIFByb3RvY29sIQ==" } ] }, "id": "dontcare" } ``` **Note**: Currently, the response includes a `proof` field directly in the `result`, and a `proof` fields on each element of the `values` list. In the future, the `result.proof` will be included only if the result is **not empty**, and the `proof` field will be removed from all `values`. When parsing the result, you should accept objects with or without these fields set.Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "8woqfx6kyjgfgU1S2L6Kur27h5jpBtDTmG8vQ8vpAUut", "changes": [ { "cause": { "receipt_hash": "FseKd4rmjPSAuEz9zh9b5PfUS4jJV4rB6XkeHwVkyXkk", "type": "receipt_processing" }, "change": { "account_id": "contract.rpc-examples.testnet", "key_base64": "U1RBVEU=", "value_base64": "HQAAAEdyZWV0aW5ncyBmcm9tIE5FQVIgUHJvdG9jb2whAQAAAHI=" }, "type": "data_update" }, { "cause": { "receipt_hash": "FseKd4rmjPSAuEz9zh9b5PfUS4jJV4rB6XkeHwVkyXkk", "type": "receipt_processing" }, "change": { "account_id": "contract.rpc-examples.testnet", "key_base64": "cgEAAAAAAAAA", "value_base64": "FQAAAEhlbGxvLCBOZWFyIFByb3RvY29sIQ==" }, "type": "data_update" } ] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "D1ZY3y51Z2v5tXq2nZPmXHgA3zZsPBzbtwHXjCvAEuLV", "changes": [ { "cause": { "receipt_hash": "AR4cxtxc52WfnZcGEZHmPfQ1Dk3vQNb7vjSyicykfJWZ", "type": "receipt_processing" }, "change": { "account_id": "contract.rpc-examples.testnet", "code_base64": "AGFzbQEAAAABugEbYAJ/fwF/YAN/f38Bf2ACf38AYAN/..." }, "type": "contract_code_update" } ] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "GTZdXfNmnL6TkJFdBeVMHCadgLuKChVfRNCSVsEQoJ7L", "block_height": 187444191, "logs": [], "result": [ 34, 71, 114, 101, 101, 116, 105, 110, 103, 115, 32, 102, 114, 111, 109, 32, 78, 69, 65, 82, 32, 80, 114, 111, 116, 111, 99, 111, 108, 33, 34 ] }, "id": "dontcare" } ``` **Note**: `[34, 71, ..., 33, 34]` is an array of bytes, to be specific it is an ASCII code of `"Greetings from NEAR Protocol!"`. `near-sdk-rs` and `near-sdk-js` return JSON-serialized results.
Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "block_hash": "8Gp8x1ZcanL3C2ris9rgk1nY8v6MuickLWeM6Gj2jGKs", "block_height": 187445443, "logs": [], "result": [ 34, 72, 101, 108, 108, 111, 44, 32, 78, 101, 97, 114, 32, 80, 114, 111, 116, 111, 99, 111, 108, 33, 34 ] }, "id": "dontcare" } ``` **Note**: `[34, 72, ..., 108, 33, 34]` is an array of bytes, to be specific it is an ASCII code of `"Hello, Near Protocol!"`. `near-sdk-rs` and `near-sdk-js` return JSON-serialized results.
Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.### Running the Frontend To start the frontend you will need to install the dependencies and start the server. ```bash cd frontend yarn yarn dev ``` Go ahead and login with your NEAR account. If you don't have one, you will be able to create one in the moment. Once logged in, use the `+` and `-` buttons to increase and decrease the counter. Then, use the Gameboy buttons to reset it and make the counter blink an eye!  _Frontend of the Counter_
### Understanding the Frontend The frontend is a [Next.JS](https://nextjs.org/) project generated by [create-near-app](https://github.com/near/create-near-app). Check `_app.js` and `index.js` to understand how components are displayed and interacting with the contract.
This global counter lives in the NEAR blockchain!
{!signedAccountId &&You'll need to sign in to interact with the counter:
= 0 ? 'smile' : 'cry'}`}>
{number}
### Deploying the Contract to the NEAR network In order to deploy the contract you will need to create a NEAR account.
### CLI: Interacting with the Contract To interact with the contract through the console, you can use the following commands. #### Get the current number of the counter
#### Increment the counter
#### Decrement the counter
#### Reset the counter to zero
The last bid was {lastBid} $NEAR
Made by {highestBidder}
Refresh page in {lastUpdate}
{!highestBid ? }
{!auctionEndTime ? }
{!highestBidder ? }
### AWS S3 Credentials To be able to get objects from the AWS S3 bucket you need to provide your AWS credentials. AWS default profile configuration with aws configure looks similar to the following: ``` ~/.aws/credentials ``` ``` [default] aws_access_key_id=
Concatenating Promises
✅ You can concatenate promises: `P1.then(P2).then(P3)`: `P1` executes, then `P2` executes with the result of `P1`, then `P3` executes with the result of `P2` ✅ You can join promises: `(P1.and(P2)).then(P3)`: `P1` and `P2` execute in parallel, after they finish `P3` will execute and have access to **both their results** ⛔ You cannot **return** a joint promise without a callback: `return P1.and(P2)` is invalid, you need to add a `.then()` ⛔ You cannot join promises within a `then`: `P1.then(P2.join([P3]))` is invalid ⛔ You cannot use a `then` within a `then`: `P1.then(P2.then(P3))` is invalid### What happens if the function I call fails? If the external function fails (i.e. it panics), then your callback will be **executed anyway**. Here you need to **manually rollback** any changes made in your contract during the original call. Particularly: 1. **Refund the predecessor** if needed: If the contract attached NEAR to the call, the funds are now back in **the contract's account** 2. **Revert any state changes**: If the original function made any state changes (i.e. changed or stored data), you need to manually roll them back. **They won't revert automatically** :::warning If your original function finishes correctly then the callback executes **even if the external function panics**. Your state will **not** rollback automatically, and $NEAR will **not** be returned to the signer automatically. Always make sure to check in the callback if the external function failed, and manually rollback any operation if necessary. ::: --- ## Calling Multiple Functions on the Same Contract You can call multiple functions in the same external contract, which is known as a **batch call**. An important property of batch calls is that they **act as a unit**: they execute in the same [receipt](/protocol/transaction-execution#receipts--finality), and if **any function fails**, then they **all get reverted**.
### Using Global Contract You can deploy a new DAO using our global contract - a pre-deployed [a Sputnik DAO contract](https://github.com/near-daos/sputnik-dao-contract/tree/main/sputnikdao2) that you can reuse. [Global contracts](../smart-contracts/global-contracts.md) are deployed once and can be reused by any account without incurring high storage costs.
### Voting policy Currently, DAOs support two different types of [voting policies](https://github.com/near-daos/sputnik-dao-contract#voting-policy): `TokenWeight`, and `RoleWeight`. When the vote policy is `TokenWeight`, the council votes using [tokens](./ft/ft.md). The weigh of a vote is the proportion of tokens used for voting over the token's total supply. When the vote policy is `RoleWeight(role)`, the vote weigh is computed as "one over the total number of people with the role".
Voting Threshold
Both voting policies further include a `threshold` for passing a proposal, which can be a ratio or a fixed number. The ratio indicates that you need a proportion of people/tokens to approve the proposal (e.g. half the people need to vote, and to vote positively). A fixed number indicated that you need a specific number of votes/tokens to pass the proposal (e.g. 3 people/tokens are enough to approve the proposal).Example response
```bash [ 'ref-finance.sputnik-dao.near' 'gaming-dao.sputnik-dao.near', ... ] ```
Example response
```bash [ 'ref-finance.sputnik-dao.near' 'gaming-dao.sputnik-dao.near', ... ] ```Example response
```bash [ { id: 9262, proposer: 'pasternag.near', description: 'NEAR, a top non-EVM blockchain, has gone live on Router’s Testnet Mandara. With Router Nitro, our flagship dApp, users in the NEAR ecosystem can now transfer test tokens to and from NEAR onto other supported chains. $$$$https://twitter.com/routerprotocol/status/1727732303491961232', kind: { Transfer: { token_id: '', receiver_id: 'pasternag.near', amount: '500000000000000000000000', msg: null } }, status: 'Approved', vote_counts: { council: [ 1, 0, 0 ] }, votes: { 'brzk-93444.near': 'Approve' }, submission_time: '1700828277659425683' }, { id: 9263, proposer: 'fittedn.near', description: 'How to deploy BOS component$$$$https://twitter.com/BitkubAcademy/status/1728003163318563025?t=PiN6pwS380T1N4JuQXSONA&s=19', kind: { Transfer: { token_id: '', receiver_id: 'fittedn.near', amount: '500000000000000000000000', msg: null } }, status: 'InProgress', vote_counts: { 'Whitelisted Members': [ 1, 0, 0 ] }, votes: { 'trendheo.near': 'Approve' }, submission_time: '1700832601849419123' } ] ```
Example response
```bash [ { "id": 9262, "proposer": "pasternag.near", "description": "NEAR, a top non-EVM blockchain, has gone live on Router’s Testnet Mandara. With Router Nitro, our flagship dApp, users in the NEAR ecosystem can now transfer test tokens to and from NEAR onto other supported chains. $$$$https://twitter.com/routerprotocol/status/1727732303491961232", "kind": { "Transfer": { "token_id": "", "receiver_id": "pasternag.near", "amount": "500000000000000000000000", "msg": null } }, "status": "Approved", "vote_counts": { "council": [1, 0, 0] }, "votes": { "brzk-93444.near": "Approve" }, "submission_time": "1700828277659425683" }, { "id": 9263, "proposer": "fittedn.near", "description": "How to deploy BOS component$$$$https://twitter.com/BitkubAcademy/status/1728003163318563025?t=PiN6pwS380T1N4JuQXSONA&s=19", "kind": { "Transfer": { "token_id": "", "receiver_id": "fittedn.near", "amount": "500000000000000000000000", "msg": null } }, "status": "Expired", "vote_counts": { "Whitelisted Members": [2, 0, 0] }, "votes": { "trendheo.near": "Approve", "vikash.near": "Approve" }, "submission_time": "1700832601849419123" } ] ```#### Examples ```bash # Query user's FTs curl https://api.fastnear.com/v1/account/root.near/ft # Query user's NFTs curl https://api.fastnear.com/v1/account/root.near/nft # Query all user's assets curl https://api.fastnear.com/v1/account/root.near/full ``` --- ## NearBlocks API [NearBlocks API](https://api.nearblocks.io/api-docs/) provides an endpoint to query actions that happened on a NEAR account, possible use cases include: - Query an account balance - Query all function calls to specific contract - Get total NEAR supply and circulating supply - Query the number of total transactions on NEAR
#### Examples ```bash # All the transactions where somebody called `create_drop` on Keypom curl -X GET "https://api.nearblocks.io/v1/account/v2.keypom.near/txns?method=create_drop" # All the times that `gagdiez.near` called `create_drop` on Keypom curl -X GET "https://api.nearblocks.io/v1/account/v2.keypom.near/txns?method=create_drop&from=gagdiez.near" ``` --- ## Pikespeak API The [Pikespeak API](https://doc.pikespeak.ai/) allows you to fetch blockchain events and aggregated analytics on wallets, validators, delegators, money transfers, dApps activity, and more. Use case includes: - Querying account balances - Querying the most active wallets - Querying historic account events _To access the Pikespeak API you'll need to [register and create an account](https://pikespeak.ai/plans). Once you're registered, under the [`My Account`](https://pikespeak.ai/myaccount) page you can get your API key_
#### Examples ```sh # Check the account balance for `root.near`: curl -X GET https://api.pikespeak.ai/account/balance/root.near -H "accept: application/json" -H "x-api-key: YOUR-PIKESPEAK-API-KEY" # Most active wallets NEAR senders curl -X GET https://api.pikespeak.ai/hot-wallets/near -H "accept: application/json" -H "x-api-key: YOUR-PIKESPEAK-API-KEY" # Get historic account events for `keypom.near` curl -X GET https://api.pikespeak.ai/event-historic/keypom.near -H "accept: application/json" -H "x-api-key: YOUR-PIKESPEAK-API-KEY" ``` --- ## The Graph [The Graph](https://thegraph.com/docs/en/cookbook/near/) gives developers tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. [Graph Node](https://github.com/graphprotocol/graph-node) is now able to process NEAR events, which means that NEAR developers can now build subgraphs to index their smart contracts. --- ## SubQuery [SubQuery](https://academy.subquery.network/quickstart/quickstart_chains/near.html): A fast, flexible, and reliable open-source data indexer that provides you with custom APIs for your web3 project across NEAR and many other chains --- # Source: https://docs.near.org/chain-abstraction/data-availability.md --- id: data-availability title: Rollup Data Availability description: "Learn about NEAR's Data Availability layer for rollups, including blob store contracts, light clients, RPC nodes, and integrations with L2 solutions like Polygon CDK and Optimism." --- Every monolithic blockchain has a data availability layer. NEAR's Data Availability (DA) represents a pioneering initiative to modularize the data availability layer from the NEAR blockchain to make it available as a roll-up solution for builders on other chains. This infrastructure consists of a smart contract, a light client, and a Remote Procedure Call (RPC) node. The smart contract is designed to accept blob data, which is then processed through NEAR's consensus. The RPC node functions as the serving node, where users can transmit their data. Lastly, the light client operates as a node that rollups can verify to ensure the availability of data. - [Blob Store Contract](#blob-store-contract): A contract that provides the store for arbitrary DA blobs. - [Light Client](#light-client): A trustless off-chain light client for NEAR with DA-enabled features. - [RPC Client](#da-rpc): The defacto client for submitting data blobs to NEAR. - [Integrations](#integrations): Proof of concept works for integrating with L2 rollups. NEAR DA is notably inexpensive due to several key factors: - NEAR offers a substantial amount of block space per shard, ensuring efficient utilization. - NEAR optimizes this space by avoiding unnecessary cryptographic bloat, ensuring that each 4MB allocated equals precisely 4MB of usable data. - NEAR's scalability is unmatched, as it can readily reshard and scale in response to increasing demand, unlike competitors who would need to resort to constructing rollups or sidechains, thus maintaining a consistently ample and cost-effective data availability solution. :::tip For the latest information, please check the [Near DA](https://github.com/near/rollup-data-availability/) repository. ::: --- ## System Context This outlines the system components that we build and how it interacts with external components. Red lines denote external flow of commitments. White lines denote flow of blob data. :::note `Fisherman` is just an example how a rollup can work with the light client in the initial stage of DA, until we implement a more non-interactive approach, such as KZG. ::: ```mermaid C4Context title NEAR Data Availability System Context Enterprise_Boundary(b1, "Ethereum") { System_Ext(SystemEth, "Ethereum") System_Boundary(b2, "Rollup") { System_Ext(SystemRollup, "Rollup", "Derives blocks, execute transactions, posts commitments & sequence data") System(SystemNearDa, "NEAR DA Client", "Submits/Gets blob data, creates commitments") } BiRel(SystemRollup, SystemEth, "Posts sequences, proofs of execution, DA frame references") BiRel(SystemRollup, SystemNearDa, "Post batches, retrieves commitments") Rel(fisherman, SystemEth, "Looks for commitments, posts results") } Enterprise_Boundary(b0, "NEAR") { System(SystemLc, "Light Client", "Syncs headers, provides inclusion proofs") System(SystemNear, "NEAR Protocol", "NEAR validators, archival nodes") Rel(SystemLc, SystemNear, "Syncs headers") Rel(SystemNearDa, SystemNear, "Submits/Gets blob") %% This doesn't exist yet %% System(SystemDas, "Data Availability Sampling", "Data redundancy, retrieval, sample responses") %% BiRel(SystemDas, SystemLc, "Commitments") } Person_Ext(fisherman, "Fisherman") Rel(fisherman, SystemLc, "Requests inclusion proofs, validates inclusion proofs") UpdateRelStyle(fisherman, SystemEth, $offsetY="-10" $lineColor="red") UpdateRelStyle(fisherman, SystemLc, $offsetY="-10", $lineColor="red") UpdateRelStyle(SystemRollup, SystemEth, $offsetY="-30", $lineColor="white") UpdateElementStyle(fisherman, $bgColor="grey", $borderColor="red") UpdateRelStyle(SystemRollup, SystemNearDa, $offsetX="-200", $lineColor="white", $textColor="white") UpdateRelStyle(SystemNearDa, SystemNear, $textColor="white", $lineColor="white", $offsetY="10") UpdateRelStyle(SystemNearLc, SystemNear, $offsetX="30") ``` --- ## [Blob Store Contract](https://github.com/near/rollup-data-availability/tree/main/contracts/blob-store) The [blob store contract](https://github.com/near/rollup-data-availability/tree/main/contracts/blob-store) provides the store for arbitrary DA blobs. In practice, these "blobs" are sequencing data from rollups, but they can be any data. NEAR blockchain state storage is pretty cheap. At the time of writing, 100KiB is a flat fee of 1NEAR. To limit the costs of NEAR storage even more, we don't store the blob data in the blockchain state. It works by taking advantage of NEAR consensus around receipts. When a chunk producer processes a receipt, there is consensus around the receipt. However, once the chunk has been processed and included in the block, the receipt is no longer required for consensus and can be pruned. The pruning time is at least 3 NEAR epochs, where each epoch is 12 Hours; in practice, this is around five epochs. Once the receipt has been pruned, it is the responsibility of archival nodes to retain the transaction data, and we can even get the data from indexers. We can validate that the blob was retrieved from ecosystem actors in the format submitted by checking the blob commitment. The blob commitment currently needs to be more efficient and will be improved, but it benefits us because anybody can build this with limited expertise and tooling. It is created by taking a blob, chunking it into 256-byte pieces, and creating a Merkle tree, where each leaf is a Sha-256 hash of the shard. The root of the Merkle tree is the blob commitment, which is provided as [transaction_id ++ commitment] to the L1 contract, which is 64 bytes. What this means: - Consensus is provided around the submission of a blob by NEAR validators - The function input data is stored by full nodes for at least three days - Archival nodes can store the data for longer - We don't occupy consensus with more data than needs to be - Indexers can also be used, and this Data is currently indexed by all significant explorers in NEAR - The commitment is available for a long time, and the commitment is straightforward to create --- ## [Light Client](https://github.com/near/rollup-data-availability/tree/main/) A trustless off-chain light client for NEAR with DA-enabled features, Such as KZG commitments, Reed-Solomon erasure coding & storage connectors. The light client provides easy access to transaction and receipt inclusion proofs within a block or chunk. This is useful for checking any dubious blobs which may not have been submitted or validating that a blob has been submitted to NEAR. A blob submission can be verified by: - Taking the NEAR transaction ID from Ethereum for the blob commitment. - Ask the light client for an inclusion proof for the transaction ID or the receipt ID if you're feeling specific; this will give you a Merkle inclusion proof for the transaction/receipt. - Once you have the inclusion proof, you can ask the light client to verify the proof for you, or advanced users can manually verify it themselves. - Armed with this knowledge, rollup providers can have advanced integration with light clients and build proving systems around it. In the future, we will provide extensions to light clients such that non-interactive proofs can be supplied for blob commitments and other data availability features. It's also possible that the light client may be on-chain for the header syncing and inclusion proof verification, but this is a low priority right now. --- ## DA RPC This client is the defacto client for submitting blobs to NEAR. These crates allow a client to interact with the blob store. It can be treated as a "black box", where blobs go in, and `[transaction_id ++ commitment]` emerges. There are multiple versions: - The [`da-rpc` crate](https://github.com/near/rollup-data-availability/tree/main/crates/da-rpc) is the rust client, which anyone can use if they prefer rust in their application. The responsibility of this client is to provide a simple interface for interacting with NEAR DA. - The [`da-rpc-sys` crate](https://github.com/near/rollup-data-availability/tree/main/crates/da-rpc-sys) is the FFI client binding for use by non-rust applications. This calls through to `da-rpc` to interact with the blob store, with some additional black box functionality for dealing with pointers wrangling and such. - The [`da-rpc-go` package](https://github.com/near/rollup-data-availability/tree/main/gopkg/da-rpc) is the go client bindings for use by non-rust applications, and this calls through to `da-rpc-sys`, which provides another application-level layer for easy interaction with the bindings. :::info See also [the diagram](https://github.com/near/near-cli-rs/blob/main/docs/da_rpc_client.md) ::: --- ## Integrations We have developed some proof of concept works for integrating with L2 rollups: - [CDK Stack](https://github.com/firatNEAR/cdk-validium-node/tree/near): We have integrated with the Polygon CDK stack. Using the Sequence Sender for submissions to NEAR. - [Optimism](https://github.com/near/optimism): We have integrated with the Optimism OP stack. Using the `Batcher` for submissions to NEAR and the proposer for submitting NEAR commitment data to Ethereum. - [Arbitrum Nitro](https://github.com/near/nitro): We have integrated a small plugin into the DAC daserver. This is much like our http sidecar and provides a very modular integration into NEAR DA whilst supporting arbitrum DACs. :::info In the future, the `Arbitrum Nitro` integration will likely be the easiest way to support NEAR DA as it acts as an independent sidecar which can be scaled as needed. This also means that the DAC can opt-in and out of NEAR DA, lowering their infrastructure burden. With this approach, the DAC committee members just need to have a "dumb" signing service, with the store backed by NEAR. ::: --- # Source: https://docs.near.org/data-infrastructure/data-services.md --- id: data-services title: Existing Services description: "Indexers are constantly listening for transactions and storing them so they can be easily queried." --- Data Services are constantly listening to the blockchain, processing the transactions and storing them in a database that can be easily queried. You can use them to access blockchain data efficiently: - [BigQuery](./big-query.md): Blockchain data indexing in NEAR Public Lakehouse is for anyone wanting to understand blockchain data. - [NEAR Lake Framework](./near-lake-framework.md): a companion library to NEAR Lake. It allows you to build your own indexer that watches a stream of blocks **from a NEAR Lake data source** and allows you to **create your own logic to process that data**. Keep in mind this is **the one you want to use for future projects**, instead of the Indexer Framework. Read [why it is better](/data-infrastructure/near-lake-framework#comparison-with-near-indexer-framework). - [Indexer.xyz Multichain Indexer](https://indexer.xyz/): Indexer.xyz is an application layer that you can build your NFT or DeFi applications entirely on top of. In addition to raw transaction indexing, Indexer.xyz provides you with a standardized GraphQL API layer to easily tap into transactions across contracts and chains. - [The Graph](https://thegraph.com/docs/en/cookbook/near/): development tools to process blockchain events and make the resulting data easily available via a GraphQL API, known individually as a subgraph. [Graph Node](https://github.com/graphprotocol/graph-node) is able to process NEAR events, which means that NEAR developers can build subgraphs to index their smart contracts. - [GetBlock](https://getblock.io/explorers/near/blocks/): developer tools offering a simple and reliable API access to multiple blockchains including NEAR Protocol. - [Community APIs](./data-api.md): build precise & reliable dApps with our community's APIs. - [Covalent](https://www.covalenthq.com/docs/networks/aurora/): for [Aurora EVM](https://aurora.dev/) indexing, Covalent provides a unified API bringing visibility to billions of Web3 data points. - [NEAR Indexer Framework](https://github.com/near/nearcore/tree/master/chain/indexer): a micro-framework providing you with a "live" stream of blocks. Useful to handle on-chain real-time `events`. - [SubQuery](https://academy.subquery.network/quickstart/quickstart_chains/near.html): is an end to end multi-blockchain indexing solution that provides NEAR developers with fast, flexible, universal, open source and decentralized APIs for web3 projects. The [NEAR starter project](https://github.com/subquery/near-subql-starter/tree/main/Near/near-starter) provides a template for developers to get up and running within minutes. --- # Source: https://docs.near.org/web3-apps/concepts/data-types.md --- id: data-types title: Handling NEAR Types description: "Learn how to handle common data types when interacting with NEAR" --- When calling methods in a contract or receiving results from them, you will need to encode/decode parameters correctly. For this, it is important to know how the contracts encode timestamps, balances, and gas. :::info Searching for Smart Contract Data Types? Check the [Smart Contract Data Types](../../smart-contracts/anatomy/types.md) section for more information on how to handle data types within smart contracts. ::: --- ## Time The block timestamp in a smart contract is encoded using nanoseconds (i.e. 19 digits: `1655373910837593990`).
### Setting Validator Whitelist Account Before you can add validators, you first need to set the validator whitelist account. This account acts as a single source of truth for which validators are allowed to be used by the contract. The validator whitelist account must implement the following interface that allows the contract to verify if a given validator is approved. ```rust #[ext_contract(ext_whitelist)] pub trait ExtWhitelist { fn is_whitelisted(&self, staking_pool_account_id: AccountId) -> bool; } ``` To update the validator whitelist account, please run the following command: ```bash near contract call-function as-transaction
### Adding Validators After the whitelist account is in place, you can register a list of validators that the contract will delegate tokens to, along with their weights. Each weight defines a proportion of how much of the total stake should go to a particular validator compared to the others. To add validators, please run the following comand: ```bash near contract call-function as-transaction
### Storage Deposit Before you can hold or receive any liquid tokens, your account needs to be registered in the contract’s storage. You only need to do this once, and the amount is fully refundable if you ever unregister your account. To register the account, run the following command: ```bash near contract call-function as-transaction
### Check Balance To check how many liquid tokens (e.g., `tNEAR`) you own, run the following command: ```bash near contract call-function as-read-only
### Check Total Supply To check the total supply of the liquid token (e.g., `tNEAR`), run the following command: ```bash near contract call-function as-read-only
### Transfer Tokens To transfer tokens to another account directly, run the following command: ```bash near contract call-function as-transaction
### Check Token Price While most methods follow the NEP-141 standard, the liquid staking contract also provides an additional helper method called `ft_price`. This method isn’t part of the standard itself — it’s implemented specifically for this contract to make it easier to check the current exchange rate between the liquid token and `NEAR`, since the price of the token is determined by the formula: `exchange_rate = total_staked_near / total_liquid_token_supply` To query the current price, run the following command: ```bash near contract call-function as-read-only
### 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
### Change methods 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
What is a Phala Cloud
Phala Cloud is a cloud service that supports hosting applications in a TEE. It makes it easy to run an agent in TEE.Example response
```json { "token_contract_id": "token.v2.ref-finance.near", "price": "0.08153090" } ```
Examples Response
```bash 'wrap.near', 'usdt.tether-token.near', 'berryclub.ek.near', 'farm.berryclub.ek.near', 'token.v2.ref-finance.near', 'token.paras.near', 'marmaj.tkn.near', 'meta-pool.near', ... ```Examples Response
```bash 'wrap.near', 'usdt.tether-token.near', 'berryclub.ek.near', 'farm.berryclub.ek.near', 'token.v2.ref-finance.near', 'token.paras.near', 'marmaj.tkn.near', 'meta-pool.near', ... ```Example response
```json { "token.v2.ref-finance.near": "0", "wrap.near": "0" } ```
Example response
```bash { 'token.v2.ref-finance.near': '0', 'wrap.near': "0" } ```
Example response
```bash { 'token.v2.ref-finance.near': '0', 'wrap.near': "0" } ```
Example response
```js [ { pool_kind: 'SIMPLE_POOL', token_account_ids: ['token.skyward.near', 'wrap.near'], amounts: ['51865812079751349630100', '6254162663147994789053210138'], total_fee: 30, shares_total_supply: '1305338644973934698612124055', amp: 0, }, { pool_kind: 'SIMPLE_POOL', token_account_ids: [ 'c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.factory.bridge.near', 'wrap.near', ], amounts: ['783621938569399817', '1100232280852443291118200599'], total_fee: 30, shares_total_supply: '33923015415693335344747628', amp: 0, }, ]; ```
Example response
```bash [ { pool_kind: 'SIMPLE_POOL', token_account_ids: [ 'token.skyward.near', 'wrap.near' ], amounts: [ '51865812079751349630100', '6254162663147994789053210138' ], total_fee: 30, shares_total_supply: '1305338644973934698612124055', amp: 0 }, { pool_kind: 'SIMPLE_POOL', token_account_ids: [ 'c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.factory.bridge.near', 'wrap.near' ], amounts: [ '783621938569399817', '1100232280852443291118200599' ], total_fee: 30, shares_total_supply: '33923015415693335344747628', amp: 0 } ] ```
Example response
```bash [ { pool_kind: 'SIMPLE_POOL', token_account_ids: [ 'token.skyward.near', 'wrap.near' ], amounts: [ '51865812079751349630100', '6254162663147994789053210138' ], total_fee: 30, shares_total_supply: '1305338644973934698612124055', amp: 0 }, { pool_kind: 'SIMPLE_POOL', token_account_ids: [ 'c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2.factory.bridge.near', 'wrap.near' ], amounts: [ '783621938569399817', '1100232280852443291118200599' ], total_fee: 30, shares_total_supply: '33923015415693335344747628', amp: 0 } ] ```
Example response
```json "5019606679394603179450" ```Example response
```bash '5019606679394603179450' ```
Example response
```bash '5019606679394603179450' ```
Authors
Built in collaboration with NTT DATA Innovation Center Web3### Running the Frontend To start the frontend you will need to install the dependencies and start the server. ```bash cd frontend yarn yarn dev ``` Go ahead and login with your NEAR account. If you don't have one, you will be able to create one in the moment. Once logged in, input the amount of NEAR you want to donate and press the donate button. You will be redirected to the NEAR Wallet to confirm the transaction. After confirming it, the donation will be listed in the "Latest Donations".
### Understanding the Frontend The frontend is a [Next.JS](https://nextjs.org/) project generated by [create-near-app](https://github.com/near/create-near-app). Check `DonationsTable.jsx` and `DonationsForm.jsx` to understand how components are displayed and interacting with the contract.
| User | Total Donated Ⓝ |
|---|---|
| {donation.account_id} | {utils.format.formatNearAmount(donation.total_amount)} |
Page {currentPage}
{[10, 20, 50, 100].map((amount) => (
))}
);
};
export default DonationForm;
```
### Testing the Contract The contract readily includes a set of unit and sandbox testing to validate its functionality. To execute the tests, run the following commands:
### Deploying the Contract to the NEAR network In order to deploy the contract you will need to create a NEAR account.
### CLI: Interacting with the Contract To interact with the contract through the console, you can use the following commands #### Get donations
#### Get beneficiary
#### Get number of donors
#### Get donation for an account
#### Donate to the contract
:::tip If you're using your own account, replace `donation.near-examples.testnet` with your `accountId`. ::: --- ## Moving Forward A nice way to learn is by trying to expand a contract. Modify the donation example so it accumulates the tokens in the contract instead of sending it immediately. Then, make a method that only the `beneficiary` can call to retrieve the tokens.
• If the block had been produced more than 5 epochs ago, try to send your request to [an archival node](https://near-nodes.io/intro/node-types#archival-node) | | INVALID_ACCOUNT | The requested `account_id` is invalid | • Provide a valid `account_id` | | UNKNOWN_ACCOUNT | The requested `account_id` has not been found while viewing since the account has not been created or has been already deleted | • Check the `account_id`
• Specify a different block or retry if you request the latest state | | UNAVAILABLE_SHARD | The node was unable to found the requested data because it does not track the shard where data is present | • Send a request to a different node which might track the shard | | NO_SYNCED_BLOCKS | The node is still syncing and the requested block is not in the database yet | • Wait until the node finish syncing
• Send a request to a different node which is synced | | NOT_SYNCED_YET | The node is still syncing and the requested block is not in the database yet | • Wait until the node finish syncing
• Send a request to a different node which is | ### Access Keys Errors specific to [Access Keys API](/api/rpc/access-keys). | ERROR_CAUSE | Reason | Solution | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | | UNKNOWN_ACCESS_KEY | The requested `public_key` has not been found while viewing since the public key has not been created or has been already deleted | • Check the `public_key`
• Specify a different block or retry if you request the latest state | ### Accounts / Contracts Errors specific to [Accounts / Contracts API](/api/rpc/contracts). | ERROR_CAUSE | Reason | Solution | | ------------------------ | ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | NO_CONTRACT_CODE | The account does not have any `contract` deployed on it | • Use different account
• Specify a different block or retry if you request the latest state | | TOO_LARGE_CONTRACT_STATE | The requested contract state is too large to be returned from this node (the default limit is 50kb of state size) | • Send the request to a node with larger limits in order to view the requested state
• Spin up your own node where you can increase the limits to view state | | CONTRACT_EXECUTION_ERROR | The execution of the view function call failed (crashed, run out of the default 200 TGas limit, etc) | • Check `error.cause.info` for more details | ### Block / Chunk Errors specific to [Block / Chunk API](/api/rpc/block-chunk). | ERROR_CAUSE | Reason | Solution | | ---------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------- | | UNKNOWN_CHUNK | The requested chunk is not available or has been garbage-collected | • Check chunk ID validity
• Try an archival node for older chunks | | INVALID_SHARD_ID | The provided shard ID is invalid or doesn't exist | • Provide a valid shard ID within the network's shard range | ### Network Errors specific to [Network API](/api/rpc/network). | ERROR_CAUSE | Reason | Solution | | ------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | UNKNOWN_EPOCH | An epoch for the provided block can't be found in a database | • Check that the requested block is legit
• If the block had been produced more than 5 epochs ago, try to send your request to an archival node
•Check that the requested block is the last block of some epoch | ### Transactions Errors specific to [Transactions API](/api/rpc/transactions). | ERROR_CAUSE | Reason | Solution | | ------------------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | INVALID_TRANSACTION | An error happened during transaction execution | • See `error.cause.info` for details, likely a field in the transaction was invalid
•If `error.cause.info` is `ShardCongested`, resubmit the identical transaction after a delay. (Consider adding a priority fee once [NEP-541](https://github.com/near/NEPs/pull/541) is released.)
• If `error.cause.info` is `ShardStuck`, you may also resubmit the identical transaction after a delay | | UNKNOWN_RECEIPT | The receipt with the given `receipt_id` was never observed on the node | • Check the provided `receipt_id` is correct
• Send a request on a different node | ## 400 - Bad Request These errors indicate that the request was malformed or contains invalid parameters that prevent the server from processing it. **ERROR_TYPE:** `REQUEST_VALIDATION_ERROR` | ERROR_CAUSE | Reason | Solution | | ----------- | ------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | | PARSE_ERROR | Passed arguments can't be parsed by JSON RPC server (missing arguments, wrong format, etc.) | • Check the arguments passed and pass the correct ones
• Check `error.cause.info` for more details | ## 408 - Request Timeout These errors occur when a request takes too long to process and times out before completion. **ERROR_TYPE:** `REQUEST_VALIDATION_ERROR` ### Transaction Timeouts Errors specific to [Transactions API](/api/rpc/transactions) that occur due to timeout conditions. | ERROR_CAUSE | Reason | Solution | | ------------- | ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | TIMEOUT_ERROR | Transaction was routed, but has not been recorded on chain in 10 seconds. | • Resubmit the request with the identical transaction (in NEAR Protocol unique transactions apply exactly once, so if the previously sent transaction gets applied, this request will just return the known result, otherwise, it will route the transaction to the chain once again)
• Check that your transaction is valid
• Check that the signer account id has enough tokens to cover the transaction fees (keep in mind that some tokens on each account are locked to cover the storage cost) | ## 500 - Internal Server Error These errors indicate that something went wrong on the server side, typically due to internal issues or server overload. **ERROR_TYPE:** `INTERNAL_ERROR` | ERROR_CAUSE | Reason | Solution | | -------------- | ------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | | INTERNAL_ERROR | Something went wrong with the node itself or overloaded | • Try again later
• Send a request to a different node
• Check `error.cause.info` for more details | --- # Source: https://docs.near.org/web3-apps/concepts/eth-wallets-on-near.md --- title: EVM Wallets on NEAR id: eth-wallets-on-near description: "Understand how NEAR supports Ethereum wallets" --- Thanks to the [NEAR Wallet Selector](./web-login.md#wallet-selector), users can login into NEAR applications using [Ethereum-compatible wallets](https://ethereum.org/en/wallets/), such as MetaMask, Trust Wallet, and others. To make this possible, different components interact to translate Ethereum transactions into NEAR transactions, and vice-versa. Let's see how they work! :::info This page provides a high-level overview on how these components works, for a detailed specification please see the [NEAR Enhancement Proposal (NEP-518)](https://github.com/near/NEPs/issues/518). ::: :::tip Searching for a tutorial? Check our step-by-step tutorial on how to add Ethereum wallets support to your NEAR app using the [NEAR Wallet Selector](../tutorials/web-login/ethereum-wallets.md) ::: --- ## Components Overview Since Ethereum wallets create _ethereum transactions_ and talk with _ethereum RPCs_, three components are needed to make them work on NEAR: 1. A `Transaction Encoder` service, that encodes NEAR actions into Ethereum transactions 2. A `Translator RPC` service, that translates Ethereum RPC calls into NEAR RPC calls 3. A `Wallet Contract` that allows NEAR accounts to process EVM transactions
*High-level architecture of Ethereum wallets on NEAR*
### Transaction Encoder The `Translator Encoder` - implemented [directly in the NEAR Wallet Selector](https://github.com/near/wallet-selector/blob/main/packages/ethereum-wallets/src/lib/index.ts) - takes the intent of the user (e.g. call `set_greeting` on `hello.near`) and translates it into an Ethereum transaction that the EVM wallet can sign. #### To (field) The `to` field of the Ethereum transaction is transformed following these rules: - If the `receiverId` matches `^0x[a-f0-9]{40}$` (e.g. `0xD79...314`), then the `to` field is set to the `receiverId` - Otherwise (e.g. `ana.near` or an implicit account) the `to` field is set as `keccak-256(receiverId)[12,32]` #### Data (field) The `data` field meanwhile contains the RLP-encoded NEAR actions wanted by the user, encoded as function calls on Ethereum, for example: - `FunctionCall(to: string, method: string, args: bytes, yoctoNear: uint32)` - `Transfer(to: string, yoctoNear: uint32)` - `Stake(public_key: bytes, yoctoNear: uint32)` - `AddKey(public_key: bytes, nonce: uint64, is_full_access: bool, allowance: uint256, receiver_id: string, method_names: string[])` :::info For more information on how other fields (such as `value`, `gas`, and `chainId`) are set, please refer to the [NEP-518 technical specification](https://github.com/near/NEPs/issues/518) :::
### Translator RPC The `Translator RPC` is a service deployed at `https://eth-rpc.mainnet.near.org` (for mainnet) and `https://eth-rpc.testnet.near.org` (for testnet) that translates Ethereum RPC calls into NEAR RPC calls. In other words, the `Translator RPC` simply acts as a relayer, taking the Ethereum transactions signed by the user and translating them into a function call into the `Wallet Contract` deployed in the user's account.
### Wallet Contract The `Wallet Contract` is a smart contract on NEAR that allows NEAR accounts to process EVM transactions. The contract exposes a method called `rlp_execute`, which takes as argument an RLP-encoded Ethereum transaction, verifies its signature, and executes the NEAR actions encoded in the `data` field of the transaction. Every NEAR account created through an EVM wallet has the `Wallet Contract` deployed on it. :::tip Wallet Accounts Remember that in NEAR **all accounts** can **have contracts**, and that **contracts** can perform **all the actions** that the **account can do**. ::: --- ## How it Works? Let's see how the components described above interact when a user logs in and uses an application.
### First Time Login The first time you login through your EVM wallet, the wallet selector will contact the account `ethereum-wallets.near` to create a NEAR account with the same address as your Ethereum wallet. For example, if your address on Metamask is `0xD79...314`, the NEAR account created will be `0xD79...314`. On this account, the `Wallet Contract` is deployed and a function-call key is added for the `rlp_execute` function of the contract
*On your first login, a NEAR accounts with the same address as your Ethereum wallet is created, and the Wallet Contract is deployed on it*
### Using the Account Once you have logged in, you can start interacting with the application. If at some point the application needs to interact with the blockchain, Metamask will ask you to sign a transaction. Under the hood, Metamask will create an Ethereum transaction and send it to the `Translator API`, deployed at `https://eth-rpc.mainnet.near.org`. The `Translator API` will then translate the Ethereum transaction into a **function call** into the `Wallet Contract` deployed in your account. Particularly, it will call the `rlp_execute` function, passing the Ethereum transaction as an argument.
The `Wallet Contract` will then execute the function call, and the application will receive the result.
---
## Resources
Check the following resources to learn more about Ethereum wallets on NEAR:
- [Adding EVM Wallets to your NEAR App](../tutorials/web-login/ethereum-wallets.md) - Step-by-step tutorial on how to add Ethereum wallets support to your NEAR app
- [NEP-518 Technical Specification](https://github.com/near/NEPs/issues/518) - Full technical specification of how Ethereum wallets work on NEAR
---
# Source: https://docs.near.org/web3-apps/tutorials/web-login/ethereum-wallets.md
---
title: EVM Wallets Login
id: ethereum-wallets
description: "Learn how to integrate Ethereum wallets like MetaMask into your NEAR DApp using the Near Wallet Selector, Web3Modal, and wagmi libraries."
---
Using the [Wallet Selector](./wallet-selector.md) it is possible to login into NEAR applications using Ethereum wallets like MetaMask, WalletConnect and many others.
This tutorial will guide you to add Ethereum wallet support to your NEAR application using the [Reown](https://reown.com/appkit) library, which is widely used in the Ethereum ecosystem.
:::info
Learn more about Ethereum Wallets on NEAR in our [concepts page](../../concepts/eth-wallets.md)
:::
---
## Overview
To integrate Metamask and other EVM wallets you will need to:
1. Add the `@near-wallet-selector/ethereum-wallets` module
2. Add the EVM libraries `wagmi` and `reown`
3. Create configurations so the Ethereum wallets can communicate with our [Translator RPC](../../concepts/eth-wallets.md#translator-rpc)
4. Create a Web3Modal and connect it to the Near Wallet Selector
5. Initialize the Ethereum Wallets
We will show how we added Ethereum Wallets support to our [**Hello Near Examples**](https://github.com/near-examples/hello-near-examples/tree/main/frontend).
:::tip
This article was created by the AuroraLabs team, and appeared originally in the [official Aurora documentation](https://doc.aurora.dev/dev-reference/eth-wallets)
:::
---
## 1. Update Wallet Selector libraries
Lets start by updating the `package.json`, adding all the necessary libraries to support Ethereum wallets.
### Wallet Selector Packages In your `package.json`, add the `@near-wallet-selector/ethereum-wallets` package, and update **all** wallet selector packages to version `8.9.13` or above: ```json title="package.json" "dependencies": { ... "@near-wallet-selector/core": "^9.5.0", // highlight-next-line "@near-wallet-selector/ethereum-wallets": "^9.5.0", "@near-wallet-selector/here-wallet": "^9.5.0", "@near-wallet-selector/modal-ui": "^9.5.0", "@near-wallet-selector/my-near-wallet": "^9.5.0", ... } ```
### Add Web3Modal libraries [Web3Modal (also known as AppKit)](https://reown.com/appkit) is a standard way to integrate multiple wallets in Ethereum community. It is based on [wagmi] hooks library for React. We will describe the React integration here, but if you are on another platform - just go [here](https://docs.reown.com/appkit/overview#get-started), and try using specific instructions suitable for you to install it. ```bash npm install @reown/appkit-adapter-wagmi @reown/appkit @wagmi/core viem ``` --- ## 2. Add Web3Modal First, let's create a new file to handle the Web3Modal (i.e. the modal shown when selecting the `Ethereum Wallets` on the `Wallet Selector`), and all the configs needed to setup the Ethereum Wallets. ``` import { reconnect } from '@wagmi/core'; import { createAppKit } from '@reown/appkit/react' import { nearTestnet } from '@reown/appkit/networks' import { WagmiAdapter } from '@reown/appkit-adapter-wagmi' const projectId = '5bb0fe33763b3bea40b8d69e4269b4ae'; export const wagmiAdapter = new WagmiAdapter({ projectId, networks: [nearTestnet], }); export const web3Modal = createAppKit({ adapters: [wagmiAdapter], projectId, networks: [nearTestnet], enableWalletConnect: true, features: { analytics: true, swaps: false, onramp: false, email: false, // Smart accounts (Safe contract) not available on NEAR Protocol, only EOA. socials: false, // Smart accounts (Safe contract) not available on NEAR Protocol, only EOA. }, coinbasePreference: "eoaOnly", // Smart accounts (Safe contract) not available on NEAR Protocol, only EOA. allWallets: "SHOW", }); // force reconnecting if the user has already signed in with an ethereum wallet // this is a workaround until `ethereum-wallets` supports the `reconnect` method if (typeof window !== "undefined") { const recentWallets = localStorage.getItem("near-wallet-selector:recentlySignedInWallets"); recentWallets && recentWallets.includes("ethereum-wallets") && reconnect(wagmiAdapter.wagmiConfig) } ```
Metadata
You can pass a `metadata` object to the `walletConnect` connector. This object will be displayed in the EVM wallets, like MetaMask. ```js title="source/wallets/web3modal.js" const url = "http://localhost:3000"; const metadata = { name: "Onboard to NEAR Protocol with EVM Wallet", description: "Discover NEAR Protocol with Ethereum and NEAR wallets.", url: url, icons: [`${url}/icon.svg`], }; ``` This tracks the app requesting the connection on the WalletConnect side. See more [here](https://wagmi.sh/core/api/connectors/walletConnect#metadata).### Get `projectId` Notice that the modal uses a `projectId`, which refers to your unique project on `Reown`. Let's get the Web3Modal `projectId` for your project: 1. Go to [Cloud Reown](https://cloud.reown.com/). 2. Register there. 3. Create a project on Cloud Reown. 4. You can copy your `projectId`:  :::tip You can read more about the `projectId` and how it works [here](https://docs.reown.com/appkit/react/core/installation#cloud-configuration). ::: --- ## 4. Setup Wallet Selector The last step is to add the Ethereum Wallets selector to your Near Wallet Selector. Let's find your `setupWalletSelector` call and add `setupEthereumWallets` there: ```js showLineNumbers ``` ``` import { setupBitgetWallet } from "@near-wallet-selector/bitget-wallet"; import { setupRamperWallet } from "@near-wallet-selector/ramper-wallet"; import { setupUnityWallet } from "@near-wallet-selector/unity-wallet"; import { setupOKXWallet } from "@near-wallet-selector/okx-wallet"; import { setupCoin98Wallet } from "@near-wallet-selector/coin98-wallet"; import { setupIntearWallet } from "@near-wallet-selector/intear-wallet"; // Ethereum adapters import { wagmiAdapter, web3Modal } from "@/wallets/web3modal"; // Types import type { WalletModuleFactory } from "@near-wallet-selector/core"; const walletSelectorConfig = { network: NetworkId, modules: [ setupEthereumWallets({ wagmiConfig: wagmiAdapter.wagmiConfig, web3Modal }), setupMeteorWallet(), setupMeteorWalletApp({ contractId: HelloNearContract }), setupHotWallet(), setupLedger(), ``` --- ## 5. Use It! That is it! Just re-build your project and click on login! You should see Ethereum Wallets option in your Near Selector:  And after click to be able to choose the EVM wallet of your taste:  --- ## Resources 1. [Source code of the project above](https://github.com/near-examples/hello-near-examples/blob/main/frontend/) 2. [Example of the EVM account on the Near Testnet](https://testnet.nearblocks.io/address/0xe5acd26a443d2d62f6b3379c0a5b2c7ac65d9454) to see what happens in reality on-chain during the execution. 3. Details about how does it work are in [NEP-518](https://github.com/near/NEPs/issues/518) 4. [Recording of the Near Devs call](https://drive.google.com/file/d/1xGWN1yRLzFmRn1e29kbSiO2W1JsxuJH-/view?usp=sharing) with the EthWallets presentation. --- # Source: https://docs.near.org/integrations/exchange-integration.md --- id: exchange-integration title: Exchange Integration sidebar_label: Exchange Integration description: "Learn how to integrate NEAR Protocol into exchanges, including transactions, accounts, tokens, blocks, finality, archival nodes, and staking." --- This document provides an overview of how to integrate with NEAR Protocol for exchanges, including account management, token transfers, and handling implicit accounts. ## Integration Reference {#integration-reference} - [Balance Changes](/integrations/balance-changes) - [Accounts](/integrations/accounts) - [Fungible Tokens](/integrations/fungible-tokens) - [Implicit Accounts](/integrations/implicit-accounts) ### Transaction Reference Links {#transaction-reference-links} - [Basics](/protocol/transactions) - [Specifications](https://nomicon.io/RuntimeSpec/Transactions) - [Constructing Transactions](/integrations/create-transactions) ## Blocks and Finality {#blocks-and-finality} Some important pieces of information regarding blocks and finality include: - Expected block time is around 1s and expected time to finality is around 2s. The last final block can be queried by specifying `{"finality": "final"}` in the block query. For example, to get the latest final block on mainnet, one can run ```bash http post https://rpc.mainnet.near.org method=block params:='{"finality":"final"}' id=123 jsonrpc=2.0 ``` - Block height are not necessarily continuous and certain heights may be skipped if, for example, a block producer for that height is offline. For example, after a block at height 100 is produced, the block at height 101 may be skipped. When block at height 102 is produced, its previous block is the block at height 100. - Some blocks may not include new chunks if, for example, the previous chunk producer is offline. Even though in the RPC return result every block will have non-empty `chunks` field, it does not imply that there is a new chunk included in the block. The way to tell whether the chunk is included in the block is to check whether `height_included` in the chunk is the same as the height of the block. ## Running an Archival Node {#running-an-archival-node} Please refer to configuration changes required in `config.json` for archival node by referring to the documentation on [Run an Archival Node](https://near-nodes.io/archival/run-archival-node-with-nearup). ## Staking and Delegation {#staking-and-delegation} - [https://github.com/nearprotocol/stakewars](https://github.com/nearprotocol/stakewars) - [https://github.com/near/core-contracts](https://github.com/near/core-contracts) :::tip Got a question? Ask it on StackOverflow! ::: --- # Source: https://docs.near.org/tools/explorer.md --- id: explorer title: Explorer sidebar_label: Explorers description: "Explore the chain through a Web UI." --- Explorers are web applications that allow you to quickly obtain information from the blockchain through a friendly user interface. An explorer can help you to check the balance of an account, search for a transaction and its receipts, check the history of interactions in an account or contract, and view block creations in real time. --- ## NearBlocks Created by the community, [NearBlocks](https://nearblocks.io/) enables to check accounts and transactions with an interface similar to etherscan.  *Main page of [NearBlocks](https://nearblocks.io/)*
## Nearscope [Nearscope](https://nearscope.net/) provides a NEAR node validator and delegator explorer.  *Main page of [Nearscope](https://nearscope.net/)*
## DappLooker [DappLooker](https://dapplooker.com/) lets you analyze and query NEAR blockchain data, build dashboards to visualize data and share with your community.  *Main page of [DappLooker](https://dapplooker.com/)*
## Pikespeak [Pikespeak](https://pikespeak.ai/) provides access to real-time and historical data on the NEAR Protocol.  *Main page of [Pikespeak](https://pikespeak.ai/)* ## NEARCatalog [NEARCatalog](https://nearcatalog.xyz/) provides access to trending decentralized applications (DApps) on the NEAR Protocol.  *Main page of [NEARCatalog](https://nearcatalog.xyz/)* --- # Source: https://docs.near.org/tutorials/examples/factory.md --- id: factory title: Factory description: "Learn how a factory contract deploys other contracts on sub-accounts using a global contract ID." --- A factory is a smart contract that stores a global contract id, and automatizes deploying contracts onto new sub-accounts. We have a [**A Generic Factory**](https://github.com/near-examples/factory-rust) that deploys new contracts based on global contract id. The global contract id can be global account id or hash. You can change the global contract id by calling `update_global_contract_id` method. The factory creates sub-accounts of itself and deploys corresponding contract on them. :::info You can learn more about global contracts on NEAR [here](../../smart-contracts/global-contracts.md). ::: --- ## Overview {#generic-factory} The factory is a smart contract that: 1. Creates sub-accounts of itself and deploys its contract on them (`deploy`) 2. Can update the contract it deploys
### Build and Deploy the Factory You can automatically compile and deploy the contract in the NEAR testnet by running: ```bash cargo near deploy ```
### Deploy the Stored Contract Into a Sub-Account Method `deploy` will create a sub-account of the factory and deploy contract on it using stored global contract id. It also asserts that the attached deposit is at least the minimum required deposit stored in the factory. :::info Technically, there is no need to attach any deposit just to deploy a contract using global contracts. But to initialize it further, you will need some NEAR tokens to cover the storage cost. Since initiliazing method can't accept deposit, it makes sense to attach some minimum amount of tokens during creating account and deploying a contract. ::: The following command will create the `sub.
### Update the Stored Contract `update_global_contract_id` enables to change the global contract id that the factory stores. The method is interesting because it has no declared parameters, and yet it takes an input: the new contract to store as a stream of bytes. To use it, we need to pass the contract id we want to store. It can be in form of account id or global contract hash. What is the difference between them you can read in [Global Contracts](../../smart-contracts/global-contracts.md#solution) section. ```bash near contract call-function as-transaction
### Automatically Creating Accounts NEAR accounts can only create sub-accounts of itself, therefore, the `factory` can only create and deploy contracts on its own sub-accounts. This means that the factory: 1. **Can** create `sub.factory.testnet` and deploy a contract on it. 2. **Cannot** create sub-accounts of the `predecessor`. 3. **Can** create new accounts (e.g. `account.testnet`), but **cannot** deploy contracts on them. It is important to remember that, while `factory.testnet` can create `sub.factory.testnet`, it has no control over it after its creation.
### The Deploy Method During the creation of a sub-account we add signers public key to the new sub-account as a full access key. It means that the predecessor will be able to control the new sub-account after its creation. Also, in the tutorial, we attach deposit to the `deploy` call which goes straight to the new sub-account. When we deploy a new contract using global contracts, we need to initialize it after deployment. That tokens will cover the storage after the deployed contract is initialized. --- # Source: https://docs.near.org/integrations/faq.md --- id: faq title: Integrator FAQ sidebar_label: Integrator FAQ description: "Frequently asked questions about NEAR protocol integrations, including account management, transaction fees, and common development challenges." --- This document provides answers to frequently asked questions about integrating with the NEAR Protocol. It covers topics such as account management, validator operations, transaction processing, and more. ## Orientation ### What is a good project summary for NEAR? NEAR is a sharded, public, proof-of-stake blockchain and smart contract platform. It is built in Rust and contracts compile to WASM. It is conceptually similar to Ethereum 2.0. ### What's special about NEAR? NEAR is the blockchain for builders. If you understand the basics of web development, you can write, test and deploy scalable decentralized applications in minutes on the most developer-friendly blockchain without having to learn new tools or languages. ### Is NEAR open source? Yes. Have a look at our [GitHub organization](https://github.com/near). ### How are cryptographic functions used? We support both `secp256k1` and `ed25519` for account keys and `ed25519` for signing transactions. We currently use the `ed25519_dalek` and `sha2` libraries for crypto. ### Do you have any on-chain governance mechanisms? NEAR does not have any on-chain governance at the moment. Any changes to state or state transition function must be done through a hard fork. ### Do you have a bug-bounty program? Our plan is to have a transparent Bug Bounty program with clear guidelines for paying out to those reporting issues. Payments will likely be based on publicly available rankings provided by protocol developers based on issue severity. ### What contracts should we be aware of right now? We have developed a number of [initial contracts](https://github.com/near/core-contracts) with **ones in bold** being most mature at time of writing - **Staking Pool / Delegation contract** - **Lockup / Vesting contract** - Whitelist Contract - Staking Pool Factory - Multisig contract ### Do you have a cold wallet implementation (ie. Ledger)? https://github.com/near/near-ledger-app ## Validators ### What is the process for becoming a validator? Validation is permissionless and determined via auction. Parties who want to become a validator submit a special transaction to the chain one day ahead which indicates how many tokens they want to stake. An auction is run which determines the minimum necessary stake to get a validation seat during the next epoch and, if the amount submitted is greater than the minimum threshold, the submitter will validate at least one shard during the next epoch. ### How long does a validator remain a validator? A validator will stop being a validator for the following reasons: - Not producing enough blocks or chunks. - Not getting elected in the auction for next epoch because their stake is not large enough. - Getting slashed. Otherwise a validator will remain a validator indefinitely. Validator election happens in epochs. The [Nightshade whitepaper](/papers/Nightshade.pdf) introduces epochs this way: "the maintenance of the network is done in epochs" where an epoch is a period of time on the order of half a day. At the beginning of each epoch, some computation produces a list of validators for the _very next epoch_. The input to this computation includes all accounts that have "raised their hand to be a validator" by submitting a special transaction ([`StakeAction`](https://nomicon.io/RuntimeSpec/Actions.html#stakeaction)) expressing the commitment of some amount of tokens over the system's staking threshold, as well as validators from the previous epoch. The output of this computation is a list of the validators for the very next epoch. ### What is the penalty for misbehaving validators? Validators are not slashed for being offline but they do miss out on the rewards of validating. Validators who miss too many blocks or chunks will be removed from the validation set in the next auction and not get any reward (but, again, without slashing). Any foul play on the part of the validator that is detected by the system may result in a "slashing event" where the validator is marked as out of integrity and forfeits their stake (according to some formula of progressive severity). The slashed stake is burnt. ### What is the mechanism for delegating stake to validators? NEAR supports separate validation keys that can be used in smart contracts to delegate stake. Delegation is done via smart contract which allows for a validator to define a custom way to collect stake, manage it and split rewards. This also allows validators to provide leverage or derivatives on stake. Delegated stake will be slashed like any other stake if the node misbehaves. If a validator misbehaves the funds of the delegators are also slashed. There is no waiting period for delegators to withdraw their stake. ### Does a validator control funds that have been delegated to them? Delegation is custodial (you are transferring funds to a different account, the smart contract that implements staking pool). We provide a reference implementation being security reviewed and tested by 100 validators at time of writing. We allow validators to write and deploy new contracts but it is up to users to decide if they want to delegate. Validators can compete for delegation by choosing different logic and conditions around tax optimization, etc. Currently no slashing but will be added as we add shards into the system. At some point validators will be able to add an option to shield delegators from slashing (similar to Tezos model). ### How do we get the balance of an account after it has delegated funds? One would need to query the staking pool contract to get balance. ## Nodes ### Can a node be configured to archive all blockchain data since genesis? v Yes. Start the node using the following command: ```sh ./target/release/near run --archive ``` ### Can a node be configured to expose an RPC (ex: HTTP) interface? Yes. All nodes expose this interface by default which can be configured by setting the value of `listen_addr:port` in the node's `config.json` file. ### Can a node be gracefully terminated and restarted (using archived data on disk to continue syncing)? Yes. ### Does a node expose an interface for retrieving health telemetry in a structured format (ex: JSON) over RPC? Yes. `GET /status` and `GET /health` provide this interface. - `/status`: block height, syncing status, peer count, etc - `/health`: success/failure if node is up running & progressing ### Can a node be started using a Dockerfile without human supervision? Yes. ```sh docker run
Manual Interaction
Here is how to directly interact with the factory contract through your application:### Global Contracts You can deploy a new Fungible Token using our global FT contract - a pre-deployed [standard FT contract](https://github.com/near-examples/FT) that you can reuse. [Global contracts](../../smart-contracts/global-contracts.md) are deployed once and can be reused by any account without incurring high storage costs.
Example response
```json { "spec": "ft-1.0.0", "name": "Ref Finance Token", "symbol": "REF", "icon": "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='16 24 248 248' style='background: %23000'%3E%3Cpath d='M164,164v52h52Zm-45-45,20.4,20.4,20.6-20.6V81H119Zm0,18.39V216h41V137.19l-20.6,20.6ZM166.5,81H164v33.81l26.16-26.17A40.29,40.29,0,0,0,166.5,81ZM72,153.19V216h43V133.4l-11.6-11.61Zm0-18.38,31.4-31.4L115,115V81H72ZM207,121.5h0a40.29,40.29,0,0,0-7.64-23.66L164,133.19V162h2.5A40.5,40.5,0,0,0,207,121.5Z' fill='%23fff'/%3E%3Cpath d='M189 72l27 27V72h-27z' fill='%2300c08b'/%3E%3C/svg%3E%0A", "reference": null, "reference_hash": null, "decimals": 18 } ```
Example response
```bash { spec: "ft-1.0.0", name: "Ref Finance Token", symbol: "REF", icon: "data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='16 24 248 248' style='background: %23000'%3E%3Cpath d='M164,164v52h52Zm-45-45,20.4,20.4,20.6-20.6V81H119Zm0,18.39V216h41V137.19l-20.6,20.6ZM166.5,81H164v33.81l26.16-26.17A40.29,40.29,0,0,0,166.5,81ZM72,153.19V216h43V133.4l-11.6-11.61Zm0-18.38,31.4-31.4L115,115V81H72ZM207,121.5h0a40.29,40.29,0,0,0-7.64-23.66L164,133.19V162h2.5A40.5,40.5,0,0,0,207,121.5Z' fill='%23fff'/%3E%3Cpath d='M189 72l27 27V72h-27z' fill='%2300c08b'/%3E%3C/svg%3E%0A", reference: null, reference_hash: null, decimals: 18 } ```
Example response
```json "3479615037675962643842" ```
Example response
```bash '376224322825327177426' ```
Example response
```json "100000000000000000" ```
Example response
```bash '100000000000000000' ```
Exposing trait implementations
Functions can also be exposed through trait implementations. This can be useful if implementing a shared interface or standard for a contract. This code generation is handled very similarly to basic `pub` functions, but the `#[near]` macro only needs to be attached to the trait implementation, not the trait itself: ```rust pub trait MyTrait { fn trait_method(&mut self); } #[near] impl MyTrait for MyContractStructure { fn trait_method(&mut self) { // .. method logic here } } ```Separate impl block
Another way of not exporting methods is by having a separate `impl Contract` section, that is not marked with `#[near]`. ```rust #[near] impl Contract { pub fn increment(&mut self) { self.internal_increment(); } } impl Contract { /// This methods is still not exported. pub fn internal_increment(&mut self) { self.counter += 1; } } ```**Example Response:**
```json { "id": "myid", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "serhii.testnet", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "e30=", "deposit": "125000000000000000000000", "gas": 100000000000000, "method_name": "storage_deposit" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "4urgFabknn1myZkjTYdb1BFSoEimP21k9smCUWoSggA7", "receiver_id": "ft.demo.testnet" }, { "predecessor_id": "ft.demo.testnet", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "123750000000000000000000" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "7neJYE45vXnQia1LQqWuAfyTRXHy4vv88JaULa5DnNBd", "receiver_id": "serhii.testnet" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "19200274886926125000" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "2c59u2zYj41JuhMfPUCKjNucmYfz2Jt83JLWP6VyQn1S", "receiver_id": "serhii.testnet" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "18587201427159524319124" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "kaYatRKxcC1NXac69WwTqg6K13oXq2yEuy4LLZtsV2G", "receiver_id": "serhii.testnet" } ], "receipts_outcome": [ { "block_hash": "6Gz6P8N3F447kRc7kkxEhuZRZTzfuTUEagye65bPVGb", "id": "4urgFabknn1myZkjTYdb1BFSoEimP21k9smCUWoSggA7", "outcome": { "executor_id": "ft.demo.testnet", "gas_burnt": 4258977405434, "logs": [], "receipt_ids": [ "7neJYE45vXnQia1LQqWuAfyTRXHy4vv88JaULa5DnNBd", "kaYatRKxcC1NXac69WwTqg6K13oXq2yEuy4LLZtsV2G" ], "status": { "SuccessValue": "eyJ0b3RhbCI6IjEyNTAwMDAwMDAwMDAwMDAwMDAwMDAiLCJhdmFpbGFibGUiOiIwIn0=" }, "tokens_burnt": "425897740543400000000" }, "proof": [] }, { "block_hash": "J6YXMnLPfLEPyvL3fWdhWPzpWAeW8zNY2CwAFwAg9tfr", "id": "7neJYE45vXnQia1LQqWuAfyTRXHy4vv88JaULa5DnNBd", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 223182562500, "logs": [], "receipt_ids": [ "2c59u2zYj41JuhMfPUCKjNucmYfz2Jt83JLWP6VyQn1S" ], "status": { "SuccessValue": "" }, "tokens_burnt": "22318256250000000000" }, "proof": [ { "direction": "Right", "hash": "D6tGfHwKh21PqzhBTsdKCsTtZvXFDkmH39dQiQBoGN3w" } ] }, { "block_hash": "HRRF7N1PphZ46eN5g4DjqEgYHBYM76yGiXSTYWsfMGoy", "id": "2c59u2zYj41JuhMfPUCKjNucmYfz2Jt83JLWP6VyQn1S", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [] }, { "block_hash": "J6YXMnLPfLEPyvL3fWdhWPzpWAeW8zNY2CwAFwAg9tfr", "id": "kaYatRKxcC1NXac69WwTqg6K13oXq2yEuy4LLZtsV2G", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Left", "hash": "1uVJZ8vNQpHMwPA38DYJjk9PpvnHDhsDcMxrTXcwf1s" } ] } ], "status": { "SuccessValue": "eyJ0b3RhbCI6IjEyNTAwMDAwMDAwMDAwMDAwMDAwMDAiLCJhdmFpbGFibGUiOiIwIn0=" }, "transaction": { "actions": [ { "FunctionCall": { "args": "e30=", "deposit": "125000000000000000000000", "gas": 100000000000000, "method_name": "storage_deposit" } } ], "hash": "6sDUF1f5hebpybUbipNJer5ez13EY4HW1VBJEBqZjCEm", "nonce": 47589658000011, "public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN", "receiver_id": "ft.demo.testnet", "signature": "ed25519:31PfuinsVvM1o2CmiZbSguFkZKYqAtkf5PHerfexhDbC3SsJWDzRFBpoUYTNDJddhKeqs93GQ3SHtUyqaSYhhQ9X", "signer_id": "serhii.testnet" }, "transaction_outcome": { "block_hash": "5XiuxzTpyw6p2NTD5AqrZYNW7SHvpj8MhUCyn1x2KSQR", "id": "6sDUF1f5hebpybUbipNJer5ez13EY4HW1VBJEBqZjCEm", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 2427959010878, "logs": [], "receipt_ids": [ "4urgFabknn1myZkjTYdb1BFSoEimP21k9smCUWoSggA7" ], "status": { "SuccessReceiptId": "4urgFabknn1myZkjTYdb1BFSoEimP21k9smCUWoSggA7" }, "tokens_burnt": "242795901087800000000" }, "proof": [] } } } ```**Example Response:**
```json { "id": "myid", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "serhii.near", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6InZvbG92eWsubmVhciIsImFtb3VudCI6IjEifQ==", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.near", "signer_public_key": "ed25519:eLbduR3uJGaAHLXeGKEfo1fYmYFKkLyR1R8ZPCxrJAM" } }, "receipt_id": "ExhYcvwAUb3Jpm38pSQ5oobwJAouBqqDZjbhavKrZtur", "receiver_id": "berryclub.ek.near" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "18418055677558685763688" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.near", "signer_public_key": "ed25519:eLbduR3uJGaAHLXeGKEfo1fYmYFKkLyR1R8ZPCxrJAM" } }, "receipt_id": "EAPh8XrBMqm6iuVH5jsfemz4YqUxWsV8Mz241cw5tjvE", "receiver_id": "serhii.near" } ], "receipts_outcome": [ { "block_hash": "6Re4NTkKzD7maKx3MuoxzYVHQKqjgnXW8rNjGjeVx8YC", "id": "ExhYcvwAUb3Jpm38pSQ5oobwJAouBqqDZjbhavKrZtur", "outcome": { "executor_id": "berryclub.ek.near", "gas_burnt": 6365774114160, "logs": [ "Transfer 1 from serhii.near to volovyk.near" ], "receipt_ids": [ "EAPh8XrBMqm6iuVH5jsfemz4YqUxWsV8Mz241cw5tjvE" ], "status": { "SuccessValue": "" }, "tokens_burnt": "636577411416000000000" }, "proof": [ { "direction": "Left", "hash": "2eUmWnLExsH5jb6mALY9jTC8FiQH4FcuxQ16tn7RfkYr" }, { "direction": "Right", "hash": "266d5QfDKXNbAWJgXMJXgLP97VwoMiC4Qyt8wH7xcs1Q" }, { "direction": "Right", "hash": "EkJAuJigdVSZj41yGXSZYAtDV7Xwe2Hv9Xsqcv6LUZvq" } ] }, { "block_hash": "3XMoeEdm1zE64aByFuWCrZaxfbvsjMHRFcL8Wsp95vyt", "id": "EAPh8XrBMqm6iuVH5jsfemz4YqUxWsV8Mz241cw5tjvE", "outcome": { "executor_id": "serhii.near", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Right", "hash": "EGC9ZPJHTbmCs3aQDuCkFQboGLBxU2uzrSZMsp8WonDu" }, { "direction": "Right", "hash": "EsBd1n7bDAphA3HY84DrrKd1GP1VugeNiqFCET2S5sNG" }, { "direction": "Left", "hash": "H4q3ByfNB7QH9QEuHN3tcGay7tjhsZwjXx3sq3Vm3Lza" } ] } ], "status": { "SuccessValue": "" }, "transaction": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6InZvbG92eWsubmVhciIsImFtb3VudCI6IjEifQ==", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer" } } ], "hash": "2Fy4714idMCoja7QLdGAbQZHzV2XEnUdwZX6yGa46VMX", "nonce": 10, "public_key": "ed25519:eLbduR3uJGaAHLXeGKEfo1fYmYFKkLyR1R8ZPCxrJAM", "receiver_id": "berryclub.ek.near", "signature": "ed25519:5eJPGirNkBUbMeyRfEA4fgi1FtkgGk8pmbbkmiz3Faf6zrANpBsCs5bZd5heSTvQ6b3fEPLSPCPi2iwD2XJT93As", "signer_id": "serhii.near" }, "transaction_outcome": { "block_hash": "EAcwavyaeNWZnfhYP2nAWzeDgMiuiyRHfaprFqhXgCRF", "id": "2Fy4714idMCoja7QLdGAbQZHzV2XEnUdwZX6yGa46VMX", "outcome": { "executor_id": "serhii.near", "gas_burnt": 2428041740436, "logs": [], "receipt_ids": [ "ExhYcvwAUb3Jpm38pSQ5oobwJAouBqqDZjbhavKrZtur" ], "status": { "SuccessReceiptId": "ExhYcvwAUb3Jpm38pSQ5oobwJAouBqqDZjbhavKrZtur" }, "tokens_burnt": "242804174043600000000" }, "proof": [ { "direction": "Right", "hash": "GatQmy7fW5uXRJRSg7A315CWzWWcQCGk4GJXyW3cjw4j" }, { "direction": "Right", "hash": "89WJwAetivZLvAkVLXUt862o7zJX7YYt6ZixdWebq3xv" }, { "direction": "Right", "hash": "CH3wHSqYPJp35krLjSgJTgCFYnv1ymhd9bJpjXA31VVD" } ] } } } ```**Example Response:**
```json { "id": "myid", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "serhii.near", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6InZvbG92eWsubmVhciIsImFtb3VudCI6IjEwMDAwMDAwMDAwMDAwMDAwMDAwIn0=", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.near", "signer_public_key": "ed25519:eLbduR3uJGaAHLXeGKEfo1fYmYFKkLyR1R8ZPCxrJAM" } }, "receipt_id": "5bdBKwS1RH7wm8eoG6ZeESdhNpj9HffUcf8RoP6Ng5d", "receiver_id": "berryclub.ek.near" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "1" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "system", "signer_public_key": "ed25519:11111111111111111111111111111111" } }, "receipt_id": "Td3QxpKhMdi8bfVeMiQZwNS1VzPXceQdn6xdftoC8k6", "receiver_id": "serhii.near" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "18653463364152698495356" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.near", "signer_public_key": "ed25519:eLbduR3uJGaAHLXeGKEfo1fYmYFKkLyR1R8ZPCxrJAM" } }, "receipt_id": "DwLMVTdqv9Z4g9QC4AthTXHqqeJVAH4s1tFXHQYMArW7", "receiver_id": "serhii.near" } ], "receipts_outcome": [ { "block_hash": "DTruWLgm5Y56yDrxUipvYqKKm8F7hxVQTarNQqe147zs", "id": "5bdBKwS1RH7wm8eoG6ZeESdhNpj9HffUcf8RoP6Ng5d", "outcome": { "executor_id": "berryclub.ek.near", "gas_burnt": 4011776278642, "logs": [], "receipt_ids": [ "Td3QxpKhMdi8bfVeMiQZwNS1VzPXceQdn6xdftoC8k6", "DwLMVTdqv9Z4g9QC4AthTXHqqeJVAH4s1tFXHQYMArW7" ], "status": { "Failure": { "ActionError": { "index": 0, "kind": { "FunctionCallError": { "ExecutionError": "Smart contract panicked: The account doesn't have enough balance" } } } } }, "tokens_burnt": "401177627864200000000" }, "proof": [ { "direction": "Right", "hash": "6GHrA42oMEF4g7YCBpPw9EakkLiepTHnQBvaKtmsenEY" }, { "direction": "Right", "hash": "DCG3qZAzf415twXfHmgBUdB129g2iZoQ4v8dawwBzhSh" } ] }, { "block_hash": "F9xNWGhJuYW336f3qVaDDAipsyfpudJHYbmt5in3MeMT", "id": "Td3QxpKhMdi8bfVeMiQZwNS1VzPXceQdn6xdftoC8k6", "outcome": { "executor_id": "serhii.near", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Right", "hash": "CJNvis1CoJmccshDpPBrk3a7fdZ5HnMQuy3p2Kd2GCdS" }, { "direction": "Left", "hash": "4vHM3fbdNwXGMp9uYzVKB13abEM6qdPUuZ9rfrdsaDzc" } ] }, { "block_hash": "F9xNWGhJuYW336f3qVaDDAipsyfpudJHYbmt5in3MeMT", "id": "DwLMVTdqv9Z4g9QC4AthTXHqqeJVAH4s1tFXHQYMArW7", "outcome": { "executor_id": "serhii.near", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Left", "hash": "BR3R7tjziEgXMiHaJ7VuuXCo2yBHB2ZzsoxobPhPjFeJ" }, { "direction": "Left", "hash": "4vHM3fbdNwXGMp9uYzVKB13abEM6qdPUuZ9rfrdsaDzc" } ] } ], "status": { "Failure": { "ActionError": { "index": 0, "kind": { "FunctionCallError": { "ExecutionError": "Smart contract panicked: The account doesn't have enough balance" } } } } }, "transaction": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6InZvbG92eWsubmVhciIsImFtb3VudCI6IjEwMDAwMDAwMDAwMDAwMDAwMDAwIn0=", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer" } } ], "hash": "CKHzodHvFw4C87PazsniycYZZHm37CEWLE2u8VUUMU7r", "nonce": 12, "public_key": "ed25519:eLbduR3uJGaAHLXeGKEfo1fYmYFKkLyR1R8ZPCxrJAM", "receiver_id": "berryclub.ek.near", "signature": "ed25519:63MC3f8m5jeycpy97G9XaCwmJLx4YHRn2x5AEJDiYYzZ3TzdzWsrz8dgaz2kHR2jsWh35aZoL97tw1RRTHK6ZQYq", "signer_id": "serhii.near" }, "transaction_outcome": { "block_hash": "7YUgyBHgmbGy1edhaWRZeBVq9zzbnzrRGtVRQS5PpooW", "id": "CKHzodHvFw4C87PazsniycYZZHm37CEWLE2u8VUUMU7r", "outcome": { "executor_id": "serhii.near", "gas_burnt": 2428084223182, "logs": [], "receipt_ids": [ "5bdBKwS1RH7wm8eoG6ZeESdhNpj9HffUcf8RoP6Ng5d" ], "status": { "SuccessReceiptId": "5bdBKwS1RH7wm8eoG6ZeESdhNpj9HffUcf8RoP6Ng5d" }, "tokens_burnt": "242808422318200000000" }, "proof": [ { "direction": "Right", "hash": "Agyg5P46kSVa4ptG9spteHpZ5c8XkvfbmDN5EUXhC1Wr" }, { "direction": "Right", "hash": "3JDKkLCy5bJaAU3exa66sotTwJyGwyChxeNJgKReKw34" }, { "direction": "Right", "hash": "7GXEmeQEJdd4c2kgN7NoYiF2bkjzV4bNkMmkhpK14NTz" } ] } } } ```**Example Response:**
```json { "id": "myid", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "serhii.testnet", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6ImRldi0xNjIzNjkzMTIxOTU1LTcxNjY3NjMyNTMxMTc2IiwiYW1vdW50IjoiMTAiLCJtc2ciOiJ0YWtlLW15LW1vbmV5In0=", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer_call" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "Hw6z8kJ7CSaC6SgyQzcmXzNX9gq1gaAnLS169qgyZ2Vk", "receiver_id": "dev-1623333795623-21399959778159" }, { "predecessor_id": "dev-1623333795623-21399959778159", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "eyJzZW5kZXJfaWQiOiJzZXJoaWkudGVzdG5ldCIsImFtb3VudCI6IjEwIiwibXNnIjoidGFrZS1teS1tb25leSJ9", "deposit": "0", "gas": 70000000000000, "method_name": "ft_on_transfer" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [ { "data_id": "EiDQi54XHfdD1KEcgiNzogXxXuwTpzeQfmyqVwbq7H4D", "receiver_id": "dev-1623333795623-21399959778159" } ], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "EB69xtJiLRh9RNzAHgBGmom8551hrK2xSRreqbjvJgu5", "receiver_id": "dev-1623693121955-71667632531176" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "13116953530949529501760" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "AkwgvxUspRgy255fef2hrEWMbrMWFtnTRGduSgDRdSW1", "receiver_id": "serhii.testnet" }, { "predecessor_id": "dev-1623333795623-21399959778159", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "eyJzZW5kZXJfaWQiOiJzZXJoaWkudGVzdG5ldCIsInJlY2VpdmVyX2lkIjoiZGV2LTE2MjM2OTMxMjE5NTUtNzE2Njc2MzI1MzExNzYiLCJhbW91bnQiOiIxMCJ9", "deposit": "0", "gas": 5000000000000, "method_name": "ft_resolve_transfer" } } ], "gas_price": "186029458", "input_data_ids": [ "EiDQi54XHfdD1KEcgiNzogXxXuwTpzeQfmyqVwbq7H4D" ], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "4Tc8MsrJZSMpNZx7u4jSqxr3WhRzqxaNHxLJFqz8tUPR", "receiver_id": "dev-1623333795623-21399959778159" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "761030677610514102464" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "9rxcC9o8x4RX7ftsDCfxK8qnisYv45rA1HGPxhuukWUL", "receiver_id": "serhii.testnet" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "2137766093631769060520" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "H7YWFkvx16Efy2keCQ7BQ67BMEsdgdYLqJ99G4H3dR1D", "receiver_id": "serhii.testnet" } ], "receipts_outcome": [ { "block_hash": "B9yZz1w3yzrqQnfBFAf17S4TLaHakXJWqmFDBbFxaEiZ", "id": "Hw6z8kJ7CSaC6SgyQzcmXzNX9gq1gaAnLS169qgyZ2Vk", "outcome": { "executor_id": "dev-1623333795623-21399959778159", "gas_burnt": 20612680932083, "logs": [ "Transfer 10 from serhii.testnet to dev-1623693121955-71667632531176" ], "receipt_ids": [ "EB69xtJiLRh9RNzAHgBGmom8551hrK2xSRreqbjvJgu5", "4Tc8MsrJZSMpNZx7u4jSqxr3WhRzqxaNHxLJFqz8tUPR", "H7YWFkvx16Efy2keCQ7BQ67BMEsdgdYLqJ99G4H3dR1D" ], "status": { "SuccessReceiptId": "4Tc8MsrJZSMpNZx7u4jSqxr3WhRzqxaNHxLJFqz8tUPR" }, "tokens_burnt": "2061268093208300000000" }, "proof": [] }, { "block_hash": "7Z4LHWksvw7sKYKwpQfjEMG8oigjtRXKa3EopN7hS2v7", "id": "EB69xtJiLRh9RNzAHgBGmom8551hrK2xSRreqbjvJgu5", "outcome": { "executor_id": "dev-1623693121955-71667632531176", "gas_burnt": 3568066327145, "logs": [ "Sender @serhii.testnet is transferring 10 tokens using ft_on_transfer, msg = take-my-money" ], "receipt_ids": [ "AkwgvxUspRgy255fef2hrEWMbrMWFtnTRGduSgDRdSW1" ], "status": { "SuccessValue": "IjEi" }, "tokens_burnt": "356806632714500000000" }, "proof": [ { "direction": "Right", "hash": "5X2agUKpqmk7QkUZsDQ4R4HdX7zXeuPYpVAfvbmF5Gav" } ] }, { "block_hash": "CrSDhQNn72K2Qr1mmoM9j3YHCo3wfZdmHjpHJs74WnPk", "id": "AkwgvxUspRgy255fef2hrEWMbrMWFtnTRGduSgDRdSW1", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Right", "hash": "4WG6hF5fTAtM7GSqU8mprrFwRVbChGMCV2NPZEjEdnc1" } ] }, { "block_hash": "CrSDhQNn72K2Qr1mmoM9j3YHCo3wfZdmHjpHJs74WnPk", "id": "4Tc8MsrJZSMpNZx7u4jSqxr3WhRzqxaNHxLJFqz8tUPR", "outcome": { "executor_id": "dev-1623333795623-21399959778159", "gas_burnt": 6208280264404, "logs": [ "Refund 1 from dev-1623693121955-71667632531176 to serhii.testnet" ], "receipt_ids": [ "9rxcC9o8x4RX7ftsDCfxK8qnisYv45rA1HGPxhuukWUL" ], "status": { "SuccessValue": "Ijki" }, "tokens_burnt": "620828026440400000000" }, "proof": [ { "direction": "Left", "hash": "BzT8YhEDDWSuoGGTBzH2Cj5GC4c56uAQxk41by4KVnXi" } ] }, { "block_hash": "3Q2Zyscj6vG5nC2vdoYfcBHU9RVaAwoxHsHzAKVcAHZ6", "id": "9rxcC9o8x4RX7ftsDCfxK8qnisYv45rA1HGPxhuukWUL", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [] }, { "block_hash": "7Z4LHWksvw7sKYKwpQfjEMG8oigjtRXKa3EopN7hS2v7", "id": "H7YWFkvx16Efy2keCQ7BQ67BMEsdgdYLqJ99G4H3dR1D", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Left", "hash": "61ak42D3duBBunCz3w4xXxoEeR2N7oav5e938TnmGFGN" } ] } ], "status": { "SuccessValue": "Ijki" }, "transaction": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6ImRldi0xNjIzNjkzMTIxOTU1LTcxNjY3NjMyNTMxMTc2IiwiYW1vdW50IjoiMTAiLCJtc2ciOiJ0YWtlLW15LW1vbmV5In0=", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer_call" } } ], "hash": "5n1kwA3TQQyFTkddR2Jau3H1Pt8ebQNGaov6aCQ6TDp1", "nonce": 47589658000040, "public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN", "receiver_id": "dev-1623333795623-21399959778159", "signature": "ed25519:256qp2jAGXhhw2t2XfUAjWwzz3XcD83DH2v9THwDPsZjCLWHU8QJd6cuA773NP9yBmTd2ZyYiFHuxVEkYqnbsaSb", "signer_id": "serhii.testnet" }, "transaction_outcome": { "block_hash": "96k8kKzFuZWxyiUnT774Rg7DC3XDZNuxhxD1qEViFupd", "id": "5n1kwA3TQQyFTkddR2Jau3H1Pt8ebQNGaov6aCQ6TDp1", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 2428149065268, "logs": [], "receipt_ids": [ "Hw6z8kJ7CSaC6SgyQzcmXzNX9gq1gaAnLS169qgyZ2Vk" ], "status": { "SuccessReceiptId": "Hw6z8kJ7CSaC6SgyQzcmXzNX9gq1gaAnLS169qgyZ2Vk" }, "tokens_burnt": "242814906526800000000" }, "proof": [] } } } ```**Example response**:
```json { "id": "myid", "jsonrpc": "2.0", "result": { "receipts": [ { "predecessor_id": "serhii.testnet", "receipt": { "Action": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6ImRldi0xNjIzMzMzOTE2MzY4LTU4NzA3NDM0ODc4NTMzIiwiYW1vdW50IjoiMTAwMDAwMDAwMCIsIm1zZyI6InRha2UtbXktbW9uZXkifQ==", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer_call" } } ], "gas_price": "186029458", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "83AdQ16bpAC7BEUyF7zoRsAgeNW7HHmjhZLvytEsrygo", "receiver_id": "dev-1623333795623-21399959778159" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "1" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "system", "signer_public_key": "ed25519:11111111111111111111111111111111" } }, "receipt_id": "Euy4Q33DfvJTXD8HirE5ACoXnw9PMTQ2Hq47aGyD1spc", "receiver_id": "serhii.testnet" }, { "predecessor_id": "system", "receipt": { "Action": { "actions": [ { "Transfer": { "deposit": "18681184841157733814920" } } ], "gas_price": "0", "input_data_ids": [], "output_data_receivers": [], "signer_id": "serhii.testnet", "signer_public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN" } }, "receipt_id": "6ZDoSeV3gLFS2NXqMCJGEUR3VwBpSxBEPjnEEaAQfmXL", "receiver_id": "serhii.testnet" } ], "receipts_outcome": [ { "block_hash": "BohRBwqjRHssDVS9Gt9dj3SYuipxHA81xXFjRVLqgGeb", "id": "83AdQ16bpAC7BEUyF7zoRsAgeNW7HHmjhZLvytEsrygo", "outcome": { "executor_id": "dev-1623333795623-21399959778159", "gas_burnt": 3734715409940, "logs": [], "receipt_ids": [ "Euy4Q33DfvJTXD8HirE5ACoXnw9PMTQ2Hq47aGyD1spc", "6ZDoSeV3gLFS2NXqMCJGEUR3VwBpSxBEPjnEEaAQfmXL" ], "status": { "Failure": { "ActionError": { "index": 0, "kind": { "FunctionCallError": { "ExecutionError": "Smart contract panicked: The account doesn't have enough balance" } } } } }, "tokens_burnt": "373471540994000000000" }, "proof": [] }, { "block_hash": "4BzTmMmTjKvfs6ANS5gmJ6GQzhqianEGWq7SaxSfPbdC", "id": "Euy4Q33DfvJTXD8HirE5ACoXnw9PMTQ2Hq47aGyD1spc", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Right", "hash": "5ipmcdgTieQqFXWQFCwcbZhFtkHE4PL4nW3mknBchpG6" } ] }, { "block_hash": "4BzTmMmTjKvfs6ANS5gmJ6GQzhqianEGWq7SaxSfPbdC", "id": "6ZDoSeV3gLFS2NXqMCJGEUR3VwBpSxBEPjnEEaAQfmXL", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 0, "logs": [], "receipt_ids": [], "status": { "SuccessValue": "" }, "tokens_burnt": "0" }, "proof": [ { "direction": "Left", "hash": "9tcjij6M8Ge4aJcAa97He5nw8pH7PF8ZjRHVahBZD2VW" } ] } ], "status": { "Failure": { "ActionError": { "index": 0, "kind": { "FunctionCallError": { "ExecutionError": "Smart contract panicked: The account doesn't have enough balance" } } } } }, "transaction": { "actions": [ { "FunctionCall": { "args": "eyJyZWNlaXZlcl9pZCI6ImRldi0xNjIzMzMzOTE2MzY4LTU4NzA3NDM0ODc4NTMzIiwiYW1vdW50IjoiMTAwMDAwMDAwMCIsIm1zZyI6InRha2UtbXktbW9uZXkifQ==", "deposit": "1", "gas": 100000000000000, "method_name": "ft_transfer_call" } } ], "hash": "FQsh44pvEsK8RS9AbK868CmGwfhUU2pUrizkQ6wCWTsB", "nonce": 47589658000031, "public_key": "ed25519:5UfEFyve3RdqKkWtALMreA9jzsAGDgCtwEXGNtkGeruN", "receiver_id": "dev-1623333795623-21399959778159", "signature": "ed25519:2cPASnxKtCoQtZ9NFq63fg8RzpjvmmE8hL4s2jk8zuhnBCD3AnYQ6chZZrUBGwu7WrsGuWUyohP1bEca4vfbsorC", "signer_id": "serhii.testnet" }, "transaction_outcome": { "block_hash": "FwHUeqmYpvgkL7eBrUUAEMCuaQshcSy5vm4AHchebhK1", "id": "FQsh44pvEsK8RS9AbK868CmGwfhUU2pUrizkQ6wCWTsB", "outcome": { "executor_id": "serhii.testnet", "gas_burnt": 2428166952740, "logs": [], "receipt_ids": [ "83AdQ16bpAC7BEUyF7zoRsAgeNW7HHmjhZLvytEsrygo" ], "status": { "SuccessReceiptId": "83AdQ16bpAC7BEUyF7zoRsAgeNW7HHmjhZLvytEsrygo" }, "tokens_burnt": "242816695274000000000" }, "proof": [] } } } ```### Gas Units Every action in NEAR costs a fixed amount of **gas units**, meaning that the same operation will always cost the **same amount of gas units**. Gas units were engineered in such a way that they can be translated into compute resources, where `1Tgas` gets you approx. `1ms` of compute time. Transactions can use a maximum of `300Tgas`, meaning they should be processed in less than `300ms`, allowing the network to produce a new block approximately **every second**. :::tip Gas units encapsulate not only compute/CPU time but also bandwidth/network time and storage/IO time :::
### Gas Price To determine the actual $NEAR fee, the cost of all actions in the transaction is multiplied by a **gas price**. The gas price is **recalculated each block** based on the network's demand and floor at `1Tgas = 0.0001Ⓝ`. If the previous block is **more than half full** the price goes up by 1%, otherwise it goes down by 1% (until it reaches the floor).
What is the gas price now?
You can query how much a gas unit costs in `yoctoNEAR` (1Ⓝ = `1e24` yocto) through the [`RPC`](/api/rpc/gas#gas-price). To convert in `Tgas` per `NEAR`, you can use the following formula: `gas_price * 1e12 / 1e24`. Right now, 1 Tgas costs:### Cost for Common Actions Knowing that actions have a fixed cost in gas units, we can calculate the cost of common operations at the minimum gas price of `1Tgas = 0.0001Ⓝ`. | Action | TGas | Fee (Ⓝ) | |------------------------------|----------------|----------| | Create Account | 0.42 | 0.000042 | | Transfer NEAR | 0.45 | 0.000045 | | Add Full Access Key | 0.42 | 0.000042 | | Delete Key | 0.41 | 0.000041 | | Function Call* | ≤ 300 | ≤ 0.03 | | Deploying a `16`kb contract | 2.65 | 0.000265 | | Deploying a `X`kb contract** | 0.58 + 0.13`X` | | _Note that the fee is in $NEAR, to obtain the cost in dollars multiply by the current price of $NEAR_ :::tip Function Calls* The cost of calling a function will depend on how complex the function is, but will be consistent across function calls. Learn more below. ::: :::tip Deploying a Contract** Note that this covers the gas cost of uploading and writing bytes to storage, but does **not** cover the cost of holding them in storage (which is `1Ⓝ ~ 100kb`). :::
Where do these numbers come from?
NEAR is [configured](https://github.com/near/nearcore/blob/master/core/primitives/res/runtime_configs/parameters.yaml) with base costs. An example: ```json transfer_cost: { send_sir: 115123062500, send_not_sir: 115123062500, execution: 115123062500 }, deploy_contract_cost: 184765750000, deploy_contract_cost_per_byte: 64572944 ``` The "sir" here stands for "sender is receiver". Yes, these are all identical, but that could change in the future. When you make a request to transfer funds, NEAR immediately deducts the appropriate `send` amount from your account. Then it creates a [_receipt_, an internal book-keeping mechanism](./transaction-execution.md). Creating a receipt has its own associated costs: ```json action_receipt_creation_config: { send_sir: 108059500000, send_not_sir: 108059500000, execution: 108059500000 } ``` You can query this value by using the [`protocol_config`](/api/rpc/protocol#protocol-config) RPC endpoint and search for `action_receipt_creation_config`. The appropriate amount for creating this receipt is also immediately deducted from your account. The "transfer" action won't be finalized until the next block. At this point, the `execution` amount for each of these actions will be deducted from your account. Although gas prices can change between the time of purchase and time of execution, the gas price per transaction is fixed since protocol version 78. ``` ( transfer_cost.send_not_sir + action_receipt_creation_config.send_not_sir + transfer_cost.execution + action_receipt_creation_config.execution ) * gas_price ``` Prior to protocol version 78, the gas prices of each block was used for the work done at that height. ``` ( transfer_cost.send_not_sir + action_receipt_creation_config.send_not_sir ) * gas_price_at_block_1 + ( transfer_cost.execution + action_receipt_creation_config.execution ) * gas_price_at_block_2 ```Gas Refund Fee
Since protocol version 78, the unspent gas at the end of receipt execution is subject to a gas refund fee. The fee is still at 0 while we give projects time to adapt. The plan is to move to a fee calculated as `max(1 Tgas, 0.05 * unspent_gas) * gas_price`. The gas price is from the time of purchase. _But why introducing such a fee instead of refunding all gas?_ The reason is that attaching too much gas to function calls makes the network less efficient. Congestion control between shards gets tricky when transactions have much more gas attached than they actually use. The network limits how many cross contract calls can target a single shard per chunk, to avoid huge queues of incoming receipts on a shard. This limit sees the attached gas as an upper boundary for how much work the receipt causes on the receiving shard. Attaching too much gas can cause this limit to become too restrictive, which stalls shards unnecessarily. The other inefficiency comes from the refund receipts that prior to version 78 have been created for essentially every function call. While each of them is relatively cheap to execute, in the sum they were a significant part of the global traffic on NEAR Protocol. To read more about the deicsion to introduce this fee, please take a look at the [NEP-536](https://github.com/near/NEPs/pull/536)Derivation Paths
A NEAR account will always derive the same address on the foreign blockchain using the same derivation path Notice that, since the foreign address is derived from the NEAR account name, it is not possible for another NEAR account to control the same address### Running the Frontend To start the frontend you will need to install the dependencies and start the server. ```bash cd frontend yarn yarn dev ``` Go ahead and login with your NEAR account. If you don't have one, you will be able to create one in the moment. Once logged in, you will be able to sign a message in the guest book. You can further send some money alongside your message. If you attach more than 0.01Ⓝ then your message will be marked as "premium".
### Understanding the Frontend The frontend is a [Next.JS](https://nextjs.org/) project generated by [create-near-app](https://github.com/near/create-near-app). Check `_app.js` and `index.js` to understand how components are displayed and interacting with the contract.
📖 NEAR Guest Book
{signedAccountId ? ( ) : (### Testing the Contract The contract readily includes a set of unit and sandbox testing to validate its functionality. To execute the tests, run the following commands:
### Deploying the Contract to the NEAR network In order to deploy the contract you will need to create a NEAR account.
### CLI: Interacting with the Contract To interact with the contract through the console, you can use the following commands. #### Get messages
#### Get total number of messages
#### Add a message
:::tip If you're using your own account, replace `guestbook.near-examples.testnet` with your `accountId`. ::: --- ## Moving Forward A nice way to learn is by trying to expand a contract. You can modify the guestbook example to incorporate a feature where users can give likes to messages. Additionally, implement a method to toggle the like.
Locker Contract participant MPC as MPC Service
(off-chain) participant Other as Destination Chain note over User, Bridge: NEAR Blockchain User->>Bridge:1. Submits transfer
token request Bridge->>Bridge: 2. Locks tokens Bridge->>MPC: 3. Request signature MPC->>MPC: 3. Signs message MPC-->>Bridge: 4. Return signed msg Bridge->>Other: 5. Broadcast signed msg to destination chain Other->>Other: 4. Mint/release tokens ``` To get started building with Omni Bridge, see: - [Bridge SDK JS](https://github.com/near-one/bridge-sdk-js) Omni Bridge implementation in JavaScript - [Bridge SDK Rust](https://github.com/near-one/bridge-sdk-rs) Omni Bridge implementation in Rust --- # Source: https://docs.near.org/chain-abstraction/omnibridge/implementation-details.md --- id: implementation-details sidebar_label: Implementation Details title: Implementation Details description: "Explore Omni Bridge's technical architecture" --- The Omni Bridge is a sophisticated cross-chain bridge infrastructure that enables secure and efficient token transfers between NEAR Protocol and various other blockchain networks. This document provides a detailed technical overview of the bridge's architecture, covering its core components, security model, and operational mechanisms. By leveraging a combination of Multi-Party Computation (MPC), chain-specific light clients, and a permissionless relayer network, the bridge achieves a robust balance of security, decentralization, and user experience. For reference code implementations, see: - [Bridge SDK JS](https://github.com/near-one/bridge-sdk-js) Omni Bridge implementation in JavaScript - [Bridge SDK Rust](https://github.com/near-one/bridge-sdk-rs) Omni Bridge implementation in Rust --- ## The Bridge Token Factory Pattern At the core of Omni Bridge is the Bridge Token Factory contract on NEAR that serves as both a token factory and custodian. This unified contract handles both native tokens from the source chain and bridged tokens created by the factory itself. This design simplifies maintenance and reduces complexity compared to having separate contracts. The contract has several key responsibilities: ### For bridged tokens (tokens originally from other chains): * Deploys new token contracts when bridging tokens for the first time * Mints tokens when receiving valid transfer messages * Burns tokens when initiating transfers back to the origin chain ### For native NEAR tokens: * Acts as a custodian by locking tokens during transfers * Releases tokens when receiving valid transfer messages * Manages token operations through the NEP-141 standard ### Transfer Lifecycle A transfer's lifecycle includes several states, shown below for a NEAR to Ethereum transfer of native NEAR tokens: ```mermaid stateDiagram-v2 [*] --> Initiated: User calls transfer Initiated --> Locked: Tokens locked in bridge Locked --> Signed: MPC signature generated Signed --> Completed: Tokens released on Ethereum Completed --> [*] ``` --- ## Message Signing and Verification For most chains, the bridge uses a payload-based message signing system (with Bitcoin being a notable exception requiring full transaction signing). ### Message Types The bridge supports several types of signed messages: * **Transfer Messages** * Initiation messages * Finalization messages * **Token Messages** * Deployment messages * Metadata update messages ### Payload Structure Messages are encoded using Borsh serialization and contain: | Component | Description | |-----------|-------------| | Message Type | Identifier for the message category | | Chain Info | Chain IDs and relevant addresses | | Operation Data | Amounts, recipients, fees, etc. | ### Signature Process 1. NEAR contract creates and stores the message payload 2. MPC network observers detect valid payloads 3. Nodes jointly sign the payload 4. Signature is verified on destination chains :::tip Key Benefits * Clearer message intent through structured payloads * More efficient signature verification on destination chains * Standardized message format across chains ::: ## Transaction Flow: NEAR to Other Chains Here's an overview of how transfers are processed from NEAR to different destination chains: ```mermaid flowchart TD Start[User Initiates Transfer] --> TokenCheck{Token Type?} TokenCheck -->|NEAR Native| Lock[Lock in Bridge Contract] TokenCheck -->|Bridged Token| Burn[Burn Token] Lock --> MPCSign[Request MPC Signature] Burn --> MPCSign MPCSign --> Chain{Destination Chain} Chain -->|Bitcoin| BTCBridge[Bitcoin Script] Chain -->|Other| OtherBridge[Verify MPC Signature] BTCBridge --> Mint[Mint/Release Tokens] OtherBridge --> Mint Mint --> End[Transfer Complete] ``` ### Transfer Process Let's follow what happens when a user wants to transfer tokens from NEAR to another chain: #### 1. Initiation The user starts by calling the token contract with: * Amount to transfer * Destination chain and address * Fee preferences (whether to pay fees in the token being transferred or in NEAR) * Fees are minted on NEAR side for relayers #### 2. Token Lock The token contract transfers tokens to the locker contract, which: * Validates the transfer message * Assigns a unique nonce * Records the pending transfer * Emits a transfer event #### 3. MPC Signing The bridge contract: * Requests signature generation * MPC nodes jointly generate and aggregate signature * Maintains threshold security throughout process #### 4. Destination Chain The Bridge Token Factory on the destination chain: * Verifies the MPC signature * Mints equivalent tokens --- ## Transaction Flow: Other Chains to NEAR The reverse flow varies based on the source chain: ### 1. Ethereum Uses NEAR light client for maximum security: * Burning tokens on source chain * Submitting proof to NEAR * Verifying proof through light client * Releasing tokens to recipient ### 2. Supported Non-EVM Chains (e.g., Solana) Utilize established message passing protocols (such as Wormhole) for: * Message passing between chains * Transaction verification * Integration with NEAR token factory system ### 3. Other EVM Chains Utilize a combination of light clients (where efficient) and message passing protocols to ensure secure verification of inbound transfers. --- ## Transaction Flow: Chain to Chain (via NEAR) For transfers between two non-NEAR chains (e.g., Ethereum to Solana), the bridge combines both flows using NEAR as an intermediary routing layer. Rather than minting or unlocking tokens on NEAR, the bridge creates a forwarding message that directs tokens to be minted or unlocked on the final destination chain. From the user's perspective, this appears as a single operation - they initiate the transfer on the source chain, and the off-chain relayer infrastructure handles the intermediate NEAR routing automatically. --- ## Security Model ### Trust Assumptions Omni Bridge requires different trust assumptions depending on the chain connection: #### For Chain Signatures: * NEAR Protocol security (2/3+ honest validators) * MPC network security (2/3+ honest nodes) * No single entity controls enough MPC nodes to forge signatures * Correct implementation of the signing protocol #### For Ethereum/Bitcoin connections: * Light client security * Finality assumptions (e.g., sufficient block confirmations) * Chain-specific consensus assumptions #### For Message Passing connections: * Security of the underlying message passing protocol (e.g., Wormhole Guardian network) * Verified by NEAR network participants (e.g., validators and full nodes) --- ## Relayer Network Relayers are permissionless infrastructure operators who monitor for bridge events and execute cross-chain transactions. Unlike many bridge designs, our relayers cannot: * Forge transfers * Steal funds * Censor transactions (users can self-relay) * Front-run transactions for profit * Do not create additional security assumptions :::info The relayer's role is purely operational - executing valid transfers and collecting predetermined fees. Multiple relayers can operate simultaneously, creating competition for faster execution and lower fees. ::: --- ## Fast Transfers Standard cross-chain transfers can take time due to finality and verification requirements. **Fast Transfers** allow relayers to expedite this process by fronting liquidity. ### How it Works 1. **User Initiation:** A user sends a `FastFinTransferMsg` specifying the destination and fee. 2. **Relayer Execution:** A relayer detects the request and instantly transfers the equivalent amount (minus fees) to the user on the destination chain from their own funds. 3. **Settlement:** The bridge later reimburses the relayer once the original transfer is fully verified and finalized. :::tip Fast transfers are ideal for users who prioritize speed over cost, as relayers may charge a premium for the liquidity and convenience. ::: --- ## Multi-Token Support (ERC1155) Omni Bridge supports the **ERC1155** standard, enabling the transfer of multiple token types within a single contract. ### Address Derivation To maintain consistency across chains, bridged ERC1155 tokens use a deterministic address derivation scheme: * **Deterministic Address:** `keccak256(tokenAddress + tokenId)` * This ensures that each `tokenId` within an ERC1155 contract maps to a unique, consistent address on the destination chain. ### Key Functions * **`initTransfer1155`**: Initiates a transfer for a specific ERC1155 token ID. * **`logMetadata1155`**: Registers metadata for a specific token ID, ensuring it is recognized by indexers and wallets. --- ## Fee Structure Bridge fees are unified and processed on NEAR, with components including: ### Execution Fees * Destination chain gas costs * Source chain storage costs * Relayer operational costs * MPC signing costs ### Fee Payment Options * Native tokens of source chain * The token being transferred :::note Fees dynamically adjust based on gas prices across different chains to ensure reliable execution. ::: ### Design Goals The fee structure is designed to: * Ensure relayer economic viability * Prevent economic attacks * Allow fee market competition * Cover worst-case execution costs :::tip Users can bypass relayers entirely by executing their own transfers, paying only the necessary gas fees on each chain. This creates a natural ceiling on relayer fees. ::: --- # Source: https://docs.near.org/chain-abstraction/chain-signatures/implementation.md --- id: implementation title: Implementing Chain Signatures description: "Learn how to sign transactions across multiple blockchains." --- Chain signatures enable NEAR accounts, including smart contracts, to sign and execute transactions across many blockchain protocols. This unlocks the next level of blockchain interoperability by giving ownership of diverse assets, cross-chain accounts, and data to a single NEAR account.
Supported Networks
While you can sign transactions for any network using Eddsa or Ecdsa keys, each chain signs transactions differently. Our example implementation shows you how to sign transactions for: Bitcoin, Solana, Cosmos, XRP, Aptos, Sui and EVM networks (Ethereum, Base, BNB Chain, Avalanche, Polygon, Arbitrum, and more).EVM Function Calls
To call a function on a smart contract we need the ABI of the contract, in our repo this is defined in the [config.js](https://github.com/near-examples/near-multichain/blob/main/src/config.js#L23-L63) file (this can be gathered from Remix or using Etherscan). Then define a `Contract` object using the `ethers` library ``` const contract = new Contract(contractAddress, ABI, provider); ``` Then to construct the transaction ``` const data = contract.interface.encodeFunctionData("set", [number]); return await Evm.prepareTransactionForSigning({ from: senderAddress, to: contractAddress, data, }); }, ``` This approach allows you to call smart contract functions by encoding the function data and including it in the transaction.### Subaccount
### Using Secret Key
### Using Credentials From File
### Loading From File
### Deploy To Account
### View
1. Setting the `Worker` network to `testnet`
When creating Worker set network to `testnet` and pass your master account (an account for which you have the private key): ```ts const worker = await Worker.init({ network: 'testnet', testnetMasterAccountId: '2. Setting environment variables
Set the `NEAR_WORKSPACES_NETWORK` and `TESTNET_MASTER_ACCOUNT_ID` (an account for which you have the private key) environment variables when running your tests: ```bash NEAR_WORKSPACES_NETWORK=testnet TESTNET_MASTER_ACCOUNT_ID=3. Config file
If you are using AVA, you can use a custom config file. Other test runners allow similar config files; adjust the following instructions for your situation. Create a file in the same directory as your `package.json` called `ava.testnet.config.cjs` with the following contents: ```js module.exports = { ...require('near-workspaces/ava.testnet.config.cjs'), ...require('./ava.config.cjs'), }; module.exports.environmentVariables = { TESTNET_MASTER_ACCOUNT_ID: '### Snippet II: Testing Donations In most cases we will want to test complex methods involving multiple users and money transfers. A perfect example for this is our [Donation Example](https://github.com/near-examples/donation-examples), which enables users to `donate` money to a beneficiary. Lets see its integration tests
### Test Driven Design Using Workspaces and AVA {#test-driven-design} The video below walks through how to apply TDD with Workspaces and AVA for a simple contract: --- # Source: https://docs.near.org/integrations/errors/introduction.md # Source: https://docs.near.org/api/rpc/introduction.md # Source: https://docs.near.org/tutorials/multichain-dao/introduction.md # Source: https://docs.near.org/tutorials/controlling-near-accounts/introduction.md # Source: https://docs.near.org/tutorials/auction/introduction.md # Source: https://docs.near.org/primitives/lockup/introduction.md # Source: https://docs.near.org/web3-apps/tutorials/localnet/introduction.md # Source: https://docs.near.org/smart-contracts/testing/introduction.md # Source: https://docs.near.org/ai/shade-agents/getting-started/introduction.md # Source: https://docs.near.org/ai/introduction.md --- id: introduction title: AI and NEAR sidebar_label: Introduction description: "Introduction to NEAR's User-Owned AI vision, featuring Shade Agents and NEAR AI." --- Building AI agents that control accounts and assets on all blockchains has never been easier. NEAR enables AI agents to transact on any chain, while our **Shade Agent Framework** allows to create verifiable and trustless AI agents with multi-chain capabilities out of the box.  :::tip Using AI to build on NEAR? Searching for how to use AI to help you build NEAR dApps, check our [Building NEAR Apps with AI](./llms.md) documentation ::: --- ## Let Your Agent use NEAR AI Agents can easily control account and assets on all blockchains thanks to NEARs unique features. You simply need to give them access to a NEAR account and they can start interacting with smart contracts, sending transactions, and managing assets everywhere. Check our [NEAR MCP](./near-mcp.md) documentation to get started. --- ## Build Trustless Multi-Chain Agents The [Shade Agent Framework](./shade-agents/getting-started/introduction.md) enables to build **verifiable** **multi-chain AI agents**. These agents operate in Trusted Execution Environments (TEEs) and leverage NEAR features such as multi-key management and Chain Signatures to securely manage assets and sign transactions across multiple blockchains. Shade agents can autonomously sign transactions on any chain, interact with AI models and external data sources, and perform privacy-preserving, verifiable computations. :::info Shade Agents power [Agentic Protocols](./shade-agents/concepts/what-can-you-build#agentic-protocols): a new type of decentralized application designed to be autonomous, proactive, and intelligent. ::: --- ## Which Docs Should I Use? | Docs | Best if you... | |--------------------------------------------------------------------------------|------------------------------------------------------------------------------------------| | [AI + NEAR](./near-mcp.md) | Already have an AI Agent, and want to connect it to NEAR (and other chains) | | [Building NEAR Apps with AI](./llms.md) | Are building a NEAR App, and want your Code Agents to help you better | | [Trustless Multi-chain Agents](./shade-agents/getting-started/introduction.md) | Are building an agent from zero and need to securely handle funds across multiple chains | --- ## Common Questions ### Can Trustless Agents lose access to their wallets? Not with Shade Agents. They use decentralized key management—any instance of the agent with the same code can access the same accounts. ### Do I need to know blockchain development? Our tools and resources help to abstract away the complexity of blockchain development. ### What chains can my agent interact with? NEAR accounts allow to transact on all chains, including Bitcoin, Ethereum and Solana thanks to Chain Signatures. --- # Source: https://docs.near.org/data-infrastructure/tutorials/running-near-lake/lake-start-options.md --- title: Start options id: lake-start-options description: "Learn how to create an indexer using the NEAR Lake Framework." --- This tutorial will guide you through creating a simple indexer using the NEAR Lake Framework that can start from a specified block height, the latest final block, or the last indexed block. ### Start Options There are three options to start an indexer using NEAR Lake Framework: - from specified block height (out of the box) ```bash ./target/release/indexer mainnet from-block 65359506 ``` - from the latest final block from the network ```bash ./target/release/indexer mainnet from-latest ``` - from the block indexer has indexed the last before it was interrupted ```bash ./target/release/indexer mainnet from-interruption ``` --- ## Motivation To find out whether you need an indexer for you project and to create one means you're covering only one side of things - the development. There is another important side - the maintenance. This involves: - indexer needs to be upgraded with a newer version of dependencies - indexer needs to be updates with a new features you've made - your server needs some maintenance - incident had happened - etc. Almost in all of the above cases you might want to start or restart your indexer not only from the specific block you need to provide, but from the block it was stopped, or from the latest final block in the network. [NEAR Lake Framework](/data-infrastructure/near-lake-framework) doesn't provide such options. Actually, we didn't empower the library with these options to start indexer intentionally. :::info Intent We want to keep [NEAR Lake Framework](/data-infrastructure/near-lake-framework) crate in the narrowest possible way. The goal for the library is to do a single job and allow it to be empowered with any features but outside of the crate itself ::: Though, the possibility to start indexer from the latest block or from the block after the one it has indexed the last, might be very useful. Also, during [the April Data Platform Community Meeting](https://github.com/near/indexers-docs/blob/main/blog/2022-05-11-community-meeting-record.mdx) we had a question whether we plan to add this feature to the library. We've promised to create a tutorial showing how to do it by your own. So here it is. --- ## Preparation In this tutorial we're not going to focus our attention on the indexer itself, but on the start options instead. :::note To simplify the code samples in the tutorial, we're writing entire application in a single file `src/main.rs`. **Please, do not take it as a design advice. We do it only for the simplicity** ::: Let's prepare a project with a base dependencies, so we can focus on the main goal of this tutorial. Create a new Rust project ```bash cargo new --bin indexer && cd indexer ``` Replace the content of the `Cargo.toml` file with this: ```toml title=Cargo.toml [package] name = "indexer" version = "0.1.0" edition = "2021" rust-version = "1.60.0" [dependencies] clap = { version = "3.1.6", features = ["derive"] } futures = "0.3.5" itertools = "0.9.0" tokio = { version = "1.1", features = ["sync", "time", "macros", "rt-multi-thread"] } tokio-stream = { version = "0.1" } tracing = "0.1.13" tracing-subscriber = "0.2.4" serde = { version = "1", features = ["derive"] } serde_json = "1.0.55" near-lake-framework = "0.3.0" ``` Replace the content of `src/main.rs` with this: ```rust use clap::{Parser, Subcommand}; use futures::StreamExt; use tracing_subscriber::EnvFilter; // TODO: StartOptions #[tokio::main] async fn main() -> Result<(), tokio::io::Error> { init_tracing(); let opts = Opts::parse(); // TODO: Config let stream = near_lake_framework::streamer(config); let mut handlers = tokio_stream::wrappers::ReceiverStream::new(stream) .map(handle_streamer_message) .buffer_unordered(1usize); while let Some(_handle_message) = handlers.next().await {} Ok(()) } async fn handle_streamer_message( streamer_message: near_lake_framework::near_indexer_primitives::StreamerMessage, ) { eprintln!( "{} / shards {}", streamer_message.block.header.height, streamer_message.shards.len() ); std::fs::write("last_indexed_block", streamer_message.block.header.height.to_string().as_bytes()).unwrap(); } fn init_tracing() { let mut env_filter = EnvFilter::new("near_lake_framework=info"); if let Ok(rust_log) = std::env::var("RUST_LOG") { if !rust_log.is_empty() { for directive in rust_log.split(',').filter_map(|s| match s.parse() { Ok(directive) => Some(directive), Err(err) => { eprintln!("Ignoring directive `{}`: {}", s, err); None } }) { env_filter = env_filter.add_directive(directive); } } } tracing_subscriber::fmt::Subscriber::builder() .with_env_filter(env_filter) .with_writer(std::io::stderr) .init(); } ``` This code is not going to build yet. Meanwhile let's have a quick look of what we've copy/pasted for now: - We have imported [`clap`](https://docs.rs/clap/latest/clap/) to set up what command line arguments we're going to accept - Also, we've important necessary stuff like `futures` and `tracing_subscriber` - `init_tracing` in the end of the file is a helper function that subscribes our application to the logs from `near-lake-framework` - An asynchronous `main` function with the indexer boilerplate code, but missing the `LakeConfig` creation part we're going to cover in the tutorial. - You can find a few `// TODO: ...` sections we've marked for you to find places to write the code from this tutorial. OK, all the preparations are done. Let's move on. --- ## Design the `StartOptions` So we want to be able to pass a command that defines the way our indexer should start. In this tutorial we'll be using `clap`. We need a structure that receives the chain id. This will allow us to use command: ```bash ./target/release/indexer mainnet ... ``` OR ```bash ./target/release/indexer testnet ... ``` Let's replace the `// TODO: StartOptions` in the `src/main.rs` with: ```rust title=src/main.rs #[derive(Parser, Debug, Clone)] #[clap(version = "0.1", author = "Near Inc.
### `FromLatest` In order to query the JSON RPC from within Rust code we need to use [`near-jsonrpc-client-rs` crate](https://github.com/near/near-jsonrpc-client-rs) You can find a [bunch of useful examples](https://github.com/near/near-jsonrpc-client-rs/tree/master/examples) in the corresponding folder of the project's repository on GitHub. Add it to `Cargo.toml` in the end: ```toml title=Cargo.toml near-jsonrpc-client = "0.3.0" ``` The code for getting the final block height would look like the following: ```rust use near_jsonrpc_client::{methods, JsonRpcClient}; use near_lake_framework::near_indexer_primitives::types::{BlockReference, Finality}; async fn final_block_height() -> u64 { let client = JsonRpcClient::connect("https://rpc.mainnet.near.org"); let request = methods::block::RpcBlockRequest { block_reference: BlockReference::Finality(Finality::Final), }; let latest_block = client.call(request).await.unwrap(); latest_block.header.height } ``` Nice and easy. Though, a hardcoded value of `"https://rpc.mainnet.near.org"` looks not so great. Especially when we want to support both networks. But we can handle it by passing the JSON RPC URL to the `get_start_block_function` like this: ```rust title=src/main.rs async fn get_start_block_height( start_options: &StartOptions, rpc_url: &str, ) -> u64 { ... } ... match &opts.chain_id { ChainId::Mainnet(start_options) => { lake_config_builder = lake_config_builder .mainnet() .start_block_height( get_start_block_height( start_options, "https://rpc.mainnet.near.org", ).await ); } ChainId::Testnet(start_options) => { lake_config_builder = lake_config_builder .testnet() .start_block_height( get_start_block_height( start_options, "https://rpc.testnet.near.org", ).await ) } } ``` Meh. It's ugly and why should we pass it everytime if it is required in only one case from three possible? Instead we can pass to the `get_start_block_height` function the entire `Opts`. ```rust title=src/main.rs async fn get_start_block_height(opts: &Opts) -> u64 { match opts.chain_id { ChainId::Mainnet(start_options) => { match start_options { StartOptions::FromBlock { height } => height, StartOptions::FromLatest => } } } } ``` At least we have everything we need. Though, it still looks ugly and will definitely involve code duplication. What we propose instead to is create `impl Opts` with a few useful methods to get JSON RPC URL and to get `StartOptions` instance. **Now you may proceed copying the code safely** Somewhere under the `StartOptions` definition add the following: ```rust title=src/main.rs impl Opts { pub fn rpc_url(&self) -> &str { match self.chain_id { ChainId::Mainnet(_) => "https://rpc.mainnet.near.org", ChainId::Testnet(_) => "https://rpc.testnet.near.org", } } pub fn start_options(&self) -> &StartOptions { match &self.chain_id { ChainId::Mainnet(args) | ChainId::Testnet(args) => args } } } ``` And now we can create our `get_start_block_height` function with the helper function that will query the final block `final_block_height` (we're going to reuse it, watch for the hands): ```rust title=src/main.rs async fn get_start_block_height(opts: &Opts) -> u64 { match opts.start_options() { StartOptions::FromBlock { height } => *height, StartOptions::FromLatest => final_block_height(opts.rpc_url()).await, // a placeholder StartOptions::FromInterruption => 0, } } async fn final_block_height(rpc_url: &str) -> u64 { let client = JsonRpcClient::connect(rpc_url); let request = methods::block::RpcBlockRequest { block_reference: BlockReference::Finality(Finality::Final), }; let latest_block = client.call(request).await.unwrap(); latest_block.header.height } ``` You may have noticed the `FromInterruption` and a comment about the placeholder. The reason we've made is to be able to build the application right now to test out that `FromLatest` works as expected.
### Testing `FromLatest` :::danger Credentials Please, ensure you've the credentials set up as described on the [Credentials](credentials.md) page. Otherwise you won't be able to get the code working. ::: Let's try to build and run our code ```bash cargo build --release ./target/release/indexer mainnet from-latest ``` Once the code is built you should see something like that in your terminal: ``` 65364116 / shards 4 65364117 / shards 4 65364118 / shards 4 65364119 / shards 4 65364120 / shards 4 ``` You can stop it by pressing `CTRL+C` And now we can move on to `FromInterruption`
### `FromInterruption` In order to let an indexer know at what block it was interrupted, the indexer needs to store the block height somewhere. And it should do it in the and of the `handle_message` function. In the boilerplate code you've copy/pasted in the beginning of this tutorial you can notice a line of code: ```rust std::fs::write("last_indexed_block", streamer_message.block.header.height.to_string().as_bytes()).unwrap(); ``` It saves the last indexed block height into a file `last_indexed_block` right near the indexer binary. In the real world indexer you'd probably go with some other storage, depending on the toolset you're using. But to show you the concept, we've decided to go with the easiest approach by saving it to the file. Now we need to implement the reading the value from the file. :::note If it is a first start of your indexer and you ask it to start from interruption it wouldn't be able to find `last_indexed_block` and would just fail. It's not the behavior we expect. That's why we assume you want it to start from interruption (if possible) or from the latest. ::: Let's finish up our `get_start_block_height` ```rust title=src/main.rs async fn get_start_block_height(opts: &Opts) -> u64 { match opts.start_options() { StartOptions::FromBlock { height } => *height, StartOptions::FromLatest => final_block_height(opts.rpc_url()).await, // a placeholder StartOptions::FromInterruption => { match &std::fs::read("last_indexed_block") { Ok(contents) => { String::from_utf8_lossy(contents).parse().unwrap() } Err(e) => { eprintln!("Cannot read last_indexed_block.\n{}\nStart indexer from latest final", e); latest_block_height(opts.rpc_url()).await } } }, } } ``` What we are doing here: - Trying to read the file `last_indexed_block` - If the `Result` is `Ok`, we are reading the `contents` and parsing it - If the `Result` is `Err` we print a message about the error and call `last_block_height` to get the final block from the network (the fallback we were talking earlier)
### Testing `FromInterruption` In order to ensure everything works as expected we will start index from the genesis to store the last indexed block. And then we will start it from interruption to ensure we're not starting from latest. Let's build and run from genesis. :::info Genesis Trick To start NEAR Lake Framework based indexer from the genesis block, you need to just specify the `start_block_height` as `0`. ::: ```bash cargo build --release ./target/release/indexer mainnet from-block 0 ``` You will see something like: ``` 9820210 / shards 1 9820214 / shards 1 9820216 / shards 1 9820219 / shards 1 9820221 / shards 1 9820226 / shards 1 9820228 / shards 1 9820230 / shards 1 9820231 / shards 1 9820232 / shards 1 9820233 / shards 1 9820235 / shards 1 9820236 / shards 1 9820237 / shards 1 9820238 / shards 1 ``` Stop it by pressing `CTRL+C` Memorize the last block height you see. In our example it is `9820238` Restart the indexer from interruption ```bash ./target/release/indexer mainnet from-interruption ``` You should see the indexer logs beginning from the block you've memorized. Perfect! It's all done. Now you can adjust the code you got in the result to your needs and use it in your indexers. --- ## Summary You've seen the way how you can empower your indexer with the starting options. As you can see there is nothing complex here. You can find the source code in the [`near-examples/lake-indexer-start-options`](https://github.com/near-examples/lake-indexer-start-options) --- # Source: https://docs.near.org/primitives/linkdrop/linkdrop.md --- id: linkdrop title: Using Linkdrops description: "Learn about linkdrops following NEP-452 standard - distribute assets and onboard users to Web3 apps through simple web links using access keys and the Keypom platform." --- Wanting to use Linkdrops in your dApp? Here you will find all the information you need to get started. :::tip The simplest way to create a linkdrop is by interacting with our [LinkDrop Generator](/toolbox) ::: --- ## AccessKeys In order to create any kind of drop, you need to first generate key pairs. You will need to create **one key per drop**. - The `linkdrop` contract will store the **`public`** part of the key. - You will give the `private` part of the key to the user you want to receive the drop.
Generate a new key on [Lantstool](https://app.lantstool.dev/)
### Deposit and Stake Tokens To stake your `NEAR` and receive the liquid token, run the command: ```bash near contract call-function as-transaction
### Unstake When you feel ready, simply request unstake with the following command. You will need to wait standard delay of 4 epochs (24-28 hours) for funds to become available for withdrawal. ```bash near contract call-function as-transaction
### Withdraw As soon as 4 epochs have gone by, run the following command to withdraw `NEAR` tokens back. ```bash near contract call-function as-transaction
### AWS Credentials To access the data provided by [NEAR Lake](../lake-framework/near-lake) you need to provide valid AWS credentials in order to be charged by the AWS for the S3 usage. :::info AWS credentials Please note that using your own AWS Credentials is the only way to access the data provided by [NEAR Lake](../lake-framework/near-lake) ecosystem. ::: AWS default profile configuration with aws configure looks similar to the following: ``` ~/.aws/credentials ``` ``` [default] aws_access_key_id=
### Lake Configuration To initialize the NEAR Lake Framework, we need to provide the following basic settings: - The S3 bucket name: the bucket where the NEAR Lake data is stored. The value is `near-lake-data-testnet` for the testnet and `near-lake-data-mainnet` for the mainnet. - The S3 region: The AWS region where the S3 bucket is located. The default value is `eu-central-1`. - Start block height: The block height from which the indexer will start processing blocks.
### Install developer tools ```bash apt update apt install -y git binutils-dev libcurl4-openssl-dev zlib1g-dev libdw-dev libiberty-dev cmake gcc g++ python docker.io protobuf-compiler libssl-dev pkg-config clang llvm cargo awscli ``` :::danger NEAR Indexer Framework only works on **`Linux x86`**, it does **not** support Windows or MacOS :::
### Clone nearcore repository ```bash git clone git@github.com:near/nearcore.git ``` --- ## Initialization In order for our indexer to process blocks it needs to join the NEAR network as a node. To do that, we need first to initialize it, which will download the blockchain `genesis` config, and create a `key` for our node to communicate with other nodes. Go to the `nearcore/tools/indexer/example` folder and build the indexer: ```bash cd nearcore/tools/indexer/example && cargo build --release ``` Then, run the following command to initialize the network configuration:
How it works
- The command initializes the indexer's configuration: home directory, sync mode, streaming mode, finality, etc. - Creates a Tokio runtime on a dedicated thread. - Creates an instance of the Indexer using the provided configuration, starts it, and streams blocks to our handler. Within the handler (`listen_blocks` method), there is an infinite loop that parses block data for each new block received. ``` SubCommand::Run => { let indexer_config = near_indexer::IndexerConfig { home_dir, sync_mode: near_indexer::SyncModeEnum::FromInterruption, await_for_node_synced: near_indexer::AwaitForNodeSyncedEnum::WaitForFullSync, finality: near_primitives::types::Finality::Final, validate_genesis: true, }; let tokio_runtime = tokio::runtime::Builder::new_current_thread() .enable_all() .build() .expect("Failed to create Tokio runtime"); tokio_runtime.block_on(async move { let indexer = near_indexer::Indexer::new(indexer_config).await.expect("Indexer::new()"); let stream = indexer.streamer(); listen_blocks(stream).await; }); } SubCommand::Init(config) => near_indexer::indexer_init_configs(&home_dir, config.into())?, ```### Sync Mode You can choose Indexer Framework sync mode by setting what to stream: - LatestSynced - Real-time syncing, always taking the latest finalized block to stream - FromInterruption - Starts syncing from the block NEAR Indexer was interrupted last time - BlockHeight(u64) - Specific block height to start syncing from. ``` sync_mode: near_indexer::SyncModeEnum::FromInterruption, await_for_node_synced: near_indexer::AwaitForNodeSyncedEnum::WaitForFullSync, ```
### Streaming Mode You can choose Indexer Framework streaming mode by setting what to stream: - StreamWhileSyncing - Stream while node is syncing - WaitForFullSync - Don't stream until the node is fully synced ``` await_for_node_synced: near_indexer::AwaitForNodeSyncedEnum::WaitForFullSync, finality: near_primitives::types::Finality::Final, ```
### Finality You can choose finality level at which blocks are streamed: - None - `optimistic`, a block that (though unlikely) might be skipped - DoomSlug - `near-final`, a block that is irreversible, unless at least one block producer is slashed - Final - `final`, the block is final and irreversible. ``` finality: near_primitives::types::Finality::Final, validate_genesis: true, ```
### Boot Nodes If your node can't find any peers to connect to, you can manually specify some boot nodes in the `config.json` file. You can get a list of active peers for your network by running the following command:
### Historical Data Indexer Framework also exposes access to the internal APIs (see Indexer::client_actors method), so you can fetch data about any block, transaction, etc, yet by default, nearcore is configured to remove old data (garbage collection), so querying the data that was observed a few epochs before may return an error saying that the data is not found. If you only need blocks streaming, you don't need this tweak, but if you need access to the historical data right from your Indexer, consider updating "archive" setting in config.json to true: ```json ... "archive": true, ... ``` --- ## Using NEAR Indexer in your Project You can also use NEAR Indexer Framework as a dependency in your own Rust project. To do that, add the following to your `Cargo.toml` file (replace `2.8.0` with the latest stable release version): ```toml [dependencies] near-indexer = { git = "https://github.com/near/nearcore", tag = "2.9.1" } near-indexer-primitives = { git = "https://github.com/near/nearcore", tag = "2.9.1" } near-config-utils = { git = "https://github.com/near/nearcore", tag = "2.9.1" } near-o11y = { git = "https://github.com/near/nearcore", tag = "2.9.1" } near-primitives = { git = "https://github.com/near/nearcore", tag = "2.9.1" } ```
Example response:
```json { "jsonrpc": "2.0", "id": "dontcare", "result": [ [1028, 1031], [1034, 1038] ] } ```The result will be a list of future maintenance windows in current epoch. For example a window `[1028, 1031]` includes block heights 1028, 1029 and 1030.
Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Relaying with wallets
At the moment, wallet selector standard doesn't support signing transactions without immediately sending them. This functionality is essential for routing transactions to a relayer. Therefore, to smoothly integrate relaying on the client side, it's necessary to be able to sign transactions without relying on wallets. Progress is being made to make this possible in the future.Adding keys
```js const keyPair = nearAPI.KeyPair.fromRandom("ed25519"); const receipt = await account.addKey(keyPair.getPublicKey().toString()) ``` After saving these keys, its possible to rotate the private keys randomly when instantiating accounts before relaying ensuring you won't create a nonce collision.Technical Details
Technically, the end user (client) creates a `SignedDelegateAction` that contains the data necessary to construct a `Transaction`, signs the `SignedDelegateAction` using their key, and send it to the relayer service. When the request is received, the relayer uses its own key to sign a `Transaction` using the fields in the `SignedDelegateAction` as input to create a `SignedTransaction`. The `SignedTransaction` is then sent to the network via RPC call, and the result is sent back to the client. The `Transaction` is executed in such a way that the relayer pays the GAS fees, but all actions are executed as if the user had sent the transaction.Why using a relayer?
## Why use a Relayer? There are multiple reasons to use a relayer: 1. Your users are new to NEAR and don't have any gas to cover transactions 2. Your users have an account on NEAR, but only have a Fungible Token Balance. They can now use the FT to pay for gas 3. As an enterprise or a large startup you want to seamlessly onboard your existing users onto NEAR without needing them to worry about gas costs and seed phrases 4. As an enterprise or large startup you have a user base that can generate large spikes of user activity that would congest the network. In this case, the relayer acts as a queue for low urgency transactions 5. In exchange for covering the gas fee costs, relayer operators can limit where users spend their assets while allowing users to have custody and ownership of their assets 6. Capital Efficiency: Without relayer if your business has 1M users they would have to be allocated 0.25 NEAR to cover their gas costs totalling 250k NEAR. However, only ~10% of the users would actually use the full allowance and a large amount of the 250k NEAR is just sitting there unused. So using the relayer, you can allocate 50k NEAR as a global pool of capital for your users, which can refilled on an as needed basis.### Accounts must be initialized Any transaction, including meta transactions, must use NONCEs to avoid replay attacks. The NONCE must be chosen by Alice and compared to a NONCE stored on chain. This NONCE is stored on the access key information that gets initialized when creating an account. --- ## Constraints on the actions inside a meta transaction A transaction is only allowed to contain one single delegate action. Nested delegate actions are disallowed and so are delegate actions next to each other in the same receipt. --- ## Gas costs for meta transactions Meta transactions challenge the traditional ways of charging gas for actions. Let's assume Alice uses a relayer to execute actions with Bob as the receiver. 1. The relayer purchases the gas for all inner actions, plus the gas for the delegate action wrapping them. 2. The cost of sending the inner actions and the delegate action from the relayer to Alice's shard will be burned immediately. The condition `relayer == Alice` determines which action `SEND` cost is taken (`sir` or `not_sir`). Let's call this `SEND(1)`. 3. On Alice's shard, the delegate action is executed, thus the `EXEC` gas cost for it is burned. Alice sends the inner actions to Bob's shard. Therefore, we burn the `SEND` fee again. This time based on `Alice == Bob` to figure out `sir` or `not_sir`. Let's call this `SEND(2)`. 4. On Bob's shard, we execute all inner actions and burn their `EXEC` cost. Each of these steps should make sense and not be too surprising. But the consequence is that the implicit costs paid at the relayer's shard are `SEND(1)` + `SEND(2)` + `EXEC` for all inner actions plus `SEND(1)` + `EXEC` for the delegate action. This might be surprising but hopefully with this explanation it makes sense now! --- ## Gas refunds in meta transactions Gas refund receipts work exactly like for normal transaction. At every step, the difference between the pessimistic gas price and the actual gas price at that height is computed and refunded. At the end of the last step, additionally all remaining gas is also refunded at the original purchasing price. The gas refunds go to the signer of the original transaction, in this case the relayer. This is only fair, since the relayer also paid for it. --- ## Balance refunds in meta transactions Unlike gas refunds, the protocol sends balance refunds to the predecessor (a.k.a. sender) of the receipt. This makes sense, as we deposit the attached balance to the receiver, who has to explicitly reattach a new balance to new receipts they might spawn. In the world of meta transactions, this assumption is also challenged. If an inner action requires an attached balance (for example a transfer action) then this balance is taken from the relayer. The relayer can see what the cost will be before submitting the meta transaction and agrees to pay for it, so nothing wrong so far. But what if the transaction fails execution on Bob's shard? At this point, the predecessor is `Alice` and therefore she receives the token balance refunded, not the relayer. This is something relayer implementations must be aware of since there is a financial incentive for Alice to submit meta transactions that have high balances attached but will fail on Bob's shard. --- ## Function Call Access Keys in Meta Transactions [Function Call Access Keys](../protocol/access-keys.md#function-call-keys) are limited to signing transactions for specific methods on a specific contract. Additionally, they can have an allowance, which limits the amount of tokens that can be spent on GAS fees. This limit however can be circumvented by using meta transactions. When a `DelegateAction` is processed in the network, the access key of the sender is checked against the receiver and the methods called. If the access key is allowed to make the call, the action is executed. The allowance however is not checked, as all costs have been covered by the relayer. Hence, the action will be executed even if the allowance is insufficient to cover the costs. --- # Source: https://docs.near.org/tools/near-api.md --- id: near-api title: NEAR API sidebar_label: NEAR API description: "Learn to use APIs in JavaScript, Rust, and Python to interact with the blockchain." --- We offer a collection of language-specific libraries that allow developers to interact with the NEAR blockchain from both frontend and backend applications. The different APIs allow you to perform a variety of actions on the NEAR blockchain, including but not limited to: 1. Create and manage NEAR accounts 2. Call functions on smart contracts 3. Transfer tokens, including native NEAR, Fungible Tokens, Non-Fungible Tokens 4. Sign transactions/meta-transactions/messages and broadcasting them to the network 5. Deploy smart contracts --- ## Available APIs We have APIs available for Javascript, Rust, and Python. Add them to your project using the following commands:
### Get State {#get-state} Get basic account information, such as its code hash and storage usage.
### Create Named Account {#create-named-account} To create a named account like `user.testnet`, you need to call the `create_account` function on `near` (or `testnet`), passing as parameters the new account ID, and a public key to add as [FullAccess key](/protocol/access-keys#full-access-keys)
Creating an account from a seed phrase
You can also create an account via a randomly generated seed phrase. ``` let (seed_phrase, seed_pk) = signer::generate_seed_phrase().unwrap(); let create_account_result = Account::create_account(new_account_id.clone()) // example-account.testnet .fund_myself( account_id.clone(), NearToken::from_millinear(100), // Initial balance for new account in yoctoNEAR ) .public_key(seed_pk).unwrap() .with_signer(signer.clone()) // Signer is the account that is creating the new account .send_to(&network) .await .unwrap(); println!("Seed phrase: {:?}", seed_phrase); println!("{:?}", create_account_result); } ```### Create Sub-Account {#create-sub-account} Accounts on NEAR can create sub-accounts under their own namespace, which is useful for organizing accounts by purpose — for example, `project.user.testnet`.
### Delete Account {#delete-account} Accounts on NEAR can delete themselves, transferring any remaining balance to a specified beneficiary account.
### Call Function A smart contract exposes its methods, and making a function call that modifies state requires a `Signer`/`KeyPair`. You can optionally attach a `NEAR` deposit to the call.
### Batch Actions You can send multiple [actions](../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 The only way to have true simultaneous transactions is to use multiple access keys on a same account. Each access key maintains its own nonce, allowing transactions signed with different keys to be processed in parallel:
### Deploy a Contract {#deploy-a-contract} On NEAR, a smart contract is deployed as a WASM file. Every account has the potential to become a contract — you simply need to deploy code to it.
### Deploy a Global Contract {#deploy-a-global-contract} [Global contracts](../smart-contracts/global-contracts.md) allow smart contracts to be deployed once and reused by any account without incurring high storage costs. There are two ways to reference a global contract: - **[By account](../smart-contracts/global-contracts.md#reference-by-account):** The contract code is tied to another account. - **[By hash](../smart-contracts/global-contracts.md#reference-by-hash):** You reference the contract by its immutable code hash.
### Add Full Access Key {#add-full-access-key} A [Full Access key](/protocol/access-keys.md#full-access-keys) grants complete control over the account. Anyone with this key can transfer funds, sign transactions, interact with contracts, or even delete the account entirely.
### Add Function Call Key {#add-function-call-key} A [Function Call access key](/protocol/access-keys.md#function-call-keys) is designed specifically to sign transactions that include only [`functionCall` actions](/protocol/transaction-anatomy#actions) to a specific contract. You can further restrict this key by: - Limiting which method names can be called - Capping the amount of `NEAR` the key can spend on transaction fees
### Delete Access Key {#delete-access-key} Accounts on NEAR can delete their own keys.
### Import `import-account` - import existing account (a.k.a. "sign in").
### Export `export-account` - export existing account. ```bash export ACCOUNT_ID=bob.testnet near account export-account $ACCOUNT_ID using-web-wallet network-config testnet ```
### Create `create-account` - create a new account.
### Delete `delete-account` - delete an account.
### Add key `add-key` - add an access key to an account.
### Delete key `delete-keys` - delete an access key from an account.
### Send FT `send-ft` - transfer Fungible Tokens to a specified user. ```bash export ACCOUNT_ID=bob.testnet export RECEIVER_ID=alice.testnet export FT_CONTRACT_ID=0c97251cd1f630c444dbusdt.testnet near tokens $ACCOUNT_ID send-ft $FT_CONTRACT_ID $RECEIVER_ID amount-ft '1 USDT' prepaid-gas '100.0 Tgas' attached-deposit '1 yoctoNEAR' network-config testnet sign-with-keychain send ```
### Send NFT `send-nft` - transfers NFTs between accounts. ```bash export ACCOUNT_ID=bob.testnet export RECEIVER_ID=alice.testnet export NFT_CONTRACT_ID=nft.examples.testnet near tokens $ACCOUNT_ID send-nft $NFT_CONTRACT_ID $RECEIVER_ID 1 --prepaid-gas '100.0 Tgas' --attached-deposit '1 yoctoNEAR' network-config testnet sign-with-keychain send ```
### View NEAR balance `view-near-balance` - view the balance of NEAR tokens. ```bash export ACCOUNT_ID=bob.testnet near tokens $ACCOUNT_ID view-near-balance network-config testnet now ```
### View FT balance `view-ft-balance` - view the balance of Fungible Tokens. ```bash export ACCOUNT_ID=bob.testnet export FT_CONTRACT_ID=0c97251cd1f630c444dbusdt.testnet near tokens $ACCOUNT_ID view-ft-balance $FT_CONTRACT_ID network-config testnet now ```
### View NFT balance `view-nft-assets` - view the balance of NFT tokens. ```bash export ACCOUNT_ID=bob.testnet export NFT_CONTRACT_ID=nft.examples.testnet near tokens $ACCOUNT_ID view-nft-assets $NFT_CONTRACT_ID network-config testnet now ``` --- ## Contract This option allows you to manage and interact with your smart contracts. ### Call `call-function` - execute function (contract method).
### Deploy `deploy` - add a new contract code.
### Inspect `inspect` - get a list of available function names.
### Edit connection `edit-connection` - edit a network connection. ```bash near config edit-connection testnet --key rpc_url --value https://test.rpc.fastnear.com ``` --- :::important We provide examples only of the most used commands. If you want to explore all options provided by `near-cli` use [the interactive mode](#interactive-mode). ::: --- ## Validators You can use the following commands to interact with the blockchain and view validator stats. There are three reports used to monitor validator status: - [Proposals](#proposals) - [Current validators](#current-validators) - [Next validators](#next-validators) :::tip To use these commands, you **must** install the CLI [validator extension](#validator-extension). ::: ### Validator Extension If you want to interact with [NEAR Validators](https://pages.near.org/papers/economics-in-sharded-blockchain/#validators) from command line, you can install the [NEAR Validator CLI Extension](https://github.com/near-cli-rs/near-validator-cli-rs):
### Selecting Wallets Unlike traditional wallet selectors that bundle wallet code, NEAR Connect uses a **manifest-based approach**: 1. Wallet providers register their integration scripts in a public manifest 2. The connector dynamically loads wallet scripts when users want to connect This architecture eliminates the need to install individual wallet packages and ensures wallet code can be updated independently from your app. ```tsx connector = new NearConnector({ network: "testnet", // or "mainnet" features: { signMessage: true, // Only show wallets that support message signing signTransaction: true, signInWithoutAddKey: true, signAndSendTransaction: true, signAndSendTransactions: true }, }); ```
### Creating an Access Key The connector can request a [Function-Call Key](/protocol/access-keys#function-call-keys) for a specific contract on behalf of the user. This allows your app to interact with the contract without asking the user to sign every transaction. ```tsx title="lib/near.ts" const connector = new NearConnector({ network: "testnet", // or "mainnet" // Optional: Request access key for contract interaction connectWithKey: { contractId: "your-contract.testnet", methodNames: ["method1", "method2"], allowance: "250000000000000", // 0.25 NEAR }, }); ``` --- ## Signing In The connector uses the Observer Pattern (pub/sub), for which we need to do two things: 1. Subscribe to the `signIn` event: ```tsx connector.on("wallet:signIn", async({ wallet, accounts, success }) => { const address = await wallet.getAddress(); console.log(`User signed in: ${address}`); }); ``` 2. Call the `connect` function to open a modal where the user can select a wallet and sign in: ```tsx ``` --- ## Signing Out Similarly, to sign out we need to subscribe to the `signOut` event and call the `disconnect` function: ```tsx // Listen for sign-out connector.on("wallet:signOut", () => { console.log("User signed out"); }); // Disconnect current wallet ``` --- ## Calling Contract Method To call a contract method, first get the connected wallet instance using `connector.wallet()`, then use the wallet's `signAndSendTransaction` method to make a function call: ```tsx // Get the connected wallet const wallet = await connector.wallet(); // Call a change method const result = await wallet.signAndSendTransaction({ receiverId: "hello.near-examples.testnet", actions: [ { type: "FunctionCall", params: { methodName: "set_greeting", args: { greeting: "Hello from NEAR Connect!" }, gas: "30000000000000", // 30 TGas deposit: "0", // No deposit }, }, ], }); console.log("Transaction:", result.transaction.hash); ```
Read-only Methods
The `near-connector` does not provide a built-in way to call read-only (view) methods. However, you can use the `@near-js/providers` package to create a JSON-RPC provider and call view methods directly: ```tsx const provider = new JsonRpcProvider({ url: "https://test.rpc.fastnear.com" }); const greeting = await provider.callFunction( "hello.near-examples.testnet", "get_greeting", {} ); ```Contract's interface
#### `create_near_drop(public_keys, amount_per_drop)` Creates `#public_keys` drops, each with `amount_per_drop` NEAR tokens on them #### `create_ft_drop(public_keys, ft_contract, amount_per_drop)` Creates `#public_keys` drops, each with `amount_per_drop` FT tokens, corresponding to the `ft_contract` #### `create_nft_drop(public_key, nft_contract)` Creates a drop with an NFT token, which will come from the `nft_contract` #### `claim_for(account_id)` Claims a drop, which will be sent to the existing `account_id` #### `create_account_and_claim(account_id)` Creates the `account_id`, and then drops the tokens into it### Storage Costs While we will not go into the details of how the storage costs are calculated, it is important to know what is being taken into account: 1. The cost of storing each Drop, which will include storing all bytes associated with the `Drop` struct 2. The cost of storing each `PublicKey -> DropId` relation in the maps 3. Cost of storing each `PublicKey` in the account Notice that (3) is not the cost of storing the byte representation of the `PublicKey` on the state, but the cost of adding the key to the contract's account as a FunctionCall key. --- ## Claim a drop In order to claim drop, a user needs to sign a transaction using the `Private Key`, which is the counterpart of the `Public Key` that was added to the contract. All `Drops` have a `counter` which decreases by 1 each time a drop is claimed. This way, when all drops are claimed (`counter` == 0), we can remove all information from the Drop. There are two ways to claim a drop: claim for an existing account and claim for a new account. The main difference between them is that the first one will send the tokens to an existing account, while the second one will create a new account and send the tokens to it.
(but only mainnet and testnet networks) Decentralized | **Yes** | No
(Pagoda Inc dumps the blocks to AWS S3) Reaction time (end-to-end) | minimum 3.8s (estimated average 5-7s) | [minimum 3.9s (estimated average 6-8s)](./near-lake-framework.md#latency) Reaction time (framework overhead only) | 0.1s | 0.2-2.2s Estimated cost of infrastructure | [$500+/mo](https://near-nodes.io/rpc/hardware-rpc) | [**$20/mo**](./near-lake-framework.md#cost) Ease of maintenance | Advanced
(need to follow every nearcore upgrade, and sync state) | **Easy**
(deploy once and forget) How long will it take to start? | days (on mainnet/testnet) | **seconds** Ease of local development | Advanced
(localnet is a good option, but testing on testnet/mainnet is too heavy) | **Easy**
(see [tutorials](./tutorials/near-lake-state-changes-indexer.md)) Programming languages that a custom indexer can be implemented with | Rust only | **Any**
(currently, helper packages are released in [Python](http://pypi.org/project/near-lake-framework), [JavaScript](https://www.npmjs.com/package/near-lake-framework), and [Rust](https://crates.io/crates/near-lake-framework)) --- --- # Source: https://docs.near.org/data-infrastructure/near-lake-framework.md --- id: near-lake-framework title: What is Lake Framework? description: "A library to build your own indexer using the existing Data Lake" --- NEAR Lake Framework is an ecosystem of library companions that read data from the [`NEAR Data Lake`](#data-lake). They allow you to build your own indexer by simply subscribing to the stream of blocks that is being constantly pushed to the [NEAR Lake](#data-lake) *Example of a simple indexer built on top of NEAR Lake Framework* You can create your own logic to process the NEAR Protocol data in the programming languages of your choice: - [Python](http://pypi.org/project/near-lake-framework) - [JavaScript](https://github.com/near/near-lake-framework-js) - [Rust](https://crates.io/crates/near-lake-framework) :::note GitHub repo https://github.com/near/near-lake-framework/ ::: --- ## Data Lake The NEAR Lake is a set of AWS S3 buckets which are constantly receiving new blocks from a [running indexer](https://github.com/aurora-is-near/near-lake-indexer) maintained by [Aurora](https://aurora.dev) Events such as [FT Events](https://github.com/near/NEPs/tree/master/neps/nep-0300.md) and [NFT Events](https://github.com/near/NEPs/tree/master/neps/nep-0256.md) are constantly being written as JSON files in two AWS S3 buckets: - `near-lake-data-testnet` (`eu-central-1` region) - `near-lake-data-mainnet` (`eu-central-1` region) Both buckets are set up the way the requester pays for the access. Anyone can read from these buckets by connecting to them with their own AWS credentials to be charged by Amazon. --- ## Latency Indexers based on the Lake Framework inherit [the latency characteristics of a NEAR Indexer](https://github.com/near/nearcore/tree/master/chain/indexer) **plus an extra 0.1-2.1s latency** of dumping to and reading from AWS S3. :::tip Most of the latency is there due to the finalization delay and both Indexer Framework and Lake Framework add quite a minimum overhead. ::: --- ## Cost Indexers based on NEAR Lake consume 100-500MB of RAM depending on the size of the preloading queue, it does not require any storage, and it can potentially run even on Raspberry PI. Getting the blockchain data from S3 will cost around $30,16 per month as NEAR Lake configured S3 buckets in such a way that **the reader is paying the costs**.
AWS S3 Cost Breakdown
Assuming NEAR Protocol produces 1 block every 600ms, on a full day the network can create up to 144000 blocks (86400s / 600ms per block). According to the [Amazon S3 prices](https://aws.amazon.com/s3/pricing/?nc1=h_ls) `list` requests are charged for $0.005 per 1000 requests and `get` is charged for $0.0004 per 1000 requests. Calculations (assuming we are following the tip of the network all the time): ``` 144000 blocks per day * 10 requests for each block / 1000 requests * $0.0004 per 1k requests = $0.576 * 30 days = $17.20 ``` **Note:** 10 requests for each block means we have 9 shards (1 file for common block data and 9 separate files for each shard) And a number of `list` requests we need to perform for 30 days: ``` 144000 blocks per day / 1000 requests * $0.005 per 1k list requests = $0.72 * 30 days = $21.60 $17,20 + $21,60 = $30,16 ```(but only mainnet and testnet networks) Decentralized | **Yes** | No
(Pagoda Inc dumps the blocks to AWS S3) Reaction time (end-to-end) | minimum 3.8s (estimated average 5-7s) | [minimum 3.9s (estimated average 6-8s)](#latency) Reaction time (framework overhead only) | 0.1s | 0.2-2.2s Estimated cost of infrastructure | [$500+/mo](https://near-nodes.io/rpc/hardware-rpc) | [**$20/mo**](#cost) Ease of maintenance | Advanced
(need to follow every nearcore upgrade, and sync state) | **Easy**
(deploy once and forget) How long will it take to start? | days (on mainnet/testnet) | **seconds** Ease of local development | Advanced
(localnet is a good option, but testing on testnet/mainnet is too heavy) | **Easy**
(see [tutorials](./tutorials/near-lake-state-changes-indexer.md)) Programming languages that a custom indexer can be implemented with | Rust only | **Any**
(currently, helper packages are released in [Python](http://pypi.org/project/near-lake-framework), [JavaScript](https://www.npmjs.com/package/near-lake-framework), and [Rust](https://crates.io/crates/near-lake-framework)) --- ## Examples & Tutorials - [`near-examples/near-lake-raw-printer`](https://github.com/near-examples/near-lake-raw-printer): simple example of a data printer built on top of NEAR Lake Framework - [`near-examples/near-lake-accounts-watcher`](https://github.com/near-examples/near-lake-accounts-watcher): source code for a video tutorial on how to use the NEAR Lake Framework - [`near-examples/indexer-tx-watcher-example-lake`](https://github.com/near-examples/indexer-tx-watcher-example-lake) indexer example that watches for transaction for specified accounts/contracts build on top of NEAR Lake Framework :::note Tutorials See [Tutorials page](./tutorials/near-lake-state-changes-indexer.md) ::: --- # Source: https://docs.near.org/data-infrastructure/lake-framework/near-lake.md --- id: near-lake sidebar_label: Lake Overview title: NEAR Lake Indexer description: "Learn how NEAR Lake indexes the network" --- NEAR Lake is an indexer built on top of [NEAR Indexer Framework](https://github.com/near/nearcore/tree/master/chain/indexer) to watch the network and store all the event logs such as [FT Events](https://github.com/near/NEPs/tree/master/neps/nep-0300.md) and [NFT Events](https://github.com/near/NEPs/tree/master/neps/nep-0256.md) as JSON files on AWS S3. :::info GitHub repo You can find the Lake Indexer source code in [this GitHub repository](https://github.com/near/near-lake-indexer/). ::: ### How it works :::tip [Pagoda Inc.](https://www.pagoda.co) runs NEAR Lake nodes to store the data in JSON format on AWS S3. There is no need to run your own NEAR Lake unless you have specific reasons to do that. ::: There are AWS S3 buckets created: - `near-lake-data-testnet` (`eu-central-1` region) - `near-lake-data-mainnet` (`eu-central-1` region) All the buckets are set up the way the requester pays for the access. Anyone can read from these buckets by connecting to them with their own AWS credentials to be charged by Amazon. ### Data structure The data structure used by Lake Indexer is the following: ```
### Quickstart You can either install the MCP server globally and start it, or run it directly using `npx`.
### Local MCP Server Once the NEAR MPC starts locally it starts what is called a [`stdio server`](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#stdio). To connect your AI agent to the server you will need to use an MCP client library: ``` server_params = StdioServerParameters( command="npx", args=["@nearai/near-mcp@latest", "run"] ) ``` In order to use the NEAR MCP server, you will need to manually parse its tool: ``` def convert_mcp_tools_to_openai(tools_result) -> list[dict]: """Convert MCP tools to OpenAI function format""" return [ { "type": "function", "function": { "name": tool.name, "description": tool.description, "parameters": getattr(tool, 'inputSchema', {"type": "object", "properties": {}}) } } for tool in tools_result.tools ] ``` You can then use the tools as part of your prompt: ``` response = client.chat.completions.create( model=MODEL, messages=message_history, tools=near_mpc_tools, tool_choice="auto", ) ``` :::tip Accounts By default the MCP server will have no accounts loaded, your agent can either import and account using the `system_import_account` tool, or you can specify which keystore to load by setting the `NEAR_KEYSTORE` environment variable ```bash NEAR_KEYSTORE=/path/to/keystore npx @nearai/near-mcp@latest run ``` :::
### Example Prompts The Agent using the MCP server will readily have tool to answer prompts like: - What is the balance of `agency.testnet`? - Add the account `example.testnet` using the private key `ed25519:...` - Transfer 0.1 NEAR from `agency.testnet` to `example.testnet` - Call the `ft_transfer` method on the `usdc.fakes.testnet` contract - What are the public methods of `social.near`? --- ## Integrate With AI Clients You can use the NEAR MCP server with any standard MCP client. Here are instructions for some popular clients:
Example response:
```json { "jsonrpc": "2.0", "result": { "chain_id": "testnet", "genesis_hash": "FWJ9kR6KFWoyMoNjpLXXGHeuiy7tEY6GmoFeCA5yuc6b", "latest_protocol_version": 73, "node_key": null, "node_public_key": "ed25519:DC7DbfZq4dkPqUKaKpWNimgtRBxnD9rja2KcZRs4e3DL", "protocol_version": 73, "rpc_addr": "0.0.0.0:3030", "sync_info": { "earliest_block_hash": "uz2gwgYxpx8dHsjgiPQefbwAhWk41CCvEmHU7ktYE2C", "earliest_block_height": 187251995, "earliest_block_time": "2025-02-10T13:54:22.616904144Z", "epoch_id": "94jeudySZcxGBSVgKXn3xPT3P5iFF6YcnxC43F15QtkQ", "epoch_start_height": 187443633, "latest_block_hash": "EfL8Rc1EH13UxgbJB4skt8xSF8vojNQPcAX1opf6RFab", "latest_block_height": 187456272, "latest_block_time": "2025-02-12T22:10:10.530341781Z", "latest_state_root": "3Vpebx4DuKAYmMjL96XMmLqWYUfuS2raZWoAbxFxeqBm", "syncing": false }, "uptime_sec": 6020117, "validator_account_id": null, "validator_public_key": null, "validators": [ { "account_id": "kiln.pool.f863973.m0", "is_slashed": false }, { "account_id": "node2", "is_slashed": false }, { "account_id": "legends.pool.f863973.m0", "is_slashed": false } ], "version": { "build": "2.4.0-rc.1", "rustc_version": "1.82.0", "version": "2.4.0-rc.1" } }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "active_peers": [ { "id": "ed25519:GkDv7nSMS3xcqA45cpMvFmfV1o4fRF6zYo1JRR6mNqg5", "addr": "35.193.24.121:24567", "account_id": null } ], "num_active_peers": 34, "peer_max_count": 40, "sent_bytes_per_sec": 17754754, "received_bytes_per_sec": 492116, "known_producers": [ { "account_id": "node0", "addr": null, "peer_id": "ed25519:7PGseFbWxvYVgZ89K1uTJKYoKetWs7BJtbyXDzfbAcqX" } ] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "current_fishermen": [], "current_proposals": [ { "account_id": "01node.pool.f863973.m0", "public_key": "ed25519:3iNqnvBgxJPXCxu6hNdvJso1PEAc1miAD35KQMBCA3aL", "stake": "14508308808748255650142126217547", "validator_stake_struct_version": "V1" } ], "current_validators": [ { "account_id": "kiln.pool.f863973.m0", "is_slashed": false, "num_expected_blocks": 2622, "num_expected_chunks": 9298, "num_produced_blocks": 2622, "num_produced_chunks": 9288, "public_key": "ed25519:Bq8fe1eUgDRexX2CYDMhMMQBiN13j8vTAVFyTNhEfh1W", "shards": [0], "stake": "92891729926051855086331836750992" } ], "epoch_height": 3358, "epoch_start_height": 187443633, "next_fishermen": [], "next_validators": [ { "account_id": "kiln.pool.f863973.m0", "public_key": "ed25519:Bq8fe1eUgDRexX2CYDMhMMQBiN13j8vTAVFyTNhEfh1W", "shards": [0], "stake": "92921980033422214461941381687070" } ], "prev_epoch_kickout": [] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.### Global Contract You can deploy a new Non-Fungible Token using our global NFT contract - a pre-deployed [standard NFT contract](https://github.com/near-examples/NFT) that you can reuse. [Global contracts](../../smart-contracts/global-contracts.md) are deployed once and can be reused by any account without incurring high storage costs.
Manual Interaction
Here is how to directly interact with the factory contract through your application:### Minting Collections Many times people want to create multiple 100 copies of an NFT (this is called a collection). In such cases, what you actually need to do is to mint 100 different NFTs with the same metadata (but different `token-id`). :::tip Notice that [minting in Mintbase](#minting-a-nft) allows you to pass a `num_to_mint` parameter. :::
### Royalties You might have noticed that one of the parameters is a structure called royalties. Royalties enable you to create a list of users that should get paid when the token is sell in a marketplace. For example, if `anna` has `5%` of royalties, each time the NFT is sell, `anna` should get a 5% of the selling price. --- ## Querying NFT data You can query the NFT's information and metadata by calling the `nft_token`.
Example response
```json { "token_id": "1", "owner_id": "bob.near", "metadata": { "title": "string", // ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" "description": "string", // free-form description "media": "string", // URL to associated media, preferably to decentralized, content-addressed storage "media_hash": "string", // Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. "copies": 1, // number of copies of this set of metadata in existence when token was minted. "issued_at": 1642053411068358156, // When token was issued or minted, Unix epoch in milliseconds "expires_at": 1642053411168358156, // When token expires, Unix epoch in milliseconds "starts_at": 1642053411068358156, // When token starts being valid, Unix epoch in milliseconds "updated_at": 1642053411068358156, // When token was last updated, Unix epoch in milliseconds "extra": "string", // anything extra the NFT wants to store on-chain. Can be stringified JSON. "reference": "string", // URL to an off-chain JSON file with more info. "reference_hash": "string" // Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. } } ```Example response
```json { "token_id": "1", "owner_id": "bob.near", "metadata": { "title": "string", // ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" "description": "string", // free-form description "media": "string", // URL to associated media, preferably to decentralized, content-addressed storage "media_hash": "string", // Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. "copies": 1, // number of copies of this set of metadata in existence when token was minted. "issued_at": 1642053411068358156, // When token was issued or minted, Unix epoch in milliseconds "expires_at": 1642053411168358156, // When token expires, Unix epoch in milliseconds "starts_at": 1642053411068358156, // When token starts being valid, Unix epoch in milliseconds "updated_at": 1642053411068358156, // When token was last updated, Unix epoch in milliseconds "extra": "string", // anything extra the NFT wants to store on-chain. Can be stringified JSON. "reference": "string", // URL to an off-chain JSON file with more info. "reference_hash": "string" // Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. } } ```Example response
```json { "token_id": "1", "owner_id": "bob.near", "metadata": { "title": "string", // ex. "Arch Nemesis: Mail Carrier" or "Parcel #5055" "description": "string", // free-form description "media": "string", // URL to associated media, preferably to decentralized, content-addressed storage "media_hash": "string", // Base64-encoded sha256 hash of content referenced by the `media` field. Required if `media` is included. "copies": 1, // number of copies of this set of metadata in existence when token was minted. "issued_at": 1642053411068358156, // When token was issued or minted, Unix epoch in milliseconds "expires_at": 1642053411168358156, // When token expires, Unix epoch in milliseconds "starts_at": 1642053411068358156, // When token starts being valid, Unix epoch in milliseconds "updated_at": 1642053411068358156, // When token was last updated, Unix epoch in milliseconds "extra": "string", // anything extra the NFT wants to store on-chain. Can be stringified JSON. "reference": "string", // URL to an off-chain JSON file with more info. "reference_hash": "string" // Base64-encoded sha256 hash of JSON from reference field. Required if `reference` is included. } } ```### How Does it Work? Assume you want to attach an NFT (🎫) to a call on the receiver contract. The workflow is as follows: 1. You call `nft_transfer_call` in the NFT-contract passing: the receiver, a message, and the token-id of 🎫. 2. The NFT contract transfers the NFT 🎫 to the receiver. 3. The NFT contract calls **`receiver.nft_on_transfer(sender, token-owner, token-id, msg)`**. 4. The NFT contract handles errors in the `nft_resolve_transfer` callback. 5. The NFT contract returns `true` if it succeeded. #### The nft_on_transfer method From the workflow above it follows that the receiver we want to call needs to implement the `nft_on_transfer` method. When executed, such method will know: - Who is sending the NFT, since it is a parameter - Who is the current owner, since it is a parameter - Which NFT was transferred, since it is a parameter. - If there are any parameters encoded as a message The `nft_on_transfer` **must return true** if the NFT has to be **returned to the sender**. --- ## Approving Users You can authorize other users to transfer an NFT you own. This is useful, for example, to enable listing your NFT in a marketplace. In such scenario, you **trust** that the marketplace will only transfer the NFT upon receiving a certain amount of money in exchange.
Example Response
```bash [ [ 'wrap.near', { reports: [ { oracle_id: 'thorinoracle.near', timestamp: '1669795900809627816', price: { multiplier: '17030', decimals: 28 } }, ... ] } ] ] ```Example Response
```bash [ [ 'wrap.near', { reports: [ { oracle_id: 'thorinoracle.near', timestamp: '1669795900809627816', price: { multiplier: '17030', decimals: 28 } }, ... ] } ] ] ```Example response
```bash { timestamp: '1706631861981947371', recency_duration_sec: 90, prices: [ { asset_id: 'wrap.near', price: { multiplier: '30702', decimals: 28 } }, { asset_id: 'aurora', price: { multiplier: '235662', decimals: 20 } }, { asset_id: 'meta-pool.near', price: { multiplier: '38770', decimals: 28 } }, { asset_id: 'linear-protocol.near', price: { multiplier: '36432', decimals: 28 } }, ```Example response
```bash { timestamp: '1706631861981947371', recency_duration_sec: 90, prices: [ { asset_id: 'wrap.near', price: { multiplier: '30702', decimals: 28 } }, { asset_id: 'aurora', price: { multiplier: '235662', decimals: 20 } }, { asset_id: 'meta-pool.near', price: { multiplier: '38770', decimals: 28 } }, { asset_id: 'linear-protocol.near', price: { multiplier: '36432', decimals: 28 } }, ```Example response:
```json { "jsonrpc": "2.0", "result": { "avg_hidden_validator_seats_per_shard": [0], "block_producer_kickout_threshold": 80, "chain_id": "testnet", "chunk_producer_assignment_changes_limit": 5, "chunk_producer_kickout_threshold": 90, "chunk_validator_only_kickout_threshold": 80, "dynamic_resharding": false, "epoch_length": 43200, "fishermen_threshold": "340282366920938463463374607431768211455", "gas_limit": 1000000000000000, "gas_price_adjustment_rate": [1, 100], "genesis_height": 42376888, "genesis_time": "2020-07-31T03:39:42.911378Z", "max_gas_price": "10000000000000000000000", "max_inflation_rate": [1, 20], "max_kickout_stake_perc": 100, "min_gas_price": "5000", "minimum_stake_divisor": 10, "minimum_stake_ratio": [1, 6250], "minimum_validators_per_shard": 1, "num_block_producer_seats": 200, "num_block_producer_seats_per_shard": [200], "num_blocks_per_year": 31536000, "num_chunk_only_producer_seats": 300, "num_chunk_producer_seats": 100, "num_chunk_validator_seats": 300, "online_max_threshold": [99, 100], "online_min_threshold": [90, 100], "protocol_reward_rate": [1, 10], "protocol_treasury_account": "near", "protocol_upgrade_stake_threshold": [4, 5], "protocol_version": 29, "shard_layout": { "V0": { "num_shards": 1, "version": 0 } }, "shuffle_shard_assignment_for_chunk_producers": false, "target_validator_mandates_per_shard": 68, "total_supply": "2089646653180081825096998107194444", "transaction_validity_period": 86400, "use_production_config": false, "validators": [ { "account_id": "masternode24.pool.f863973.m0", "amount": "2096547887468158804726149840014", "public_key": "ed25519:9E3JvrQN6VGDGg1WJ3TjBsNyfmrU6kncBcDvvJLj6qHr" }, { "account_id": "lunanova.pool.f863973.m0", "amount": "6023592217250515747116857534108", "public_key": "ed25519:2fZ59qfo9QHNLijoht9cwUb9enSNcnRmXbQn1gKZxvkw" }, { "account_id": "node0", "amount": "7017386808510582905904716139001", "public_key": "ed25519:7PGseFbWxvYVgZ89K1uTJKYoKetWs7BJtbyXDzfbAcqX" }, { "account_id": "node1", "amount": "7021733510638228632380895173752", "public_key": "ed25519:6DSjZ8mvsRZDvFqFxo8tCKePG96omXW7eVYVSySmDk8e" }, { "account_id": "nodeasy.pool.f863973.m0", "amount": "350028003459257633077889642325", "public_key": "ed25519:25Dhg8NBvQhsVTuugav3t1To1X1zKiomDmnh8yN9hHMb" }, { "account_id": "valeraverim.pool.f863973.m0", "amount": "2460437541222457077732687804254", "public_key": "ed25519:3686ABqNUZc1qhLWLHg5xZpBzrWPiUCMNZxcCNmg3e2s" }, { "account_id": "node2", "amount": "7022280566885326956797181813724", "public_key": "ed25519:GkDv7nSMS3xcqA45cpMvFmfV1o4fRF6zYo1JRR6mNqg5" }, { "account_id": "orangeclub.pool.f863973.m0", "amount": "3073208665436498671483798256985", "public_key": "ed25519:HezFeSzcwuR5wvkqccgMCMnpf1eQkVCfk52tXZEdKZHz" }, { "account_id": "tribe-pool.pool.f863973.m0", "amount": "502021509894008520748060961431", "public_key": "ed25519:CRS4HTSAeiP8FKD3c3ZrCL5pC92Mu1LQaWj22keThwFY" }, { "account_id": "staked.pool.f863973.m0", "amount": "1835541810883701332840668361355", "public_key": "ed25519:D2afKYVaKQ1LGiWbMAZRfkKLgqimTR74wvtESvjx5Ft2" }, { "account_id": "node3", "amount": "7025309465335462891886410729905", "public_key": "ed25519:ydgzeXHJ5Xyt7M1gXLxqLBW1Ejx6scNV5Nx2pxFM8su" }, { "account_id": "moonlet.pool.f863973.m0", "amount": "396044187712024170314465720781", "public_key": "ed25519:3e1nVCVGNS3yr6CcUvpDAs3BhiWtyM9uTBWkyVR5Xn3K" }, { "account_id": "sweden.pool.f863973.m0", "amount": "385869819054217573549654420144", "public_key": "ed25519:2RVUnsMEZhGCj1A3vLZBGjj3i9SQ2L46Z1Z41aEgBzXg" }, { "account_id": "shawnpool.pool.f863973.m0", "amount": "326196336737920044305254508558", "public_key": "ed25519:6dfAfW3oy1kp4u9ePuticHy3Y2WDcHwx8yKSdyLNMPSr" }, { "account_id": "chorus-one.pool.f863973.m0", "amount": "1318859742119402879751178031888", "public_key": "ed25519:6LFwyEEsqhuDxorWfsKcPPs324zLWTaoqk4o6RDXN7Qc" }, { "account_id": "inotel.pool.f863973.m0", "amount": "4945759122706953812641339874642", "public_key": "ed25519:C55jH1MCHYGa3tzUyZZdGrJmmCLP22Aa4v88KYpn2xwZ" }, { "account_id": "p2p.pool.f863973.m0", "amount": "991547852404615467434919132596", "public_key": "ed25519:4ie5979JdSR4f7MRAG58eghRxndVoKnAYAKa1PLoMYSS" }, { "account_id": "dokia.pool.f863973.m0", "amount": "4004628852742744225484204285260", "public_key": "ed25519:935JMz1vLcJxFApG3TY4MA4RHhvResvoGwCrQoJxHPn9" }, { "account_id": "01node.pool.f863973.m0", "amount": "1416856356232757387343764992394", "public_key": "ed25519:3iNqnvBgxJPXCxu6hNdvJso1PEAc1miAD35KQMBCA3aL" }, { "account_id": "legends.pool.f863973.m0", "amount": "303006135607766172564337480878", "public_key": "ed25519:AhQ6sUifJYgjqarXSAzdDZU9ZixpUesP9JEH1Vr7NbaF" }, { "account_id": "blazenet.pool.f863973.m0", "amount": "1892937440977093265954787297596", "public_key": "ed25519:DiogP36wBXKFpFeqirrxN8G2Mq9vnakgBvgnHdL9CcN3" } ] }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Example response:
```json { "jsonrpc": "2.0", "result": { "avg_hidden_validator_seats_per_shard": [0, 0, 0, 0, 0, 0], "block_producer_kickout_threshold": 80, "chain_id": "testnet", "chunk_producer_kickout_threshold": 80, "chunk_validator_only_kickout_threshold": 70, "dynamic_resharding": false, "epoch_length": 43200, "fishermen_threshold": "340282366920938463463374607431768211455", "gas_limit": 1000000000000000, "gas_price_adjustment_rate": [1, 100], "genesis_height": 42376888, "genesis_time": "2020-07-31T03:39:42.911378Z", "max_gas_price": "10000000000000000000000", "max_inflation_rate": [1, 20], "max_kickout_stake_perc": 30, "min_gas_price": "5000", "minimum_stake_divisor": 10, "minimum_stake_ratio": [1, 62500], "minimum_validators_per_shard": 1, "num_block_producer_seats": 20, "num_block_producer_seats_per_shard": [20, 20, 20, 20, 20, 20], "num_blocks_per_year": 31536000, "num_chunk_only_producer_seats": 0, "online_max_threshold": [99, 100], "online_min_threshold": [90, 100], "protocol_reward_rate": [1, 10], "protocol_treasury_account": "near", "protocol_upgrade_stake_threshold": [4, 5], "protocol_version": 73, "runtime_config": { "account_creation_config": { "min_allowed_top_level_account_length": 65, "registrar_account_id": "registrar" }, "congestion_control_config": { "allowed_shard_outgoing_gas": 1000000000000000, "max_congestion_incoming_gas": 400000000000000000, "max_congestion_memory_consumption": 1000000000, "max_congestion_missed_chunks": 5, "max_congestion_outgoing_gas": 10000000000000000, "max_outgoing_gas": 300000000000000000, "max_tx_gas": 500000000000000, "min_outgoing_gas": 1000000000000000, "min_tx_gas": 20000000000000, "outgoing_receipts_big_size_limit": 4718592, "outgoing_receipts_usual_size_limit": 102400, "reject_tx_congestion_threshold": 0.8 }, "storage_amount_per_byte": "10000000000000000000", "transaction_costs": { "action_creation_config": { "add_key_cost": { "full_access_cost": { "execution": 101765125000, "send_not_sir": 101765125000, "send_sir": 101765125000 }, "function_call_cost": { "execution": 102217625000, "send_not_sir": 102217625000, "send_sir": 102217625000 }, "function_call_cost_per_byte": { "execution": 1925331, "send_not_sir": 47683715, "send_sir": 1925331 } }, "create_account_cost": { "execution": 3850000000000, "send_not_sir": 3850000000000, "send_sir": 3850000000000 }, "delegate_cost": { "execution": 200000000000, "send_not_sir": 200000000000, "send_sir": 200000000000 }, "delete_account_cost": { "execution": 147489000000, "send_not_sir": 147489000000, "send_sir": 147489000000 }, "delete_key_cost": { "execution": 94946625000, "send_not_sir": 94946625000, "send_sir": 94946625000 }, "deploy_contract_cost": { "execution": 184765750000, "send_not_sir": 184765750000, "send_sir": 184765750000 }, "deploy_contract_cost_per_byte": { "execution": 64572944, "send_not_sir": 47683715, "send_sir": 6812999 }, "function_call_cost": { "execution": 780000000000, "send_not_sir": 200000000000, "send_sir": 200000000000 }, "function_call_cost_per_byte": { "execution": 2235934, "send_not_sir": 47683715, "send_sir": 2235934 }, "stake_cost": { "execution": 102217625000, "send_not_sir": 141715687500, "send_sir": 141715687500 }, "transfer_cost": { "execution": 115123062500, "send_not_sir": 115123062500, "send_sir": 115123062500 } }, "action_receipt_creation_config": { "execution": 108059500000, "send_not_sir": 108059500000, "send_sir": 108059500000 }, "burnt_gas_reward": [3, 10], "data_receipt_creation_config": { "base_cost": { "execution": 36486732312, "send_not_sir": 36486732312, "send_sir": 36486732312 }, "cost_per_byte": { "execution": 17212011, "send_not_sir": 47683715, "send_sir": 17212011 } }, "pessimistic_gas_price_inflation_ratio": [103, 100], "storage_usage_config": { "num_bytes_account": 100, "num_extra_bytes_record": 40 } }, "wasm_config": { "alt_bn128": true, "disable_9393_fix": false, "discard_custom_sections": true, "ed25519_verify": true, "eth_implicit_accounts": true, "ext_costs": { "alt_bn128_g1_multiexp_base": 713000000000, "alt_bn128_g1_multiexp_element": 320000000000, "alt_bn128_g1_sum_base": 3000000000, "alt_bn128_g1_sum_element": 5000000000, "alt_bn128_pairing_check_base": 9686000000000, "alt_bn128_pairing_check_element": 5102000000000, "base": 264768111, "bls12381_g1_multiexp_base": 16500000000, "bls12381_g1_multiexp_element": 930000000000, "bls12381_g2_multiexp_base": 18600000000, "bls12381_g2_multiexp_element": 1995000000000, "bls12381_map_fp2_to_g2_base": 1500000000, "bls12381_map_fp2_to_g2_element": 900000000000, "bls12381_map_fp_to_g1_base": 1500000000, "bls12381_map_fp_to_g1_element": 252000000000, "bls12381_p1_decompress_base": 15000000000, "bls12381_p1_decompress_element": 81000000000, "bls12381_p1_sum_base": 16500000000, "bls12381_p1_sum_element": 6000000000, "bls12381_p2_decompress_base": 15000000000, "bls12381_p2_decompress_element": 165000000000, "bls12381_p2_sum_base": 18600000000, "bls12381_p2_sum_element": 15000000000, "bls12381_pairing_base": 2130000000000, "bls12381_pairing_element": 2130000000000, "contract_compile_base": 0, "contract_compile_bytes": 0, "contract_loading_base": 35445963, "contract_loading_bytes": 1089295, "ecrecover_base": 278821988457, "ed25519_verify_base": 210000000000, "ed25519_verify_byte": 9000000, "keccak256_base": 5879491275, "keccak256_byte": 21471105, "keccak512_base": 5811388236, "keccak512_byte": 36649701, "log_base": 3543313050, "log_byte": 13198791, "promise_and_base": 1465013400, "promise_and_per_promise": 5452176, "promise_return": 560152386, "read_cached_trie_node": 2280000000, "read_memory_base": 2609863200, "read_memory_byte": 3801333, "read_register_base": 2517165186, "read_register_byte": 98562, "ripemd160_base": 853675086, "ripemd160_block": 680107584, "sha256_base": 4540970250, "sha256_byte": 24117351, "storage_has_key_base": 54039896625, "storage_has_key_byte": 30790845, "storage_iter_create_from_byte": 0, "storage_iter_create_prefix_base": 0, "storage_iter_create_prefix_byte": 0, "storage_iter_create_range_base": 0, "storage_iter_create_to_byte": 0, "storage_iter_next_base": 0, "storage_iter_next_key_byte": 0, "storage_iter_next_value_byte": 0, "storage_large_read_overhead_base": 1, "storage_large_read_overhead_byte": 1, "storage_read_base": 56356845749, "storage_read_key_byte": 30952533, "storage_read_value_byte": 5611004, "storage_remove_base": 53473030500, "storage_remove_key_byte": 38220384, "storage_remove_ret_value_byte": 11531556, "storage_write_base": 64196736000, "storage_write_evicted_byte": 32117307, "storage_write_key_byte": 70482867, "storage_write_value_byte": 31018539, "touching_trie_node": 16101955926, "utf16_decoding_base": 3543313050, "utf16_decoding_byte": 163577493, "utf8_decoding_base": 3111779061, "utf8_decoding_byte": 291580479, "validator_stake_base": 911834726400, "validator_total_stake_base": 911834726400, "write_memory_base": 2803794861, "write_memory_byte": 2723772, "write_register_base": 2865522486, "write_register_byte": 3801564, "yield_create_base": 153411779276, "yield_create_byte": 15643988, "yield_resume_base": 1195627285210, "yield_resume_byte": 47683715 }, "fix_contract_loading_cost": false, "function_call_weight": true, "grow_mem_cost": 1, "implicit_account_creation": true, "limit_config": { "account_id_validity_rules_version": 1, "contract_prepare_version": 2, "initial_memory_pages": 1024, "max_actions_per_receipt": 100, "max_arguments_length": 4194304, "max_contract_size": 4194304, "max_functions_number_per_contract": 10000, "max_gas_burnt": 300000000000000, "max_length_method_name": 256, "max_length_returned_data": 4194304, "max_length_storage_key": 2048, "max_length_storage_value": 4194304, "max_locals_per_contract": 1000000, "max_memory_pages": 2048, "max_number_bytes_method_names": 2000, "max_number_input_data_dependencies": 128, "max_number_logs": 100, "max_number_registers": 100, "max_promises_per_function_call_action": 1024, "max_receipt_size": 4194304, "max_register_size": 104857600, "max_stack_height": 262144, "max_total_log_length": 16384, "max_total_prepaid_gas": 300000000000000, "max_transaction_size": 1572864, "max_yield_payload_size": 1024, "per_receipt_storage_proof_size_limit": 4000000, "registers_memory_limit": 1073741824, "wasmer2_stack_limit": 204800, "yield_timeout_length_in_blocks": 200 }, "math_extension": true, "regular_op_cost": 822756, "storage_get_mode": "FlatStorage", "vm_kind": "NearVm", "yield_resume_host_functions": true }, "witness_config": { "combined_transactions_size_limit": 4194304, "main_storage_proof_size_soft_limit": 4000000, "new_transactions_validation_state_size_soft_limit": 572864 } }, "shard_layout": { "V1": { "boundary_accounts": [ "aurora", "aurora-0", "game.hot.tg", "kkuuue2akv_1630967379.near", "tge-lockup.sweat" ], "shards_split_map": [[0], [1], [2, 3], [4], [5]], "to_parent_shard_map": [0, 1, 2, 2, 3, 4], "version": 3 } }, "shuffle_shard_assignment_for_chunk_producers": false, "target_validator_mandates_per_shard": 68, "transaction_validity_period": 86400 }, "id": "dontcare" } ```Error handling:
When making RPC API requests, you may encounter various errors related to network configuration, rate limiting, or request formatting. For comprehensive information about error types, causes, and solutions, see the [RPC Errors](/api/rpc/errors) documentation.Prefer an online IDE?
Want to jump right into the code without setting up a local dev environment? Check out [NEAR Playground](https://nearplay.app/) for an easy-to-use online IDE with pre-configured templates. Working on Windows?
See our blog post [getting started on NEAR using Windows](/blog/getting-started-on-windows) for a step-by-step guide on how to set up WSL and your environmentFailing tests?
Make sure that you are using `node v24 / 22 / 20`, and that you have installed `Rosetta` if you have a Mac with Apple Silicon### Create an Account Let us now create a NEAR account where we will deploy the contract: ```bash # Replace
Got an error on Windows?
When working on `WSL` - or any other headless Linux environment - you might encounter issues when trying to create an account as the `cli` tries to save the keys into the system's keychain. In such cases, you can try the following command to create the account: ```bash near account create-account sponsor-by-faucet-service### Deploy it! With the contract ready, we can now deploy it to the `testnet` account we created earlier:
#### Place a Bid We can now place a bid in the auction by calling the `bid` method while attaching some NEAR deposit. On each bid, the highest bid and bidder information will be recorded in the contract's [storage](./anatomy/storage.md). ```bash # Create a new account to place the bid near create-account
#### Get Highest Bid The `get_highest_bid` function only reads from the contract state, so it does not require a transaction or signature: ```bash near view
Expected Output
```json { "bidder": "#### Claim After the auction ends, anyone can call the `claim` method, which will transfer the `highest bid` amount to the auctioneer and end the auction. ```bash near call
Versioning for this article
At the time of this writing, this example works with the following versions: - node: `22.18.0` - rustc: `1.86.0` - near-cli-rs: `0.22.0` - cargo-near: `0.16.1` - Python: `3.13` - near-sdk-py: `0.7.3` - uvx nearc: `0.9.2` - emscripten: `4.0.9` (required for Python contracts)How does the math work here?
Imagine you always bet for `heads`. In a fair coin-flip game you have 50-50 percent chance of winning, this is because after the coin is flipped there are two possible outcomes: `H` and `T`, and you only win in one (`H`). However, if you can choose to flip again if `tails` comes out, now there are 4 scenarios: `H H` `T H` `H T` `T T`, and in 3 of those you win (all the ones including an `H`)!!!.Expand to see what's available from sys.rs
```
//! Blockchain-specific methods available to the smart contract that allow to interact with NEAR runtime.
//! This is a wrapper around a low-level [`near_sys`](near_sys).
//!
//! Unless you know what you are doing prefer using `env::*`
//! whenever possible.
//!
//! In case of cross-contract calls prefer using higher-level API available
//! through [`crate::Promise`], and [`crate::PromiseOrValue### Derivation Path The parameter `derivation seed number` will be used to derive which external address we will be requesting signatures from, the address will be derived as: `DAO Address` + `Derivation Path` + `Contract Address` = `EVM Address` For example, if we register a request from the address `...` using the derivation path `0` we will obtain control the `0x...` account. :::tip Learn more about derivation paths [here](../../chain-abstraction/chain-signatures.md) :::
### Transaction Payload The `transaction_payload` contains all the information on the transaction that we want to perform, particularly: - `to`: The recipient address of the transaction - `nonce`: The transaction nonce, used to ensure uniqueness - `function_data`: (optional) Defines the function that will be called on the recipient's contract, including: - `function_abi`: The ABI of the function being called - `arguments`: The input arguments for the function, all ABI encoded (e.g. integers are `base64`) There are a couple important points to notice about this `transaction_payload`: - **Readable Payload:** The parameters make it easy for anyone to quickly understand what transaction will be executed externally. The Abstract DAO is designed to be transparent and easy to audit, abstracting away the complexity of creating the transaction. - **We Are Setting a Nonce:** By setting the nonce, we make sure that the transaction will only be valid once, as future transactions will need higher `nonces` - **We Are Not Setting the GAS:** Gas prices are expected to vary wildly across EVMs, for which it makes no sense to setup a fixed gas amount and gas price for all the networks, for this is that we use the last parameter `allowed_account`
### Allowed Account In this case, the `allowed_account` will be the one in charge of generating the signatures. At the time of generating the signature, the account will also set the `gas_price` for the transaction on a per-chain basis. --- # Source: https://docs.near.org/chain-abstraction/omnibridge/roadmap.md --- id: roadmap sidebar_label: Roadmap title: Omni Bridge Roadmap description: "Explore the Omni Bridge roadmap, including hybrid architecture launch, Chain Signatures migration path, and future development plans for cross-chain infrastructure." --- Omni Bridge launches with a hybrid architecture, utilizing different verification methods based on chain-specific requirements and technical constraints. This approach allows us to support multiple chains from day one while progressively transitioning to full Chain Signatures integration. ## Supported Chains The bridge currently supports the following networks: - **EVM Chains:** - Ethereum - Base - Arbitrum - BNB Chain - Polygon (PoS) - **Non-EVM Chains:** - Bitcoin - Solana - Zcash ## Architecture Overview Omni Bridge utilizes **Chain Signatures** as its primary verification mechanism for outbound transfers from NEAR. Incoming transfers rely on chain-specific verification methods, including light clients for maximum security where available. ### Verification Methods - **Ethereum & Bitcoin:** Light Client verification for inbound transfers. - **Other Chains:** Message passing protocols verified by the NEAR network. - **Outbound (All Chains):** Chain Signatures (MPC) for secure transaction signing. ## Future Development 1. **Protocol Improvements** - Enhanced fee mechanisms - Cross-chain contract calls - New token standards support Beyond basic asset transfers, we're expanding the bridge's capabilities. Enhanced fee mechanisms will better handle gas price volatility, while cross-chain contract calls will enable more complex interactions. 2. **Infrastructure** - Expanded relayer network - Improved monitoring tools - Enhanced developer tooling Infrastructure development focuses on reliability and usability. An expanded relayer network improves transfer speeds and reliability, while better monitoring and developer tools make integration and maintenance easier. ## Get Involved ### Areas for Contribution - Chain integrations - Performance optimization - Security analysis - Developer tools - [Near-One/omni-bridge](https://github.com/Near-One/omni-bridge) - Omni Bridge repository - [Near-One/bridge-sdk-js](https://github.com/Near-One/bridge-sdk-js) - JavaScript SDK - [Near-One/bridge-sdk-rs](https://github.com/Near-One/bridge-sdk-rs) - Rust SDK and Bridge CLI The code is open source and we welcome contributions from the community. Whether you're interested in adding support for new chains, optimizing performance, or building developer tools, there's room for meaningful contribution. Bridge infrastructure is a fundamental component of a multi-chain future. Through Chain Signatures, we're creating a more efficient, secure, and scalable approach to cross-chain communication. Join us in building it. --- # Source: https://docs.near.org/data-infrastructure/tutorials/running-near-lake/run-lake-indexer.md --- id: run-lake-indexer title: Running Lake Indexer description: "Learn how to set up and run a NEAR Lake Indexer, including prerequisites, network configuration, and commands for syncing from the latest or a specific block." --- At NEAR we already have a working solution to index blockchain data and store it in AWS S3 buckets called **NEAR Lake**. In this guide you will learn how to set up and run an instance of the NEAR Lake Indexer. The Lake Indexer setup consists of the following components: - AWS S3 Bucket as a storage - NEAR Lake binary that operates as a regular NEAR Protocol peer-to-peer node, so you will operate it as any other [Regular/RPC Node in NEAR](https://near-nodes.io/rpc/hardware-rpc) :::info NEAR Lake is an indexer specialized on storing events as JSON files on AWS S3, built on top of the [NEAR Indexer microframework](https://github.com/nearprotocol/nearcore/tree/master/chain/indexer) :::
### Prepare Development Environment Before you proceed, make sure you have the following software installed: - [Rust compiler](https://rustup.rs/) of the version that is mentioned in `rust-toolchain` file in the root of [nearcore](https://github.com/nearprotocol/nearcore) project. - Ensure you have [AWS Credentials configured](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) From AWS Docs: > For example, the files generated by the AWS CLI for a default profile configured with aws configure looks similar to the following. > > ~/.aws/credentials > > ``` > [default] > aws_access_key_id=AKIAIOSFODNN7EXAMPLE > aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY > ```
### Compile NEAR Lake ```bash $ cargo build --release ```
### Configure NEAR Lake To connect NEAR Lake to the specific chain you need to have necessary configs, you can generate it as follows: ```bash $ ./target/release/near-lake --home ~/.near/testnet init --chain-id testnet --download-config --download-genesis ``` The above code will download the official genesis config and generate necessary configs. You can replace `testnet` in the command above to different network ID (`betanet`, `mainnet`). Configs for the specified network are in the `--home` provided folder. We need to ensure that NEAR Lake follows all the necessary shards, so `"tracked_shards"` parameters in `~/.near/testnet/config.json` needs to be configured properly. Currently, `nearcore` treats empty value for `"tracked_shards"` as "do not track any shard" and **any value** as "track all shards". For example, in order to track all shards, you just add the shard #0 to the list: ``` ... "tracked_shards": [0], ... ```
### Run NEAR Lake Commands to run NEAR Lake, after `./target/release/near-lake` | Command | Key/Subcommand | Required/Default | Responsible for | |---------|-------------------------------|------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | | `--home` | Default
`~/.near` | Tells the node where too look for necessary files:
`config.json`
,
`genesis.json`
,
`node_key.json`
, and
`data`
folder | | `init` | | | Tells the node to generate config files in `--home-dir` | | | `--chain-id` | Required
_ `localnet`
_ `testnet`
\* `mainnet` | Defines the chain to generate config files for | | | `--download-config` | Optional | If provided tells the node to download `config.json` from the public URL. You can download them manually
- [testnet config.json](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/testnet/rpc/config.json)
- [mainnet config.json](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/mainnet/rpc/config.json) | | | `--download-genesis` | Optional | If provided tells the node to download `genesis.json` from the public URL. You can download them manually
- [testnet genesis.json](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/testnet/genesis.json)
- [mainnet genesis.json](https://s3-us-west-1.amazonaws.com/build.nearprotocol.com/nearcore-deploy/mainnet/genesis.json) | | | TODO:
Other `neard` keys | | | | `run` | | | Runs the node | | | `--bucket` | Required | AWS S3 Bucket name | | | `--region` | Required | AWS S3 Bucket region | | | `--fallback-region` | Default eu-central-1 | AWS S3 Fallback region | | | `--endpoint` | Optional | AWS S3 compatible API endpoint | | | `--stream-while-syncing` | Optional | If provided Indexer streams blocks while they appear on the node instead of waiting the node to be fully synced | | | `--concurrency` | Default 1 | Defines the concurrency for the process of saving block data to AWS S3 | | | `sync-from-latest` | One of the `sync-` subcommands is required | Tells the node to start indexing from the latest block in the network | | | `sync-from-interruption` | One of the `sync-` subcommands is required | Tells the node to start indexing from the block the node was interrupted on (if it is a first start it will fallback to `sync-from-latest`) | | | `sync-from-block --height N` | One of the
`sync-`
subcommands is required | Tells the node to start indexing from the specified block height `N` (**Ensure** you node data has the block you want to start from) | ```bash $ ./target/release/near-lake --home ~/.near/testnet run --stream-while-syncing --concurrency 50 sync-from-latest ``` After the network is synced, you should see logs of every block height currently received by NEAR Lake. --- ## Syncing Whenever you run NEAR Lake for any network except localnet you'll need to sync with the network. This is required because it's a natural behavior of `nearcore` node and NEAR Lake is a wrapper for the regular `nearcore` node. In order to work and index the data your node must be synced with the network. While snapshot-based syncing was previously the recommended default, we now recommend [Epoch Sync](https://near-nodes.io/intro/node-epoch-sync) —a faster, more lightweight method that allows a node to catch up from genesis without downloading a large state snapshot. --- ## Running NEAR Lake as an archival node It's not necessary but in order to index everything in the network it is better to do it from the genesis. `nearcore` node is running in non-archival mode by default. That means that the node keeps data only for [5 last epochs](/protocol/network/epoch). In order to index data from the genesis you need to turn the node in archival mode. To do it you need to update `config.json` located in `--home-dir` (by default it is `~/.near`). Find next keys in the config and update them as following: ```json { ... "archive": true, "tracked_shards": [0], ... } ``` The syncing process in archival mode can take a lot of time, so it's better to download a backup provided by NEAR and put it in your `data` folder. After that your node will download only the data after the backup was cut and it takes reasonable amount time. All the backups can be downloaded from the public [S3 bucket](https://docs.fastnear.com/docs/snapshots/mainnet#archival-mainnet-snapshot) provided by FastNEAR. See [this link](https://near-nodes.io/archival/run-archival-node-with-nearup) for reference --- ## Using the data We write all the data to AWS S3 buckets: - `near-lake-data-testnet` (`eu-central-1` region) for testnet - `near-lake-data-mainnet` (`eu-central-1` region) for mainnet --- ## Custom S3 storage In case you want to run you own `near-lake` instance and store data in some S3 compatible storage ([Minio](https://min.io/) or [Localstack](https://localstack.cloud/) as example) You can override default S3 API endpoint by using `--endpoint` option - run `minio` ```bash $ mkdir -p /data/near-lake-custom && minio server /data ``` - run `near-lake` ```bash $ ./target/release/near-lake --home ~/.near/testnet run --endpoint http://127.0.0.1:9000 --bucket near-lake-custom sync-from-latest ```
### Data structure The data structure we use is the following: ```
### Access the data All NEAR Lake AWS S3 buckets have [Request Payer](https://docs.aws.amazon.com/AmazonS3/latest/userguide/RequesterPaysBuckets.html) enabled. It means that anyone with their own AWS credentials can List and Read the bucket's content and **be charged for it by AWS**. Connections to the bucket have to be done with AWS credentials provided. See [NEAR Lake Framework](https://github.com/near/near-lake-framework) for a reference.
### NEAR Lake Framework Once we [set up the public access to the buckets](https://github.com/near/near-lake/issues/22) anyone will be able to build their own code to read it through. For our own needs we are working on [NEAR Lake Framework](https://github.com/near/near-lake-framework) to have a simple way to create an indexer on top of the data stored by NEAR Lake itself. :::note See the official NEAR Lake Framework [announcement on the NEAR Gov Forum](https://gov.near.org/t/announcement-near-lake-framework-brand-new-word-in-indexer-building-approach/17668). ::: --- # Source: https://docs.near.org/web3-apps/tutorials/localnet/run.md --- id: run title: Run Your Own Localnet description: "Learn how to run a localnet on NEAR." --- Now that we understand what a localnet is, let's walk through the complete workflow of running it and testing it with a simple smart contract and a frontend application. For this tutorial, we'll use `near-sandbox`, since it's the easiest and fastest option to start with. Our goal for this tutorial is to set up a local network, create a wallet account on it, deploy a contract, and finally run [a frontend application](https://github.com/near-examples/hello-localnet) that interacts with this contract directly through the local blockchain. :::tip Also check the [localnet tutorial](https://github.com/near/mpc/blob/main/docs/localnet/localnet.md) by the NEAR MPC team ::: ### Prerequisites Before we begin, make sure you have a few essential tools installed. - [near-cli-rs](https://github.com/near/near-cli-rs) - the CLI for interacting with the NEAR blockchain; - [cargo-near](https://github.com/near/cargo-near) - the CLI that simplifies building/deploying Rust smart contracts. ### Walkthrough #### Step 1. Setup and boot up sandbox node First, run the following command: ```sh npx near-sandbox --home /tmp/near-sandbox init ``` This command prepares a fresh configuration inside the home folder, which is `/tmp/near-sandbox` in the command above. Once it's finished, you'll find several files created in that directory: - `config.json` - main node configuration, defining network ports, storage paths, runtime settings, etc - `genesis.json` - defines the initial blockchain state, including default account `near` and the validator account (by default, it's `test.near`) - `validator_key.json` - validator's keypair used to produce blocks - `node_key.json` - keypair used for signing network packets This initialization process is a one-time setup. Once the configuration is in place, you can start and stop the node as many times as you like, the blockchain state will persist inside this folder. After initialization, start the node: ```sh npx near-sandbox --home /tmp/near-sandbox run ``` The node will boot up and begin producing blocks locally. :::tip To confirm that your node is actually running, you can query its `status` RPC endpoint with the following command `curl http://127.0.0.1:3030/status`. ::: #### Step 2. Import `test.near` account In this step, we'll import the default `test.near` account that was created during `near-sandbox` initialization. We'll need this account later to deploy our smart contract, so let's prepare it now. First, make sure your `near-cli-rs` knows how to connect to your local network. If you already have a `localnet` configuration, you can skip this step. Otherwise, run: ```sh near config add-connection --network-name localnet --connection-name localnet-sandbox --rpc-url http://localhost:3030/ --wallet-url http://localhost:3030/ --explorer-transaction-url http://localhost:3030/ ``` During this process, the CLI may ask you a few interactive questions. You can safely answer "No" to all of them - all required values are already defined in the command above. :::tip To confirm that the connection was set up correctly, you can view information about the `test.near` account with the following command `near account view-account-summary test.near network-config localnet-sandbox now`. ::: When you initialized the `near-sandbox`, it created a file named `validator_key.json` inside the home directory. This file contains the secret key for the `test.near` account, which we'll need to import into `near-cli-rs`. To view the key, run: ```sh cat /tmp/near-sandbox/validator_key.json ``` You'll see output similar to this: ```json { "account_id": "test.near", "public_key": "ed25519:...", "secret_key": "ed25519:..." } ``` Copy the `secret_key` value and import it into `near-cli-rs` by running the following command (replace `
### [JSON](https://www.json.org/json-en.html): Objects to Strings #### Features - Self-describing format - Easy interoperability with JavaScript - Multiple implementations readily available - But... it is not efficient both in computational times and resulting size #### Example ```js Example{ number: i32 = 2; arr: Vector
### [Borsh](https://borsh.io/): Objects to Bytes #### Features - Compact, binary format built to be efficiently (de)serialized - Strict and canonical binary representation - Less overhead: it does not need to store attributes names - But... it is necessary to know the schema to (de)serialize the data #### Example ```js Example{ number: i32 = 2; arr: Vector
Result
```bash [ { key: 'STATE', value: '\x02\x00\x00\x00hi\x01\x00\x00\x00\x00\x00\x00\x00\x06\x00\x00\x00prefix' }, { key: 'prefix\x00\x00\x00\x00\x00\x00\x00\x00', value: '\x00' } ] ```Result
```bash [ { key: 'STATE', value: '\x03\x00\x00\x00bye\x02\x00\x00\x00\x00\x00\x00\x00\x06\x00\x00\x00prefix' }, { key: 'prefix\x00\x00\x00\x00\x00\x00\x00\x00', value: '\x00' }, { key: 'prefix\x01\x00\x00\x00\x00\x00\x00\x00', value: '\x01' } ] ```### Deserialization Error When somebody invokes a smart contract method, the first step for the contract is to deserialize its own state. In the example used above, the contract will start by reading the `STATE` key and try to deserialize its value into an object `Contract{string: String, vector: Vector
## RPC Endpoint Setup - `POST` for all methods - `JSON RPC 2.0` - `id: "dontcare"` - endpoint URL varies by network: - mainnet `https://rpc.mainnet.near.org` - testnet `https://rpc.testnet.near.org` - betanet `https://rpc.betanet.near.org` _(may be unstable)_ - localnet `http://localhost:3030` ### Limits - Maximum number of requests per IP for mainnet: 30 req/min, 75 req per 10 mins - Maximum number of requests per IP for testnet: 30 req/min, 75 req per 10 mins
## Querying Historical Data Querying historical data (older than 5 [epochs](../../protocol/network/epoch.md) or ~2.5 days), you may get responses that the data is not available anymore. In that case, archival RPC nodes will come to your rescue: - mainnet `https://archival-rpc.mainnet.near.org` - testnet `https://archival-rpc.testnet.near.org` You can see this interface defined in `nearcore` [here](https://github.com/near/nearcore/blob/bf9ae4ce8c680d3408db1935ebd0ca24c4960884/chain/jsonrpc/client/src/lib.rs#L181). ### Limits - Maximum number of requests per IP for mainnet: 4 req/min, 10 req per 10 mins - Maximum number of requests per IP for testnet: 20 req/min, 50 req per 10 mins --- :::important The endpoints https://*.near.org are officially deprecated and heavy rate-limited. Please use any of [the available RPC providers](https://docs.near.org/api/rpc/providers) in production. See [this announcement](https://www.near.org/blog/deprecation-of-near-org-and-pagoda-co-rpc-endpoints) for more info. ::: ## Postman Setup {#postman-setup} An easy way to test the queries in this documentation page is to use an API request tool such as [Postman](https://www.postman.com/). You only need to configure two things: 1. Make sure you add a header with a key of `Content-Type` and value of `application/json`.  2. Then select the `Body` tab and choose the `raw` radio button and ensure `JSON` is the selected format.  After that is set up, just copy/paste the `JSON object` example snippets below into the `body` of your request, on Postman, and click `send`. --- ## JavaScript Setup {#javascript-setup} All of the queries listed in this documentation page can be called using [`near-api-js`](https://github.com/near/near-api-js). - For `near-api-js` installation and setup please refer to `near-api-js` [quick reference documentation](../../tools/near-api.md). --- ## HTTPie Setup {#httpie-setup} If you prefer to use a command line interface, we have provided RPC examples you can use with [HTTPie](https://httpie.org/). Please note that params take either an object or array passed as a string. ```bash http post https://rpc.testnet.near.org jsonrpc=2.0 id=dontcare method=network_info params:='[]' ``` --- ## Using `block_id` param {#using-block_id-param} The `block_id` param can take either the block number (e.g. `27912554`) or the block hash (e.g. `'3Xz2wM9rigMXzA2c5vgCP8wTgFBaePucgUmVYPkMqhRL'` ) as an argument. :::caution The block IDs of transactions shown in [NearBlocks Explorer](https://testnet.nearblocks.io) are not necessarily the block ID of the executed transaction. Transactions may execute a block or two after its recorded, and in some cases, can take place over several blocks. Due to this, it is important to check subsequent blocks to be sure all results related to the queried transaction are discovered. ::: --- ## Using `finality` param {#using-finality-param} The `finality` param has three options: `optimistic`, `near-final` and `final`: 1. `optimistic` the transaction is in a block that - though unlikely - might be skipped (~1s after submission) 2. `near-final` the transaction is in a block that is irreversible, unless at least one block producer is slashed (~2s after submission) 3. `final` the block is final and irreversible (~3s after submission) The `near-final` finallity has **enough guarantees** for any normal operations, and thus should be preferred for most applications, you can learn more about it [in this official blog post](https://near.org/blog/doomslug-comparison)
How Is Finality Calculated?
After a simple transaction (no cross-contract calls) is submitted it is included in a block B and converted into a receipt. At this point, the transaction will be in an "optimistic" state. This means that the transaction could still be skipped, but only if another block is . The receipt for the transaction will execute in the following block (B+1), at which point the transaction is now "near-final". This means that the transaction is now irreversible, unless at least one block producer is slashed (because they produced a malign block). The transaction will be in a "final" state after a new block (B+2) is produced, meaning that it is now irreversible. :::info Cross-Contract Calls For cross-contract calls, the transaction might take longer to be in its final state, as each call to a contract will create a new receipt, and each receipt will be executed in the next block :::List validators using CLI
If you prefer, you can get the list of current validators by using the [`near-validator`](../../tools/cli.md#validator-extension) CLI: ```sh near-validator validators network-config mainnet now ```### Stake Tokens
### Staked Balance To check your staked balance on the `
Staking pool balances
You can view additional information and balances from the staking pool using the following CLI commands: #### Total staked balance of the entire pool### Unstake Tokens
### Query Unstaked Balance
### Withdraw Tokens Once the unbonding period has passed, you can withdraw your unstaked tokens:
### Interface #### `ft_total_supply` (*read-only*) Returns the total supply of the token ```ts ft_total_supply(): string ```
#### `ft_balance_of` (*read-only*) Returns the balance of a given account ```ts ft_balance_of(account_id: string): string ```
#### `ft_transfer` Transfers `amount` of tokens from the account calling the function to a `receiver_id`, optionally the function can include a `memo` field to provide additional information to the contract > *Requirement: The caller must attach [exactly 1 yoctoNEAR](../../smart-contracts/security/one_yocto.md) to the call* ```ts ft_transfer(receiver_id: string, amount: string, memo: string?): void ```
#### `ft_transfer_call` The function transfers `amount` of tokens to the `receiver_id` **and calls the method `ft_on_transfer(sender_id, amount, msg)`** on `receiver_id`. Optionally the function can include a `memo` for the FT contract, and a `msg` field to which will be sent to the receiver contract. > 📖 This function is useful to transfer tokens to a contract and trigger some action on the receiver side in a single transaction, thus acting as **attaching fungible tokens to a function call**. > *Requirement: The caller must attach [exactly 1 yoctoNEAR](../../smart-contracts/security/one_yocto.md) to the call* ```ts ft_transfer_call(receiver_id: string, amount: string, memo: string?, msg: string): void ```
ft_on_transfer
Smart contracts expecting to **receive** Fungible Tokens **must** implement this method. The method **must** return the amount of tokens that were **NOT used** by the receiver, so that the **sender can be refunded**. ```ts ft_on_transfer(sender_id: string, amount: string, msg: string): string ``` ⚠️ Note that this method does not need to be implemented by the FT contract itself, but rather by any contract that expects to receive fungible tokens See a reference implementation in the [using FTs page](./ft.md#handling-deposits)#### `ft_resolve_transfer` This method is used as a [callback](../../smart-contracts/anatomy/crosscontract.md#callback-function) to resolve the `ft_transfer_call` transaction, handling refunds if necessary. ```js ft_resolve_transfer(sender_id: string, receiver_id: string, amount: string): string ``` --- ## NEP-145 (Storage Management) On NEAR, accounts need to pay for the storage they use on the network. As more users hold tokens on a fungible token contract, more information needs to be stored, and thus the contract needs to reserve more storage. [NEP-145](https://github.com/near/NEPs/blob/master/neps/nep-0145.md) is a standard that defines a common interface for registering users, allowing FT contracts to **charge users for the storage they use**. :::tip While not mandatory, it is highly recommended for FT contracts to implement the NEP-145 standard to avoid running out of storage :::
### Interface #### `storage_balance_bounds` (*read-only*) Returns the minimum and maximum storage balance required for an account to be registered with the contract ```ts storage_balance_bounds(): { min: string, max?: string} | null ``` #### `storage_balance_of` (*read-only*) Returns the storage balance of a given account, or `null` if the account is not registered ```ts storage_balance_of(account_id: string): { total: string, available: string } | null ``` #### `storage_unregister` Removes all information from an account from the contract, returning the storage deposit to the user. The function can only be called by the user themselves. ```ts storage_unregister(force?: boolean): boolean ``` #### `storage_deposit` Registers an account with the contract, reserving enough storage to keep track of the user's balance. The function can be called by the user themselves **or by a third party** on behalf of the user. ```ts storage_deposit(account_id?: string, registration_only?: boolean): { total: string, available: string } ``` #### `storage_withdraw` Unregisters an account from the contract, returning the storage deposit to the user. The function can only be called by the user themselves. ```ts storage_withdraw(amount: string): { total: string, available: string } ``` --- ## NEP-148 (Token Metadata) [NEP-148](https://github.com/near/NEPs/tree/master/neps/nep-0141.md) is an extension to the NEP-141 standard that defines the fungible tokens **metadata**. Metadata provides **key information** about the token, such as its **name, symbol, and decimal precision**, particularly, the following fields MUST be included in the token's metadata: - `spec`: a string. Should be `ft-1.0.0` to indicate that a Fungible Token contract adheres to the current versions of this Metadata and the [Fungible Token Core][FT Core] specs - `name`: the human-readable name of the token - `symbol`: the abbreviation, like wETH or AMPL - `decimals`: used in frontends to show the proper significant digits of a token The metadata is useful for wallets and other user interfaces to display the token correctly, for example if a token is defined as: ```json { "spec": "ft-1.0.0", "name": "My Awesome Token", "symbol": "MAT", "decimals": 4 } ``` A balance of `123456` units of such token should be displayed in a user interface as `12.3456 MAT`. --- # Source: https://docs.near.org/data-infrastructure/tutorials/state-changes.md --- id: state-changes title: "Tutorial: State Changes" description: "This tutorial will guide you through building a simple indexer using the NEAR Lake Framework. The indexer will listen for StateChange events and print relevant data about account changes." --- This tutorial will guide you through building a simple indexer using the NEAR Lake Framework. The indexer will listen for `StateChange` events and print relevant data about account changes. :::note Source code for the tutorial [`near-examples/near-lake-accounts-watcher`](https://github.com/near-examples/near-lake-accounts-watcher/tree/0.2.0): source code for a video tutorial on how to use the NEAR Lake Framework ::: :::info Version 0.2.0 The video is based on the [`near-lake-framework`](/data-infrastructure/near-lake-framework) version 0.2.0 At the same time we're keeping the source code up to date with the latest version of the published crate. ::: We've created a video tutorial to empower the release announcement of [NEAR Lake Framework](/data-infrastructure/near-lake-framework). In this tutorial you will build an indexer application to watch for any `StateChange`s affecting the account or a list of account provided. --- # Source: https://docs.near.org/protocol/storage/storage-solutions.md --- id: storage-solutions title: Decentralized Storage Solutions sidebar_label: Alternative Solutions description: "Explore decentralized storage alternatives for NEAR Protocol applications, including Arweave, Crust, and IPFS integration for cost-effective data storage." --- > In this article you'll find a brief overview of different decentralized storage solutions that can be integrated into your decentralized applications (dApps). This will allow you to store large amounts of data using a more economical alternative to native NEAR storage. - [Arweave](#arweave) - [Crust](#crust) - [IPFS](#ipfs) --- ## On-Chain Storage Constraints For storing data on-chain it's important to keep in mind the following: - You can store an unlimited amount of files, but will cost you 1Ⓝ per 100KB - There is a 4 MB limit on how much you can upload at once For example, if you want to store an NFT purely on-chain (rather than using IPFS or some other decentralized storage solution as mentioned below) you'll have almost an unlimited amount of storage but will have to pay 1 $NEAR per 100 KB of storage used (see [Storage Staking](/protocol/storage/storage-staking)) Users will be limited to 4MB per contract call upload due to `MAX_GAS` constraints. The maximum amount of gas one can attach to a given `functionCall` is 300TGas. ## Arweave [Arweave](https://www.arweave.org/) is a new type of storage that backs data with sustainable and perpetual endowments (tokens held within the protocol that benefit from inflation and the decrease in the cost of storage over long periods of time). This allows users and developers to store data forever. Arweave acts as a collectively owned hard drive, and allows their users to preserve valuable information, apps, and history indefinitely. The Arweave protocol matches a torrent-like swarm of incentivised miners with massive collective hard drive space with those individuals and organizations that need to store data or host content permanently. This is achieved in a decentralized network, and all data stored is backed by block mining rewards and a [sustainable endowment](https://arwiki.wiki/#/en/storage-endowment) ensuring it is available in perpetuity. :::info To learn more about Arweave, check its [mining mechanism](https://arwiki.wiki/#/en/arweave-mining) and its [bandwidth-sharing system](https://arwiki.wiki/#/en/karma). ::: ### Example implementation Let's see how to store some files on Arweave, by running a local Arweave gateway-like server. ### Arlocal setup [Arlocal](https://github.com/textury/arlocal) essentially creates a simulated version of Arweave. Think of it like a local node that runs on your computer to store information. In this example you'll need to run **two terminals**. - Open your first terminal and run: ```bash npx arlocal ``` You should see the response: `arlocal started on port 1984`. :::tip You can specify the port by using `npx arlocal
Waiting for a Transaction
When using our libraries (or directly contacting the RPC), you can specify how long you want to wait for a transaction to be processed using a `wait_until` parameter. Let's explore the different stages of a transaction's lifecycle. After a transaction is submitted, it first gets validated by the RPC node. If the transaction fails structural checks it will be immediately rejected. Otherwise, it enters the following lifecycle: 1. The transaction has been accepted by the RPC node and is waiting to be included in a block. If `wait_until = None`, the RPC will return a response at this stage. The transaction hasn’t started executing yet, though it will typically start in the next block. 2. Once the transaction reaches a validator, it ensures a signature matches signer access key and that the account is charged gas pre-payment, then updates access key nonce. The transaction is included in a chunk/block and converted into a single receipt for execution. If `wait_until = Included`, the RPC returns a response immediately indicating that the transaction has just started the execution (no execution results, logs, and outcomes are available at this point). 3. In the next blocks, the receipt will get executed and it may produce more receipts for cross-contract interactions. Once all receipts finish the execution, RPC returns a response if `wait_until = ExecutedOptimistic`. 4. The block that contains the transaction has been finalized. This may occur even sooner than receipts execution finishes (depending on how many cross-contract interactions there), and when it finishes, the RPC returns a response if `wait_until = IncludedFinal`. 5. Once the block that contains the transaction has been finalized and all receipts have completed execution (both `IncludedFinal` and `ExecutedOptimistic` are satisfied), then RPC returns a response if `wait_until = Executed`. 6. Once blocks containing the transaction and all of its receipts are finalized, the RPC returns a response at this point if `wait_until = Final`.Status Examples
#### Example: Transaction with Transfer 1. `bob.near` creates a transaction to transfer 10 NEAR to `alice.near` 2. The transaction is converted into a receipt 3. The conversion fails because `bob.near` does not have enough balance 4. The transaction is marked as failed ⛔ #### Example: Deploying a Contract 1. `bob.near` creates a transaction to: - create the account `contract.bob.near` - transfer 5 NEAR to `contract.bob.near` - deploy a contract in `contract.bob.near` 2. The transaction is transformed into one receipt 3. The account is created, the money transfer and the contract deployed 4. The transaction is marked as successful ✅ #### Example: Deploying a Contract Fails 1. `bob.near` creates a transaction to: - create the account `contract.bob.near` - transfer 5 NEAR to `contract.bob.near` - deploy a contract in `contract.bob.near` 2. The transaction is transformed into one receipt 3. The account is created, but the transfer fails because `bob.near` does not have enough balance 4. The whole process is reverted (i.e. no account is created) 5. The transaction is marked as failed ⛔ #### Example: Calling a Function 1. `bob.near` creates a transaction to call the function `cross-call` in `contract.near` 2. The transaction is transformed into one receipt 3. The function `cross-call` creates a promise to call the function `external-call` in `external.near` 4. The function finishes correctly and the transaction is marked as successful ✅ 5. A new receipt is created to call the function `external-call` in `external.near` 5. The function `external-call` fails 6. The original transaction is still marked as successful ✅ because the first receipt was successful{validAuction}
{nftMetadata?.title}
{nftMetadata?.description}
### 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 :::tip 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:
Why we should remove old structures from the state?
To understand why we should remove old structures from the state let's take a look to how the data is stored. For example, if the old version of the contract stores two messages with payments according methods `get_messages` and `get_payments` will return the following results:get_messags result
```bash INFO --- Result ------------------------- | [ | { | "premium": false, | "sender": "test-ac-1719933221123-3.testnet", | "text": "Hello" | }, | { | "premium": false, | "sender": "test-ac-1719933221123-3.testnet", | "text": "Hello" | } | ] | ------------------------------------ ```get_payments result
```bash INFO --- Result ------------------------- | [ | "10000000000000000000000", | "10000000000000000000000" | ] | ------------------------------------ ```Storage as text result
```bash 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 | -------------------------------- ```Is there a plan to support GPU compute if certain validator nodes can offer that or is it just CPU?## Block & Chunk producers The top 100 validators are responsible for producing and validating blocks, as well as producing chunks. Under normal circumstances, each validator is assigned to a single shard, for which it produces chunks. Block & Chunk producers are guaranteed a minimum annual reward of 2.5%. If less than 100% of the network’s tokens are staked, validators have the potential to earn even higher annual rewards. ## Chunk Validators [Note] Block & Chunk producers also serve as chunk validators. Non-top 100 validators take on the role of chunk validators, which has lower hardware and staking requirements, making it more accessible. This role helps expand the network's validator set, increasing opportunities to earn rewards and strengthen the security of the NEAR ecosystem. Chunk validators do not track shards. Their responsibilities are focused solely on validating and endorsing chunks. Like block and chunk producers, chunk validators are guaranteed a minimum of 2.5% annual rewards. If less than 100% of the network’s tokens are staked, chunk validators may earn even higher rewards. For more details on validator economics, check out [NEAR’s Economics Explained](https://near.org/blog/near-protocol-economics/). ## Dedicated Validator Documentation Site If you'd like to further explore Validators and Nodes in general, you can visit the [Dedicated Validator Documentation Site](https://near-nodes.io/).
We don't need GPU support as we are a POS chain and we require very little compute power. You can read more about our consensus strategy on our Validator Quickstart and Staking FAQ.
If a developer writes a vulnerable or malicious dApp, is a validator implicitly taking on risk?--- # Source: https://docs.near.org/tutorials/multichain-dao/voting.md --- id: voting title: MultiSig Voting description: "Learn how to deploy a MultiSig contract and vote on multi-chain proposals using the Abstract DAO." --- Now that we understand how the Abstract DAO works, it is time to use it in within an organization. Lets see how to deploy a MultiSig contract, where users will vote on a multi-chain proposal. --- ## Creating a MultiSig Contract As a first step we need to create an account and deploy a MultiSig contract on it, so users can start creating proposals and voting on them. :::info Deploy Multisig You can download the [compiled multisig](https://github.com/near/core-contracts/raw/refs/heads/master/multisig2/res/multisig2.wasm) from the near repository ::: ```bash near create-account
No. We have handled the potential damages to the network on the protocol level. For example, we have a lot of limiters that constrain how much data you can pass into a function call or how much compute you can do in one function call, etc. That said, smart contract developers will need to be responsible for their own dApps, as there is no stage gate or approval process. All vulnerabilities can only damage the smart contract itself. Luckily, updating smart contracts is very smooth on NEAR, so vulnerabilities can be updated/patched to an account in ways that cannot be done on other blockchains.
Selecting Wallets
Unlike traditional wallet selectors that bundle wallet code, NEAR Connect uses a **manifest-based approach**: 1. Wallet providers register their integration scripts in a public manifest 2. The connector dynamically loads wallet scripts when users want to connect This architecture eliminates the need to install individual wallet packages and ensures wallet code can be updated independently from your app. ```tsx connector = new NearConnector({ network: "testnet", // or "mainnet" features: { signMessage: true, // Only show wallets that support message signing signTransaction: true, signInWithoutAddKey: true, signAndSendTransaction: true, signAndSendTransactions: true }, }); ```### Custom RPC If you want to use a user-defined RPC endpoint with the Wallet Selector, you can set up a [network options](https://github.com/near/wallet-selector/tree/main/packages/core#options) object with the custom URLs. For example: ```js const my_network = { networkId: "my-custom-network", nodeUrl: "https://rpc.custom-rpc.com", helperUrl: "https://helper.custom-helper.com", explorerUrl: "https://custom-explorer.com", indexerUrl: "https://api.custom-indexer.com", }; ```
### Creating an Access Key If you instantiated the `wallet-selector` passing an account id for the `createAccessKeyFor` parameter, then the wallet will create a [Function-Call Key](/protocol/access-keys#function-call-keys) and store it in the web's local storage. ```js const walletSelectorConfig = { network: "testnet", // "mainnet" createAccessKeyFor: "hello.near-examples.testnet", modules: [ setupMeteorWallet() // ... ], } ``` By default, such key enables to expend a maximum of `0.25Ⓝ` on GAS calling methods in **the specified** contract **without prompting** the user to sign them. If, on the contrary, you do not create an access key, then the user will be asked to sign every single transaction (except calls to `view methods`, since those are always free). :::tip Please notice that this only applies to **non-payable** methods, if you attach deposit to any call the user will **always** be redirected to the wallet to confirm the transaction. ::: --- ## Calling View Methods Once the wallet-selector is up, we can start calling view methods, i.e., the methods that perform read-only operations. Because of their read-only nature, view methods are **free** to call, and do **not require** the user to be **logged in**. To make a view call, you simply need to import the `viewFunction` from the wallet selector hooks:
## Sending Multiple Transactions The wallet-selector hook also exposes a method that can be used to send multiple transactions at once: ```js const { signAndSendTransactions } = useWalletSelector(); const txs = await signAndSendTransactions({ transactions: [{ receiverId: "hello.near-examples.testnet", actions: [{ type: "FunctionCall", params: { methodName: "set_greeting", args: { greeting: "Hello World" }, gas: THIRTY_TGAS, deposit: NO_DEPOSIT } }] }] }); ``` Transactions can either be sent as multiple separate transactions simultaneously or as a batch transaction made up of actions where if one of the actions fails, they are all reverted. An example of both can be seen [here](../../../tutorials/examples/frontend-multiple-contracts#dispatching-multiple-transactions). --- ## Querying Account Balance By calling the `getBalance` method the user can get the balance of a given account. ```js const { getBalance } = useWalletSelector(); const balance = await getBalance("account.testnet"); ``` --- ## Get Access Keys The final method the wallet selector hooks exposes is `getAccessKeys`, which is used to return an object of all the access keys on the account that is currently logged in. ```js const { getAccessKeys } = useWalletSelector(); const keys = await getAccessKeys("account.testnet"); ``` ::: :::note Versioning for this article At the time of this writing, this example works with the following versions: - next: `15.0.3` - near-api-js: `^5.0.1` - wllet-selector/core: `^8.10.0` ::: --- # Source: https://docs.near.org/web3-apps/concepts/web-login.md --- title: Web Login Methods id: web-login description: "Learn all the login options available for your website or web app" --- NEAR offers multiple options to allow users to login using NEAR accounts. Below are the most popular methods to integrate web login into your web app or website, each tailored to different use cases and user experiences. Once the user is logged in, they will be able to use their accounts to interact with the NEAR blockchain, making call to smart contracts, transfer tokens, and more. --- ## NEAR Connector [NEAR Connect](https://github.com/azbang/near-connect) is a zero-dependency lightweight library that allows users to connect to your dApp using their preferred wallet. It uses a secure sandbox-based architecture where wallet scripts run in isolated iframes.  :::tip You can learn how to integrate NEAR Connect into your app in the [NEAR Connector tutorial](../tutorials/wallet-login.md) ::: --- ## Social Login [Privy](https://www.privy.io/) is a third-party service that allows users to login using their email or social accounts (Google, Facebook, Twitter, etc). Upon login, a NEAR wallet is created for the user, which they can fund and use to interact with your dApp. :::tip Check our [Privy Integration Example](https://github.com/near-examples/hello-privy/) to learn how to integrate Privy into your web app :::  :::info Web3Auth For an alternative social login method you can check [Web3Auth](https://web3auth.io/). We have a functional [Web3Auth Integration Example](https://github.com/near-examples/hello-web3auth/) to show how to integrate Web3Auth into your web app. ::: --- # Source: https://docs.near.org/web3-apps/tutorials/web-login/web3-auth.md --- id: web3-auth title: Web3Auth Social Login Integration sidebar_label: Web3Auth Integration --- # Integrating Web3Auth with NEAR This tutorial demonstrates how to integrate [Web3Auth](https://web3auth.io/) into a NEAR application, enabling users to log in with social accounts (Google, Facebook, Twitter, etc.) while maintaining full blockchain functionality. :::tip What is Web3Auth? Web3Auth is a pluggable authentication infrastructure that allows users to authenticate using familiar Web2 logins (OAuth providers like Google, Facebook, etc.) while generating a cryptographic key pair for Web3 interactions. This provides a seamless onboarding experience without requiring users to manage seed phrases or private keys directly. ::: ## Clone and Install Start by cloning the repository and installing dependencies: ```bash git clone https://github.com/near-examples/hello-web3auth.git cd hello-web3auth/modal yarn install ``` --- ## Get Web3Auth Credentials To enable social login, you need to create a Web3Auth project and obtain a Client ID. ### Create a Web3Auth Account 1. Go to [Web3Auth Dashboard](https://dashboard.web3auth.io/) 2. Sign up or log in with your preferred method 3. You'll be redirected to the dashboard ### Create a New Project 1. Click on **"Add new project"** 2. Fill in the project details: - **Project Name**: Choose a descriptive name (e.g., "NEAR Social Login") - **Environment**: Select **"Sapphire Devnet"** for development - **Chain Namespace**: Choose **"Other"** (since NEAR is not natively supported) 3. Click **"Create"** ### Configure Your Project 1. Once created, click on your project to open its settings.In this section you can find Client ID and Client Secret which will be used in the application configuration. 2. Change the **Select Product** to **MPC Core Kit** 3. Change **Project platform** to **Web Application** 4. Go to the **"Domains"** tab 5. Add your application's URLs: - **Whitelist URLs**: Add `http://localhost:5173` for local development - For production, add your deployed URL (e.g., `https://yourdomain.com`) --- ## Configure Google OAuth (Optional but Recommended) While Web3Auth provides default OAuth providers, setting up your own Google OAuth gives you more control and branding. ### Create a Google Cloud Project 1. Open the [Google Cloud Console](https://console.cloud.google.com/). 2. Click Select a project → New Project (or choose an existing project). 3. Enter a project name (for example, NEAR Web3Auth) and click Create. 4. In the left sidebar, go to **APIs & Services** → **OAuth consent screen** ([direct link](https://console.cloud.google.com/auth/overview/create)). ### Configure OAuth Consent Screen 1. Go to **"APIs & Services"** → **"OAuth consent screen"** 2. Choose **"External"** (unless you have a Google Workspace) 3. Fill in the required information: - **App name**: Your application name - **User support email**: Your email - **Developer contact**: Your email 4. Click **"Save and Continue"** 5. On the **Scopes** page, click **"Save and Continue"** (default scopes are fine) 6. On the **Test users** page, add your email for testing 7. Click **"Save and Continue"** ### Create OAuth Credentials 1. Go to **"APIs & Services"** → **"Credentials"** 2. Click **"+ Create Credentials"** → **"OAuth client ID"** ([direct link](https://console.cloud.google.com/auth/clients/create)) 3. Select **"Web application"** 4. Configure: - **Name**: Choose a descriptive name - **Authorized JavaScript origins**: - Add `http://localhost:5173` (for development) - Add your production domain (when ready) - **Authorized redirect URIs**: - Add `https://auth.web3auth.io/auth` - This is Web3Auth's callback URL 5. Click **"Create"** 6. Copy the **Client ID** and **Client Secret** ### Add Google Credentials to Web3Auth 1. Return to [Web3Auth Dashboard](https://dashboard.web3auth.io/) 2. Go to the **Authentication** in left sidebar 3. Click on **Google** in social Logins 4. Click on **Add connection** and fill in the following details: - **Auth Connection ID***: Your desired connection ID (e.g., `near-login`),This use for verifier value in application configuration. - **Enter Google Client ID***: Your Google OAuth Client Secret from previous step.(e.g., `17426988624-32m2gh1o1n5qve6govq04ue91sioruk7WWapps.googleusercontent.com`) --- ## Configure Your Application Now that you have your Web3Auth Client ID, update your application configuration. ### Update the Config File Open `src/config.js` and replace the `clientId` with your own: ``` // Web3Auth Config import { CHAIN_NAMESPACES, WEB3AUTH_NETWORK } from '@web3auth/base' import { CommonPrivateKeyProvider } from '@web3auth/base-provider' const chainConfig = { chainNamespace: CHAIN_NAMESPACES.OTHER, chainId: 'near:testnet', // NEAR mainnet rpcTarget: 'https://rpc.testnet.near.org', displayName: 'NEAR Mainnet', blockExplorerUrl: 'https://nearblocks.io', ticker: 'NEAR', tickerName: 'NEAR', } const privateKeyProvider = new CommonPrivateKeyProvider({ config: { chainConfig } }) export const web3AuthContextConfig = { web3AuthOptions: { clientId: 'BP1rATmBxrPQ5BK0cMry4vmcOXJwYVSElff0dnb3in004j9lFE2SI2QUlC9Sy9lkqVgzussY6QPkOXWocnoJGGI', web3AuthNetwork: WEB3AUTH_NETWORK.SAPPHIRE_DEVNET, chainConfig, privateKeyProvider, } } // NEAR Config const contractPerNetwork = { mainnet: 'hello.near-examples.near', testnet: 'hello.near-examples.testnet', } export const NetworkId = 'testnet' export const providerUrl = 'https://test.rpc.fastnear.com' export const HelloNearContract = contractPerNetwork[NetworkId] ``` --- ## Run the Application Start the development server: ```bash yarn run dev ``` Open your browser and navigate to `http://localhost:5173`. ### Testing the Integration 1. Click the **"Login"** button in the navigation bar 2. The Web3Auth modal will appear with various login options 3. Choose **"Continue with Google"** (or another provider) 4. Complete the authentication flow 5. Once logged in, you'll see: - Your derived NEAR account ID in the navigation - Your NEAR balance - A logout button with your email/name --- ## Understanding the Implementation ### Architecture Overview This integration uses two main components: 1. **Web3Auth Modal** (`@web3auth/modal-react-hooks`): Provides the UI and authentication flow 2. **NEAR Integration** (custom provider): Derives NEAR keys from Web3Auth and manages blockchain interactions ### Key Components #### 1. Web3Auth Provider (`App.jsx`) ``` import { NEARxWeb3Auth } from './context/provider' import { web3AuthContextConfig } from './config'; function App() { // Use HashRouter when deployed under a subpath (GitHub Pages) const useHashRouter = import.meta.env.BASE_URL !== '/' const Router = useHashRouter ? HashRouter : BrowserRouter return (
Example: Cross-Chain NFT Marketplace
Imagine building a digital art marketplace where users can purchase NFTs from different blockchains (Ethereum, Solana, etc.). Without chain abstraction, you'd need to: - Implement multiple blockchain connections - Handle different wallet types - Manage cross-chain transfers - Build complex UIs to explain blockchain concepts With chain abstraction, both you and your users just focus on the core experience: browsing and trading art. All blockchain complexity is handled automatically behind the scenes.### Querying for the Greeting The contract performs a cross-contract call to `hello.near-example.testnet` to get the greeting message, and then handles the response in a **callback function**.
### Callback Function The callback function processes the result of the cross-contract call. In this case, it simply returns the greeting message obtained from the `hello-near` contract. Notice that the callback function is marked as **private**, meaning it can only be called by the contract itself.
### Deploying the Contract to the NEAR network In order to deploy the contract you will need to create a NEAR account.
### CLI: Interacting with the Contract To interact with the contract through the console, you can use the following commands: