Skip to content

Docs/2859 localnet indexer #3040

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
matiasbenary wants to merge 2 commits into
base: master
Choose a base branch
from
Draft

Docs/2859 localnet indexer #3040

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0b80190
docs: add localnet indexer tutorial
matiasbenary May 12, 2026
1e8148b
feat: add indexer for localnet tutorial
matiasbenary May 14, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
86 changes: 82 additions & 4 deletions web3-apps/tutorials/localnet/run.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -47,6 +47,17 @@ npx near-sandbox --home /tmp/near-sandbox run

The node will boot up and begin producing blocks locally.

<Note>
If the node fails to start with `IO error: While lock file: .../data/LOCK: Resource temporarily unavailable`, it means another sandbox process was previously running and left a stale lock. Kill any running sandbox processes and remove the lock file:

```sh
pkill -f near-sandbox || true
rm -f /tmp/near-sandbox/data/LOCK
```

Then run the `npx near-sandbox ... run` command again.
</Note>

<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`.
</Tip>
Expand Down Expand Up @@ -129,7 +140,7 @@ When you run the command above, you'll be prompted to enter the account ID. Type

In this step, we'll deploy a simple [Hello World smart contract](https://github.com/near-examples/hello-near-examples) to our `localnet`.

Before deploying, we need to create an accont to which a contract will be deployed. Since we've already imported the `test.near` account, we can use it as the parent account to create a new subaccount:
Before deploying, we need to create an account to which a contract will be deployed. Since we've already imported the `test.near` account, we can use it as the parent account to create a new subaccount:

```sh
near account create-account fund-myself hello-world.test.near '10 NEAR' autogenerate-new-keypair save-to-legacy-keychain sign-as test.near network-config localnet-sandbox sign-with-legacy-keychain send
Expand All @@ -152,8 +163,35 @@ cargo near deploy build-non-reproducible-wasm hello-world.test.near without-init

This command compiles the smart contract, optimizes the resulting `.wasm` file, and deploys it directly to the `hello-world.test.near` account on `localnet`.

<Warning>
There is a known dependency conflict in `hello-near-examples`: `near-sdk 5.x` transitively requires `darling 0.23` (via `near-primitives → serde_with`), which needs rustc ≥ 1.88. However, `near-sandbox 0.2.x` ships `nearcore 2.9.0`, which does not execute wasm compiled with rustc ≥ 1.87. If the `cargo near deploy` command above fails, use the following workaround:

First, make sure `wasm-opt` is available (if not already installed):

```sh
npm install -g wasm-opt
```

Then build and deploy manually:

```sh
# Build with the host toolchain, bypassing the rust-version check
cargo build --target wasm32-unknown-unknown --release --ignore-rust-version

# Optimize the wasm (required for nearcore compatibility on rustc ≥ 1.82)
mkdir -p target/near
wasm-opt -O --enable-nontrapping-float-to-int --enable-bulk-memory \
target/wasm32-unknown-unknown/release/contract_rs.wasm \
-o target/near/contract_rs.wasm

# Deploy
near contract deploy hello-world.test.near use-file target/near/contract_rs.wasm \
without-init-call network-config localnet-sandbox sign-with-legacy-keychain send
```
</Warning>

<Tip>
To verify that the contract was deployed successfully, you can inspect the code of the `hello-world.test.near` account with the following command `near contract inspect hello-world.test.near network-config localnet-sandbox now`. If the deployment worked, you'll see a list of the contract's methods printed in the output, like `get_greeting` and `set_greeting`.
To verify that the contract was deployed successfully, call `get_greeting` directly: `near contract call-function as-read-only hello-world.test.near get_greeting json-args '{}' network-config localnet-sandbox now`. If it returns `"Hello"`, the contract is running correctly.
</Tip>

#### Step 4. Create user's wallet account
Expand All @@ -162,7 +200,7 @@ In this step, we'll create a user account inside a wallet that can connect to ou

