Skip to content

Commit

Permalink
feat: minor edits to introductions
Browse files Browse the repository at this point in the history
  • Loading branch information
Guillermo Alejandro Gallardo Diez authored and Guillermo Alejandro Gallardo Diez committed Jan 2, 2025
1 parent 704e759 commit fc31507
Show file tree
Hide file tree
Showing 9 changed files with 78 additions and 326 deletions.
13 changes: 7 additions & 6 deletions docs/1.concepts/basics/protocol.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,12 +3,13 @@ id: protocol
title: What is NEAR?
---

NEAR is a **user-friendly** and [**carbon-neutral**](https://near.org/blog/near-climate-neutral-product/) blockchain, built to be [fast, secure, and able to grow without limits](https://www.leewayhertz.com/comparison-of-blockchain-protocols#Parallel-comparison-of-various-blockchain-networks).
NEAR is a **user-friendly** and [**carbon-neutral**](https://near.org/blog/near-climate-neutral-product/) blockchain, built to be [fast, secure, and infinitely scalable](https://www.leewayhertz.com/comparison-of-blockchain-protocols#Parallel-comparison-of-various-blockchain-networks).

![img](@site/static/docs/assets/welcome-pages/protocol.png)

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.

NEAR is the **blockchain for everyone**.
In simpler terms, NEAR is the **blockchain for everyone**.

<details>

Expand Down Expand Up @@ -36,14 +37,14 @@ NEAR is a technical marvel, offering built-in features such as named accounts an
2. Simple sign-up: make an account using [email](https://dev.near.org/signup) or [telegram](https://web.telegram.org/k/#@herewalletbot)
3. Transactions are **fast** _(~1.3s transactions)_ and **cheap** _(< 1¢ in fees)_
4. You don't need to buy crypto thanks to **built-in account abstraction**
5. [Access Keys](../protocol/access-keys.md) make it safe and easy to use.
5. [Access Keys](../protocol/access-keys.md) make it safe and easy to use
6. Control accounts on **other chains** thanks to [chain signatures](../abstraction/chain-signatures.md)

### 🛡️ Battle-Tested

1. 4 years of **100% uptime** with more than [**800M** transactions](https://pikespeak.ai/near-world/overview) processed
2. NEAR has sustained peaks of [>13M transactions](https://pikespeak.ai/near-world/overview) in a day
3. In March 2024, the top three monthly [dApps](https://dappradar.com/rankings?range=30d), based on unique active wallets, were built on NEAR:
1. 4 years of **100% uptime** and [**3 Billion** transactions](https://pikespeak.ai/near-world/overview) processed
2. NEAR has sustained peaks of [>13M transactions](https://pikespeak.ai/near-world/overview) in a single day
3. NEAR is home to decentralized apps with [millions of users](https://dappradar.com/rankings?range=30d):
- [Kai-ching](https://cosmose.ai/)
- [Sweat](https://sweateconomy.com/)
- [Hot Wallet](https://t.me/herewalletbot/)
Expand Down
36 changes: 23 additions & 13 deletions docs/1.concepts/protocol/access-keys.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,14 +2,14 @@
id: access-keys
title: Access Keys
---
In all blockchains, users control their accounts by holding a `private key` (a secret only they know) and using it to sign [transactions](./transactions.md).
In all blockchains, users control their accounts by holding a [`private key`](](https://en.wikipedia.org/wiki/Public-key_cryptography) (a secret only they know) and using it to sign [transactions](./transactions.md).

![img](@site/static/docs/assets/welcome-pages/access-keys.png)

NEAR accounts present the **unique** feature of being able to hold multiple [Access Keys](https://en.wikipedia.org/wiki/Public-key_cryptography), each with its **own set of permissions**. We distinguish two types of Keys:
NEAR accounts present the **unique** feature of being able to hold **multiple Access Keys**, each with its **own set of permissions**. We distinguish two types of Keys:

1. `Full-Access Keys`: Have full control over the account, and should **never be shared**
2. `Function-Call Keys`: Can sign calls to specific contract, and are **meant to be shared**
2. `Function-Call Keys`: Can only sign calls for specific contracts, and are **meant to be shared**

---

Expand All @@ -25,22 +25,24 @@ As the name suggests, `Full-Access` keys have full control of an account, meanin
You should never share your `Full-Access`, otherwise you are giving **total control over the account**.

:::tip
The **first** Full-Access Key of an account is added when the account is **created**
[Implicit accounts](./account-id.md#implicit-address) already have a `Full-Access Key` by default, while for [`named accounts`](./account-id.md#named-address) their first `Full-Access Key` is added on creation
:::

---

## Function-Call Keys {#function-call-keys}

`Function-Call` keys can only sign transactions calling a **specific contract**, and do **not allow** to **attach NEAR tokens** to the call. They are defined by three attributes:
1. `receiver_id`: The **contract** which the key allows to call. No other contract can be called using this key
2. `method_names` (Optional): The contract's **methods** the key allows to call. If omitted, all methods can be called
3. `allowance` (Optional): The **amount of NEAR** allowed to be spent on [gas](gas.md). If omitted, the key can consume **unlimited** as gas
`Function-Call` keys can only sign transactions calling a **specific contract**, and do **not allow** to **attach NEAR tokens** to the call.

Function-Call keys have the main purpose of being shared, so third-parties can make contract calls in your name. This is useful in [multiple scenarios as we will see below](#benefits-of-function-call-keys).
They are defined by three attributes:
1. `receiver_id`: The **only contract** which the key allows to call, no other contract can be called with this key
2. `method_names` (Optional): The contract's **methods** the key allows to call. If omitted, all contract's methods can be called
3. `allowance` (Optional): The **amount of NEAR** allowed to be spent on [gas](gas.md). If omitted, the key can consume **unlimited** gas

`Function Call Keys` are meant to be shared with applications, so third-parties can make contract calls in your name. This is useful in [multiple scenarios as we will see below](#benefits-of-function-call-keys).

:::tip
`Function-Call` keys are secure to share, as they only permit calls to a specific contract and prohibit NEAR token transfers.
`Function-Call` keys are secure to share, as they only permit calls to a specific contract and prohibit NEAR token transfers
:::

---
Expand All @@ -62,11 +64,19 @@ Sharing this key is safe for the user, because even in the case of somebody stea

### Simple Onboarding

Another common use-case of `Function-Call` keys is to simplify the **onboarding** process for new users. It works as follows:
Another common use-case of `Function-Call` keys is to simplify the **onboarding** process for new users.

It works as follows:

1. Create a contract that has a method called `create_account`
- This method should only be callable by the contract itself and
- When executed, the method should create a new account and transfer some tokens to it

2. Add multiple `Function Call Keys` in the contract's account, that **only allow to call `create_account`**

First create a contract that has a method called `create_account`. This method should only be callable by the contract itself and, when executed, should create a new account and transfer some tokens to it.
3. Give these keys to your friends! They will be able to call the method, and easily create an account with some tokens

You can then create multiple `Function-Call` in the contract's account, that only allow to call `create_account`. Drop these keys to your friends, so they can call the method, and easily create an account with some tokens.
Your main account and your funds will never be at risk, as the keys can only be used to call the `create_account` method.

:::tip
This is the basic principle behind [NEAR Drops](../../2.build/5.primitives/linkdrop.md), a way to distribute assets to a large number of users
Expand Down
20 changes: 13 additions & 7 deletions docs/1.concepts/protocol/account-id.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,12 +6,12 @@ title: Address (Account ID)
import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

NEAR accounts are identified by a unique address, which take one of two forms:
1. [**Implicit addresses**](#implicit-address), which are 64 characters long (e.g. `fb9243ce...`)
2. [**Named addresses**](#named-address), which are simpler to remember and act as domains (e.g. `alice.near`)
NEAR accounts are identified by a unique address, which takes one of two forms:
1. [**Implicit address**](#implicit-address), which are 64 characters long (e.g. `fb9243ce...`)
2. [**Named address**](#named-address), which act as domains (e.g. `alice.near`)

:::tip Searching to create an account?
You have multiple ways to create an account, you can [sign-up using your email](https://dev.near.org/signup) (note: email-based accounts currently have limited ability to transfer funds or sign transactions), get a mobile wallet through [telegram](https://web.telegram.org/k/#@herewalletbot), or create a [web wallet](https://app.mynearwallet.com).
You have multiple ways to create an account, you can [sign-up using your email](https://dev.near.org/signup), get a mobile wallet through [telegram](https://web.telegram.org/k/#@herewalletbot), or create a [web wallet](https://wallet.meteorwallet.app/wallet).
:::

---
Expand All @@ -24,7 +24,13 @@ For example:
- Corresponds to the public key: `ed25519:CQLP1o1F3Jbdttek3GoRJYhzfT...`
- And controls the account: `a96ad3cb539b653e4b869bd7cf26590690e8971...`

Implicit accounts always *exist*, and thus do not need to be created. However, in order to use the account you will still need to fund it with NEAR tokens (or get somebody to pay the gas for your transaction).
Implicit accounts always *exist*, and thus do not need to be created. However, in order to use the account you will still need to fund it with NEAR tokens (or get a relayer to pay your transaction's [gas](./gas.md)).

:::tip

In NEAR, you can delete the private key of an implicit account, which effectively locks the account and prevents anyone to control it

:::

<details>

Expand All @@ -46,9 +52,9 @@ near account create-account fund-later use-auto-generation save-to-folder ~/.nea
---

## Named Address
In NEAR, users can register **named accounts** (e.g. `bob.near`) which are simpler to share and remember.
Users can register **named accounts** (e.g. `bob.near`) which are easy to remember and share.

Another advantage of named accounts is that they can create **sub-accounts** of themselves, effectively working as domains:
An awesome feature of named accounts is that they can create **sub-accounts** of themselves, effectively working as domains:

1. The [`registrar`](https://nearblocks.io/address/registrar) account can create top-level accounts (e.g. `near`, `sweat`, `kaiching`).
2. The `near` account can create sub-accounts such as `bob.near` or `alice.near`
Expand Down
24 changes: 15 additions & 9 deletions docs/1.concepts/protocol/account-model.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ By signing [transactions](./transactions.md) with their account, users can:
4. Help onboard new users by **covering the costs** of their transactions (gas fees)

:::tip Want to create an account?
You have multiple ways to create an account, you can [sign-up using your email](https://dev.near.org/signup) (note: email-based accounts currently have limited ability to transfer funds or sign transactions), get a mobile wallet through [telegram](https://web.telegram.org/k/#@herewalletbot), or create a [web wallet](https://app.mynearwallet.com).
You have multiple ways to create an account, you can [sign-up using your email](https://dev.near.org/signup), get a mobile wallet through [telegram](https://web.telegram.org/k/#@herewalletbot), or create a [web wallet](wallet.meteorwallet.app)
:::

---
Expand All @@ -27,22 +27,28 @@ Let's take a closer look at the different elements that compose the NEAR account


#### [Account ID](account-id.md)
NEAR implements two types of accounts IDs: **named accounts** such as `alice.near`, which are simple to remember and share, and the classic alphanumeric IDs (`fb9243ce...`) that other chains also implement.
NEAR **natively** implements two types of accounts:
1. **Named accounts** such as `alice.near`, which are simple to remember and share
2. **Implicit accounts** such as `0xfb9243ce...`, which are derived from a private key

#### [Permissions Through Access Keys](access-keys.md)
NEAR accounts can have multiple [keys](access-keys.md), each with their own set of permissions. This allows to easily swap keys if one gets compromised, and to use keys as authorization tokens for third-parties.
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

#### [Simple to Develop Smart Contracts](../../2.build/2.smart-contracts/what-is.md)
NEAR accounts can optionally hold a simple program, known as a [smart contract](../../2.build/2.smart-contracts/what-is.md). In NEAR, developers can create smart contracts using languages such as Javascript or Rust.
NEAR accounts can optionally hold an application - known as a [smart contract](../../2.build/2.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 Wallet | NEAR Account |
|-------------------|---------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------|
| Public Identifier | Public Key (`0x123...`) | Named IDs (`alice.near`) and implicit accounts (Public Key `0x123...`) |
| Secret Key | Private Key (`0x456...`) | Multiple key-pairs with permissions:<br />- `FullAccess` key<br />- `FunctionCall` key |
| Characteristics | - Private key gives full access<br />- Account doesn't have to be created via a transaction | - Permission-based keypair<br />- Account ID must be created via blockchain transaction |
| | Ethereum Account | NEAR Account |
|-----------------|--------------------------|----------------------------------------------------------------------------------------|
| Account ID | Public Key (`0x123...`) | - Native named accounts (`alice.near`) <br />- Implicit accounts (`0x123...`) |
| Secret Key | Private Key (`0x456...`) | Multiple key-pairs with permissions:<br />- `FullAccess` key<br />- `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 | ~1.3 second |
19 changes: 1 addition & 18 deletions docs/1.concepts/protocol/gas.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -198,25 +198,8 @@ Notice that the fee comes from the gas burned during the function execution, and

## Estimating Costs for a Call

:::warning
This section will soon be moved from here to the [build documentation](../../2.build/2.smart-contracts/anatomy/environment.md).
:::

If you're developing a smart contract, you might want to estimate how much gas a function call will consume. This is useful to estimate limits for your function and avoid running into out-of-gas errors.

One of the most accurate ways to estimate gas costs is by running your function in `testnet`. To know exactly how much gas a specific part of your function uses, you can use the `used_gas` method from our SDK.

Another option is to use `Sandbox Testing` (available in [Rust](https://github.com/near/workspaces-rs/tree/main/examples/src) and [JavaScript](https://github.com/near/workspaces-js)), which simulates the NEAR network. There you can access the gas burnt after each function call.

Finally, you can obtain gas cost estimates for a given function call using `api.gasbuddy.tech`. This API is experimental and may be removed in the future. One can obtain a gas cost estimate for a given function call by sending a POST request to `https://api.gasbuddy.tech/profile` with the following JSON body:

```json
{
"contract_id": "<your-contract-account-id>",
"method": "<your-contract-method-name>",
"args": {
"arg1": "value1",
"arg2": "value2"
}
}
```
Another option is to use `Sandbox Testing` (available in [Rust](https://github.com/near/workspaces-rs/tree/main/examples/src) and [JavaScript](https://github.com/near/workspaces-js)), which simulates the NEAR network. There you can access the gas burnt after each function call.
Loading

0 comments on commit fc31507

Please sign in to comment.