From 0d37edc190c70f14fc0ce19aba1d6f961bef8745 Mon Sep 17 00:00:00 2001 From: Guille Date: Tue, 21 Jan 2025 19:07:01 +0100 Subject: [PATCH] Improvements based on how our Docs AI answer (#2438) * feat: consolidate frontend docs * feat: collections of improvements --------- Co-authored-by: Guillermo Alejandro Gallardo Diez Co-authored-by: Guillermo Alejandro Gallardo Diez --- blog/2024-11-07.md | 4 +- .../3.advanced/near-indexer-framework.md | 59 -- docs/1.concepts/abstraction/meta-tx.md | 29 +- docs/1.concepts/protocol/access-keys.md | 8 +- docs/1.concepts/web3/blockchain.md | 163 ----- docs/1.concepts/web3/economics.md | 52 -- docs/1.concepts/web3/intro.md | 23 - docs/1.concepts/web3/near.md | 208 ------ docs/1.concepts/web3/nfts.md | 629 ------------------ .../4.web3-apps}/ethereum-wallets.md | 0 docs/2.build/4.web3-apps/quickstart.md | 2 +- .../lake-framework}/near-lake-framework.md | 27 +- .../crosswords/02-beginner/05-logging-in.md | 4 +- docs/4.tools/cli.md | 7 +- docs/4.tools/ecosystem-apis/fastnear-api.md | 76 +-- docs/4.tools/ecosystem-apis/nearblocks-api.md | 38 +- docs/4.tools/ecosystem-apis/pikespeak-api.md | 40 +- docs/4.tools/explorer.md | 9 +- docs/4.tools/indexing-tools.md | 8 +- docs/4.tools/near-api.md | 15 +- docs/4.tools/wallet-selector.md | 55 +- docs/4.tools/wallets.md | 25 - docs/4.tools/welcome.md | 28 +- website/docusaurus.config.js | 29 +- website/package.json | 4 +- website/sidebars.js | 60 +- 26 files changed, 210 insertions(+), 1392 deletions(-) delete mode 100644 docs/1.concepts/3.advanced/near-indexer-framework.md delete mode 100644 docs/1.concepts/web3/blockchain.md delete mode 100644 docs/1.concepts/web3/economics.md delete mode 100644 docs/1.concepts/web3/intro.md delete mode 100644 docs/1.concepts/web3/near.md delete mode 100644 docs/1.concepts/web3/nfts.md rename docs/{4.tools => 2.build/4.web3-apps}/ethereum-wallets.md (100%) rename docs/{1.concepts/3.advanced => 2.build/6.data-infrastructure/lake-framework}/near-lake-framework.md (78%) delete mode 100644 docs/4.tools/wallets.md diff --git a/blog/2024-11-07.md b/blog/2024-11-07.md index 36c9a46da0d..0fc0db21d72 100644 --- a/blog/2024-11-07.md +++ b/blog/2024-11-07.md @@ -65,13 +65,13 @@ Check [this transaction](https://testnet.nearblocks.io/txns/GrVGFVFmGBcNP5xkoA21 In order to support Ethereum wallets, you only need to update your version of `wallet-selector`, and configure it to include the new `ethereum-wallets` module. -Do not worry! it is very simple, check our [**tutorial**](/tools/ethereum-wallets) and working example [**hello world frontend**](https://github.com/near-examples/hello-near-examples/tree/main/frontend). +Do not worry! it is very simple, check our [**tutorial**](/build/web3-apps/ethereum-wallets) and working example [**hello world frontend**](https://github.com/near-examples/hello-near-examples/tree/main/frontend). --- ## Resources -1. [**Integration Tutorial**](/tools/ethereum-wallets) +1. [**Integration Tutorial**](/build/web3-apps/ethereum-wallets) 2. [Hello World Example](https://github.com/near-examples/hello-near-examples/blob/main/frontend/) diff --git a/docs/1.concepts/3.advanced/near-indexer-framework.md b/docs/1.concepts/3.advanced/near-indexer-framework.md deleted file mode 100644 index a534edde98b..00000000000 --- a/docs/1.concepts/3.advanced/near-indexer-framework.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -sidebar_label: "Indexer Framework" ---- - -# NEAR Indexer Framework - -:::note GitHub repo - -https://github.com/near/nearcore/tree/master/chain/indexer - -::: - - -:::caution You might be looking for NEAR Lake Framework - -[NEAR Lake Framework](near-lake-framework.md) is a lightweight alternative to NEAR Indexer Framework that is recommended for use when centralization can be tolerated. - -::: - - -## Description - -NEAR Indexer Framework is a Rust package (crate) that embeds [nearcore](https://github.com/near/nearcore), and abstracts away all the complexities of collecting every bit of information related to each produced block in NEAR network. The crate name is [`near-indexer`](https://github.com/near/nearcore/tree/master/chain/indexer), and it is part of the [nearcore repository](https://github.com/near/nearcore). - -`near-indexer` is a micro-framework, which provides you with a stream of blocks that are recorded on NEAR network. It is useful to handle real-time "events" on the chain. - -## Rationale - -As scaling dApps enter NEAR’s mainnet, an issue may arise: how do they quickly and efficiently access state from our deployed smart contracts, and cut out the cruft? Contracts may grow to have complex data structures and querying the network RPC may not be the optimal way to access state data. The NEAR Indexer Framework allows for streams to be captured and indexed in a customized manner. The typical use-case is for this data to make its way to a relational database. Seeing as this is custom per project, there is engineering work involved in using this framework. - -## Limitations - -NEAR Indexer Framework embeds the full NEAR node and thus requires to sync with the peer-to-peer network and store all the network data locally thus it is subject to the storage requirements, which is hundreds of GBs on SSD if you only need to extract the data that is not older than ~2.5 days, and thousands of GBs on SSD if you want to be able to go over the whole history of the network. Also, the network sync process is known to be extremely slow (while the block production is 1 block per second, while the block sync usually reaches 2 blocks per second, which means that it is capable to catch up with the live network at a speed of 1 block per second, so if your node was offline for one hour, it will take one hour to catch up to the tip of the network that keeps getting freshly produced blocks). - -NEAR Indexer Framework only exposes the blocks that were finalized. In NEAR Protocol, it takes 3 consecutive blocks to get the block finalized which means that there is at least a 3-second delay between the time when some transaction hits the network, and the time it is finalized and streamed from NEAR Indexer Framework. If we measure the delay between the moment when a transaction gets submitted from the client device to the moment Indexer Framework-based indexers would receive it, we can see the following timings: - -* A serialized transaction being transferred over the Internet to NEAR node (most commonly, through [NEAR JSON RPC broadcast_tx_commit](https://docs.near.org/api/rpc/transactions#send-transaction-await)): around 50ms (it is not measured precisely as it is mostly network latency of TCP handshake + HTTPS handshake) -* The transaction is routed to the [validation node](https://near-nodes.io/intro/what-is-a-node): around 50ms (again, mostly network latency between the peer nodes) -* The transaction arrives in the mempool on the validation node and will be delayed at least until the next chunk/block is produced, so if the transaction was received right at the moment when transactions for the current block were selected, it would take 1.2 seconds on mainnet to get the next block produced -* Once the transaction is included in a block, it will produce a receipt which often will be executed in the next block (another 1.2-second delay) - learn more about the NEAR Protocol data flow [here](../data-flow/near-data-flow.md) -* Given that block finalization takes 3 blocks (1.2 seconds * 3), Indexer Framework will only get the opportunity to start collecting the information about the block where the transaction was included 3.6 seconds later, but we should also include at least a 50ms delay that is introduced by the network latency when produced blocks propagate back from the validation nodes back to the regular nodes -* Indexer Framework then collects all the bits of information for the produced block and streams it: around 50-100ms -* Custom indexer implementation receives the block and there could be additional delays down the line, but that is outside of our scope here - -Ultimately, it takes at least 3.8 seconds from the moment one submits a transaction to the network, and Indexer Framework-based indexers pick it up, where the finalization time contributes the most of the delay. In real life scenario, dApps usually need to know the result of the execution, and so it will take a couple of blocks after the transaction is included to get all the receipts executed (read more about the data flow [here](../data-flow/near-data-flow.md)), so the delay between the transaction submission and the result being observed by an indexer could be 5-7 seconds. - -## Current Status - -Indexer Framework is a tool that provides a straightforward way of getting a stream of finalized NEAR Protocol blocks as soon as possible operating over a decentralized NEAR Protocol peer-to-peer network. - -However, in our experiments with the Indexer ecosystem, we realized that we need a lightweight foundation to build micro-indexers instead of maintaining a full [nearcore](https://github.com/near/nearcore) node. We considered various solutions to deliver events (Kafka, RabbitMQ, etc), but ultimately we decided to dump all the blocks as is to AWS S3 bucket. This is where NEAR Lake ecosystem was born, learn more about it [here](near-lake-framework.md). - -These days, we use NEAR Indexer Framework to implement [NEAR Lake Indexer](https://github.com/near/near-lake-indexer) and from there we build micro-indexers based on [NEAR Lake Framework](near-lake-framework.md). Having said that, Indexer Framework plays a crucial role in the ecosystem even though most of the indexers these days are implemented without using it directly. - -## Applications - -See the [example](https://github.com/nearprotocol/nearcore/tree/master/tools/indexer/example) for further technical details. - -- [`near-examples/indexer-tx-watcher-example`](https://github.com/near-examples/indexer-tx-watcher-example) NEAR Indexer example that watches for transaction for specified accounts/contracts diff --git a/docs/1.concepts/abstraction/meta-tx.md b/docs/1.concepts/abstraction/meta-tx.md index 4a937c80e81..e930bc99fb5 100644 --- a/docs/1.concepts/abstraction/meta-tx.md +++ b/docs/1.concepts/abstraction/meta-tx.md @@ -159,23 +159,20 @@ but will fail on Bob's shard. --- -## Function access keys in meta transactions +## Function Call Access Keys in Meta Transactions + +[Function Call Access Keys](../protocol/access-keys.md#function-call-keys-function-call-keys) +are limited to signing transactions for specific methods on a specific contract. -Function access keys can limit the allowance, the receiving contract, and the -contract methods. The allowance limitation acts slightly strange with meta -transactions. -But first, both the methods and the receiver will be checked as expected. That -is, when the delegate action is unwrapped on Alice's shard, the access key is -loaded from the DB and compared to the function call. If the receiver or method -is not allowed, the function call action fails. +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. -For allowance, however, there is no check. All costs have been covered by the -relayer. Hence, even if the allowance of the key is insufficient to make the call -directly, indirectly through meta transaction it will still work. +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. -This behavior is in the spirit of allowance limiting how much financial -resources the user can use from a given account. But if someone were to limit a -function access key to one trivial action by setting a very small allowance, -that is circumventable by going through a relayer. An interesting twist that -comes with the addition of meta transactions. +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. \ No newline at end of file diff --git a/docs/1.concepts/protocol/access-keys.md b/docs/1.concepts/protocol/access-keys.md index ed8613d0490..9eaae4fc181 100644 --- a/docs/1.concepts/protocol/access-keys.md +++ b/docs/1.concepts/protocol/access-keys.md @@ -2,15 +2,19 @@ id: access-keys title: Access Keys --- -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). + +In most blockchains, users control their accounts by holding a single [`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**, each with its **own set of permissions**. We distinguish two types of Keys: +In NEAR we distinguish two types of Access Keys: 1. `Full-Access Keys`: Have full control over the account, and should **never be shared** 2. `Function-Call Keys`: Can only sign calls for specific contracts, and are **meant to be shared** +Every account in NEAR can hold **multiple keys**, and keys can be added or removed, allowing a +fine-grained control over the account's permissions. + --- ## Full-Access Keys {#full-access-keys} diff --git a/docs/1.concepts/web3/blockchain.md b/docs/1.concepts/web3/blockchain.md deleted file mode 100644 index aedd5c37411..00000000000 --- a/docs/1.concepts/web3/blockchain.md +++ /dev/null @@ -1,163 +0,0 @@ ---- -id: basics -title: Blockchain basics -sidebar_label: Blockchain basics ---- - -Before diving deeper into the intricacies of Web 3 development, let’s explore what it is and why it exists. -First of all - what does number 3 mean? The World Wide Web, or Internet in general, has evolved through the years and can be loosely divided into the 3 “generations”: - -- Web 1.0 - the first generation, roughly from 1991 to 2004. At this time, the Internet was slow, expensive, and dominated by static web pages. Most people were content consumers, with only a handful of content creators who created and hosted sites. JavaScript was at its infancy, media was rarely seen (due to speed and cost), and social media hadn't been invented yet. The Internet was highly decentralized and open to anyone. Everyone ran their own server or used one of the numerous hosting providers. Open protocols and standards were used for everything - HTTP, HTML, FTP, SMTP. -- Web 2.0 - the current generation, from around 2004 till now. A massive paradigm shift started to happen in the early 2000s. The Internet became faster and cheaper, and slowly but steadily spread into the lives of ordinary people. And as people trickled in, businesses followed. More and more services were offered through the web, like payments, shopping, and deliveries. Pages became more interactive and rich with media, but most importantly - users transitioned from just consuming content, to actively creating one. Social media boomed, smartphones were invented, and the web began its explosive growth we are still seeing to this day. -At present day, the Internet touches almost every aspect of modern life, but with all of its usefulness comes a darker side. As it grew, it became more and more centralized. While this centralization brought a number of benefits, there are a number of problems as well. Digital ownership is one of them. As digital assets became ubiquitous, it became apparent that users don't really own them. Instead, ownership remained with centralized companies. Google can block access to your emails on Gmail any time it wants ([one example](https://www.businessinsider.com/terraria-google-youtube-gmail-play-2021-2)), or a game company can shut down a game server and destroy forever a game you once bought. -Another major problem is a loss of privacy. A new business model has emerged, where users “pay” for the services with their personal data. Social platforms ask us to share our personal information so they can feed us information we want to see. Once they have our attention they sell it to anyone who will buy it, effectively [harming society for financial gain](https://mitsloan.mit.edu/ideas-made-to-matter/social-media-broken-a-new-report-offers-25-ways-to-fix-it). -- Web 3.0 - the next generation. It’s still in its early stages, and no one knows for sure how it will evolve, but several key aspects can already be outlined: - - Focus on decentralization and privacy. Shift digital ownership from companies to users. - - Trustless and permissionless. - - Driven by the community through tokenomics and governance. - -In this guide we’ll demonstrate some of these Web3 principles in practice and show how to build an application, in which digital assets are decentralized and owned by users. - -## Building blocks of Web decentralization - -As we already briefly discussed, the current Web is highly centralized, and mostly built using [client-server architecture](https://en.wikipedia.org/wiki/Client%E2%80%93server_model) on centralized servers hosted on one of the clouds (AWS, Azure, GCP, etc). According to one [report](https://www.statista.com/statistics/292840/distribution-global-cloud-and-non-cloud-traffic/), 90% of mobile traffic goes to the clouds, which means a significant portion of the Internet is basically controlled by a handful of companies. This consolidation of power has a number of downsides and this article on "[Why Decentralization Matters](https://onezero.medium.com/why-decentralization-matters-5e3f79f7638e)" does a good job explaining some of those problems. - -The first decentralization revolution happened in file sharing, with the arrival of the (in)famous BitTorrent protocol. By being a p2p protocol, it’s truly decentralized, and allows data to be stored distributedly without any central authority (and sometimes without consent of a central authority, which caused a lot of drama, but that’s a story for another time). Ideas behind this protocol have been used in modern decentralized file storages like IPFS and FileCoin, we’ll come back to this later and explore it in more details. - -The next revolution happened in the world of finance. For a long time transferring money required a central authority (banks), which would monitor, approve and execute these transfers. This has changed when the first cryptocurrency - Bitcoin - appeared. As already mentioned BitTorrent protocol, it also uses p2p communication, but instead of files it operates a transaction ledger, which is stored as a blockchain. Blockchain structure is needed to ensure that stored ledger cannot be altered, and at the same time to incentivize storage of this data. Unlike BitTorrent, Bitcoin network participants are rewarded for their services using a process called “mining”. This created a foundation for a new form of currency - digital currency (or cryptocurrency), with a unique property that it doesn’t need a central authority to function. Instead, users themselves maintain and operate it. And as with the previous decentralized system, BitTorrent, central authorities have issues with this. - -Following the success of Bitcoin, other cryptocurrencies started to appear. The most important one is Ethereum, which took the concept of blockchain one step further and adapted it to store not just a transactions leger, but any kind of data, and, most importantly code (which is just another form of data). Basically, it turned out we can use it as a decentralized database transaction log. And if we have data and code living in the decentralized database, the only thing we lack to build a decentralized application is an ability to execute this code. So Ethereum did just that, and a Smart Contract was born. Now, let's dive deeper into the world of blockchains, smart contracts, and explore how we can build decentralized applications with them. - -## Blockchain basics - -Let's start with a brief overview of what blockchain and smart contracts are. - -In classical Web 2.0 applications, you need 2 things to build an application backend: a database to store data and a server to execute your code. The same is true for the Web 3.0, but instead of a database we have a blockchain, and instead of a server we have smart contracts. - -Blockchain itself is just a linked list (chain) of transactions. As a performance optimization, instead of linking individual transactions, they are grouped into blocks. Linking happens using hashes - each block contains the cryptographic hash of a previous block. Such a structure grants us an important property - we cannot modify an individual transaction inside a chain, since it would change its hash and invalidate all transactions after it. This makes it an ideal structure to store in a decentralized fashion, since everyone can quickly verify the integrity of a transaction on a chain (and of the entire chain). - -![image](/docs/assets/web3/web3-1.png) - -Since we can only add new transactions to the chain, it serves as a decentralized transaction log. And if we have a [transaction log](https://en.wikipedia.org/wiki/Transaction_log), we basically have our database. Another good mental model is to think about this as a decentralized [event sourcing pattern](https://docs.microsoft.com/en-us/azure/architecture/patterns/event-sourcing), where each transaction represents a separate event. - -Due to the distributed nature of a blockchain, that has no single server which would manage a blockchain, a [consensus mechanism](https://www.investopedia.com/terms/c/consensus-mechanism-cryptocurrency.asp) is used to add new blocks, synchronize data between machines, and incentivize network participation. Several consensus mechanisms exist, we’ll discuss them in more detail later. - -It’s important to remember that every transaction on blockchain is publicly visible, so sensitive data should be encrypted beforehand. - -But how do we put transactions into a blockchain? That’s the purpose of a Blockchain Node. Everyone can set up their own node, connect to the p2p blockchain network, and post new transactions. Also, this node provides access to the current blockchain data. - -
-image -
- -Blockchain transactions themselves can be of a different type; exact supported types depend on a specific blockchain network. In the first Blockchain network, the Bitcoin, which stored only a financial ledger, transactions were quite simple - mostly just transfers of funds between accounts. This works very well for decentralized financing (Bitcoin is still the most popular cryptocurrency), but if we want to build general-purpose decentralized applications (or dApps for short), we need something better. That's where smart contracts come into the stage. - -For Web 2.0 developers, a good way to think about a smart contract is as a serverless function which runs on blockchain nodes, instead of a traditional cloud. However, It has a few important properties: - -- It is a pure function, which accepts the current state (which is stored on the blockchain) and caller-supplied arguments, and returns a modified state: _F(state, args)_ -> _state_. In practical terms, it means that we can’t do any external (off-blockchain) calls from it - no API or DB server calls are allowed. The reason behind this is decentralization - different nodes on the network should be able to execute it and get the same result. -- It’s fully open-source. Everyone is able to view your code and check what it’s doing. -- It cannot be changed. Once deployed, code remains on the chain forever and cannot be altered. Different upgrade mechanisms are possible, but are chain-specific. - -Such properties allow us to make analogies with real-world legal contracts - they cannot be changed (usually), they're predictable and they're publicly accessible for participants. Smart contracts are basically such contracts, or agreements, but instead of a human performing actions, they are represented as code. - -But how do we deploy and execute them, if everything we can do is to create a transaction? All we need are 2 specific types of transactions: - -- Deploy smart contract code, so it will be persisted in the blockchain, together with other data. -- Call a smart contract with given arguments. As an outcome, a modified state will be returned. - -When a call transaction arrives on a node, it will read the contract's code and state from the blockchain, execute it, and put a modified state back on a chain (as a transaction). - -
-image -
- - -So far we’ve explored how the backend layer of a dApp looks like, but what about the client side? Since we are using an API to communicate, we can use any kind of a client we use in the Web 2.0 - web, mobile, desktop, and even other servers. However, an important distinction lies with users. - -In a traditional Web 2.0 application, each server owns the identities of its users, and fully in control over who can and can’t use its services. In blockchain, however, there are no such restrictions, and anyone can interact with it (there are [private blockchains](https://www.investopedia.com/terms/p/permissioned-blockchains.asp), but we’ll leave them out of scope). - -But how do we perform authentication if there is no standard login/registration process? Instead, we use public key cryptography, where a public key serves as a username, and a private key is a loose equivalent of a password. The major distinction is that instead of a login procedure, in which the server verifies the credentials and grants some form of an access token, here the users sign transactions with a private key. This means there's no classical Web 2 identity (like username, email, or an ID) available. This should be considered if you are building applications that require [KYC](https://en.wikipedia.org/wiki/Know_your_customer). - -Another important implication of using private/public key pairs for auth, is that they cannot be easily memorized, like username/password pair. For this purpose, special applications called wallets are used. They store user’s key pairs and can sign transactions or provide them for other applications. - -
-image -
- - -The one aspect we haven’t considered yet is infrastructure cost. In WEB 2.0, users pay for the provided service (directly with money or indirectly with their data, or both), and service providers pay for the infrastructure. - - - -![image](/docs/assets/web3/web3-4.png) - - - -In a Web 3.0 model, users pay directly to the infrastructure provider (nodes running in the blockchain), bypassing the service provider. - - -![image](/docs/assets/web3/web3-5.png) - - - -This has huge implications: -- Service providers can’t shut down services or restrict their usage, since they are deployed on blockchain and can’t be removed. This means the application will live forever (or at least while the blockchain network is alive). -- A new monetization model should be used for such services, since users don’t pay directly to service providers. For example, a fee can be coded into a smart contract for performing certain actions. -- Since users should pay for the infrastructure, there’s no free lunch (this is usually true for Web 2.0 as well, but it’s often not obvious for ordinary users). Service providers can cover some cost or provide a credit to simplify onboarding, but ultimately users would have to pay. - -But how do users pay? Since it’s a blockchain, they can’t pay directly with a credit card - in this way it will be tied to a central authority and not really decentralized. A solution is to use a decentralized currency - cryptocurrency. Each blockchain has its own currency, which is used for payments inside of it. - -Whenever a user wants to perform an action on a blockchain by calling a smart contract, it should always pay an infrastructure cost, and optionally a service cost to the service provider. - - -![image](/docs/assets/web3/web3-6.png) - - - -This infrastructure cost, often called “gas”, usually consists of 2 parts: -- Computational cost - to cover computational power needed to add a transaction into a blockchain. -- Storage cost - to cover additional storage requirements necessary for each transaction. - -However, the question still remains how users can obtain cryptocurrency tokens in the first place. One option is to buy it from other users who already own it by using traditional money or another cryptocurrency. There are exchanges which provide such kind of functionality, e.g. [Binance](https://www.binance.com/en). But this will work only if there is already an existing supply of tokens already in circulation. - -In order to create and grow this supply the blockchain consensus mechanism is used. Earlier, we mentioned that it is used to incentivize blockchain network participation, but how exactly does it happen? Each node that processes transactions receives a reward for its work: - - -``` -reward = infrastructureCostReward + coinbaseReward -``` - - -where: - -- `infrastructureCostReward` - share of infrastructure cost paid for the transactions by the users -- `coinbaseReward` - new cryptocurrency token created specifically to reward processing nodes - -This means each time a transaction is processed a small amount of cryptocurrency is created, so the amount of cryptocurrency in circulation grows over time (of course some amount of tokens should be created to bootstrap the network, e. g. by using [ICO](https://www.investopedia.com/terms/i/initial-coin-offering-ico.asp)). - -At a present day, two consensus mechanisms are commonly used: -- [Proof-of-work](https://www.investopedia.com/terms/p/proof-work.asp) - original consensus mechanism, which is currently used by Bitcoin and was used by Ethereum. It’s highly criticized for its inefficiency - processing of new transactions requires “mining”, which is a highly computationally intensive process. Because of this, graphic cards became an endangered species. Another disadvantage - cost of transactions is very high and processing speed is also quite slow. -- [Proof-of-stake](https://www.investopedia.com/terms/p/proof-stake-pos.asp) - newer consensus mechanism, which doesn’t require significant processing power (and graphic cards). Processing of transactions is usually called “validation”. Newer chains, like NEAR, use it. Ethereum switched to Proof-of-stake (PoS) mechanism in September 2022. Transactions are usually much cheaper and processing speed is faster. - -At this point, we should have enough knowledge to proceed to the next chapter - choosing the best blockchain to build dApps. - -## Choosing the right blockchain - -There are a lot of blockchains out there and it might be hard to choose the most suitable one for your needs. First of all, we should define the most important characteristics for a chain: - -- Consensus algorithm - by now Proof-of-work proved to be too inefficient and not suitable for high-scale applications. Proof-of-stake seems like a much better choice for now. Other alternatives exist, but they are less explored and tried in practice. -- Transaction/Storage cost - cheaper cost directly benefits users (recall, that users will pay for it). -- Transaction speed - faster transactions processing time means better user experience. -- Scalability - whether a network is designed to support a large number of transactions. If not, transaction speed/cost may grow out of control over time. -- Development experience - most importantly, what language we’ll use to write our smart contracts. Ethereum popularized [Solidity](https://docs.soliditylang.org/en/v0.8.12/) as a programming language of choice for contracts. Several newer chains, like NEAR, chose Rust, which is a more mature general-purpose programming language. - -Historically, the first blockchain to introduce smart contracts was Ethereum. However, as the number of users grew, transaction speed and cost skyrocketed, and it became apparent that it couldn't handle the demand. So, a number of [scaling solutions](https://ethereum.org/en/developers/docs/scaling/) appeared - [layer 2 chains](https://ethereum.org/en/developers/docs/scaling/#layer-2-scaling), [sidechains](https://ethereum.org/en/developers/docs/scaling/sidechains/), and [plasma chains](https://ethereum.org/en/developers/docs/scaling/plasma/). However, they all use some kind of workarounds with their own unique drawbacks. Ethereum tries to fix the core problem and redesign its network - like switching to a Proof-of-stake consensus, which is ongoing for quite a long time, but exact timeline when all of the problems will be fixed is very unclear. - -Meanwhile, a new generation of blockchains started to appear. They learned from the Ethereum mistakes, and designed them from ground-up to be fast, cheap and scalable. -Choosing the right one is by no means an easy task, but for us we found the [NEAR](https://near.org/) blockchain to be an ideal solution, because of the following properties: -- Transactions are cheap and very fast. -- Designed to be extremely scalable from the beginning. This means we can count that transaction cost and speed will remain stable in the future. -- Uses Proof-of-stake consensus mechanism - so no hated “mining” is needed. -- Rust is used as a primary programming language. Since it’s [a popular language](https://insights.stackoverflow.com/survey/2021#most-popular-technologies-language-prof) (and [one of the most loved](https://insights.stackoverflow.com/survey/2021#most-loved-dreaded-and-wanted-language-love-dread)), it’s much easier to learn and find developers on the market. - -All of the further sections will use NEAR as an underlying blockchain, so before we jump into the intricacies of the Web 3.0 migration, we should take a closer look at it first. diff --git a/docs/1.concepts/web3/economics.md b/docs/1.concepts/web3/economics.md deleted file mode 100644 index e48e42fb426..00000000000 --- a/docs/1.concepts/web3/economics.md +++ /dev/null @@ -1,52 +0,0 @@ ---- -id: economics -title: Web 3.0 Economics -sidebar_label: Economics ---- - -With technological decentralization also came economical decentralization. It stands on 3 pillars - Non-Fungible tokens (NFTs), Fungible tokens (FTs) and Decentralized Finance (DeFi). - -## Non-Fungible Tokens -At the heart of the new Web 3 economy lies [Non-Fungible token](https://en.wikipedia.org/wiki/Non-fungible_token) (NFT). In a nutshell, it’s a way to represent digital ownership in a decentralized way. From a technical perspective, it’s just a piece of data on a blockchain. The simplest case of such data is just a `(token_id, account_id)` tuple, where `token_id` uniquely identifies an asset, and `account_id` identifies an owner. A smart contract that owns this data defines a set of allowed operations - like creation of a new token (minting) or transfer of a token to another account. An exact set of allowed operations is defined in an NFT standard. Different blockchains have different standards, NEAR NFT Standard is available [here](https://nomicon.io/Standards/NonFungibleToken/). - -Because NFTs are tied to a specific contract, they mostly make sense only in scope of this contract, and subsequently they are tied to a specific dApp. It’s possible to implement transfer of NFTs between contracts, but there’s no standard way to do this. - -What digital asset is hiding behind a `token_id` is up to the smart contract to decide. There are few common ways how to handle this: - -- Store an asset itself in a smart contract alongside the ownership information. This is the most straightforward way, but often is not feasible since storage cost is quite high and many types of digital assets, especially media, are quite big. - -
-image -
- -- Store token data off-chain. Such an approach solves storage cost problems, but requires some level of trust to guarantee that data in the off-chain storage won’t be changed or removed. - -![image](/docs/assets/web3/web3-21.png) - - -- Store asset’s metadata and hash on chain, and an asset itself on some off-chain storage. Storing an asset’s hash on a chain guarantees data integrity and immutability. On-chain metadata usually includes basic token information, like title, description and media url. It’s required to quickly identify an asset without downloading it from the storage. This is the most popular approach to handle NFT’s since it combines the best of 2 previous approaches - token is immutable and storage cost is cheap (exact cost depends on the storage solution, but it usually several orders of magnitude cheaper than an on-chain storage) - -![image](/docs/assets/web3/web3-22.png) - - -Choosing the right off-chain storage also can be a challenge, in general they can be divided into 2 buckets: -- Centralized storages - traditional Web 2 storage solutions, like relational databases or blob storages. While suitable for some applications, this means NFTs can be destroyed if a central server goes offline, so they aren’t the most popular in the Web 3 world. -- Decentralized storages. As we already mentioned, BitTorrent protocol is one of the first examples of such decentralized storage solutions, but in recent years more advanced solutions have appeared - like [IPFS](https://ipfs.io/), [FileCoin](https://filecoin.io/) and [Arweawe](https://www.arweave.org/). Such solutions are a preferred method to store digital assets, since they are cheap and decentralized, so no-one can destroy or alter NFT assets. - -In addition to the NFT standard, NEAR also provides [its implementation](https://docs.rs/near-contract-standards/latest/near_contract_standards/non_fungible_token/index.html), which can be used by Smart Contract developers to implement NFTs in their smart contract. Implementation itself doesn’t dictate assets storage model, so it’s up to a developer to decide how and where it will be stored. - -## Fungible Tokens -NFTs changed digital assets ownership model, but by itself they are not enough to build a full digital economy. In the simplest model, NFTs can be sold and bought using main blockchain currency (e.g. NEAR tokens), but this is quite limiting since circulation and price of such tokens is dictated by the blockchain itself. What if, instead of relying on blockchain currency, applications could create their own? For exactly this reason, Fungible Tokens (FT) have been created. - -Similarly to NFTs, fungible tokens are also just a piece of data stored in a smart contract, but instead of storing unique token ids, an amount of tokens held by an account is stored. - -
-image -
- -Smart Contracts can define allowed operations - like transfer or payment using this token. [NEAR defines a standard](https://nomicon.io/Standards/FungibleToken/Core) for fungible tokens and provides a [default implementation](https://docs.rs/near-contract-standards/latest/near_contract_standards/fungible_token/index.html). - -Since an application is fully in control over emission and circulation of such tokens, a full fledged application economy can be created. For example, users can earn FTs for performing actions, and spend them to buy or mint new NFTs. -Another exciting option is creation of [Decentralized Autonomous Organizations](../../2.build/5.primitives/dao.md) (DAOs), in which FTs can be used as a membership (or governance) tool. In such scenarios, tokens are awarded to members and can be used to vote on decisions or participate in community events. - -But we can push our tokens even further, by tying them to other cryptocurrencies and giving them a real-life monetary value. That’s where [Decentralized Finance](https://www.investopedia.com/decentralized-finance-defi-5113835) (DeFi), and especially [Decentralized Exchanges](https://en.wikipedia.org/wiki/Decentralized_exchange) (DEX) come into play. We won’t go into details here, but at the core a [liquidity pool](https://academy.binance.com/en/articles/what-are-liquidity-pools-in-defi) for a Fungible Token can be created on DEX, which allows trades of this token for other tokens or [stablecoins](https://en.wikipedia.org/wiki/Stablecoin). This opens the door for a new gaming model - [Play-to-Earn](https://en.wikipedia.org/wiki/Blockchain_game), where players can earn real-life money just by playing a game. diff --git a/docs/1.concepts/web3/intro.md b/docs/1.concepts/web3/intro.md deleted file mode 100644 index 51bb16a2c6d..00000000000 --- a/docs/1.concepts/web3/intro.md +++ /dev/null @@ -1,23 +0,0 @@ ---- -id: intro -title: Moving from Web 2 to Web 3 -sidebar_label: Introduction ---- - -by Sigma Software - ->DISCLAIMER. All references to particular products, frameworks, solutions, libraries and other software of NEAR ecosystem are provided for educational purposes only. All product names, logos, brands, trademarks and registered trademarks are property of their respective owners. Use of these names, trademarks and brands throughout the document does not imply endorsement. - -## Introduction - -In this guideline we’ll see how to bring a traditional Web 2 application into a Web 3 world using NEAR Protocol. - -It’s written for developers who are just starting their journey into the world of Web 3 and Blockchain, so we’ll start by explaining what Web 3 and blockchain are. Then, we’ll explore how to build decentralized applications (dApps) using NEAR Protocol. And after we’ve learned the basics, we’ll guide you through the intricacies of fusing client applications, traditional web servers and the NEAR blockchain. - -During our journey we’ll focus on high-level decisions, architecture, and explore not just HOW to do something, but also WHY it’s done this way. And as with anything, there’s no single right way, so we’ll explore different alternatives and help you to choose the right one. - -Of course, real world applications aren’t built with words, but with code, so links to numerous code examples will be provided. But to make it as useful as possible, this guideline itself will be kept implementation and technology agnostic whenever possible. - -If you are already familiar with Web 3 and blockchains, feel free to skip to the [NEAR Protocol section](near.md). And if you are already quite comfortable with NEAR, you can jump straight ahead into the [NFTs for Web 2 Applications](nfts.md) chapter, where we’ll guide you on how to connect Web 2 and the NEAR blockchain together to bring the full power of NFTs into your app. - -Without further ado, let’s begin our journey! diff --git a/docs/1.concepts/web3/near.md b/docs/1.concepts/web3/near.md deleted file mode 100644 index b54da43497a..00000000000 --- a/docs/1.concepts/web3/near.md +++ /dev/null @@ -1,208 +0,0 @@ ---- -id: near -title: NEAR Protocol -sidebar_label: NEAR Protocol ---- - - -For beginners, it’s always better to start with [documentation](/concepts/basics/protocol), and NEAR has an excellent one. Here, we only focus on basic concepts necessary to understand later chapters, so an entire guideline can be understood without prior NEAR knowledge. - -## Accounts & Transactions -NEAR's account system is very powerful and differs substantially from other blockchains, like Bitcoin or Ethereum. Instead of identifying users by their public/private key pairs, it defines accounts as first-class entities. This has a few important implications: -- Instead of public keys, users can use readable account names. -- Multiple key pairs with [different permissions](../protocol/access-keys.md) can be used. This provides a better security model for users, since loss of one key pair doesn’t compromise an entire account and has a quite limited impact. -- Hierarchical accounts structure is supported. This is useful if we want to manage multiple smart contracts under one parent account. -- Accounts/public keys are created using transactions, since they are stored on the blockchain. - -More information on NEAR accounts can be [found in the docs](../protocol/account-model.md). - -But an account by itself won’t get us anywhere, its [transactions](../protocol/transactions.md) that make things happen. In NEAR, we have only one transaction type, but the transaction itself may have different actions included. For most practical purposes, transactions will have a single action included, so for simplicity we’ll use “action” and “transaction” terms interchangeably further down the road. Each transaction always has sender and receiver accounts (and it is cryptographically signed by the sender’s key). The following transaction (action) types are supported: - -- CreateAccount/DeleteAccount, AddKey/DeleteKey - accounts and key management transactions. -- Transfer - send NEAR tokens from one account to another. The basic command of any blockchain. -- Stake - needed to become a validator in a Proof-of-Stake blockchain network. We won’t touch this topic in this guideline, more information [can be found here](https://near-nodes.io/validator/staking-and-delegation). -- DeployContract - deploy a smart contract to a given account. An important thing to remember - one account can hold only one contract, so the contract is uniquely identified by the account name. If we issue this transaction to an account which already has a deployed contract, a contract update will be triggered. -- FunctionCall - the most important action on the blockchain, it allows us to call a function of a smart contract. - -Smart Contracts on NEAR are written in Rust or JavaScript, and compiled into [WebAssembly](https://developer.mozilla.org/en-US/docs/WebAssembly). Each contract has one or more methods that can be called via a FunctionCall transaction. Methods may have arguments provided, so each smart contract call includes the following payload: account id, method name, and arguments. - -There are 2 ways to call a method on a smart contract: -1. Issue a FunctionCall transaction. This will create a new transaction on a blockchain which may modify a contract state. -2. Make a smart contract view call. NEAR blockchain [RPC nodes](https://near-nodes.io/intro/node-types#rpc-node) provide a special API that allow execution of methods that do not modify contract state (readonly methods). - - -The second method should always be used whenever possible since it doesn’t incur any transaction cost (of course, there is some cost of running a node, but it’s still much cheaper than a transaction; public nodes are available which can be used free of charge). Also, since there’s no transactions, we don’t need an account to make a view call, which is quite useful for building client-side applications - -## Gas and Storage - -As we already discussed, users should pay computational costs for each transaction. This cost is called “gas” and is measured in [gas units](../protocol/gas.md) (this is an established term in the blockchain world). Each time a transaction is posted, an amount of gas is attached to it to cover the cost. For simple transactions, gas can be calculated ahead of time to attach an exact amount. For FunctionCall transactions, however, exact cost is impossible to automatically calculate beforehand, so the usual approach is to attach a large enough amount of gas to cover the cost, and any excess will get automatically refunded. - - -![image](/docs/assets/web3/web3-7.png) - - - - -But why do we need separate gas units, why not just pay directly with NEAR tokens? It’s necessary to accommodate for changing infrastructure costs - as the network evolves over time, cost of gas units may change, but the amount of gas required for a transaction will remain constant. - -However, computational cost is not everything - most smart contracts also need storage. The storage cost in NEAR is quite different from gas. -First of all, it’s not cheap - while gas is very cheap and its cost will be almost unnoticeable by the users, storage is very expensive. As a consequence, the storage budget should be carefully calculated and only necessary data stored on the blockchain. Any auxiliary data (that is not necessary to the contract operations) should be stored off-chain (possible solutions will be covered in later chapters). -The second important difference - storage is not bought, but leased (in NEAR, it’s called staking). When a smart contract wants to store some data, storage cost is computed and the appropriate amount of NEAR tokens is “locked” on the account. When data is removed, tokens are unlocked. And unlike gas, these tokens are locked on the smart contract’s account, so the user doesn’t directly pay for it. - -But what if we want users to pay for the storage (or just pay some fee for using a smart contract)? So far, the only way we’ve seen to transfer a token is a Transfer transaction. It turns out, a FunctionCall transaction also allows us to transfer tokens alongside the call (this is called a deposit). Smart Contracts can verify that an appropriate amount of tokens has been attached, and refuse to perform any actions if there’s not enough (and refund any excess of tokens attached). - -In combination, gas fee and deposit attachments enable creation of contracts that need zero cost from developers to support and can live on blockchain forever. Even more, 30% of gas fees spent on the contract execution will go to a contract’s account itself (read more [here](https://near.org/blog/near-protocol-economics/#:~:text=a%20new%20entity.-,Contract%20rewards,-As%20one%20of)), so just by being used it will bring some income. To be fair, due to the cheap gas cost this will make a significant impact only for most popular and often-called contracts, but it’s nice to have such an option nonetheless. - -One last gotcha about storage - remember that smart contracts themselves are also just a code stored on a blockchain, so a DeployContract transaction will also incur storage fees. Since smart contracts code can be quite big, it’s important to optimize their size. A few tips on this: -- Don’t build Rust code on Windows, it produces quite big output. Use WSL or build on other OSes. -- Optimize smart contracts code for size - [more info here](../../2.build/2.smart-contracts/anatomy/reduce-size.md) - -More details on the storage model can be [found in the docs](../storage/storage-staking.md). - -## Clients Integration - -So far, we’ve discussed how to call smart contracts in a client-agnostic way. However, in the real world, calls we’ll be performed from a client side - like web, mobile or a desktop application. - -As we’ve learned from previous chapters, each transaction should be signed using a key. And since keys are managed by a wallet, each application should integrate with it. At the time of this writing, there’s only one officially supported [NEAR Wallet](https://wallet.near.org/). It is a web application, so integration happens using HTTP redirects. This is relatively straightforward to do in web applications (JavaScript SDK is available), but for mobile or desktop applications it may require deep linking or other more advanced approaches. - -The general flow for transactions signing looks like this: - - -![image](/docs/assets/web3/web3-9.png) - - - -Each time we want to post a transaction, the client redirects the user to a wallet, where the transaction is approved and wallet returns a signed transaction back to the client (via redirect). This is a quite secure way of signing, since the private key is not exposed to the client, but constant redirects might quickly get annoying for users, especially if we just want to call smart contract functions that incur only small gas fees. That’s why NEAR introduced [two types of access keys](../../1.concepts/protocol/access-keys.md) - full keys and functional call keys. Full access keys, as the name implies, can be used to sign any types of transactions. Functional call keys, on the other hand, aim to solve this UX problem. They are tied to a specific contract, and have a budget for gas fees. Such a key can’t be used to sign transactions that transfers NEAR tokens (payable transactions), and can only be used to cover gas fees, that’s why it’s not so security-critical and can be stored on the client. Because of this, we can create a simplified signing flow for non-payable transactions. First of all, a login flow to obtain a Functional Call key is used. - - -![image](/docs/assets/web3/web3-10.png) - - - -The client generates a new key pair and asks a wallet to add it as a functional call key for a given contract. After this, a login session is established and considered alive until the client has the generated key pair. -To provide the best user experience usage of both keys is combined - type of signing is determined based on a transaction type (payable or non-payable). In case of a payable transaction, flow with wallet redirection is used, otherwise simplified local signing flow (using a stored function call key) is applied: - - -
-image -
- - -It’s important to note that it’s possible to generate a Full Access key using the same key addition flow as for the Functional Call key, but this is very dangerous since compromise of such key will give full control over an account. Applications that want to work with Full Key directly should be designed with extreme care, especially in the matters of security. - -## Cross-contracts calls - -Throughout this section, we’ve discussed how to call a smart contract from a client. But a single smart contract can only take us so far. The true power is achieved when smart contracts are working in concert and communicating with each other. To achieve this, NEAR provides cross-contract calls functionality, which allows one contract to call methods from another contract. The general flow looks like this: - - - -![image](/docs/assets/web3/web3-12.png) - - - - -Looks simple enough, but there are few gotchas: -- In order to provide a call status (success or failure) and a return value to the calling contract, a callback method should be called, so there’s no single activation of ContractA. Instead, an entry method is called first by the user, and then a callback is invoked in response to cross-contract call completion. -- Transaction status is determined by the success or failure of a first function call. For example, if a ContractB.methodB or ContractA.methodACb call fails, the transaction will still be considered successful. This means that to ensure proper rollbacks in case of expected failures, custom rollback code must be written in the ContractA.methodACb, and the callback method itself must not fail at all. Otherwise, smart contract state might be left inconsistent. -- Cross-contract calls must have gas attached by the calling contract. Total available gas is attached to a transaction by a calling user, and distributed inside the call chain by contracts. For example, if 15TGas are attached by the user, ContractA may reserve 5TGas for itself and pass the rest to ContractB. All unspent gas will be refunded back to the user. - - -![image](/docs/assets/web3/web3-13.png) - - - -- NEAR tokens can also be attached to cross contract calls, but they work differently from the gas. Attached deposit is taken directly from the predecessor account. It means even if a user hasn’t attached any deposit, a contract still can attach tokens, which will be taken from its account. Also, since cross-contract call failure doesn’t mean transaction failure, there are no automatic refunds. All refunds should be done explicitly in the rollback code. - - -![image](/docs/assets/web3/web3-14.png) - - - -A few notes on failure modes - since smart contracts run on a decentralized environment, which means they are executed on multiple machines and there is no single point of failure, they won’t fail because of environment issues (e.g. because a machine suddenly lost power or network connectivity). The only possible failures come from the code itself, so they can be predicted and proper failover code added. - -In general, cross-contract call graphs can be quite complex (one contract may call multiple contracts and even perform some conditional calls selection). The only limiting factor is the amount of gas attached, and there is a hard cap defined by the network of how many gas transactions may have (this is necessary to prevent any kind of DoS attacks on the Network and keep contracts complexity within reasonable bounds). - -## Data Structures, Indexers and Events - -We’ve already discussed the storage model on NEAR, but only in abstract terms, without bringing the exact structure, so it’s time to dive a bit deeper. - -Natively, NEAR smart contracts store data as key-value pairs. This is quite limiting, since even simplest applications usually need more advanced data structures. To help in development, NEAR provides [SDK for smart contracts](https://github.com/near/near-sdk-rs), which includes data structures like [vectors, sets and maps](../../2.build/2.smart-contracts/anatomy/collections.md). While they are very useful, it’s important to remember a few things about them: -- Ultimately, they are stored as binary values, which means it takes some gas to serialize and deserialize them. Also, different operations cost different amounts of gas ([complexity table](../../2.build/2.smart-contracts/anatomy/collections.md#complexity)). Because of this, careful choice of data structures is very important. Moving to a different data structure later will not be easy and would probably require data migration. -- While very useful, vectors, maps and sets won’t match the flexibility and power of classical relational databases. Even implementations of simple filtering and searching might be quite complex and require a lot of gas to execute, especially if multiple entities with relations between them are involved. -- They are limited to a single contract. If data from multiple contracts is required, aggregation should be performed using cross-contract calls or on a client side, which is quite expensive in terms of gas and time. - -To support more complex data retrieval scenarios, smart contract data should be put in a more appropriate store, like a relational database. Indexers are used to achieve this. In a nutshell, indexer is just a special kind of blockchain node that processes incoming transactions and puts relevant data into a database. Collected data can be exposed to a client using a simple API server (e.g. REST or GraphQL). - - -![image](/docs/assets/web3/web3-15.png) - - - -In order to simplify creation of indexers, [NEAR Indexer Framework](/concepts/advanced/near-indexer-framework) has been created. However, even with a framework available, extracting data from a transaction may not be an easy task, since each smart contract has its unique structure and data storage model. To simplify this process, smart contracts can write structured information about outcome into the logs (e.g. in the JSON format). Each smart contract can use its own format for such logs, but the general format has been standardized as [Events](https://nomicon.io/Standards/EventsFormat). - -Such architecture is very similar to Event Sourcing, where blockchain stores events (transactions), and they are materialized to a relational database using an indexer. This means the same drawbacks also apply. For instance, a client should be designed to accommodate indexing delay, which may take a few seconds. - -As an alternative to building your own indexer with a database and an API server, [The Graph](https://thegraph.com/en/) can be used instead, which currently has [NEAR support in beta](https://thegraph.com/docs/en/supported-networks/near/). It works using the Indexer-as-a-Service model, and even has decentralized indexing implementation. - -## Development tools - -By now, we should be familiar with necessary concepts to start developing WEB 3.0 applications, so let’s explore the development tools available. - -First of all, we need a development and testing environment. Of course, we could theoretically perform development and testing on the main blockchain network, but this would not be cheap. For this reason, NEAR provides [several networks](../../1.concepts/basics/networks.md) that can be used during development: -- testnet - public NEAR network which is identical to mainnet and can be used for free. -- localnet - you can deploy your personal NEAR network on your own environment. Because it’s owned by you, data and code can be kept private during development. More info on how you can run your own node can be [found here](https://near-nodes.io/validator/running-a-node). Alternatively, you can bootstrap an entire testing infrastructure in Docker on your local machine using Kurtosis - [guide is here](../../2.build/2.smart-contracts/testing/kurtosis-localnet.md). -- workspaces - you can start your own local network to perform e2e testing. More info [here](../../2.build/2.smart-contracts/testing/integration-test.md). - -Once we’ve chosen a network to use, we need a way to interact with it. Of course, transactions can be constructed manually and posted into [node’s API](/api/rpc/setup). But [this is tedious](https://github.com/near-examples/transaction-examples) and isn’t fun at all. That’s why, NEAR [provides a CLI](../../4.tools/cli.md) which automates all of the necessary actions. It can be used locally for development purposes or on build machines for CI/CD scenarios. - -In order to manage accounts on the NEAR network, [Wallet](https://wiki.near.org/overview/tokenomics/creating-a-near-wallet) can be used. It can show an effective account balance and active keys. - -![image](/docs/assets/web3/web3-16.png) - - -On the image above, “Reserved for storage” are tokens locked by a smart contract to cover current storage requirements, and “Reserved for transactions” represents the amount of tokens locked to cover gas cost by Functional Call keys. -Currently, there’s no UI to connect sub-accounts into a wallet. Instead, they should be imported via a specially constructed direct link: -``` -https://testnet.mynearwallet.com/auto-import-secret-key#YOUR_ACCOUNT_ID/YOUR_PRIVATE_KEY -``` -(you should provide a private key of a full access key for the account in question, so make sure this link is used securely). - -Last, but not least, blockchain transactions can be viewed using NEAR Explorer. It provides insights into transaction execution and outcome. Let’s look at [one example](https://testnet.nearblocks.io/txns/ABh4zQ5aZ3CGhpQzstL16TAB8TvqPbiirJG1uTPJVxTt). -First of all, we can see general transaction information - sender, receiver, status. After this, we can see gas usage information: -- Attached gas - total gas provided for the transaction. -- Gas used - actual gas spend. -- Transaction fee - gas used multiplied to current gas price, shows an actual cost of a transaction in NEAR tokens. -Also, Deposit Value shows the amount of NEAR tokens transferred from sender to receiver. - -![image](/docs/assets/web3/web3-17.png) - - -Below this, we can inspect transaction actions (recall, that transactions may have multiple actions). In this case, we have a single FunctionCall action with arguments: - -![image](/docs/assets/web3/web3-18.png) - - -At the end, transaction execution details, including token transfers, logs, cross-contract calls and gas refunds are provided. One thing that we haven’t covered yet is shown here - [receipts](/concepts/protocol/transaction-execution#receipts--finality). For most practical purposes they are just a transaction implementation detail. They are quite useful in a transaction explorer to understand how a transaction was executed, but aren’t really relevant outside of it. - -![image](/docs/assets/web3/web3-19.png) - - - -## Contract upgrades - -During the development, and sometimes even in production, updates to a contract’s code (or even data) are needed. That’s why different contract upgrades mechanisms have been created. - -While developing the contract, we recommend just creating a new account each time you need to deploy a contract (the [create-account](../../4.tools/cli.md#create) command in NEAR CLI exists for this). With such an approach, you will start with a clean state each time. - -However, once we move to a more stable environment, like testing or production, more sophisticated methods are needed. Redeployment of code is quite simple: we just issue another `DeployContract` transaction, and NEAR will handle the rest. The biggest challenge is to migrate contract state - [several approaches are possible](../../2.build/2.smart-contracts/release/upgrade.md#migrating-the-state), but all of them involve some kind of migration code. - -But we can take our upgrade strategy one step further. In the previous strategies, developers are fully in control of code upgrades. This is fine for many applications, but it requires some level of trust between users and developers, since malicious changes could be made at any moment and without the user’s consent (as it [sometimes happens](https://www.bleepingcomputer.com/news/security/dev-corrupts-npm-libs-colors-and-faker-breaking-thousands-of-apps/) in npm world). To solve this, a contract update process itself can also be decentralized - this is called [Programmatic Updates](../../2.build/2.smart-contracts/release/upgrade.md#programmatic-update). The exact strategy may vary, but the basic idea is that the contract update code is implemented in a smart contract itself, and a Full Access key to the contract account is removed from a blockchain (via DeleteKey transaction). In this way, an update strategy is transparent to everyone and cannot be changed by developers at will. - -## Further reading - -For a deep dive into NEAR, the following links will be useful: - -- [NEAR docs](https://docs.near.org) -- [Smart Contract quick start guide](../../2.build/2.smart-contracts/quickstart.md) -- [NEAR Protocol Specification](https://nomicon.io/) -- [How to build a dApp on NEAR](../../3.tutorials/examples/guest-book.md) diff --git a/docs/1.concepts/web3/nfts.md b/docs/1.concepts/web3/nfts.md deleted file mode 100644 index f6013b1cd9b..00000000000 --- a/docs/1.concepts/web3/nfts.md +++ /dev/null @@ -1,629 +0,0 @@ ---- -id: nfts -title: NFTs for Web 2 Applications -sidebar_label: NFTs for Web 2.0 Apps ---- - -# NFTs for Web 2 Applications - -At the first stage of our Web 3 transformation, let’s decentralize ownership of our digital assets using blockchain technology. By doing this, we can create a user-owned economy, where digital assets are exchanged and traded without any participation or control from the developers. Later, we’ll discuss how to bring it to the next level by adding Fungible Tokens into the mix. - -As we discussed previously, in the Web 3 world, NFTs are used to represent ownership of an asset. This can be anything a user owns, e.g. in case of a game this can be a character, upgrade, crafting material, skin, etc. However, since NFTs are living on the blockchain, and the rest of the application resides on traditional servers, we need to find a way to connect these different worlds together. - -## Blockchain-Enabled Application Architecture - -First of all, let’s outline a typical architecture of a Web 2 application. In most cases, a classic client-server model is used: - -
-image -
- -In such architecture, we usually have 3 layers: -- Database - stores application’s data. This can be a single database, or several databases of different types, but this is mostly an implementation detail - for our purposes we can view it as a single logical database. -- Server - a centralized web-server. It may be implemented using different architecture patterns (monolithic, microservices, serverless) and technologies, but again, we can consider it as a single logical server. -- Client - client side application user directly interacts with. Different client types are possible: web, mobile or desktop. There is a difference between these clients in regards to blockchain integration, which we’ll discuss later. - -Now, let’s compare it to a dApp architecture: - -
-image -
- -We can notice that there is a common component in these architectures - the client application. This means we can use it as a junction point to connect them together. - -
-image -
- -A keen reader may notice an additional connection between the Server and RPC Node. This is required because in a client-server architecture clients cannot be trusted. That’s why every action performed from the client should be validated by a backend server. But in our case everything is complicated by the fact that we essentially have two backends: Web 2 server and a smart contract, so two possible validation flows are possible: -- Client performs an action on a server, which involves blockchain data. In this case the server should talk to the blockchain and verify that valid data is provided. -- Client performs an action on a smart contract, which involves server-owned data. Since the smart contract can’t talk to the server directly to verify it, we should use a different way to verify the authenticity of the data. In blockchain terminology, such a server is called an [Oracle](https://en.wikipedia.org/wiki/Blockchain_oracle). -We’ll explore how to implement both of these approaches later. - -By now, we've reached the point where the type of our client begins to matter. Specifically, problems arise from the dApps payment model - user’s pay for the blockchain infrastructure using gas, so money goes directly to infrastructure providers. Also, users make payments directly on the blockchain, without using any intermediaries, like banks or payment services. This approach is at odds with mobile app stores (Google Play Store and Apple App Store) - they don’t allow any payments on their respective mobile platforms without their cut. Although some shifts in policy are starting to happen (e.g. [Apple vs Epic Games duel](https://en.wikipedia.org/wiki/Epic_Games_v._Apple)), at the time of this writing getting blockchain-enabled applications into the stores will probably get vetoed by reviewers. There are some ways to bypass these limitations, e.g. by not using Play Store on Android, but all of these ways are either sub-par in terms of usability or involve some risk of getting banned by stores. That’s why for mobile applications an alternative approach is needed. - -Sometimes, to move forward we need to take a step back. In our case, to solve a problem with mobile clients we can return to our initial concept of having two clients - one for blockchain integration, and another one for Web 2 server. Blockchain client can be a usual web application, which isn’t subject to any constraints from stores. It can also serve as a connection point between blockchain and our existing application. - -![image](/docs/assets/web3/nfts-4.png) - - -In this architecture the mobile client is still allowed to talk to the blockchain, but only in a read-only way, which doesn’t require wallet connection or any payments. All actions on the blockchain happen on the Web Client instead. -Further in this guide we’ll use such dual-client architecture, since simpler architecture with a single client can be directly derived from it by merging two clients together. - -At this point, our architecture covers almost everything we need to start building our application. However, since we want to build a user-owned economy, we need a marketplace where it’ll happen. An obvious choice is to put this marketplace into the web client, but there’s one gotcha. If we recall the smart contract’s storage model, it’s not suitable to serve complex data queries, so an indexer should be used to aggregate data from blockchain into a proper database. - - -![image](/docs/assets/web3/nfts-5.png) - - - -By now, every building-block is in place and we can start exploring how to implement this architecture in practice. - - -## NFTs in Web 2 Applications - -In order to implement a fully functional application using a hybrid Web 2 - Web 3 architecture, a lot of technological challenges have to be addressed, like authentication and authorization, seamless NFTs usage in client and server, and proper NFT storage model. In the following sections we’ll take a closer look at this and describe common patterns and approaches. - - -### Authentication and Authorization - -Since our digital assets are represented as NFTs on blockchain, in order to use them in our Web 2 application, a server needs a way to authorize their usage. The basic idea is pretty simple - it can just read data from blockchain by calling a smart contract method and check an owner’s account id. For such flow, we have 3 actors: - - - -* Client that wants to use some digital asset (NFT). -* Smart Contract for NFTs. Should be implemented according to [NEAR NFT standards](https://nomicon.io/Standards/NonFungibleToken/). -* Server that verifies ownership of NFT and uses it in its internal logic. - -A general flow looks like this: - - - -![image](/docs/assets/web3/nfts-6.png) - - - - - -However, such an authorization process cannot be performed without authentication, so the server also needs a way to authenticate a user. - -Recall that the user's identity on a blockchain is represented by a key pair. However, since in NEAR a user may have multiple key pairs and an account is a separate entity, the authentication procedure is a bit more complicated. - -To authenticate our requests, we can use public-key cryptography - a client can sign a request using a user’s private key, and then a server can verify the signature and key ownership. A typical request with authentication may look like this: - - -```javascript -{ - "payload": { /* request-specific payload */ }, - "accountId": "account.near", - "publicKey": "...", - "timestamp": 1647091283342, - "signature": "..." -} -``` - - -where: - - - -* `accountId` – user’s account id on NEAR. -* `publicKey` - public key of the key pair used for signature, must be either Functional or Full access key for the provided account. -* `timestamp` - current datetime, must be verified on server. It’s needed to prevent [replay attacks](https://en.wikipedia.org/wiki/Replay_attack). Alternative to timestamps is usage of [nonce](https://en.wikipedia.org/wiki/Cryptographic_nonce), but it’s more complicated. -* `signature` - signature of the request payload and other fields. Usually, a payload is hashed beforehand. - -Depending on the implementation, request body, headers, or other side channels can be used to transfer authentication data - exact implementation depends on used technologies and protocols. - -Server can use this data to authenticate a request using the following approach: - - -![image](/docs/assets/web3/nfts-7.png) - - - - -3 authentication steps are performed on the server: - - - -1. Signature verification - if the signature is correct, we are sure that the client really has the private key for the provided public key. Also, this proves that request data hasn't been modified in transit. -2. Timestamp verification - prevents replay attacks. Server can verify that the request’s timestamp is not too old (e.g. has been created no more than 10 seconds ago). -3. Public key ownership verification - by calling [view_access_key method](../../5.api/rpc/access-keys.md), we can make sure that the provided public key is really associated with the provided account. - -Such authentication approach is the simplest one, but has a few major drawbacks: - - - -* Performing a REST API call to RPC Node is quite expensive to do each time from the performance perspective. -* We can’t sign requests from the mobile client, since it usually should be disconnected from the blockchain due to store policies, and hence doesn’t have a key pair. -* A NEAR account is required in order to start using the application, which complicates the onboarding process. - -To solve the first problem, we can simply issue a JWT token or authenticate connection in some other way after a successful NEAR account authentication, so the it will serve as “login” of sorts: - - - -![image](/docs/assets/web3/nfts-8.png) - - - - -While this may be enough for some applications, it doesn’t address the last 2 problems. In order to solve all of them, we can use a hybrid authentication approach with 2 accounts: - - - -1. “Classic” Web 2 account - all clients can use this account to call a server. For example, this can be a simple username/password or OAuth 2 login with a JWT token. -2. NEAR account - can be used from non-mobile clients only. Instead of performing NEAR account auth each time we need to use it, we can do it a single time in order to “connect” this account to our primary Web 2 account and store Classic-NEAR account connection in our server database. In this way we solve all problems - server doesn’t need to authenticate NEAR account each time it wants to perform an authorization, instead it can read an associated NEAR account from its own database. - -With such hybrid approach, different authentication methods are used for blockchain and server: - -
-image -
- -NEAR account connection sequence can be implemented in a very similar way to the already described NEAR authentication method, where at the end we store an authenticated account in our database: - - - -![image](/docs/assets/web3/nfts-10.png) - - - - -There’s one more improvement we can make to this flow. Since a Web Client uses both accounts, a user is forced to login using both Web 2 login method (e.g. login/password) and NEAR Wallet. This is not ideal from the UX perspective, so we can simplify it by introducing a “Login with Wallet” method to our server, which would work when a user already has a wallet connected. We can do this in a similar way to the account connection flow: - - - -![image](/docs/assets/web3/nfts-11.png) - - - - - -Now, as we’ve discussed possible approaches for authentication, let’s summarize it as an overall login flow for our clients: - - - -![image](/docs/assets/web3/nfts-12.png) - - - - - -Of course, this is just one possible flow, and a different solution can be assembled from described building blocks. The most important considerations for choosing right authentication flow are following: - - - -* Type of your client - for web/desktop clients, or sideloaded Android clients, it’s possible to use Wallet as a single authentication method. For mobile clients installed from a store, a hybrid approach with multiple auth methods should be used. -* Target audience - if you target regular users that are not familiar with blockchain technologies, having a hybrid auth method to simplify onboarding might be better than forcing users to learn blockchain before trying your application. - - -#### Blockchain Auth & Auth - -So far, we’ve discussed authentication and authorization on the Web 2 server’s side. But what about Web 3 smart contracts? Everything is much more straightforward in this case. - -Since everything is public data on the blockchain, we don’t need any authentication for read calls. For transactions, each is signed by an account’s private key, and authentication is performed by the network. More details on transaction signing can be found [in the docs](../protocol/transactions.md). - -Authorization, on the other hand, must be performed on a smart contract itself, the simplest way is just to check whether caller is allowed to perform an action: - - -```rust -assert_eq!( - env::predecessor_account_id(), - self.tokens.owner_id, - "Unauthorized" - ); -``` - - - -### NFT usage - -After we’ve learned how to authenticate users and how to authorize NFTs usage, let’s find out how we can actually use them in our application. - -Since we essentially have two backends in our application - server and smart contract(s), they both can use NFTs for different purposes: - - - -* Server usually uses NFTs for actual functional purposes, e.g. by treating NFT as an in-game character, it can read its properties and stats and apply them using some logic. -* Smart contract is responsible for NFTs ownership, as well as NFTs creation, modification and burning (destruction). - -This is the point where the NFT data storage model comes into place. Let’s recall, that there are 3 possible options: - - - -1. Store data in a smart-contract (on-chain). -2. Store data in an [off-chain decentralized storage](../../1.concepts/storage/decentralized-storage.md), like IPFS (off-chain). -3. Store data in an application itself (in-application). - -First 2 approaches provide good decentralization, but make NFT harder to work with, especially if we need to modify its properties. Let’s consider usage options depending on a storage model used: - - - -1. On-chain storage: - * Server can read data from the blockchain by making an API call. Server can’t directly modify data, it should make a smart contract call instead (by issuing a transaction). - * Smart contract can directly read/modify NFT data. - * Clients can read all data directly from the blockchain. -2. Off-chain storage: - * Server can read data from storage by making an API call. Data on the off-chain storage is usually immutable, so no modifications are possible. - * Smart contract cannot read data directly, an Oracle should be used. Data cannot be modified from it. - * Clients should read data from both blockchain and off-chain storage. -3. In-application storage: - * Server can read/modify data from its own database. - * Smart contract cannot read data directly, an Oracle should be used. Data cannot be modified from it. - * Clients should read data from both blockchain and server. - -Depending on a particular use case, any approach, or combination of them, can be used. The simplest case is when we don’t have any dynamic NFT data, and we can easily divide data by domains: - - - -* Data that is used by smart contracts is stored on-chain. -* Other data is stored either off-chain or in-application. - - -
-image -
- - -In this approach the server needs to read data from the smart contract, and, optionally, from an off-chain storage (like IPFS or Database). - -This will work well for simple use cases, but everything becomes more complicated if we need to have some dynamic data associated with NFTs. E.g we may want to have experience points associated with our game character. Such data can be stored either on-chain or in-application (off-chain storage is also possible, but it’s more involved, so we won’t discuss it here). - -In case of in-application storage, data can be modified by a server without any problems, but there are few drawbacks: - - - -* In order to read this data, clients should make an API call to the server. This adds a centralized point for our NFT, and may not be suitable for all applications. -* If a smart contract requires this data, a server should serve as a [Blockchain Oracle](https://en.wikipedia.org/wiki/Blockchain_oracle), which complicates things. - -If we want our server to serve as an oracle for our smart contract, the easiest way is to cryptographically sign server’s data and verify it on the contract’s side (server’s public key that was used for signing should be stored in a contract in this case). - -In order to prevent replay attacks, signed data should include a timestamp, which should also be verified. However, there’s one trick to this - smart contracts can’t access current time, since it would make them non-deterministic. Instead, transaction signature time can be used - it can be accessed using `env::block_timestamp()` function. - - - -![image](/docs/assets/web3/nfts-14.png) - - - - - -In order to avoid all these complications, we can instead store dynamic data on-chain, and use smart contract calls to update it. - - -
-image -
- - -Such an approach has one drawback - in order to call a smart contract’s method, a transaction should be created by the server, and in order to create a transaction it must be signed using an account’s key. That’s why a separate NEAR account should be created to be used by the server. Actions on the smart contract can be configured to authorize only this account, so regular users will be disallowed from modifying such data. - -Yet another option is to store data on the server-side, but a smart contract can authorize only a server account for calls that rely on this data. As with the previous scenario, the server must have its own NEAR account. - - -
-image -
- - -In general, the approach of storing dynamic data on the Smart Contract side is much easier, but an important constraint should be considered - storing data on the blockchain is not cheap, so an appropriate method can be chosen depending on a scenario. - -By now, we’ve covered methods to store and interact with NFTs from our application, an exact strategy should be chosen depending on use cases and constraints. A few things to remember: - - - -* Storing NFTs data in a centralized storage (like an application's database) goes against Web 3 philosophy, and should be used sparingly and with care. -* Storage on the blockchain is not cheap, so decentralized off-chain storages can be used to store large data. -* Storing and using dynamic NFT data is quite tricky, and should be carefully designed. If such dynamic data is needed by smart contracts, it’s better to store it inside this contract if possible. - - -### NFT minting - -So far, we’ve discussed only how to use NFTs in the application, but how do they get created? - -In the blockchain world, creation of new NFTs is usually called minting. And as with traditional digital assets, there are few ways how to create them: - - - -* Users can mint them directly. This can be done by either allowing creation of NFTs from scratch, or by using more complex processes, like breeding or upgrading. The most famous example of such process is breeding in [CryptoKitties](https://www.cryptokitties.co/) game - new NFTs are created by combining existing ones. With this approach users usually have to pay to cover the storage and gas cost of NFTs creation. -* NFTs can be distributed by the developer to a set of users - it is usually called [NFTs airdrop](https://www.investopedia.com/terms/a/airdrop-cryptocurrency.asp). Most often this is used as a marketing strategy to kickstart NFTs usage in applications. Storage and gas costs in this case are covered by developers. -* NFTs can be bought on a market or obtained from the lootbox. Depending on an exact strategy, costs can either be paid by a user or by developer. Also, in this case NFTs sometimes can be minted on-demand, to avoid paying upfront costs. - -An exact strategy used for NFTs minting depends on application use cases. However, almost always there’ll be an `nft_mint _function` defined in a smart contract, which will handle creation of new tokens. This function itself isn't defined [in the standard](https://nomicon.io/Standards/NonFungibleToken/) and is up to the application to implement, but the standard library provides a core implementation for it - [mint_internal](https://docs.rs/near-contract-standards/latest/near_contract_standards/non_fungible_token/core/struct.NonFungibleToken.html#method.internal_mint). On top of this function an additional logic, e.g. for authorization, can be added: - - -```rust -#[payable] -pub fn nft_mint( - &mut self, - token_id: TokenId, - receiver_id: AccountId, - token_metadata: TokenMetadata, -) -> Token { - assert_eq!( - env::predecessor_account_id(), - self.tokens.owner_id, - "Unauthorized" - ); - - let token = self - .tokens - .internal_mint(token_id, receiver_id, Some(token_metadata)); - - return token; -} -``` - - -This approach is quite simple, but everything becomes a bit complicated if we want to provide some on-demand minting functionality to avoid paying upfront costs. For example, we may want to create a lootbox with a set of predefined items appearing with some probability. - -One approach is to handle this logic on a server side, in this case the server will call `nft_mint` function with computed parameters. However, in this case developers will have to pay the cost of minting. If we want to avoid this, loot box logic can be moved into the smart contract itself. If users want to open a loot box, he can call a smart contract function and pay for this action (e.g. by using NEAR or Fungible Tokens). Developers would only need to pay for a lootbox configuration costs, like possible items and their probabilities. - - -## Blockchain Onboarding - -Before designing an onboarding strategy, the target audience should be carefully analyzed. As we briefly mentioned before, users can be divided into two broad buckets: - - - -1. Users that are already familiar with blockchain, have their own wallets and understand cryptocurrency basics. -2. “Casual” users that aren’t familiar with blockchain and don’t know much about it. - -If only the first category is targeted, then everything is quite simple - users are already familiar with main concepts, and will have no problem connecting their own wallet or creating a new one. However, if we want to target the second category of users as well, a strategy has to be developed to make onboarding into the blockchain world as smooth as possible. While a lot relies on proper UX and is very application-specific, a few architectural patterns and technologies exist to simplify this process: custodial wallets, NEAR drops, Prepaid Gas and Implicit Accounts. - -[Custodial Wallet](https://www.coindesk.com/learn/custodial-wallets-vs-non-custodial-crypto-wallets/) is a wallet which is managed by a third party. In our case, a wallet can be created and stored on a server side, and all blockchain operations could be done using the server as a proxy. - - - -![image](/docs/assets/web3/nfts-17.png) - - - - - -In this way, users can remain unaware about the intricacies of blockchain until they are comfortable enough to claim ownership of this account. Once they are ready, the server can transfer the account's ownership and remove it from the server. However, despite simplifying UX for the users, such approach has a few significant drawbacks: - - - -* Users should trust our application to manage their accounts. -* Accounts creation is not free, so unless developers want to pay for it, funds should be transferred from a user to cover this cost. Traditional payment methods can be used, like PayPal or Apple/Google Pay. However, such an approach should be used with care for mobile applications due to app stores policies. Alternatively, NEAR Implicit Accounts can be used to avoid paying for account creation. -* Unless we want to leave a custodial wallet as the only supported wallet type, we need to support both types of wallets (custodial and non-custodial) in our application. This will increase implementations complexity, since we need to support 2 transaction types: - * Server-signed transactions in case of custodial wallet. - * Client-signed transactions in case of non-custodial wallet. - -As we mentioned above, [Implicit Accounts](/concepts/protocol/account-id#implicit-address) can be used to avoid paying account creation costs. This is especially useful for custodial wallets, since it allows us to create a NEAR Account free of charge. Basically, they work like an Ethereum/Bitcoin-style account by using a public key as an account id, and later can be converted to a full NEAR account. However, they have drawbacks as well. First of all, human-readable account names cannot be used. Also, if we want to convert it to a proper NEAR account, which can support Functional Call keys, the account creation fee still has to be paid. - -While being very powerful, custodial accounts are quite complex and tricky to implement. An alternative approach to ease users onboarding is to simplify creation of a wallet itself. In NEAR, we can do this using [NEAR Drops](https://near.org/blog/send-near-to-anyone-with-near-drops/). It allows us to generate a link that guides users through a quick wallet creation process. However, the same problem as for the custodial accounts applies - creation of an account is not free. That’s why, such a link has NEAR tokens attached to it to cover account creation cost and to serve as an initial balance for a newly created wallet. And as with custodial accounts, funds should be transferred from a user to cover this cost using traditional payment channels. - -Another option to simplify onboarding is usage of the `Prepaid Gas` concept. For example, we can issue a Functional Call key that allows users to interact with blockchain without having an account created. In this case funds will be drawn from the developer's account. This can be used for demo purposes, or to allow users without a NEAR account to perform some smart contract actions. - - -## NFT Marketplace - -At this point, we’ve covered in detail how to integrate NFTs into our Web 2 application, but we’ve stayed away from the economy part. The essential part for having a functioning economy is a marketplace where users can freely trade and exchange their NFTs. Such a marketplace usually consists of a smart contract and a client application. This smart contract is closely integrated with a NFT’s smart contract using the cross-contract calls. The reason for having a separate smart contract is two-fold: - - - -* This provides a better separation of concerns - we can modify and upgrade our marketplace independently from the NFT contract. -* Multiple marketplaces can be used - e.g. we can have an internal marketplace, and in addition to it users can list their NFTs on external marketplaces. This is possible because a common NFT standard exists that all marketplaces can rely on. - -General flow of a simple marketplace integration can look like this: - - - -![image](/docs/assets/web3/nfts-18.png) - - - - - - -1. Client calls the [nft_approve](https://nomicon.io/Standards/NonFungibleToken/ApprovalManagement#2-approval-with-cross-contract-call) method on the NFT smart contract. This will approve Marketplace Smart Contract to sell this NFT. -2. After approving an account, NFT smart contract issues a cross-contract call to the Marketplace to create a sale object. Arguments for this call are provided as part of the `nft_approve` call. -3. Another user wants to buy the NFT on sale, so he issues a call to the marketplace contract offering to buy it. An exact call signature for such action is not standardized and depends on marketplace implementation. -4. If an offer to buy a NFT is valid, Marketplace issues an [nft_transfer_payout](https://nomicon.io/Standards/NonFungibleToken/Payout) call to transfer the NFT and return payout information. This information is used by the Marketplace to distribute profits from the sale between recipients. In the simplest case, all profits go to a seller. - -Such flow looks relatively simple, but a few important details are missing. - -First of all, in order to create a sale, storage needs to be paid for. Usually, the seller is the one who needs to pay for it, but other models are possible - e.g. marketplace or application developers could cover the cost. If we want users to pay for a sale, an approach with storage reservation can be used: - - - -* Before approving NFT for sale, a user should reserve storage on the Marketplace contract to cover sale storage requirements. -* After the NFT is bought or delisted, the user can withdraw storage reservation (remember, that in NEAR storage staking model is used, so data can be deleted and locked tokens refunded). - -While this model is relatively straightforward, it’s not ideal from the UX perspective - users must make a separate action to reserve storage if they want to sell their NFTs. To improve this, we can combine `nft_approve` call with storage reservation, and automatically refund back the storage cost after the sale is removed. - - - -![image](/docs/assets/web3/nfts-19.png) - - - - - -Another missing thing is how a client can read data about available sales. Of course, sales information can be read directly from a smart contract, but available data structures are not optimized for searching or filtering. Also, we would have to join data from the NFT and Marketplace contracts on the client side, which isn’t efficient. In order to solve these problems, an indexer can be used to aggregate data into a suitable database, where data can be stored in a way optimal for retrieval (e.g. a relational database or an ElasticSearch index can be used). - - - -![image](/docs/assets/web3/nfts-20.png) - - - - -This is just one example of how a marketplace can be designed, but with it we’ve covered all basic concepts and problems. Most important points to remember: - - - -* It’s better to implement a marketplace as a separate contract. -* Storage management should be carefully designed, with UX in mind. -* In order to implement a proper searching/filtering functionality, a separate indexing service is needed. - -An example of a simple marketplace [can be found here](../../3.tutorials/nfts/8-marketplace.md). A more sophisticated marketplace may allow purchases with Fungible Tokens as payment. - - -## Implementing Components - -Now, let’s explore our choice of libraries, frameworks and third-party solutions that can be used to implement our architecture. - - -#### Client & Server - -First of all, how can we interact with blockchain from our clients? - -If we need read-level access only, we can simply use the [REST API](https://docs.near.org/api/rpc/setup), so it can be integrated into any language and technology without any problems. But everything becomes more complicated if we need to post transactions from a client. Remember, that transaction should be signed with a private key which is stored in a wallet: - - - -* In case of a Functional Call key, it can be obtained from the wallet and used directly by the client. -* In case of a Full Access key, the user should be redirected to the wallet to approve a transaction. - -A [JavaScript API](../../4.tools/near-api.md) exists to cover all of these scenarios. It has all of the necessary functionality to integrate Web/Node.JS applications with blockchain. This SDK is a perfect choice for the Web-based clients, but it’s not suitable for desktop or mobile based clients. Other libraries can be used for them: - - - -* [.NET Client](https://github.com/good1101/NearClientApi/tree/master/NearClient) - suitable for Unity or Xamarin. -* [Swift](https://github.com/near/near-api-swift) -* [Python](https://github.com/near/near-api-py) -* [Unity](https://github.com/near/near-api-unity) - - -Same SDKs and libraries can be used for servers. The only difference is that a server cannot interact with a Wallet, so it must have access to a Full Access key, which should be stored and accessed in a secure way. - -Also, another solution is available if a server uses a technology that doesn’t have NEAR SDK available for - we can create a separate (micro)service using the Node.js, which would handle all blockchain interactions: - - -
-image -
- - -An example of such a proxy server [can be found here](https://github.com/near-examples/near-api-rest-server). - - -#### Contracts - -As we discovered in a previous section, for our application we need two smart contracts: for NFT and for Marketplace. There are two options on how to get them - use in-house implementation or some third-party/SAAS solution. Both options are viable and have different pros/cons. - -If we want to create our own contract, we are fully in control and can implement anything we want. An obvious drawback, of course, is that it will take time and money to build it. Third-party solutions, on the other hand, are limited in their functionality and often cannot be easily extended. Also, they usually have some upfront costs and/or usage fees. - -For an in-house NFT contract implementation a few resources can be used as a starting point. First of all, a [Rust library](https://docs.rs/near-contract-standards/latest/near_contract_standards/index.html) is available which implements most of the standard. Another option is to build an entire contract from scratch, a good guide on how to do this is available by [this link](../../3.tutorials/nfts/0-intro.md). - -Implementing an own Marketplace contract is more involved since there is no standard implementation. A few examples: - - - -* [Basic marketplace example](../../3.tutorials/nfts/8-marketplace.md) -* [Paras ](https://paras.id/)marketplace contract - [source](https://github.com/ParasHQ/paras-marketplace-contract/tree/master/paras-marketplace-contract/src). - -As for third-party solutions, the most complete one is [Mintbase](https://www.mintbase.io/), which provides a full suite of components for NFTs integration - including contracts, indexer, API and a web client: - - - -![image](/docs/assets/web3/nfts-22.png) - - - - -Another option is to roll-out an own NFT contract and integrate with one of the third-party marketplaces, e.g. with [Paras](https://paras.id/) ([integration docs](https://docs.paras.id/nft-smart-contract-integration)). - - - - -![image](/docs/assets/web3/nfts-23.png) - - - - - -The major advantage of an external marketplace is the fact that they usually run their own indexer and expose collected data via an API, so we don’t have to implement these components. However, they usually have their fee for providing them, so a cost-benefit analysis should be conducted before using them. - - -#### Off-chain storages - -Previously, we’ve discussed that storage on the blockchain is not cheap, so in most cases some decentralized storage solution should be used. A few options are available: - - - -* [IPFS ](https://ipfs.io/)- one of the first decentralized storage solutions, which is widely used in the blockchain world. However, in order to make sure that data is preserved on the network, an IPFS node(s) should be maintained. -* [Arweawe](https://www.arweave.org/) - blockchain-based decentralized storage. -* [Filecoin](https://filecoin.io/) - another blockchain-based storage. -* [nft.storage](https://nft.storage/) - a free service built on top of the IPFS and Filecoin. - -A more in-depth overview of such solutions is available [in the docs](../storage/decentralized-storage.md). In general, there's no “silver bullet”, so different solutions should be evaluated and the most suitable chosen. The main concerns while choosing a solution are availability guarantees, and cost. - - -#### Indexer - -As we already determined, an indexing service is needed in order to support marketplace functionality. It usually consists of 3 components: - - - -* Indexer - processes transactions from a NEAR network and puts extracted data into a database. -* Database - database of choice to store extracted data. -* Indexer API - an API layer on top of the database. - - -
-image -
- - -While any technology of choice can be used to implement Database and API, an indexer itself is can be implemented using both [Rust](https://github.com/near/near-lake-framework-rs) and [JavaScript](https://github.com/near/near-lake-framework-js). See [this example](https://github.com/near-examples/near-lake-nft-indexer) written in Rust. - -Usually, an indexer works by extracting data from [Events](https://nomicon.io/Standards/EventsFormat), which are basically just structured log messages written during contract execution. - -[The Graph](https://thegraph.com/en/) is an alternative to building an indexer from scratch. This is an Indexer-as-a-Service solution, which simplifies their creation and deployment. Guide on how to create a NEAR indexer is available [by this link](https://thegraph.com/docs/en/supported-networks/near/). - - -#### Automated Testing - -Automated testing of the code is one of the pillars of modern software development. But how do we test our dApp? - -Recall that a smart contract is a pure function, which can be easily tested using Unit Tests. Guide on how to write them is available [here](../../2.build/2.smart-contracts/testing/unit-test.md), and some examples can be found here. Another important kind of tests that is supported by NEAR are E2E tests, they can be executed either deploying contract code to either the local network environment (more info [here](../../2.build/2.smart-contracts/testing/introduction.md)), or directly to `testnet`, more info [here](../../2.build/2.smart-contracts/testing/integration-test.md)). - -Having both types of tests is equally important to ensure continuous quality of smart contracts, especially since contract upgrades usually aren’t easy to perform (remember, that in DAOs upgrade itself might be governed by a community vote). - - -## Non-Functional Concerns - -Last, but not least, let’s cover important non-functional concerns for our architecture. - - -### Security - -The most important thing to remember during the entire development is security, and especially the security of smart contracts. Since their code is public and an upgrade procedure is not trivial, it should be carefully audited for security issues and logical exploits. - -Another important thing that should be kept secure is a user's private key. In most cases, only Functional Call keys should be directly accessed from a client, and Full Access keys should be kept in a wallet. However, in some cases a Full Access key might have to be used directly (e.g. in case of server transaction signing scenarios). In such a case, it must be kept in a secure location and treated as a most sensitive secret, since its compromise might lead to a full account takeover. - -In general, before deploying an application to the NEAR mainnet, it’s a good idea to conduct a full security audit. - - -### Scalability and Availability - -Another concern is scalability and availability of a solution. There are a lot of ways to scale traditional servers, but how do we scale our blockchain and make sure it’s always available? - -Since blockchain is decentralized, it provides us with high-availability by design, and NEAR provides a great scalability by employing Proof-of-Stake consensus and sharding. However, in order to interact with a network, we need an RPC Node. NEAR maintains publicly available nodes for its networks (listed [here](https://rpc.mainnet.near.org/status)), but it doesn't provide any performance or availability guarantees for them. So, in order to make sure our architecture is scalable and fault tolerant, we need to maintain our own cluster of RPC nodes, typically behind a load balancer. - - -
-image -
- - -Information on how to set up an RPC node is available [here](https://near-nodes.io/rpc). - -Also, to guarantee availability and scalability of a whole system, all used third-party services should be reviewed as well. For example, if IPFS is used as a storage for NFTs, pinning nodes and IPFS gateway should be scalable and fault tolerant. - - -### Costs - -When building a Web 3 application, it’s important to remember that cost calculation is somewhat different from Web 2 applications. Additional costs can be broken down into several categories: - - - -1. Smart Contracts deployment costs. While deploying on NEAR testnet or local environment, it’s essentially free of charge. However, when deploying into the mainnet, developers will be charged for storage and gas cost. Gas cost for a contract deployment transaction is relatively small (around 0.04$ at the time of writing). On the other hand, storage costs can be quite substantial, e.g. a 150KB contract (compiled) will cost around 20$. -2. Smart Contracts usage cost. In Web 3, users pay for smart contract calls, so in order to make sure users aren’t discouraged to interact with a contract due to a high cost, it should be optimized to incur the lowest cost possible. This is especially important for storage costs, since gas is relatively cheap. -3. If we want to use a privately hosted RPC node for better availability, its operational costs should be taken into account as well. Cost breakdown can be found [here](https://near-nodes.io/rpc/hardware-rpc), a rough estimation is about 290$ per node per month (and remember that we need at least 2 nodes for redundancy). -4. Cost of a privately hosted indexer (if it’s used). More information can be found [here](/concepts/advanced/near-indexer-framework), a rough estimation for the costs is about 100$ per month. -5. Third party services costs. diff --git a/docs/4.tools/ethereum-wallets.md b/docs/2.build/4.web3-apps/ethereum-wallets.md similarity index 100% rename from docs/4.tools/ethereum-wallets.md rename to docs/2.build/4.web3-apps/ethereum-wallets.md diff --git a/docs/2.build/4.web3-apps/quickstart.md b/docs/2.build/4.web3-apps/quickstart.md index a7ba9e723a3..1b4e9a87ec9 100644 --- a/docs/2.build/4.web3-apps/quickstart.md +++ b/docs/2.build/4.web3-apps/quickstart.md @@ -79,7 +79,7 @@ const wallet = new Wallet({ }); ``` -This example additionally includes the option to login with `Metamask` and other `EVM wallets`. Further information on how to add EVM wallets to your application can be found in the [Ethereum Wallets on NEAR documentation](../../4.tools/ethereum-wallets.md). +This example additionally includes the option to login with `Metamask` and other `EVM wallets`. Further information on how to add EVM wallets to your application can be found in the [Ethereum Wallets on NEAR documentation](./ethereum-wallets.md).
What is the wallet selector? diff --git a/docs/1.concepts/3.advanced/near-lake-framework.md b/docs/2.build/6.data-infrastructure/lake-framework/near-lake-framework.md similarity index 78% rename from docs/1.concepts/3.advanced/near-lake-framework.md rename to docs/2.build/6.data-infrastructure/lake-framework/near-lake-framework.md index 53f739b1f95..540c47517f4 100644 --- a/docs/1.concepts/3.advanced/near-lake-framework.md +++ b/docs/2.build/6.data-infrastructure/lake-framework/near-lake-framework.md @@ -1,17 +1,8 @@ --- -sidebar_label: "Lake Framework" +id: near-lake-framework +sidebar_label: "NEAR Lake Framework" --- -# NEAR Lake Framework - -:::note GitHub repo - -https://github.com/near/near-lake-framework/ - -::: - -## Description - NEAR Lake Framework is an ecosystem of library companions to [NEAR Lake](/build/data-infrastructure/lake-framework/near-lake). They allow you to build your own indexer that subscribes to the stream of blocks from the [NEAR Lake](/build/data-infrastructure/lake-framework/near-lake) data source and create your own logic to process the NEAR Protocol data in the programming languages of your choice (at the moment, there are implementations 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)). :::tip NEAR Lake Framework announcement @@ -22,14 +13,20 @@ Please, read the post [here](https://gov.near.org/t/announcement-near-lake-frame ::: +:::note GitHub repo + +https://github.com/near/near-lake-framework/ + +::: + -## How does it compare to [NEAR Indexer Framework](near-indexer-framework.md)? +## How does it compare to [NEAR Indexer Framework](https://github.com/near/nearcore/tree/master/chain/indexer)? Feature | Indexer Framework | Lake Framework ------- | ----------------- | -------------- Allows to follow the blocks and transactions in the NEAR Protocol | **Yes** | **Yes**
(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)](near-indexer-framework.md#limitations) | [minimum 3.9s (estimated average 6-8s)](#limitations) +Reaction time (end-to-end) | minimum 3.8s (estimated average 5-7s) | [minimum 3.9s (estimated average 6-8s)](#limitations) 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**](#what-is-the-cost-of-running-a-custom-indexer-based-on-near-lake) Ease of maintenance | Advanced
(need to follow every nearcore upgrade, and sync state) | **Easy**
(deploy once and forget) @@ -40,9 +37,9 @@ Programming languages that a custom indexer can be implemented with | Rust only ## Limitations -Lake Framework relies on the data being dumped to AWS S3 from [NEAR Lake Indexer](https://github.com/near/near-lake-indexer) which is based on [NEAR Indexer Framework](near-indexer-framework.md). Thus, Lake Framework is centralized around AWS S3 storage and also around maintainers of NEAR Lake Indexer nodes (Pagoda Inc). This is the tradeoff you might still want to take given all the other benefits mentioned above. +Lake Framework relies on the data being dumped to AWS S3 from [NEAR Lake Indexer](https://github.com/near/near-lake-indexer) which is based on [NEAR Indexer Framework](https://github.com/near/nearcore/tree/master/chain/indexer). Thus, Lake Framework is centralized around AWS S3 storage and also around maintainers of NEAR Lake Indexer nodes (Pagoda Inc). This is the tradeoff you might still want to take given all the other benefits mentioned above. -Indexers based on the Lake Framework inherit [the latency characteristics of Indexer Framework](near-indexer-framework.md#limitations) and extra latency of dumping to and reading from AWS S3, which is estimated to add at least 50ms delay while writing to S3, and 50ms on polling and reading from S3 (to make the polling cost-efficient, we default to polling only every 2s, so in the worst case you may observe an additional 2-second latency). Thus, Lake Framework adds 0.1-2.1s latency on top of Indexer Framework. Yet, again, most of the latency is there due to the finalization delay and both Indexer Framework and Lake Framework add quite a minimum overhead. +Indexers based on the Lake Framework inherit [the latency characteristics of Indexer Framework](https://github.com/near/nearcore/tree/master/chain/indexer) and extra latency of dumping to and reading from AWS S3, which is estimated to add at least 50ms delay while writing to S3, and 50ms on polling and reading from S3 (to make the polling cost-efficient, we default to polling only every 2s, so in the worst case you may observe an additional 2-second latency). Thus, Lake Framework adds 0.1-2.1s latency on top of Indexer Framework. Yet, again, most of the latency is there due to the finalization delay and both Indexer Framework and Lake Framework add quite a minimum overhead. ## What is the cost of running a custom indexer based on NEAR Lake? diff --git a/docs/3.tutorials/crosswords/02-beginner/05-logging-in.md b/docs/3.tutorials/crosswords/02-beginner/05-logging-in.md index 397d8306053..129561919fd 100644 --- a/docs/3.tutorials/crosswords/02-beginner/05-logging-in.md +++ b/docs/3.tutorials/crosswords/02-beginner/05-logging-in.md @@ -54,9 +54,7 @@ When we used the `near login` command in the [previous chapter](../01-basics/01- ### Function-call access keys -Function-call access keys are sometimes called "limited access keys" because they aren't as powerful as the full access keys. - -A Function-call access key will specify: +Function-call access keys will specify: - What contract it's allowed to call - What method name(s) it's allowed to call (you can also specify all functions) diff --git a/docs/4.tools/cli.md b/docs/4.tools/cli.md index 7771ac547c6..075bc67731e 100644 --- a/docs/4.tools/cli.md +++ b/docs/4.tools/cli.md @@ -7,9 +7,12 @@ import TabItem from '@theme/TabItem'; The NEAR [Command Line Interface](https://github.com/near/near-cli-rs) (CLI) is a tool that enables to interact with the NEAR network directly from the shell. Among other things, the NEAR CLI enables you to: -- Login with a NEAR account +- Create a new NEAR account +- Query information about an account +- Send Tokens such as NEAR, FTs, and NFTs +- Create, Add and Delete Account Keys - Deploy a contract -- Interact and query information from a deployed contract +- Call functions on a deployed contract --- diff --git a/docs/4.tools/ecosystem-apis/fastnear-api.md b/docs/4.tools/ecosystem-apis/fastnear-api.md index 1db492f16c0..c382d13a34e 100644 --- a/docs/4.tools/ecosystem-apis/fastnear-api.md +++ b/docs/4.tools/ecosystem-apis/fastnear-api.md @@ -1,74 +1,40 @@ --- -id: fastnear-api -title: FastNEAR API -sidebar_label: FastNEAR API +id: fastnear +title: FastNEAR --- -[FastNEAR](https://fastnear.com/) provides high-performance infrastructure enabling seamless blockchain interactions. +[FastNEAR](https://fastnear.com/services) allows to easily query the NEAR blockchain to get an account's assets, map keys into account IDs, explore a block's transactions, etc. -## Overview +Possible use cases include: +- Querying all assets of an account (including fungible and non-fungible tokens) +- Querying the last block produced +- Mapping Public Key to Account ID +- Mapping Full Access Public Key to Account ID +- Knowing a user's staking pools (validators) +- Querying the top holders of a token -[FastNEAR](https://fastnear.com/) exposes low-latency APIs for wallets and explorers. Their API allows you to easily query the NEAR blockchain to get an account's assets, map keys into account IDs, explore a block's transactions, etc. +:::tip Documentation -:::info More info +[Click here](https://github.com/fastnear/fastnear-api-server-rs?tab=readme-ov-file#api-v1) to see the complete list of endpoints and usage examples -Find more information about the FastNear API in their [services page](https://fastnear.com/services). - -::: - -## RPC implementation - -[Fast-Near](https://github.com/fastnear/fast-near) aims to provide the fastest RPC implementation for NEAR Protocol using high-performance storage backends: - - in-memory storage in [Redis](https://redis.io/). - - SSD optimized storage using [LMDB](https://www.symas.com/lmdb). - -It is optimized for `view` call performance and ease of deploy and scaling. - - -:::note About data sync -FastNear doesn't sync with the NEAR blockchain on its own. Data needs to be loaded either from [NEAR Lake](https://github.com/near/near-lake-indexer) or from [Near State Indexer](https://github.com/vgrichina/near-state-indexer). ::: --- ## Endpoints -The [FastNEAR API server](https://github.com/fastnear/fastnear-api-server-rs) provides a low-latency RPC API for wallets and explorers. +The [FastNEAR Server](https://github.com/fastnear/fastnear-api-server-rs) provides a low-latency endpoint for wallets and explorers. - Mainnet: `https://api.fastnear.com` - Testnet: `https://test.api.fastnear.com` -#### Public Key - -- Public Key to Account ID mapping. -- Full Access Public Key to Account ID mapping. -- Any Public Key to Account ID mapping. - -#### Account ID - -- Account ID to delegated staking pools (validators). -- Account ID to fungible tokens (FT contracts). -- Account ID to non-fungible tokens (NFT contracts). - -#### Token ID - -- Token ID to top 100 accounts by balance (for FT contracts). - - -:::tip V1 API - -[Click here](https://github.com/fastnear/fastnear-api-server-rs?tab=readme-ov-file#api-v1) to see the complete list of API endpoints and usage examples. - -::: +--- ## Examples -### [Blockchain Data](https://github.com/fastnear/neardata-server/) - -- Query last block produced +### [Query last block produced](https://github.com/fastnear/neardata-server/) ```bash -# Query last block produced curl https://mainnet.neardata.xyz/v0/last_block/final ``` @@ -90,9 +56,9 @@ curl https://mainnet.neardata.xyz/v0/last_block/final
-### [User Queries](https://github.com/fastnear/fastnear-api-server-rs) +
-- Query user's FTs +### [Query User's Balance](https://github.com/fastnear/fastnear-api-server-rs) ```bash # Query user's FTs @@ -108,9 +74,7 @@ curl https://api.fastnear.com/v1/account/root.near/ft ---- - -- Query user's NFTs +
```sh # Query user's NFTs @@ -126,9 +90,7 @@ curl https://api.fastnear.com/v1/account/root.near/nft ---- - -- Query all user's assets +
```sh # Query all user's assets diff --git a/docs/4.tools/ecosystem-apis/nearblocks-api.md b/docs/4.tools/ecosystem-apis/nearblocks-api.md index ed86fae01ed..b9e5ffda5dc 100644 --- a/docs/4.tools/ecosystem-apis/nearblocks-api.md +++ b/docs/4.tools/ecosystem-apis/nearblocks-api.md @@ -1,21 +1,24 @@ --- -id: nearblocks-api -title: NearBlocks API -sidebar_label: NearBlocks API +id: nearblocks +title: NearBlocks --- -The [NearBlocks API](https://api.nearblocks.io/api-docs/) provides a simple way to query actions that happened on a NEAR account, such as function calls, token transfers, etc. +[NearBlocks](https://api.nearblocks.io/api-docs/) provides an endpoint to query actions that happened on a NEAR account, possible use cases include: -## Overview +- 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 -The [NearBlocks](https://nearblocks.io/) Developer [REST APIs](https://nearblocks.io/apis) are provided as a community service and without warranty, so please use what you need and no more. +:::tip Documentation -NearBlocks also provides an API Pro plan which is a monthly subscription-based API service that provides higher rate limits for power users and commercial solutions. To upgrade to a paid API Plan, head over to the APIs page and select a plan that suits your needs. Once payment has been made, you can create API keys to make requests to our end points. +You can find the complete endpoint list in [this page](https://api.nearblocks.io/api-docs/) -## Endpoints +::: + +--- -You can find the complete API endpoint list in [this page](https://api.nearblocks.io/api-docs/). -You can access the REST APIs using [cURL](http://curl.se), or any HTTP client. +## Endpoints - Mainnet: `https://api.nearblocks.io` - Testnet: `https://api-testnet.nearblocks.io` @@ -29,18 +32,13 @@ If you have a Pro subscription, you can pass the API key into a REST API call as ```sh curl -X GET -H "Authorization: Bearer API_KEY" "https://api.nearblocks.io/v1/account/wrap.near" ``` - -:::tip More info - -Check the [API documentation](https://api.nearblocks.io/api-docs/) for more information about the NearBlocks API. -::: +--- ## Examples -- All the times **anyone** called `create_drop` on Keypom +All the transactions where somebody called `create_drop` on Keypom ```bash -# All the times **anyone** called "create_drop" on Keypom curl -X GET "https://api.nearblocks.io/v1/account/v2.keypom.near/txns?method=create_drop" ``` @@ -53,16 +51,14 @@ curl -X GET "https://api.nearblocks.io/v1/account/v2.keypom.near/txns?method=cre ---- +
-- All the times that `gagdiez.near` called `create_drop` on Keypom +All the times that `gagdiez.near` called `create_drop` on Keypom ```sh -# 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" ``` -
Response diff --git a/docs/4.tools/ecosystem-apis/pikespeak-api.md b/docs/4.tools/ecosystem-apis/pikespeak-api.md index dcfe4e3639e..9972c147580 100644 --- a/docs/4.tools/ecosystem-apis/pikespeak-api.md +++ b/docs/4.tools/ecosystem-apis/pikespeak-api.md @@ -1,38 +1,34 @@ --- -id: pikespeak-api -title: Pikespeak API -sidebar_label: Pikespeak API +id: pikespeak +title: Pikespeak --- -[Pikespeak](https://pikespeak.ai) offers an enterprise-grade API where you can fetch blockchain events and aggregated analytics on wallets, validators, delegators, money transfers, dApps activity, and more. +[Pikespeak](https://pikespeak.ai) allows you to fetch blockchain events and aggregated analytics on wallets, validators, delegators, money transfers, dApps activity, and more. -## Overview +Use case includes: +- Querying account balances +- Querying the most active wallets +- Querying historic account events -Pikespeak is a Data & Analytics solution built on NEAR Protocol. -Since inception, Pikespeak has recorded over 1 billion on-chain events and generated over 40 data points for more than 60 million accounts. Actionable data that can supercharge Web3 projects, allowing them to take action. -The solution provides: +:::tip Documentation -- Dashboards and visualizations of the most fundamental Web3 use cases; -- An API with 50+ endpoints to consume live, historical data, and insights in a programmatic way. +You can find the complete API endpoint list in [this page](https://doc.pikespeak.ai/) +::: + +--- ## Endpoints 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. -You can find the complete API endpoint list in [this page](https://doc.pikespeak.ai/). -You can access the REST APIs using [cURL](http://curl.se), or any HTTP client. - - Mainnet: `https://api.pikespeak.ai` -:::tip More info - -Check the [API documentation](https://doc.pikespeak.ai/) for more information about the Pikespeak API. -::: +--- ## Examples -- Account balance for `root.near`: +Check the account balance for `root.near`: ```sh curl -X 'GET' \ @@ -58,9 +54,9 @@ curl -X 'GET' \
---- +
-- Most active wallets NEAR senders: +Most active wallets NEAR senders: ```sh curl -X 'GET' \ @@ -96,9 +92,9 @@ curl -X 'GET' \ ---- +
-- Get historic account events for `keypom.near`: +Get historic account events for `keypom.near`: ```sh curl -X 'GET' \ diff --git a/docs/4.tools/explorer.md b/docs/4.tools/explorer.md index e35226704b5..98952523304 100644 --- a/docs/4.tools/explorer.md +++ b/docs/4.tools/explorer.md @@ -6,12 +6,11 @@ sidebar_label: Explorers import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; -An Explorer allows you to quickly obtain information from the blockchain through a friendly user interface. -These useful tools enable for example to: +Explorers are web applications that allows you to quickly obtain information from the blockchain through a friendly user interface: -1. Search for a transactions and its receipts. -2. Check all the interactions in a smart contract. -3. See the balance of an account. +1. Check the balance of an account +2. Search for a transactions and its receipts +3. Check the history of interactions in an account / contract 4. View block creations in real time --- diff --git a/docs/4.tools/indexing-tools.md b/docs/4.tools/indexing-tools.md index bfba5be30a0..cb0ea02b754 100644 --- a/docs/4.tools/indexing-tools.md +++ b/docs/4.tools/indexing-tools.md @@ -4,9 +4,9 @@ title: Indexing Solutions on NEAR sidebar_label: "Indexing Solutions" --- -# Indexing Solutions on NEAR +Indexers are services that are constantly listening to the blockchain, processing the transactions and storing them in a database that can be easily queried. -Here's a quick overview of Indexer projects on the NEAR ecosystem: +Indexers are used by apps that need to access blockchain data efficiently, such as wallets and explorers. - [BigQuery](../2.build/6.data-infrastructure/big-query.md): Blockchain data indexing in NEAR Public Lakehouse is for anyone wanting to understand blockchain data. @@ -14,16 +14,12 @@ Here's a quick overview of Indexer projects on the NEAR ecosystem: - [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. -- [Pagoda NEAR Lake](https://docs.pagoda.co/near-lake): with this fully managed solution by [Pagoda Inc.](https://www.pagoda.co), you don't need to run your own NEAR Lake Nodes and AWS S3 buckets. - - [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. - [NearBlocks](https://api.nearblocks.io/api-docs/#/): build precise & reliable dApps with NearBlocks APIs. -- [Octopus Network NEAR Indexer](https://github.com/octopus-network/octopus-near-indexer-s3): an indexing solution based on NEAR Lake framework. - - [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://docs.near.org/concepts/advanced/near-indexer-framework): a micro-framework providing you with a "live" stream of blocks. Useful to handle on-chain real-time `events`. diff --git a/docs/4.tools/near-api.md b/docs/4.tools/near-api.md index 49b67ce80f9..12b1f9d1403 100644 --- a/docs/4.tools/near-api.md +++ b/docs/4.tools/near-api.md @@ -8,21 +8,24 @@ import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import {Github, Language} from "@site/src/components/codetabs" -The NEAR API is a set of libraries that allow you to interact with the NEAR blockchain. You can use it to create accounts, send tokens, deploy contracts, and more. +The NEAR API is a set of libraries that allow you to interact with the NEAR blockchain. You can use it to in frontend and backend applications to: -The API is available in multiple languages, including: +- Call functions on a deployed contract +- Query information about an account +- Create NEAR accounts +- Send Tokens such as NEAR, FTs, and NFTs +- Create, Add and Delete Account Keys +- Deploy a contract + +Our API is available in multiple languages, including: - JavaScript: [`near-api-js`](https://github.com/near/near-api-js) - Rust: [`near-api-rs`](https://github.com/near/near-api-rs) - Python: [`py-near`](https://github.com/pvolnov/py-near) -For example, you could use [`near-api-js`](https://github.com/near/near-api-js) to create web applications or backend services written in node.js servers. - :::tip Wallet Integration To allow users to login into your web application using a wallet you will need the `wallet-selector`. Read more in our [Web Frontend integration](/build/web3-apps/integrate-contracts) article ::: -These examples are references to code snippets, feel free to explore the full code examples in context by clicking `See full example on GitHub` below each example. - --- ## Install diff --git a/docs/4.tools/wallet-selector.md b/docs/4.tools/wallet-selector.md index b6cede55dbf..d83cd659cca 100644 --- a/docs/4.tools/wallet-selector.md +++ b/docs/4.tools/wallet-selector.md @@ -1,42 +1,57 @@ -# Wallet Selector - -An easy-to-navigate modal that allows users to select their preferred wallet to easily interact with the NEAR protocol. +--- +id: wallet-selector +title: Wallet Selector +sidebar_label: NEAR Wallet Selector +--- -Launched in March 2022 by the NEAR Foundation, this simple modal will appear whenever users are given the option to “Connect Wallet” to the NEAR blockchain. +The [Wallet Selector](https://github.com/near/wallet-selector) is a `JS`/`TS` library that lets users connect to your application using their preferred wallet. ![Preview](/docs/assets/wallet-selector-preview.png) *Initial screen of [Wallet Selector](https://near.github.io/wallet-selector/)* ---- +
+ List of NEAR Wallets -## Framework agnostic +Here is a list of user-friendly wallets that support the NEAR blockchain, you can find more at the [NEAR Wallets](https://wallet.near.org/) page. -[React](https://reactjs.org/) / [Next.js](https://nextjs.org/) and [Angular](https://angular.io/) variations of the [Guest Book](https://github.com/near-examples/guest-book-examples/) dApp can be found in the [`examples`](https://github.com/near/wallet-selector/tree/main/examples) directory. Developers can use these to gain a concrete understanding of how to integrate NEAR Wallet Selector into their own dApp. +- [HERE Wallet](https://www.herewallet.app/): Non-custodial mobile wallet with a friendly user interface and advanced features. -### Unlocking the wallet ecosystem +- [Meteor Wallet](https://wallet.meteorwallet.app/): Both a browser and extension wallet, with advanced NFT features. -Wallet Selector makes it easy for users to interact with dApps by providing an abstraction over various wallets and wallet types within the NEAR ecosystem. +- [Mintbase Wallet](https://wallet.mintbase.xyz/): A passkey meta-transaction, browser wallet, with advanced NFT and AI features. If you're looking to integrate Mintbase Wallet into your applications, [check this tutorial](https://docs.mintbase.xyz/wallet/integrating-mintbase-wallet) to get started. -:::info +- [MyNearWallet](https://mynearwallet.com/): A browser based wallet that offers the same UI and features of `wallet.near.org`. -You can check the current list of supported wallets in the [README.md](https://github.com/near/wallet-selector/blob/main/README.md) file of near/wallet-selector repository. +- [NEAR Mobile](https://nearmobile.app/): A non-custodial wallet that is easy to use and well designed to manage your crypto wherever you go. -::: +- [Nightly Wallet](https://wallet.nightly.app/download): A mobile and extension wallet, with support for multiple ecosystems. + +- [Sender Wallet](https://sender.org/): Security-audited mobile & extension wallet with 1M+ users, supporting NEAR & Aurora. + +- [WELLDONE Wallet](https://welldonestudio.io/): A multi-chain extension wallet that gives you control over all your assets from a single platform. + +
+ +--- + +## Unlocking the wallet ecosystem -Thanks to NEAR’s open and inclusive approach, other wallet developers can contribute to the NEAR ecosystem by following the documentation and instructions on the [NEAR Github repository](https://github.com/near/wallet-selector) on how to add a new wallets to the Wallet Selector. +Wallet Selector makes it easy for users to interact with dApps by providing an abstraction over various wallets and wallet types within the NEAR ecosystem. -:::tip +:::info -To learn more on how to include new wallets for Wallet Selector you can check the listing criteria for third party wallets on this [link](https://github.com/near/wallet-selector/blob/main/CONTRIBUTING.md#listing-criteria-for-third-party-wallet-on-wallet-selector). +You can check the current list of supported wallets in the [README.md](https://github.com/near/wallet-selector/blob/main/README.md) file of near/wallet-selector repository. ::: +--- + ## Install The easiest way to use NEAR Wallet Selector is to install the core package from the NPM registry, some packages may require near-api-js v0.44.2 or above check them at packages. ```bash -npm install near-api-js@^0.44.2 +npm install near-api-js ``` ```bash @@ -62,6 +77,8 @@ npm install \ @near-wallet-selector/coin98-wallet ``` +--- + ## Setup Wallet Selector Optionally, you can install our [`modal-ui`](https://www.npmjs.com/package/@near-wallet-selector/modal-ui) or [`modal-ui-js`](https://www.npmjs.com/package/@near-wallet-selector/modal-ui-js) package for a pre-built interface that wraps the `core` API and presents the supported wallets: @@ -99,11 +116,11 @@ import "@near-wallet-selector/modal-ui/styles.css" ::: -## API Reference +--- -The API reference of the selector can be found [`here`](https://github.com/near/wallet-selector/blob/main/packages/core/docs/api/selector.md) +## Reference -## Wallet API +The API reference of the selector can be found [`here`](https://github.com/near/wallet-selector/blob/main/packages/core/docs/api/selector.md) ### Sign in diff --git a/docs/4.tools/wallets.md b/docs/4.tools/wallets.md deleted file mode 100644 index a36800e9259..00000000000 --- a/docs/4.tools/wallets.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -id: wallets -title: Wallets -sidebar_label: Wallets ---- - -# Supported Wallets - -Here's a range of user-friendly wallets that support the NEAR blockchain: - -- [HERE Wallet](https://www.herewallet.app/): Non-custodial mobile wallet with a friendly user interface and advanced features. - -- [Meteor Wallet](https://wallet.meteorwallet.app/): Both a browser and extension wallet, with advanced NFT features. - -- [Mintbase Wallet](https://wallet.mintbase.xyz/): A passkey meta-transaction, browser wallet, with advanced NFT and AI features. If you're looking to integrate Mintbase Wallet into your applications, [check this tutorial](https://docs.mintbase.xyz/wallet/integrating-mintbase-wallet) to get started. - -- [MyNearWallet](https://mynearwallet.com/): A browser based wallet that offers the same UI and features of `wallet.near.org`. - -- [NEAR Mobile](https://nearmobile.app/): A non-custodial wallet that is easy to use and well designed to manage your crypto wherever you go. - -- [Nightly Wallet](https://wallet.nightly.app/download): A mobile and extension wallet, with support for multiple ecosystems. - -- [Sender Wallet](https://sender.org/): Security-audited mobile & extension wallet with 1M+ users, supporting NEAR & Aurora. - -- [WELLDONE Wallet](https://welldonestudio.io/): A multi-chain extension wallet that gives you control over all your assets from a single platform. diff --git a/docs/4.tools/welcome.md b/docs/4.tools/welcome.md index 5596ee042b2..2b9e5061a50 100644 --- a/docs/4.tools/welcome.md +++ b/docs/4.tools/welcome.md @@ -2,12 +2,28 @@ id: welcome title: Tools sidebar_label: Home +hide_table_of_contents: true --- -Welcome! The NEAR ecosystem has a complete set of tools for you to make the most out of the NEAR network. -In this page you will find: +import {FeatureList, Column, Feature} from "@site/src/components/featurelist" -1. [Wallets](https://www.mynearwallet.com/) to handle your assets. -2. [Explorers](explorer.md) to quickly obtain information from the blockchain. -3. Websites to simplify creating and participating on governance projects. -4. Developer tools to deploy and interact with contracts such as the [NEAR CLI](cli.md) and [NEAR API](./near-api.md). +The NEAR ecosystem has a complete set of tools for you to make the most out of our network. + + + + + + + + + + + + + + + + + + + diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index ab12ac3d125..ae136b34481 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -90,14 +90,14 @@ const config = { ], themeConfig: { image: 'docs/assets/welcome-pages/protocol.png', - announcementBar: { - id: 'id-0010', - content: - '🎉 Ethereum Wallets are here! Read more in our blogpost and check our tutorial to update your app 🎉', - backgroundColor: '#fcfbfa', - textColor: '#333', - isCloseable: true, - }, + // announcementBar: { + // id: 'id-0010', + // content: + // '🎉 Ethereum Wallets are here! Read more in our blogpost and check our tutorial to update your app 🎉', + // backgroundColor: '#fcfbfa', + // textColor: '#333', + // isCloseable: true, + // }, prism: { additionalLanguages: [ 'rust', @@ -152,19 +152,14 @@ const config = { { label: 'NEAR API', to: '/tools/near-api' }, { label: 'NEAR SDK', to: '/tools/sdk' }, { label: 'NEAR CLI', to: '/tools/near-cli' }, - { - type: 'html', - value: '
Wallet Integration ', - }, { label: 'Wallet Selector', to: '/tools/wallet-selector' }, { type: 'html', - value: '
IDEs ', - }, - { - label: 'Remix IDE Plugin', - href: 'https://docs.welldonestudio.io/code/getting-started', + value: '
Data Services ', }, + { label: 'Explorers', to: '/tools/explorer' }, + { label: 'Data APIs', to: '/tools/ecosystem-apis/fastnear' }, + { label: 'Indexers', to: '/tools/indexing' }, ], }, { diff --git a/website/package.json b/website/package.json index d7ec1e31ddd..14a298750e8 100644 --- a/website/package.json +++ b/website/package.json @@ -43,6 +43,7 @@ "docusaurus-plugin-sass": "^0.2.5", "gleap": "^13.7.3", "https-browserify": "^1.0.0", + "lodash": "^4.17.21", "monaco-editor": "^0.44.0", "near-api-js": "^2.1.4", "near-social-vm": "github:NearSocial/VM#2.5.5", @@ -54,7 +55,6 @@ "react-is": "^18.2.0", "react-monaco-editor": "^0.54.0", "sass": "^1.69.5", - "url": "^0.11.3", - "lodash": "^4.17.21" + "url": "^0.11.3" } } diff --git a/website/sidebars.js b/website/sidebars.js index 715815de63a..37a672d29da 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -1,17 +1,4 @@ const sidebar = { - "concepts": [ - { - "type": "html", - "value": " From Web 2 to Web 3 " - }, - [ - "concepts/web3/intro", - "concepts/web3/basics", - "concepts/web3/near", - "concepts/web3/economics", - "concepts/web3/nfts" - ] - ], "build": [ "build/welcome", { @@ -196,6 +183,7 @@ const sidebar = { { "Frontends": [ "build/web3-apps/integrate-contracts", + "build/web3-apps/ethereum-wallets" ] }, { @@ -276,7 +264,7 @@ const sidebar = { "build/data-infrastructure/big-query", { "Lake Framework": [ - "concepts/advanced/near-lake-framework", + "build/data-infrastructure/lake-framework/near-lake-framework", "build/data-infrastructure/lake-framework/near-lake", "build/data-infrastructure/lake-framework/near-lake-state-changes-indexer", "build/data-infrastructure/lake-framework/migrating-to-near-lake-framework", @@ -503,15 +491,26 @@ const sidebar = { "tools/near-api", "tools/sdk", "tools/near-cli", + "tools/wallet-selector", + { + "type": "html", + "value": "
" + }, + { + "type": "html", + "value": " Data Tools " + }, + "tools/explorer", { "type": "category", - "label": "Wallets", + "label": "Data APIs", "items": [ - "tools/wallets", - "tools/wallet-selector", - "tools/ethereum-wallets", + 'tools/ecosystem-apis/fastnear', + 'tools/ecosystem-apis/nearblocks', + 'tools/ecosystem-apis/pikespeak', ] }, + "tools/indexing", { "type": "html", "value": "
" @@ -521,31 +520,30 @@ const sidebar = { "value": " Ecosystem Tools " }, { - "type": "category", - "label": "Data APIs", - "items": [ - 'tools/ecosystem-apis/fastnear-api', - 'tools/ecosystem-apis/nearblocks-api', - 'tools/ecosystem-apis/pikespeak-api', - ] + "type": "link", + "label": "Testnet Faucet", + "href": "https://near-faucet.io/" }, { "type": "link", - "label": "Remix IDE Plugin", - "href": "https://docs.welldonestudio.io/code/getting-started" + "label": "Developer Portal", + "href": "https://dev.near.org/" }, { "type": "link", - "label": "Testnet Faucet", - "href": "https://near-faucet.io/" + "label": "NEAR Catalog", + "href": "https://app.nearcatalog.xyz/" }, { "type": "link", "label": "Keypom", "href": "https://keypom.xyz/" }, - "tools/explorer", - "tools/indexing" + { + "type": "link", + "label": "Remix IDE Plugin", + "href": "https://docs.welldonestudio.io/code/getting-started" + }, ], "api": [ "api/rpc/introduction",