Navigate to https://wallet.intear.tech. If you don't have an account yet, create one or import any existing account. It doesn't matter which one, this step is just to get you inside the wallet interface.

Once you're in the wallet, open the `Settings` panel from the sidebar, then find the `Developer` tab. You'll see a `Localnet` subsection where you can add your own local network configuration. Click `Add`, and fill in the fields as follows: set the RPC URL to `http://127.0.0.1:3030` and the Network ID to `localnet`. Then click `Save`.
Once you're in the wallet, open the `Settings` panel from the sidebar, then find the `Developer` tab. You'll see a `Localnet` subsection where you can add your own local network configuration. Click `Add`, and fill in the fields as follows: set the RPC URL to `http://localhost:3030` and the Network ID to `localnet`. Then click `Save`.

If everything is configured correctly, you should see a small, green `Online` badge appear next to the new network indicating that it's connected. Here's how it should look like:

Expand All @@ -187,6 +225,12 @@ Once you're inside the repository, install the dependencies using `pnpm`:
pnpm install --frozen-lockfile
```

Next, create a `.env.local` file to point the app at your local node:

```sh
echo "NEXT_PUBLIC_RPC_URL=http://localhost:3030" > .env.local
```

Then, start the development Next.js server:

```sh
Expand All @@ -199,6 +243,40 @@ Once connected, you'll see an input field and a button to update the greeting. T

Return to the frontend and notice that the greeting has changed.

#### Step 6. (Optional) Stream blocks with NEAR Indexer

So far our `localnet` has been producing blocks silently. In this step, we'll attach the [NEAR Indexer](/data-infrastructure/near-indexer) to the same `localnet` so we can observe every block, transaction, and receipt in real time, which is useful for building back-ends, analytics, or end-to-end tests that react to on-chain events.

The indexer is essentially a `neard` node with extra streaming features, so we can point it at the **same home directory** the sandbox is already using (`/tmp/near-sandbox`). That way it joins our `localnet` as the node itself, reusing `genesis.json`, `validator_key.json`, `node_key.json` and `config.json`, no extra network setup required.

<Danger>
The NEAR Indexer Framework only works on **`Linux x86`**, it does **not** support Windows or MacOS. If you are on another platform, skip this step or run the indexer inside a Linux x86 container/VM that can reach the sandbox home directory.
</Danger>

First, stop the running sandbox node with `Ctrl+C`. Two processes can't share the same home directory, so the indexer will take its place as the `localnet` node.

Next, clone `nearcore` and build the indexer example:

```sh
git clone https://github.com/near/nearcore.git
cd nearcore/tools/indexer/example
cargo build --release
```

Then start the indexer pointing at the sandbox home directory:

```sh
cargo run --release -- --home-dir /tmp/near-sandbox run
```

The indexer will boot up using the existing `localnet` state and begin streaming finalized blocks to its handler. You'll see block data printed to stdout as new blocks are produced.

<Tip>
With the indexer running, open a new terminal and trigger a transaction against your contract (for example, calling `set_greeting` from the frontend or from `near-cli-rs`). The corresponding block, transaction, and receipts will appear in the indexer's output almost immediately.
</Tip>

To learn how to parse the streamed block data, filter by accounts or shards, and tweak sync/finality settings, head over to the full [Creating an Indexer tutorial](/data-infrastructure/tutorials/near-indexer).

---

You've now gone through the entire process of setting up a local NEAR environment — from running the Sandbox and deploying a contract to connecting a wallet and interacting with it through a frontend. With this setup, you can experiment freely, test your contracts safely, and build end-to-end decentralized applications without touching mainnet or testnet.
You've now gone through the entire process of setting up a local NEAR environment — from running the Sandbox and deploying a contract to connecting a wallet, interacting with it through a frontend, and streaming on-chain events with the NEAR Indexer. With this setup, you can experiment freely, test your contracts safely, and build end-to-end decentralized applications without touching mainnet or testnet.