Skip to content
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

Add near-validator extension #2493

Open
wants to merge 10 commits into
base: master
Choose a base branch
from
+279 −2
Open

Add near-validator extension #2493

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
a4e0208
Update cli.md
bucanero Mar 5, 2025
8122ff1
Merge branch 'master' into 2377-295-request-for-near-validator-cli-ex…
bucanero Mar 5, 2025
fab0bcb
Update cli.md
bucanero Mar 6, 2025
eef2a38
Update staking.md
bucanero Mar 6, 2025
8668049
Update staking.md
bucanero Mar 7, 2025
4fdbc48
Update staking.md
bucanero Mar 7, 2025
4980046
Update cli.md
bucanero Mar 7, 2025
7eb76da
Update staking.md
bucanero Mar 7, 2025
b94188e
Update staking.md
bucanero Mar 7, 2025
f1f2e91
Merge branch 'master' into 2377-295-request-for-near-validator-cli-ex…
bucanero Mar 11, 2025
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
146 changes: 145 additions & 1 deletion docs/1.concepts/basics/staking.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,13 @@ Before delegating, you need to choose a validator (a node that participates in s
Once you select a validator and the stake transaction is confirmed, your tokens are delegated to the staking pool.
You will start earning staking rewards after the next epoch (approximately 12 hours).

:::info Delegation without a staking pool

For validators, there's also an option to stake NEAR tokens without deploying a staking pool smart contract.
Check [this section](../../4.tools/cli.md#staking) to learn how to stake using the [`near-validator`](../../4.tools/cli.md#validator-extension) CLI.

:::

### Selecting a Staking Pool

Use [NearBlocks](https://nearblocks.io/node-explorer), [Pikespeak](https://pikespeak.ai/validators/overview) or [Near Staking](https://near-staking.com/) to find a validator and their staking pool.
Expand All @@ -66,28 +73,74 @@ Look for validators with a good track record, uptime, and reasonable commission

:::

If you prefer, you can get the list of current validators by using the [`near-validator`](../../4.tools/cli.md#validator-extension) CLI:

```sh
near-validator validators network-config mainnet now
```

### Staking using CLI

Once you have chosen a validator you want to delegate your tokens to, follow these steps to stake them using the NEAR CLI:

1. Connect your wallet to the CLI and ensure you have NEAR tokens to delegate.

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near account import-account using-web-wallet network-config mainnet
```

</TabItem>
<TabItem value="Short">

```sh
near login
```

</TabItem>
</Tabs>


2. Deposit tokens to the `<my_validator>` staking pool:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near call <my_validator> deposit '{}' --accountId <user-account.near> --amount 100
near contract call-function as-transaction <my_validator> deposit json-args {} prepaid-gas '30.0 Tgas' attached-deposit '100 NEAR' sign-as <user-account.near> network-config testnet sign-with-keychain send
```

</TabItem>
<TabItem value="Short">

```sh
near call <my_validator> deposit '{}' --accountId <user-account.near> --deposit 100
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

there's no need to take deposit and stake actions apart, as it can be done within a single function call

near staking delegation <user-account.near> deposit-and-stake

```

</TabItem>
</Tabs>

3. Stake the deposited tokens by calling the `stake` method:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near staking delegation <user-account.near> stake '100 NEAR' <my_validator> network-config mainnet sign-with-keychain
```

</TabItem>
<TabItem value="Short">

```sh
near call <my_validator> stake '{"amount": "100000000000000000000000000"}' --accountId <user-account.near>
```

</TabItem>
</Tabs>

:::tip Interactive CLI

If you want to manage your staking actions with an interactive CLI, use this command and follow the prompts on your screen:
Expand All @@ -102,10 +155,23 @@ near staking delegation

Once the transaction is confirmed, your tokens are delegated to the staking pool.

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near staking delegation <user-account.near> view-balance <my_validator> network-config mainnet now
```

</TabItem>
<TabItem value="Short">

```sh
near view <my_validator> get_account_staked_balance '{"account_id": "<user-account.near>"}'
```

</TabItem>
</Tabs>

:::info Using a wallet to check your staked tokens

You can see your staked balance, rewards earned, and the validator you delegated to using a web3 wallet. For example, you can try `https://app.mynearwallet.com/profile/<user-account.near>`.
Expand All @@ -121,18 +187,44 @@ The rewards are typically distributed periodically, and you will be able to see

To check your total balance on the `<my_validator>` pool:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near staking delegation <user-account.near> view-balance <my_validator> network-config mainnet now
```

</TabItem>
<TabItem value="Short">

```sh
near view <my_validator> get_account_total_balance '{"account_id": "<user-account.near>"}'
```

</TabItem>
</Tabs>

#### User staked balance

To check your staked balance on the `<my_validator>` pool:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near staking delegation <user-account.near> view-balance <my_validator> network-config mainnet now
```

</TabItem>
<TabItem value="Short">

```sh
near view <my_validator> get_account_staked_balance '{"account_id": "<user-account.near>"}'
```

</TabItem>
</Tabs>

<details>
<summary>Staking pool balances</summary>

Expand Down Expand Up @@ -181,30 +273,82 @@ To un-delegate the tokens:

1. First execute the `unstake` method on the `<my_validator>` contract:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near staking delegation <user-account.near> unstake '1 NEAR' <my_validator> network-config mainnet sign-with-keychain
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I believe it's worth mentioning, that as an alternative a user can unstake all NEAR tokens at once by calling unstake_all

```

</TabItem>
<TabItem value="Short">

```sh
near call <my_validator> unstake '{"amount": "100000000000000000000000000"}' --accountId <user-account.near>
```

</TabItem>
</Tabs>

2. Check the unstaked balance for your `<user-account.near>` account:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near staking delegation <user-account.near> view-balance <my_validator> network-config mainnet now
```

</TabItem>
<TabItem value="Short">

```sh
near view <my_validator> get_account_unstaked_balance '{"account_id": "<user-account.near>"}'
```

</TabItem>
</Tabs>

3. After 4 epochs, check if you can withdraw:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near contract call-function as-read-only <my_validator> is_account_unstaked_balance_available json-args '{"account_id": "<user-account.near>"}' network-config mainnet now
```

</TabItem>
<TabItem value="Short">

```sh
near view <my_validator> is_account_unstaked_balance_available '{"account_id": "<user-account.near>"}'
```

</TabItem>
</Tabs>

If the Validator's response is `true`, then your tokens are ready for the last step.

4. Finally, withdraw the unstaked tokens:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near staking delegation <user-account.near> withdraw '1 NEAR' <my_validator> network-config mainnet sign-with-keychain
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the same as above, a user can withdraw everything at once
near staking delegation <user-account.near> withdraw-all

```

</TabItem>
<TabItem value="Short">

```sh
near call <my_validator> withdraw '{"amount": "100000000000000000000000000"}' --accountId <user-account.near>
```

</TabItem>
</Tabs>

---

## Tools and Resources
Expand Down
135 changes: 134 additions & 1 deletion docs/4.tools/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,37 @@ The NEAR [Command Line Interface](https://github.com/near/near-cli-rs) (CLI) is
</TabItem>
</Tabs>

### Validator Extension
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

let's move the installation guide down to the "Validators" section, as it's the only place on this page where it's actually needed


If you want to interact with [NEAR Validators](https://pages.near.org/papers/economics-in-sharded-blockchain/#validators) from command line, you can also install the optional [NEAR Validator CLI Extension](https://github.com/near-cli-rs/near-validator-cli-rs):

<Tabs>
<TabItem value="npm">

```bash
npm install -g near-validator
```
</TabItem>
<TabItem value="Cargo">

```bash
$ cargo install near-validator
```
</TabItem>
<TabItem value="Mac and Linux (binaries)">

```bash
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near-cli-rs/near-validator-cli-rs/releases/latest/download/near-validator-installer.sh | sh
```
</TabItem>
<TabItem value="Windows (binaries)">

```bash
irm https://github.com/near-cli-rs/near-validator-cli-rs/releases/latest/download/near-validator-installer.ps1 | iex
```
</TabItem>
</Tabs>

---

## Configuration file
Expand Down Expand Up @@ -540,4 +571,106 @@ This will allow you to change or modify the network connections for your CLI.

:::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

:::tip
To use these commands, you **must** install the CLI [validator extension](#validator-extension).
:::

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)

### Proposals

A proposal by a validator indicates they would like to enter the validator set, in order for a proposal to be accepted it must meet the minimum seat price.

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near-validator proposals network-config mainnet
```

</TabItem>
</Tabs>

### Current Validators

This shows a list of active validators in the current epoch, the number of blocks produced, number of blocks expected, and online rate. Used to monitor if a validator is having issues.

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near-validator validators network-config mainnet now
```

</TabItem>
</Tabs>

### Next Validators

This shows validators whose proposal was accepted one epoch ago, and that will enter the validator set in the next epoch.

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near-validator validators network-config mainnet next
```

</TabItem>
</Tabs>

### Staking

For validators, there's also an option to stake NEAR tokens without deploying a staking pool smart contract.

#### View validator stake

To view the validator's stake on the last block, you need to enter in the terminal command line:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near-validator staking view-stake examples.testnet network-config testnet now
```

</TabItem>
</Tabs>

#### Stake directly without a staking pool

To stake the amount you must enter in the terminal command line:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near-validator staking stake-proposal examples.testnet ed25519:AiEo5xepXjY7ChihZJ6AsfoDAaUowhPgvQp997qnFuRP '1500 NEAR' network-config testnet sign-with-keychain send
```

</TabItem>
</Tabs>

#### Unstake directly without a staking pool

To unstake you must enter in the terminal command line:

<Tabs groupId="cli-commands">
<TabItem value="Full">

```sh
near-validator staking unstake-proposal examples.testnet ed25519:AiEo5xepXjY7ChihZJ6AsfoDAaUowhPgvQp997qnFuRP network-config testnet sign-with-keychain send
```

</TabItem>
</Tabs>
Loading