diff --git a/assets/blog/2024-review/2024-blog-2.jpg b/assets/blog/2024-review/2024-blog-2.jpg new file mode 100644 index 00000000000..9e6e98359d1 Binary files /dev/null and b/assets/blog/2024-review/2024-blog-2.jpg differ diff --git a/assets/blog/2024-review/2024-blog-3.jpg b/assets/blog/2024-review/2024-blog-3.jpg new file mode 100644 index 00000000000..6010c27afa1 Binary files /dev/null and b/assets/blog/2024-review/2024-blog-3.jpg differ diff --git a/assets/blog/2024-review/2024-blog-4.jpg b/assets/blog/2024-review/2024-blog-4.jpg new file mode 100644 index 00000000000..c6be3a6d749 Binary files /dev/null and b/assets/blog/2024-review/2024-blog-4.jpg differ diff --git a/assets/blog/2024-review/2024-blog-5.jpg b/assets/blog/2024-review/2024-blog-5.jpg new file mode 100644 index 00000000000..960a5f3b932 Binary files /dev/null and b/assets/blog/2024-review/2024-blog-5.jpg differ diff --git a/assets/blog/2024-review/2024-blog-6.jpg b/assets/blog/2024-review/2024-blog-6.jpg new file mode 100644 index 00000000000..b214ac4f92e Binary files /dev/null and b/assets/blog/2024-review/2024-blog-6.jpg differ diff --git a/assets/blog/2024-review/2024-blog.jpg b/assets/blog/2024-review/2024-blog.jpg new file mode 100644 index 00000000000..01560e8818e Binary files /dev/null and b/assets/blog/2024-review/2024-blog.jpg differ diff --git a/assets/blog/contract-wait-loop.png b/assets/blog/contract-wait-loop.png new file mode 100644 index 00000000000..fb3fcdb8461 Binary files /dev/null and b/assets/blog/contract-wait-loop.png differ diff --git a/assets/blog/contract-wait-yield.png b/assets/blog/contract-wait-yield.png new file mode 100644 index 00000000000..b8692a18f9f Binary files /dev/null and b/assets/blog/contract-wait-yield.png differ diff --git a/assets/blog/legendary.jpg b/assets/blog/legendary.jpg new file mode 100644 index 00000000000..2a59bb4be4b Binary files /dev/null and b/assets/blog/legendary.jpg differ diff --git a/assets/blog/native-cross-chain.png b/assets/blog/native-cross-chain.png new file mode 100644 index 00000000000..fd6bd884958 Binary files /dev/null and b/assets/blog/native-cross-chain.png differ diff --git a/assets/blog/web3wallets/cover.png b/assets/blog/web3wallets/cover.png new file mode 100644 index 00000000000..8917ab8a140 Binary files /dev/null and b/assets/blog/web3wallets/cover.png differ diff --git a/assets/blog/web3wallets/diagram.png b/assets/blog/web3wallets/diagram.png new file mode 100644 index 00000000000..2e3c0c85f81 Binary files /dev/null and b/assets/blog/web3wallets/diagram.png differ diff --git a/assets/blog/web3wallets/function-call.png b/assets/blog/web3wallets/function-call.png new file mode 100644 index 00000000000..709a7175ac8 Binary files /dev/null and b/assets/blog/web3wallets/function-call.png differ diff --git a/assets/blog/web3wallets/login.png b/assets/blog/web3wallets/login.png new file mode 100644 index 00000000000..6df4e9ecce2 Binary files /dev/null and b/assets/blog/web3wallets/login.png differ diff --git a/assets/blog/windows-features-wsl-enabled.jpg b/assets/blog/windows-features-wsl-enabled.jpg new file mode 100644 index 00000000000..3f7e0452008 Binary files /dev/null and b/assets/blog/windows-features-wsl-enabled.jpg differ diff --git a/assets/docs/welcome-pages/contracts-landing.png b/assets/docs/welcome-pages/contracts-landing.png new file mode 100644 index 00000000000..8f145ad2285 Binary files /dev/null and b/assets/docs/welcome-pages/contracts-landing.png differ diff --git a/blog/2024-04-23-we-have-a-blog.mdx b/blog/2024-04-23-we-have-a-blog.mdx new file mode 100644 index 00000000000..9f18417ef87 --- /dev/null +++ b/blog/2024-04-23-we-have-a-blog.mdx @@ -0,0 +1,41 @@ +--- +title: "We have a blog now!" +description: "Check check check. Is this thing on? Hello, world!" +date: 2024-04-23 +author: "Guille" +tags: [updates] +--- + +{/* BYLINE:start */} +_**Guille** · April 23, 2024_ +{/* BYLINE:end */} + +*Check check check. Is this thing on? Hello, world!* + +

+ +## Hello there! +Welcome to the new NEAR documentation blog! We're excited to inaugurate this new space where we can share news and updates. We know what you are thinking — why a blog? Well, it allows us to interact with you in a different way! + +When writing documentation, it is important for us to keep the content focused and concise. This way, when you read it, you have nothing to distract you, and you can focus on learning a new concept. + +The problem with this is that many times, we want to share ideas, thoughts, or insights into why some things are the way they are. However, this would imply going off on a tangent and explaining why some decisions were made, which will probably add noise to the document. Most of the time, users just want a link to an example or working code. Also, people don't like to read long texts. + +Besides that, sometimes we just want to share what we did during the week. For example, did you notice that we fixed the nightmare that was the URL structure, or that we added new landing pages for all concepts? We want to share these things with you, but they don't really belong in the Docs. + + +You would not believe the number of times we said during a review _"let's remove that, we are writing technical documentation, not a blog post"_ ... well, now we can make the blog post! + +## What to expect + +We will be using this space to share updates about our docs, as well as **complement them** with additional information that we think you'll find interesting. + +Our aim is to keep the blog updated at least once a week, but given the limited amount of time we have, we will see how that goes. + +Moreover, we want to remind you that our Docs are an open source and **collaborative project**. If you feel like you have something to share, or want to contribute to the blog, feel free to reach out. And by reaching out, we mean [opening a PR](https://github.com/near/docs/pulls)! + +## A new era for NEAR docs + +We are super excited to start this new section and hope it helps us to connect with all of you in a better way. We are looking forward to hearing your thoughts and feedback, and hope you enjoy the content we'll be sharing. + +See you in the next post! 🚀 diff --git a/blog/2024-04-24-reorganizing-docs.mdx b/blog/2024-04-24-reorganizing-docs.mdx new file mode 100644 index 00000000000..bde1ad81511 --- /dev/null +++ b/blog/2024-04-24-reorganizing-docs.mdx @@ -0,0 +1,57 @@ +--- +title: "Reorganizing our docs" +description: "We released a mayor reorganization of our repository, so we can improve docs for everyone... including us" +date: 2024-04-24 +author: "Guille" +tags: [docusaurus, updates] +--- + +{/* BYLINE:start */} +_**Guille** · April 24, 2024_ +{/* BYLINE:end */} + +*We released a mayor reorganization of our repository, so we can improve docs for everyone... including us* + +

+ +## Organic growth +Our documentation is the result of multiple people collaborating across the span of four very active years, and it has seen a lot of changes: [2942 commits and counting](https://github.com/near/docs/commits/master/). + +In the beginning, our docs only needed to explain how to create [smart contracts](/smart-contracts/what-is), and how to [interact with them through a frontend](/web3-apps/quickstart). Fast forward to today, and we have more than 200 pages of documentation, covering topics such as [chain abstraction](/chain-abstraction/what-is), [data infrastructure](/data-infrastructure/what-is), and [primitives such as NFT, FT](/primitives/what-is). + +The best thing is that new features are released every single month. However, all progress comes at a cost, and as our ecosystem grew, so did the disorganization of our documentation. + +## What link was that again? +Let's briefly explain how [docusaurus](https://docusaurus.io/) (the framework we use in our docs) works so you can understand the problem. + +In docusaurus, all the pages are written as simple markdown files. These files go inside the `./docs` folder, and can be organized in folders. Each file has a unique ID on its header that identifies it (e.g. `id: what-is`), and this ID, alongside its folder path, is used to generate the URL. + +> For example, the document [`docs/smart-contracts/what-is.md`](https://github.com/near/docs/blob/master/docs/2.build/2.smart-contracts/what-is.md) has the `id: what-is`, so it ends being served in the URL /smart-contracts/what-is. + +### The problem + +About a year ago, we noticed that our organic growth had left us with a very inconsistent URL structure. Basically, we had a lot of folders, and the files related to the same topic (e.g. NEAR components) would be all over the place. + +For example, you would be in the "Build" section reading about "What is a NEAR Component?" and the URL was `/bos/tutorial/quickstart`. The next page was "Setup an Environment" located at `/bos/dev/intro`, followed by "Anatomy of a Component -> State" at `/bos/api/state`. Talk about consistency! + +Of course, we did not do this on purpose, it is just how things evolved. You might even notice that we are now talking about "NEAR Components" but the URL talks about "BOS". This is because when we started, "BOS" (Blockchain Operating System) felt like a good name, but community feedback made us know that, indeed, it was not. + +### The migration + +We [re-organized more than 200 files](https://github.com/near/docs/pull/1890/files) to a new structure that is more consistent. This makes it easier for users to remember the URLs, improves our SEO, and makes it easier for contributors to find where to add new content. No more need to search across multiple folders trying to find the right file! + +In the process, we updated all **internal links**, aided by our [link-checker script](https://github.com/near/docs/blob/master/website/test-links.sh) to make sure we left **no broken links**. We also added **URL redirects** in our server, so all users coming from an external site are redirected to the correct URLs. + +Besides checking broken links, we took the time to make sure all the **translations were correctly migrated**. The system Docusaurus uses (called [Crowdin](https://crowdin.com/)) is not very good at detecting changes in a file, so migrating all the translations was a huge effort in itself. + +We could write a blog post just about migrating translations in docusaurus + crowdin... but we will spare you the pain. + + +If you come across a URL that is not working, please let us know by using the `Feedback` button on the right side of the page, or by opening an [issue in our repository](https://github.com/near/docs/issues) + +## What's next +Now that most of our documentation is in a better shape, we can focus on improving the content itself. We have a lot of ideas on how to make the docs more interactive, and we are excited to start working on them. + +Stay tuned for more updates, and remember that if you have any feedback or ideas, you can always reach out to us. We are always happy to hear from you! + +See you in the next post! 🚀 diff --git a/blog/2024-05-15-chain-signatures-use-cases.mdx b/blog/2024-05-15-chain-signatures-use-cases.mdx new file mode 100644 index 00000000000..3739e8de8e8 --- /dev/null +++ b/blog/2024-05-15-chain-signatures-use-cases.mdx @@ -0,0 +1,129 @@ +--- +title: "Use cases for Chain Signatures" +description: "Chain signatures enable you to implement multichain and cross-chain workflows in a simple way. Let's take a look at a few possible use cases" +date: 2024-05-15 +author: "Damian" +tags: [docusaurus, updates] +--- + +{/* BYLINE:start */} +_**Damian** · May 15, 2024_ +{/* BYLINE:end */} + +*Chain signatures enable you to implement multichain and cross-chain workflows in a simple way. Let's take a look at a few possible use cases* + +## Trade Blockchain assets without transactions + +Trading assets across different blockchains usually requires using a bridge that supports them, bringing longer settlement times as the trades are not atomic and require confirmation on both blockchains. + +Using Chain signatures, you can trade assets across chains simply swapping the ownership of NEAR accounts that control funds on different blockchains. For example, you could trade a NEAR account that controls a Bitcoin account with `X BTC` for another NEAR account that controls an Ethereum account with `Y ETH`. + +This way, you can keep native tokens on their native blockchain (e.g., `BTC` on Bitcoin, `ETH` on Ethereum, `ARB` on Arbitrum) and trade them without bridges. +As an added bonus, trades are atomic across chains, settlement takes just 2 seconds, and supports any token on any chain. + + + + There are transactions happening on different blockchains. + The difference is that a [Multi-Party Computation service](/chain-abstraction/chain-signatures#multi-party-computation-service) (MPC) signs a transaction for you, and that transaction is then broadcast to another blockchain RPC node or API. + +For example, a basic trade flow could be: + +1. Users create an account controlled by NEAR chain signatures +2. Users funds these accounts on the native blockchains (depositing) +3. Place orders by funding a new account for the total amount of the order +4. Another user accepts the order +5. Users swap control of the keys to fulfill the order + +![docs](/assets/blog/native-cross-chain.png) + +
+- User A has `ETH` on the Ethereum blockchain, and wants to buy native Bitcoin +- User B wants to sell Bitcoin for Ethereum + +**Steps** + +1. User B, using NEAR, creates and funds a new account on Bitcoin with 1 `BTC` +2. User B, using the spot marketplace smart contract, signs a transaction to create a limit order. This transfers control of the Bitcoin account to the smart contract +3. User A creates a batch transaction with two steps + - Creating and funding a new Ethereum account with 10 `ETH` + - Accepting the order and atomically swapping control of the accounts +4. User A takes ownership of the Bitcoin account with 1 `BTC`, and User B takes ownership of the Ethereum account with 10 `ETH` +5. User A and B can _"withdraw"_ their asset from the order by transferring the assets to their respective _"main"_ accounts +
+ +--- + +## Oauth-controlled Blockchain accounts + +On-boarding is a huge problem for decentralized applications. If you want widespread adoption you can't expect people to keep seed phrases safe in order to use an application. + +An attractive way of managing Web3 accounts is to use existing Web2 accounts to on-board users. This can be done in the following way: + +1. Deploy a NEAR contract that allows the bearer of a user's [JWT token](https://jwt.io/) to sign a blockchain transaction (Ethereum, Polygon, Avalanche, and others) +2. The user validates their identity with a third-party receiving a JWT Token +3. The user holding that token can interact with blockchain applications on Ethereum/Polygon/+++ via the NEAR contract for the duration of its validity + +Any method of controlling a NEAR account can also be used to control a cross-chain account. + + +JSON Web Tokens are a standard RFC 7519 method for representing claims securely between two parties. They are used in this example to represent the claim that someone is the owner of an Oauth account. + +--- + +## Cross-chain Zero-friction onboarding + +Using unique features of the NEAR account model, [Keypom](https://docs.keypom.xyz/) provides zero-friction onboarding and transactions on NEAR. They are generally used for NFT drops, FT drops, and ticketing. + +A generic Keypom user-flow could be: + +1. The developer creates a restricted NEAR account +2. The account is funded with `NEAR` +3. The user receives a key with limited control of the account +4. The user uses the funded account to call controlled endpoints on NEAR +5. The user returns the remaining funds to the developer and their account is unlocked + + +This allows easy onboarding to decentralized apps. The accounts are initially restricted to prevent the user being able to simply withdraw the `NEAR` from the account. + +## DeFi on Bitcoin (and other non-smart contract chains). + +Using chain signatures, smart contracts on NEAR can control externally-owned accounts on non-smart contract chains like Bitcoin, Dogecoin, XRP Ledger, Bittensor, Cosmos Hub, etc. This enables developers to use NEAR as a smart contract “layer” for chains that do not support this functionality natively. + +For example, a developer can build a decentralized exchange for Bitcoin Ordinals, using a smart contract on NEAR to manage deposits (into Bitcoin addresses controlled by the contract) and to verify and execute swaps when two users agree to trade BTC for an Ordinal or BRC20 token. + +Example: +1. Seller generates a deposit address on Bitcoin that is controlled by the marketplace smart contract on NEAR via chain signatures +2. Seller deposits a Bitcoin Ordinal to the deposit address +3. The Ordinal is listed for sale with a price and a pre-commitment signature from the seller +4. Buyer accepts the order, deposits USDC +5. The control of the Bitcoin Ordinal address is given to the buyer, USDC on NEAR is transferred to the seller + +#### Using Chain Signatures + +With Chain Signatures you can do the same but across many chains, for example Polygon: + +1. The developer creates a restricted NEAR account with a key +2. The account is funded with `NEAR` and `MATIC` +3. The user receives a key with limited control of the account +4. The user uses the funded account to sign payloads calling controlled endpoints on Polygon +5. The user returns the remaining funds to the developer and their account is unlocked + +This allows developers to pay for users to use arbitrary contracts on arbitrary chains. + +--- + +## Decentralized Clients + +A big problem in decentralized applications is that while the smart contracts are tamper-proof, the clients that access them generally are not. This allows practically complete control over any user account provided they are using the frontend assets that you serve. This has security, trust, and regulatory implications. + +When smart contracts can sign payloads you can start using [signed exchanges](https://wicg.github.io/webpackage/draft-yasskin-http-origin-signed-responses.html#name-introduction) (or polyfills) to require HTTP exchanges to be signed by a certain key. If it is not signed with this key the SSL certificate is considered invalid. This means that individual users cannot be served invalid frontends without it being generally observable and non repudiable. + +--- + +## Communication with private NEAR Shards + +Companies like [Calimero](https://www.calimero.network/) offer private NEAR shards. Currently, sending messages to and from these NEAR shards is troublesome. If each shard had the ability to sign their message queues, they could be securely sent from one shard to another. Thus you could communicate bidirectionally with any shard as easily as you can with a contract on your own shard. + + +This could also simplify NEAR's sharding model, by treating each NEAR shard like one would a private shard. + diff --git a/blog/2024-05-30-yield-resume.mdx b/blog/2024-05-30-yield-resume.mdx new file mode 100644 index 00000000000..68e25ccd86b --- /dev/null +++ b/blog/2024-05-30-yield-resume.mdx @@ -0,0 +1,130 @@ +--- +title: "It's gonna be Legen... wait for it..." +description: "dary! Legendary! NEAR protocol is getting updated with the ability to yield and resume computations" +date: 2024-05-30 +author: "Guille" +tags: [protocol, updates] +--- + +{/* BYLINE:start */} +_**Guille** · May 30, 2024_ +{/* BYLINE:end */} + +*dary! Legendary! NEAR protocol is getting updated with the ability to yield and resume computations* + +![waiting on a loop](/assets/blog/legendary.jpg) + + + +We now have an [example of how to use `yield` and `resume`](https://github.com/near-examples/yield-resume) in your contracts. Check it out! + +There is also a new documentation page on [Yield and Resume](/smart-contracts/anatomy/yield-resume) that explains how to use this feature + +## The problem of waiting +Currently, smart contracts have no way to wait for an external event to happen. This can be a problem when the contract relies on an external service to provide a result. + +We encountered this issue while implementing [Chain Signatures](/chain-abstraction/chain-signatures), which work by requiring an external service to provide a signature. + +Until now, the only workaround has been to make the contract call itself in a loop, checking on each iteration if the result is ready. Each call delays the result by one block (~1 second), allowing the contract to wait almost a minute before running out of gas. + +![waiting on a loop](/assets/blog/contract-wait-loop.png) +*Until now, contracts had to wait by calling themselves until a external service replies... more often than not the contract will run out of gas waiting* + +While this method works, it's far from ideal. It wastes a lot of gas on looping and - more often than not - runs out of gas, forcing the user to retry the transaction. + +## Yield and Resume +Starting from version `1.40` of the protocol, developers can **delay the execution** of a function until certain conditions are met (e.g. an external service provides a result). + +This way, instead of the contract calling itself on a loop waiting, the contract can simply **yield** calling the function that gives the result. When an external response is provided, the contract will **resume** and return the result. + +![waiting on a yield](/assets/blog/contract-wait-yield.png) +*Contracts can now yield the execution of a function until an external service signals that the result is ready* + +### What is exactly being yielded? +It is important to notice that the contract is not **halting** or **blocking** its ability to execute, nor **halting in the middle of a function** to later resume it. + +In the same way that a function can return a promise to call another contract, now a function can return a **yield** to call another function. + +Indeed, the contract is not halting, but simply **delaying the execution of a callback** until an external agent signals that it is ok to resume. + +If the contract does not trigger a resume after 200 blocks - around 4 minutes - the yielded function will resume receiving a "timeout error" as input. + + +People can keep calling functions on the contract between a `yield`/`resume`, and the function that creates the `yield` can be called multiple times. + +The state **can change** between the `yield` and the `resume`, since people can keep interacting with the contract. + +Moreover, since the function used to signal is public, developers must make sure to guard it properly to avoid unwanted calls. This can be done by simply checking the caller of the function. + +### How does it change for the user? +Between the `yield` and `resume` the user will simply be waiting to receive the result. But, in contrast with waiting on a loop, the user will not pay GAS just for having the contract waiting! + +## How I can use yield/resume in my contract? +While we have not created any official `yield/resume` example, you can refer to [Saketh Are's example](https://github.com/near/near-sdk-rs/pull/1133/files), who has been working on the `yield/resume` implementation. + +The basic idea is that the SDK now exposes two functions: +- A `yield(function_to_yield)` that returns a `yield_ID` which identifies the yield +- A `resume(yield_ID)` that signals which instance of `function_to_yield` can now execute + +#### Simplified Example + +```rust +// const DATA_ID_REGISTER: u64 = 0; + +pub fn request_weather(&mut self, city: String) { + let index = self.next_available_request_index; + self.next_available_request_index += 1; + + let yield_promise = env::promise_yield_create( + "callback_return_result", + &serde_json::to_vec(&(index,)).unwrap(), + SIGN_ON_FINISH_CALL_GAS, + GasWeight(0), + DATA_ID_REGISTER, + ); + + // Store the request, so an external service can easily fetch it + // This is optional, as an indexer could simply observe it in the receipts + let data_id: CryptoHash = + env::read_register(DATA_ID_REGISTER).expect("").try_into().expect(""); + self.requests.insert(&index, WeatherRequest{&data_id, &city}); + + // The return will be the result of "callback_return_result" (defined below) + env::promise_return(yield_promise); +} + +/// Called by external participants to submit a response +pub fn respond(&mut self, data_id: String, weather: String) { + let mut data_id_buf = [0u8; 32]; + hex::decode_to_slice(data_id, &mut data_id_buf).expect(""); + let data_id = data_id_buf; + + // check that caller is allowed to respond, weather is valid, etc. + // ... + + log!("submitting response {} for data id {:?}", &weather, &data_id); + env::promise_yield_resume(&data_id, &serde_json::to_vec(&weather).unwrap()); +} + +/// Callback receiving the external data (or a PromiseError in case of timeout) +pub fn callback_return_result( + &mut self, + request_index: u64, + #[callback_result] weather: Result, +) -> String { + // Clean up the local state + self.requests.remove(&request_index); + + match weather { + Ok(weather) => "weather received: ".to_owned() + &weather, + Err(_) => "request timed out".to_string(), + } +} +``` + +## Conclusion +The ability to `yield` and `resume` computations is a big step forward for the NEAR protocol, as it enables developers to create contracts that rely on external services. + +Currently, the feature is only **available on testnet**, and we are looking for feedback on how to improve it. + +We expect to have a more user-friendly way to use `yield` and `resume` in the future, so stay tuned! diff --git a/blog/2024-06-05-getting-started-on-windows.mdx b/blog/2024-06-05-getting-started-on-windows.mdx new file mode 100644 index 00000000000..8ee873ee1de --- /dev/null +++ b/blog/2024-06-05-getting-started-on-windows.mdx @@ -0,0 +1,99 @@ +--- +title: "Getting Started on NEAR Using Windows" +description: "In this article, we will cover how to install WSL and setup a NEAR development environment on Windows." +date: 2024-06-05 +author: "Lyudmil" +tags: [windows, tutorial, getting-started] +--- + +{/* BYLINE:start */} +_**Lyudmil** · June 5, 2024_ +{/* BYLINE:end */} + +In this article, we will cover how to install WSL and setup a NEAR development environment on Windows. + +### WSL + +WSL, or Windows Subsystem for Linux, is a compatibility layer for running Linux binary executables natively on Windows. It allows us to run a GNU/Linux environment directly on Windows without the overhead of a traditional virtual machine or dual-boot setup. + +#### Enable WSL from `Windows Features` +First of all, make sure that WSL is enabled, for this go to: +`Control Panel > Programs > Turn Windows Features on or off` +Scrolling down will reveal the option `Windows Subsystem for Linux`. Make sure it is enabled and press OK to confirm (you will be asked to reboot your computer). + +![Windows Features WSL Enabled](/assets/blog/windows-features-wsl-enabled.jpg) + +#### Start WSL and Install Ubuntu + +Now we will spend some time in either `PowerShell` or [Windows Terminal](https://apps.microsoft.com/detail/9n0dx20hk701), which is a modern terminal application that supports various command-line tools and shells. + +```bash +# may be desirable for seamless integration between WSL2 distros of linux and docker with WSL backend +wsl --set-default-version 2 +``` + +``` +wsl --install -d Ubuntu +``` + +**Read more on WSL:** +https://learn.microsoft.com/en-us/windows/wsl/install +https://learn.microsoft.com/en-us/windows/wsl/setup/environment +https://learn.microsoft.com/en-us/windows/wsl/ + +### Install Required Packages +Once the installation is completed you will have Ubuntu installed as any other application on Windows. Open it from the start menu and you will be dropped into the [Ubuntu bash shell](https://ubuntu.com/tutorials/command-line-for-beginners#1-overview) + +Enter the following commands to install all the packages that Rust and Node might need later: + +```bash +apt-get update +apt-get install gcc make libudev-dev openssl pkg-config unzip -y +``` + + +Depending on your setup, you might need to run the commands with `sudo`. This temporarily grants your user elevated privileges to perform tasks that require higher permissions. + +### Setup Developer Environment + +Now that we have WSL enabled and running Ubuntu, it is time to setup our developer environment. At NEAR we currently support using JS/TS and Rust to develop smart contracts, and JS/TS to develop web applications. + +Below we will explain how to install both `Node.js` and `Rust`. If you want, you can install only one of them (e.g. if you are only planning to create a Rust contract, you don't need Node.js). However, we do recommend to install both so your environment is ready if you want to try something different later. + +#### Node (JS/TS) + +Node.js is a JavaScript runtime environment that executes code outside a web browser, enabling the development of server-side applications. In NEAR development, it can be used to write smart contracts in [TypeScript](https://www.typescriptlang.org/), as well as to create Web applications that interact with NEAR. + +``` +# installs nvm (Node Version Manager) +curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash +# download and install Node.js +nvm install 20 +# verifies the right Node.js version is in the environment +node -v # should print `v20.14.0` +# verifies the right NPM version is in the environment +npm -v # should print `10.7.0` +``` + +**Read more:** +[NodeJS Website](https://nodejs.org/) + +#### Rust + +[Rust](https://www.rust-lang.org/) is a programming language known for its safety and performance. It's used in NEAR development to write secure and efficient smart contracts. + +Next, we need to add the `wasm32-unknown-unknown` toolchain. This toolchain is required because the contracts we build will be compiled to [WASM](https://webassembly.org/) to run on the NEAR blockchain. + +```bash +curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh +# When prompted, press enter for default install options +. source $HOME/.cargo/env +rustup target add wasm32-unknown-unknown +``` + +**Read more:** +[Getting Started with Rust](https://www.rust-lang.org/learn/get-started) + +### That's It + +At this point, we are ready to install the relevant tooling and start building on NEAR. Head over to the [Quickstart](http://docs.near.org/smart-contracts/quickstart) section of the docs for more information or jump right into the [examples](https://github.com/near-examples). diff --git a/blog/2024-06-28-sdks-unified.mdx b/blog/2024-06-28-sdks-unified.mdx new file mode 100644 index 00000000000..d7ab94e15f8 --- /dev/null +++ b/blog/2024-06-28-sdks-unified.mdx @@ -0,0 +1,59 @@ +--- +title: "One place for all Smart Contracts Docs" +description: "We have consolidated all our documentation in a single section, so you don't need to go searching around for it" +date: 2024-06-28 +author: "Guille" +tags: [updates] +--- + +{/* BYLINE:start */} +_**Guille** · June 28, 2024_ +{/* BYLINE:end */} + +*We have consolidated all our documentation in a single section, so you don't need to go searching around for it* + +

+ +Smart contracts are small pieces of logic that can live on every NEAR account. To build a contract you use the NEAR SDKs, which comes in two flavours: Rust and JavaScript. + +Until today, we had multiple docs explaining how to build smart contracts: +- `/sdk/rust` dedicated to explain how to use the Rust SDK +- `/sdk/js` dedicated to explain how to use the JS SDK +- [`/smart-contracts/what-is`](/smart-contracts/what-is) - that explains general concepts, and how to implement them using both SDKs + +Today, this is over, as all the information on how to build smart contracts is located in a single area: [`/smart-contracts/what-is`](/smart-contracts/what-is). + +Meanwhile, we have transformed the [SDK page](/tools/sdk) to be a simple landing page with links to: +- The [Rust SDK reference docs](https://docs.rs/near-sdk/latest/near_sdk/) +- The [JS SDK reference docs](https://near.github.io/near-api-js/) +- The [Smart Contract Section](/smart-contracts/what-is) + +## Why did we have 3 sections explaining the same topic? + +The reason we had 3 different sections was that, historically, the engineers of each SDK were working on their own docs in isolation. To help mitigate this, we created a section on NEAR docs, meant to consolidate all the external documentation. + +One day, the individual SDK pages were deleted - if I remember correctly, it was because we wanted to have fewer domains - and we had to migrate everything in a rush. + +This left us in a very weird situation: we already had a section explaining how to build a smart contract... and now we had 3. + +## A single source of truth + +Luckily, this is now fixed! We have finally conquered the original dream of having a single section for [Smart Contracts](/smart-contracts/what-is), with all the information consolidated in there. + +Now, we can focus on maintaining a single section, thus making it easier to keep it updated and relevant. + +## What's next? + +We are currently undergoing a process of **consolidating** all the documentation. This means that we are looking at all the sections that have overlapping information, and trying to merge them into a single place. + +This will not only improve the quality of our docs, but also make it easier for you to find the information you need. In fact, improving search is one of the main motors of this change, since we noticed that our search tool ([Algolia](https://www.algolia.com/)) gets confused when the same concept is spread all over the place. + +Moreover, having consistent and coherent documentation will allow us to further expand our search capabilities using AI! This is something we are very excited about, as it will allow us to provide you with even more relevant information. + +## If you don't like this change, please let us know! + +As always, we are more than open to feedback. If you think that this change is not good, or that we are missing something, please let us know! You can reach out to us through the blue feedback button you see at the side of the screen. + +We are looking forward to hearing your thoughts and feedback, and hope you enjoy the content we'll be sharing. + +Happy coding, and see you in the next post! 🚀 diff --git a/blog/2024-07-01-bos-web-engine-sunset.mdx b/blog/2024-07-01-bos-web-engine-sunset.mdx new file mode 100644 index 00000000000..e5cd5bf5bba --- /dev/null +++ b/blog/2024-07-01-bos-web-engine-sunset.mdx @@ -0,0 +1,85 @@ +--- +title: "Pagoda Pauses the B.O.S. Web Engine R&D Project" +description: "After careful consideration, Pagoda has decided to discontinue its active efforts to improve the B.O.S. Web Engine" +date: 2024-07-01 +author: "Josh Ford" +tags: [updates, BWE, VM2, BOS] +--- + +{/* BYLINE:start */} +_**Josh Ford** · July 1, 2024_ +{/* BYLINE:end */} + + +**Historical post.** Kept for the record. The products, services, or links it describes may be deprecated or no longer available. + + +*After careful consideration, Pagoda has decided to discontinue its active efforts to improve the B.O.S. Web Engine* + +

+ +After many discussions with NEAR’s B.O.S. component developers and careful consideration, Pagoda has decided to discontinue its active development for [B.O.S. Web Engine R&D ](https://github.com/near/bos-web-engine)for an improved execution layer for NEAR B.O.S. Components. (also known as “BWE” & “VM2”) + +## Background + +Last year, [NEAR introduced the Blockchain Operating System](https://near.org/assets/blog/near-announces-the-blockchain-operating-system), demonstrating how NEAR’s performant tech stack could support a full-stack decentralized development platform that was multi-chain compatible. A core feature of this system consisted of composable decentralized front-ends (B.O.S. Components) paired with a user-centric data storage contract (social-db). This model, [pioneered by NEAR Social](https://thewiki.near.page/PastPresentAndFutureOfNearSocial), aimed to continue NEAR’s mission of empowering users to own their data as well as eliminate reliance on centralized, single-entity-controlled web applications. The potential of a fully decentralized web and the creation of real dApps became closer to reality with these inherently open and customizable experiences. + +As the community started to adopt B.O.S. it soon became clear that, while devs loved how fast it was to go from an idea to a product, its intrinsic technical limitations made it hard to use B.O.S. for any real-world application. This consistent feedback from multiple members of the community prompted Pagoda to start an R&D effort to improve B.O.S. such that: + +- It was as close to vanilla React as possible +- Supported npm package imports +- Unlocked multi-chain scalability limitations +- Improved performance +- Improved security + +## B.O.S. Web Engine + +In order to act on this feedback and accomplish these goals, improvements had to be made to the execution layer that makes this all possible. At its core, a virtual machine, ([NEAR Social VM](https://github.com/NearSocial/VM)) renders front-end code that developers store in a smart contract onchain (social-db). It was determined that a new approach to the original VM solution was needed, and the B.O.S. Web Engine project was created. Countless hours of hard work and dedication have gone into this project, yielding many significant achievements along the way. However, one major challenge still stands in the way of a production-ready beta release: expanding support for npm packages, particularly UI libraries. + +During the alpha testing phase of this project, we anticipated a fairly straightforward path in resolving wider npm support but unfortunately, the team discovered a more complex scenario. While standard JavaScript packages work well, React UI libraries frequently encounter difficulties. These challenges stem from the unique packaging methods of each library and the complexities involved in synchronizing changes between the iframe and the outer DOM. Although we have identified several theoretical solutions, each requires further research and development to assess their practicality and effectiveness. This has been more fully detailed in [a GitHub discussion within the BWE Repo](https://github.com/near/react-on-chain/discussions/425). + +We reached out to leading B.O.S. component contributors to determine whether this limitation would be unnegotiable and to learn what features they value most. Do they prioritize unrestricted NPM support over secure iframe composability? How important is composability, and how would they define it? (considering our approach dissects it down to the atomic level of every element) + +This revealed some interesting findings, one of which was that secure composability on an atomic level was not at the top of the list. Most favored the ease of quick prototyping, deployment, and onboarding with managed infra and wallet connections. Many valued social-db features and the ability to create custom gateways (websites) using code and user data publicly available to them. + +In short, there were three camps: + +### True Believers + +- Decentralize all the things! +- Love bleeding-edge unique tech +- Love inherent open-source +- Love social-db and its features + +### Quick Builders + +- Love the speed of development, prototyping, remixing +- Love reverse engineering existing components +- Quick onboarding with managed infra and wallet connections +- Great for hackathons + +### Detractors + +- Don't like anything about B.O.S. components +- DevX is poor and UI is slow +- Value convenience over decentralization + +After reviewing our findings and engaging extensively with developers using this platform, it became clear that continuing with the release of the B.O.S. web engine as currently planned could potentially have a net negative impact. The majority of developers indicated that they do not favor a version of the BWE with limited npm support, even if it means enhanced secure composability. Additionally, while a minority of builders prioritize decentralization over performance and convenience, those who truly value decentralized frontends might find simpler ways to achieve their objectives once the need for secure composability is eliminated. + +For those who may disagree with this perspective, the B.O.S. Web Engine remains, and will always be an open-source project. Anyone who sees value in the work we have done and wishes to advance this initiative is welcome to carry this torch and continue the development. https://github.com/near/bos-web-engine + +## What does this mean for B.O.S. components & the current VM? + +During the development of the B.O.S. Web Engine, a large focus was placed on addressing the security aspects of the existing VM and B.O.S. component architecture. The primary concern is with the composability and attack vectors that are exposed when importing components authored by third parties. Despite numerous patches to address discovered exploits, the inherent complexities of JavaScript and the current VM’s architecture suggest that such vulnerabilities may continue to persist. Pagoda has diligently monitored and addressed these issues to date but we anticipate challenges in continuing to proactively discover and mitigate future vulnerabilities. + +_For examples of previously discovered vulnerabilities, view the [VM changelog](https://github.com/NearSocial/VM/releases) going back to `v2.5.1`, paying attention to lines tagged as `FIX` on issues Reported by `BrunoModificato` from OtterSec._ + +If you find value in creating B.O.S. components and leveraging the features of the social-db smart contract, rest assured that this framework will remain open-source and permanently accessible on-chain. However, we urge caution when incorporating and using third-party components. Due to the current virtual machine's limitations, we cannot guarantee protection against potential future exploits. + +## Should I migrate my project off of B.O.S.? + +If your application relies on community-contributed or unreviewed third-party components, then **yes**. As described above, we cannot guarantee protection against future security vulnerabilities in the VM and B.O.S. component architecture. However, you can mitigate (but not eliminate) these security risks by reviewing all third-party components and either forking them or locking down dependencies to the specific version that you reviewed. + +If you are not relying on any untrusted component code, then **maybe**. You are not being forced to migrate and there are still teams actively building new applications leveraging B.O.S. Additionally, there are no plans to deprecate main B.O.S. gateways at [dev.near.org](https://dev.near.org), [near.social](https://near.social), [dapdap](https://dapdap.net) or [bos.gg](https://bos.gg). However, the underlying framework and virtual machine are no longer actively developed or maintained by the original team. Consequently, the pace at which new features are introduced and existing bugs or vulnerabilities are addressed may be slower than expected. We openly welcome new maintainers for [this codebase](https://github.com/nearsocial). However, as previously mentioned, we anticipate that additional security vulnerabilities may still be discovered. + +We have updated ["Frontends for Web3 dApps" in docs.near.org](/web3-apps/tutorials/wallet-login) to help you choose a solution that is right for you. If you need help, please reach out to one of our support channels on [Telegram](https://t.me/neardev) or [Discord](https://near.chat) and we will be happy to assist you or answer any questions you have. diff --git a/blog/2024-07-18-near-org-outage.mdx b/blog/2024-07-18-near-org-outage.mdx new file mode 100644 index 00000000000..2b0725d479b --- /dev/null +++ b/blog/2024-07-18-near-org-outage.mdx @@ -0,0 +1,57 @@ +--- +title: "An update on the near.org / RPC outage on July 11, 2024" +description: "From Thursday, July 11 to Saturday, July 13, many visitors to near.org and its subdomains (like dev.near.org and docs.near.org) were unable to reach…" +date: 2024-07-18 +author: "Eric Winer" +tags: [updates, postmortems] +--- + +{/* BYLINE:start */} +_**Eric Winer** · July 18, 2024_ +{/* BYLINE:end */} + + +**Historical post.** Kept for the record. The products, services, or links it describes may be deprecated or no longer available. + + +From Thursday, July 11 to Saturday, July 13, many visitors to [near.org](https://near.org) and its subdomains (like [dev.near.org](https://dev.near.org) and [docs.near.org](https://docs.near.org)) were unable to reach those websites. Also, NEAR applications that rely on [RPC services](/api/rpc/providers) hosted on near.org were affected. This was due to a security incident followed by an outage from one of our vendors, Squarespace. During this period, the NEAR protocol & blockchain was unaffected by this incident, as it does not rely on any centralized services. + +### Our Use of Squarespace DNS + +The near.org domain is operated by [Pagoda](https://www.pagoda.co/), an engineering arm of the NEAR Foundation. An important part of operating a domain like near.org is choosing a DNS provider; to learn more about DNS and how it operates, please see [this introduction](https://www.cloudflare.com/learning/dns/what-is-dns/). For years, we happily used Google’s domain name registration & DNS service to manage near.org, as part of our broad usage of Google Cloud services. In June 2023, Google announced it had [sold its Domains business to Squarespace](https://support.google.com/domains/answer/13689670?hl=en), and that our account would be transitioned to Squarespace “in the next few months.” We expected that the new service from Squarespace would closely match the feature set, reliability, and security we had enjoyed while using Google Domains, and if there were any problems then we could easily switch from Squarespace to another DNS provider after the transition. + +Our first domain, near.wiki, was automatically moved over to Squarespace in May 2024. As we explored the new offering, our Security & IT teams quickly had concerns about the feature set, security controls, and level of enterprise support we could get from Squarespace. After some meetings with Squarespace sales and support failed to assuage our concerns, we decided to explore other DNS providers and to start migrating our domains off of Squarespace, starting with the ‘simpler’ ones and ending with near.org, our most complex and important domain name. As of last week, when this incident began, we had not yet begun migrating near.org to our new provider, Amazon Web Services, so it was still using Squarespace as its DNS provider. + + +### The Squarespace Security Incident + +Unbeknownst to us, Squarespace had a major security vulnerability. You can read about the problem in [this in-depth blog post from Security Alliance](https://securityalliance.notion.site/A-Squarespace-Retrospective-or-How-to-Coordinate-an-Industry-Wide-Incident-Response-fead693b66c14543a48283d85aec19ad). In short, when each domain was migrated from Google to Squarespace, all existing users on the Google Domains account were sent an email inviting them to create a new Squarespace account. But not everybody clicked on that email right away – some people, e.g. managers or our accounting team, only needed to log into the DNS service rarely or in emergencies. From what we can tell, all the attacker needed to do was identify one of those email addresses and sign up for a new Squarespace account using that email address, and they would be instantly granted full access to change or delete DNS entries for near.org. From our investigation, Squarespace did not require the attacker to verify ownership of the email address before letting them have full control on our account. In fact, we see no evidence that Squarespace even sent a “welcome” email to that address upon account creation, which might have raised warning flags. + +On July 11, an attacker gained access to our Squarespace account. They deleted the DNS entries for near.org and its subdomains, causing the outage described above. But unlike some other domains affected by this attack, the impact on near.org seems limited to an outage; we have seen no evidence that the attacker put in place an ‘imposter’ site to try and phish or scam users. + +Through a combination of our actions and Squarespace’s actions behind the scenes, we were able to quickly regain control of the account. However, due to other issues with Squarespace, it took another two days for near.org and its subdomains and services to get fully back online. + + +### The Squarespace Outage + +Even with full and exclusive access to our Squarespace, we were unable to restore service on near.org. The attacker had deleted our DNS entries, and when we re-added them, Squarespace failed to propagate those new entries to other DNS providers around the world. We attempted to quickly execute a switch to Amazon Web Service’s DNS provider, but the feature to switch to a different DNS service was also broken on the Squarespace site. + +The next morning, on Friday July 12, on a hunch we deleted and re-added all of our DNS entries once again. This time, it did take effect and DNS providers around the world quickly saw the new information. That resolved the outage for many users, but not for everyone. near.org had been set up with an additional security feature, DNSSEC, in which Squarespace was supposed to digitally sign our DNS entries to prove that the entries had not been forged by another DNS provider. But Squarespace wasn’t properly updating and signing new DNSSEC entries, so any other DNS provider that validates DNSSEC was detecting near.org’s DNS entries as a forgery and refusing to allow access to near.org. This affected [approximately 34% of users](https://stats.labs.apnic.net/dnssec), especially in Europe. There is a button on the Squarespace site to turn off DNSSEC, but unsurprisingly, that button also just showed an error message. + +Finally, on Saturday July 13, we were able to make contact with a specialist on the Squarespace team, and later that day they were able to fix the DNSSEC issue. Once that change propagated to other DNS providers around the world over the next few hours, near.org and the RPC service was restored for everyone. + + +### Reflections on this Incident + +You may have noticed that we made a few assumptions in this blog post, saying “from what we can tell” and “we see no evidence of…” a few times. Ideally, almost a week after the incident began, we would have more hard truths and solid information about what happened. + +Unfortunately, we’ve seen little to no communication from Squarespace throughout this period. We tried multiple support tickets, chat, personal contacts, LinkedIn messages, and going through our Google support team, and still didn’t hear anything back from Squarespace until late on Friday July 12, about 36 hours after the incident began. Other affected companies also reported total silence from the Squarespace team. As far as we know, Squarespace has still not acknowledged this incident publicly, let alone shared details of the issue and how they remediated it, and their [status page](https://status.squarespace.com/) showed no outages or issues during this time. + +I personally find this lack of support, communication, and forthrightness to be unacceptable for any service provider. I’m also somewhat disappointed in Google for transitioning a security-critical service to a new provider without proper vetting. We are accelerating our plans to move near.org and other domains out of Squarespace to Amazon Web Services’s domain registrar and DNS provider, which has a great track record of reliability and security. + +DNS is a core part of internet infrastructure, but it’s far from a perfect system. Every domain name owner must rely on one centralized DNS provider to maintain their DNS entries, and every user and application must rely on one or more centralized DNS providers to look up entries as they navigate the internet. Various projects in the blockchain industry have created non-custodial on-chain alternatives to DNS, such as [Unstoppable Domains](https://unstoppabledomains.com/) and [3DNS](https://3dns.box/) (FYI: neither have sponsored or were made aware of this post), but the existing DNS system is so entrenched that adoption has been a challenge. Hopefully as an industry we can make headway on a more decentralized, trustless open web before further incidents like this happen. + +I’m deeply sorry to anyone affected by this outage, especially people exploring NEAR for the first time during the EthCC conference and EthGlobal hackathon. We will be more vigilant about using high-quality vendor services going forward – and, where possible, moving to decentralized on-chain solutions. + +-Eric Winer
+CTO & Managing Director, Pagoda diff --git a/blog/2024-08-13-pagoda-services.mdx b/blog/2024-08-13-pagoda-services.mdx new file mode 100644 index 00000000000..7543c8af554 --- /dev/null +++ b/blog/2024-08-13-pagoda-services.mdx @@ -0,0 +1,71 @@ +--- +title: "Future of Pagoda Services" +description: "As the NEAR ecosystem continues to decentralize, Pagoda will cease operations within the next six months and decentralize its functions into NEAR…" +date: 2024-08-13 +author: "Eric Winer" +tags: [updates] +--- + +{/* BYLINE:start */} +_**Eric Winer** · August 13, 2024_ +{/* BYLINE:end */} + + +**Historical post.** Kept for the record. The products, services, or links it describes may be deprecated or no longer available. + + +As the NEAR ecosystem continues to decentralize, Pagoda will cease operations within the next six months and decentralize its functions into NEAR ecosystem teams and committees. This document describes the transition plan for each of the services, activities, and tools that Pagoda develops or operates. + +### Critical NEAR Services + +The critical services below will continue to be operated and maintained by Pagoda until they are smoothly transitioned to new operators in the NEAR ecosystem during the second half of 2024: + +- [near.org RPC](/api/rpc/providers) ([Request for Proposals](https://dev.near.org/infrastructure-committee.near/widget/app?page=rfp&id=2)) +- [NEAR Lake](/data-infrastructure/lake-framework/near-lake) ([Request for Proposals](https://dev.near.org/infrastructure-committee.near/widget/app?page=rfp&id=3)) +- [BigQuery Public Dataset](/data-infrastructure/big-query) ([Request for Proposals](https://dev.near.org/infrastructure-committee.near/widget/app?page=rfp&id=4)) +- [Node Snapshots](https://near-nodes.io/intro/node-data-snapshots) +- [State Sync](https://near-nodes.io/rpc/state-sync) +- Undocumented but critical services: + - KitWallet Indexer API ([Request for Proposals](https://dev.near.org/infrastructure-committee.near/widget/app?page=rfp&id=1)) + - near-cli Testnet Faucet + +Each transition will be independently planned and communicated on its own timeline and this page will be updated accordingly. + +The NEAR [Infrastructure Committee](https://dev.near.org/infrastructure-committee.near/widget/near-prpsls-bos.components.pages.app?page=about) will manage this transition process by soliciting proposals from the community for continued operation of these services, then will select, fund, and oversee the new operator. + +#### A Note About near.org RPC + +The Infrastructure Committee feels that Pagoda's fully-subsidized near.org RPC service is getting in the way of decentralization efforts and is preventing high-quality commercial RPC offerings from gaining traction. If a NEAR core team continues to support a free-to-use near.org RPC service, it will be required to gradually lower its rate limits over the coming months to prevent abuse. More details on this plan will be communicated by the end of September 2024. In light of this proposed change, **high-traffic near.org RPC users should start making plans to switch to other RPC providers**. + +### Chain Abstraction Services + +[Chain Signatures](/chain-abstraction/chain-signatures), Multichain Gas Relayer, and [FastAuth](/chain-abstraction/fastauth-sdk) will continue to be developed by Pagoda, then will be taken over by the new Chain Abstraction / Multichain spinout from Pagoda and Proximity. More information will be shared in September or October 2024. + +### Pagoda Operations & Ecosystem Services + +Pagoda’s ecosystem services will transition as follows: + +- [Infrastructure Committee](https://dev.near.org/infrastructure-committee.near/widget/near-prpsls-bos.components.pages.app?page=about) administration, the recently rebooted Security Assessment Program, and management of the [near.org](http://near.org) website will move under the purview of NEAR Foundation. +- [Bug bounty](https://hackenproof.com/company/near/programs) triage will be transitioned to the protocol team at NEAR One. +- The NEAR Helpdesk will be turned into self-service documentation. +- Pagoda's informal technical / smart contract advisory services for other ecosystem companies will wind down over the next few months. + +### Open-Source Libraries + +These open-source libraries and tools will be developed by Pagoda until they reach a logical completion or stopping point: + +- [Pagoda Metatransaction Relayer](https://github.com/near/pagoda-relayer-rs) +- [Chain Hosted UI](https://github.com/near/chain-hosted-ui) +- [Modularization and Refactor](https://t.me/neardev/53280) of `near-api-js` + +Once active development by Pagoda has ceased, it doesn't mean these tools have to languish. We encourage the NEAR community to continue this work. If you need funding to do so, you can submit proposals to [DevHub](https://dev.near.org/devhub.near/widget/app) or the [Infrastructure Committee](https://dev.near.org/infrastructure-committee.near/widget/near-prpsls-bos.components.pages.app?page=about). + +### Deprecated Services + +Between now and February 2025, Pagoda's development work will slow down or stop on the following products and services: + +- QueryAPI +- Enhanced API +- Alerts & Triggers + +These are open-source services and we encourage the community to continue with their development and operation. If we can't identify new operators quickly, we will encourage remaining users of these services to switch to alternative solutions, then communicate a timeline for these services to be turned off. diff --git a/blog/2024-10-24-new-tutorial.mdx b/blog/2024-10-24-new-tutorial.mdx new file mode 100644 index 00000000000..418b844b9c1 --- /dev/null +++ b/blog/2024-10-24-new-tutorial.mdx @@ -0,0 +1,31 @@ +--- +title: "New Tutorial - Master Applications on NEAR" +description: "You might have noticed that a new tutorial has been added to the docs! This multi-part series is all about learning to build full applications on NEAR;…" +date: 2024-10-24 +author: "Owen Hassall" +tags: [updates, tutorial, getting-started] +--- + +{/* BYLINE:start */} +_**Owen Hassall** · October 24, 2024_ +{/* BYLINE:end */} + +You might have noticed that a [new tutorial](/web3-apps/tutorials/mastering-near/0-intro) has been added to the docs! This multi-part series is all about learning to build full applications on NEAR; you will see how to build an on-chain auction from start to finish, including the smart contract, deploying it on-chain, and creating a frontend to interact with it. + +Along the way you will learn several key concepts and how to use many key primitives along the way: +- Creating a simple smart contract +- Writing tests for a contract +- Deploying a contract to `testnet` +- Locking a contract +- Creating a frontend to interact with the contract +- Using an indexing API to view historical bids +- Making cross-contract calls +- Using Non-Fungible Tokens +- Using Fungible Tokens +- Modifying a factory contract to deploy your own contracts + +This tutorial is a great for beginners to follow all the way through, but each section can also be used as a reference guide for different concepts. If you have any feedback or any questions regarding the tutorial please feel free to reach out in the [Developer Telegram Channel](https://t.me/neardev). + +**Start the tutorial [here](/web3-apps/tutorials/mastering-near/0-intro)** + +Let's keep building! 🚀 diff --git a/blog/2024-11-07-hello-ethereum-wallets.mdx b/blog/2024-11-07-hello-ethereum-wallets.mdx new file mode 100644 index 00000000000..d70dfcae911 --- /dev/null +++ b/blog/2024-11-07-hello-ethereum-wallets.mdx @@ -0,0 +1,121 @@ +--- +title: "Hello Ethereum Wallets!" +description: "You can now login using MetaMask, WalletConnect and +400 Ethereum Wallets on Near!" +date: 2024-11-07 +author: "Guille, Slava Karkunov" +tags: [updates] +--- + +{/* BYLINE:start */} +_**Guille, Slava Karkunov** · November 7, 2024_ +{/* BYLINE:end */} + +*You can now login using MetaMask, WalletConnect and +400 Ethereum Wallets on Near!* + +

+ +## Ethereum Wallets on NEAR + +We are excited to announce that NEAR now supports Ethereum wallets! This means that you can now login to NEAR applications using MetaMask, WalletConnect, and over 400 other Ethereum wallets. + +In this post, we will explain how Ethereum wallets work on NEAR, and where to find information on how to integrate them into your applications. + +## How it works + +The idea of bringing Ethereum wallets to Near was born on the [NEP-518](https://github.com/near/NEPs/issues/518), and the [Aurora Labs team](https://aurora.dev) worked for over a year to make it a reality. + +Since Ethereum wallets create **ethereum transactions** and talk with **ethereum RPCs**, the Aurora team had to create three components: + +1. A `Transaction Encoder` service, that encodes NEAR actions into Ethereum transactions +2. A `Translator RPC` service, that translates Ethereum RPC calls into NEAR RPC calls +3. A `Wallet Contract` that allows NEAR accounts to process EVM transactions + + + +--- + +### Transaction Encoder + +The `Transaction Encoder` - implemented [directly in the NEAR Wallet Selector](https://github.com/near/wallet-selector/blob/main/packages/ethereum-wallets/src/lib/index.ts) - takes the intent of the user (e.g. call `set_greeting` on `hello.near`) and translates it into an Ethereum transaction that the EVM wallet can sign. + +#### To (field) +The `to` field of the Ethereum transaction is transformed following these rules: +- If the `receiverId` matches `^0x[a-f0-9]{40}$` (e.g. `0xD79...314`), then the `to` field is set to the `receiverId` +- Otherwise (e.g. `ana.near` or an implicit account) the `to` field is set as `keccak-256(receiverId)[12,32]` + +#### Data (field) +The `data` field contains the RLP-encoded NEAR actions wanted by the user, encoded as function calls on Ethereum, for example: +- `FunctionCall(to: string, method: string, args: bytes, yoctoNear: uint32)` +- `Transfer(to: string, yoctoNear: uint32)` +- `Stake(public_key: bytes, yoctoNear: uint32)` +- `AddKey(public_key: bytes, nonce: uint64, is_full_access: bool, allowance: uint256, receiver_id: string, method_names: string[])` + + +For more information on how other fields (such as `value`, `gas`, and `chainId`) are set, please refer to the [NEP-518 technical specification](https://github.com/near/NEPs/issues/518) + +--- + +### Translator RPC + +The `Translator RPC` is a service deployed at `https://eth-rpc.mainnet.near.org` (for mainnet) and `https://eth-rpc.testnet.near.org` (for testnet) that translates Ethereum RPC calls into NEAR RPC calls. + +In other words, the `Translator RPC` simply acts as a relayer, taking the Ethereum transactions signed by the user and translating them into a function call into the `Wallet Contract` deployed in the user's account. + +--- + +### Wallet Contract + +The `Wallet Contract` is a smart contract on NEAR that allows NEAR accounts to process EVM transactions. + +The contract exposes a method called `rlp_execute`, which takes as argument an RLP-encoded Ethereum transaction, verifies its signature, and executes the NEAR actions encoded in the `data` field of the transaction. + +Every NEAR account created through an EVM wallet has the `Wallet Contract` deployed on it. + + +Remember that in NEAR **all accounts** can **have contracts**, and that **contracts** can perform **all the actions** that the **account can do**. + +--- + +## Using the Account + +### First Time Login + +Imagine your account on Metamask is `0xD79...314`, and you want to login on a Near application. + +The first time you login through your EVM wallet, the wallet selector will contact the account `ethereum-wallets.near` to create a NEAR account with the same address as your Ethereum wallet. For example, if your address on Metamask is `0xD79...314`, the NEAR account created will be `0xD79...314`. + +On this account, the `Wallet Contract` is deployed and a function-call key is added for the `rlp_execute` function of the contract. + + + +### Interacting with Applications + +Once you have logged in, you can start interacting with the application. If at some point the application needs to interact with the blockchain, Metamask will ask you to sign a transaction. + +Under the hood, Metamask will create an Ethereum transaction and send it to the `Translator API`, deployed at `https://eth-rpc.mainnet.near.org`. + +The `Translator API` will then translate the Ethereum transaction into a **function call** into the `Wallet Contract` deployed in your account. Particularly, it will call the `rlp_execute` function, passing the Ethereum transaction as an argument. + + + +The `Wallet Contract` will then execute the function call, and the application will receive the result. + + + +Check [this transaction](https://testnet.nearblocks.io/txns/GrVGFVFmGBcNP5xkoA21gEJ7d5bUGVxtmkfHAzyUW895#enhanced) in our explorer to see the full execution path + +## Updating your Application + +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 the working example [**hello world frontend**](https://github.com/near-examples/hello-near-examples/tree/main/frontend). + +--- + +## Resources + +1. [Hello World Example](https://github.com/near-examples/hello-near-examples/blob/main/frontend/) + +2. [Recording of the Ethereum Wallet Presentation](https://drive.google.com/file/d/1xGWN1yRLzFmRn1e29kbSiO2W1JsxuJH-/view?usp=sharing) + +3. [NEP-518](https://github.com/near/NEPs/issues/518), the proposal that started it all diff --git a/blog/2025-01-01-a-year-in-docs.mdx b/blog/2025-01-01-a-year-in-docs.mdx new file mode 100644 index 00000000000..84703285732 --- /dev/null +++ b/blog/2025-01-01-a-year-in-docs.mdx @@ -0,0 +1,113 @@ +--- +title: "A Year in Docs" +description: "2024 was a great year for NEAR Docs! Let's take a look at what we achieved together" +date: 2025-01-01 +author: "Guille" +tags: [updates] +--- + +{/* BYLINE:start */} +_**Guille** · January 1, 2025_ +{/* BYLINE:end */} + +*2024 was a great year for NEAR Docs! Let's take a look at what we achieved together* + +

+ +## New Year, New Opportunities + +There is something that we like to do every new year, and that is to take a look at how our docs changed through the past year. + +You see, NEAR is a live ecosystem, where new features are added constantly, products and projects emerge, and our docs need to reflect that. This means that we are always adding, removing, and updating content. + +By looking at the changes we made, we get to remember what we achieved - it is always nice to see all we built in a year - and it also helps us discover what we lost along the way! + +Join us while we take a look at the changes we made in 2024, and what we are planning for 2025. + +## Consolidating Documentation + +One of the main issues we tackled this year was consolidating our documentation. + +Users often complained that we had a lot of content spread across different sections, pages, and repositories, and we wanted to bring it all together in one place. + +At the beginning of 2024, we had different menus for [Concepts](/getting-started/what-is-near), [Smart Contracts](/smart-contracts/what-is), [Web Applications](/web3-apps/what-is), and [Data Infrastructure](/data-infrastructure/what-is). + +We decided to merge all these pages into a single `Docs` section, with a shared navigation bar, so you can always easily jump from one topic to another. + +![Navigation](/assets/blog/2024-review/2024-blog.jpg) +_Navigation before (left) and now (right), notice how many links were removed from both top and left navigation bars!_ + +To keep the sidebar clean, we added a `What is...` page for each major topic, which helps you to understand the basics and decide if that section is what you are looking for. + +For example, we now have the following pages: + +- [What is NEAR Protocol?](/getting-started/what-is-near) +- [What is Chain Abstraction?](/chain-abstraction/what-is) +- [What is a Smart Contract?](/smart-contracts/what-is) + +## Code Explainer + +During this year, we took a couple of weeks to build an in-house tool to simplify explaining code! + +![code explainer](/assets/blog/2024-review/2024-blog-2.jpg) + +The new `Code Explainer` allows us to easily explain long snippets of code, by highlighting the essential parts and adding text blocks to explain what is happening. + +Our new [Smart Contract Anatomy](/smart-contracts/anatomy/anatomy) section looks amazing and is much easier to understand now! + +## 2024: A Year of Growth + +This year we have been busy adding new sections, pages, and tutorials to our documentation. Let's briefly go through some of them. + +### Primitives + +One of the first things we added was a section about [Primitives](/primitives/what-is), which explains the basic building blocks of NEAR Protocol. + +![Primitives](/assets/blog/2024-review/2024-blog-3.jpg) + +In the new Primitives section, we show how to create and use [NFTs](/primitives/nft/nft), [FTs](/primitives/ft/ft), [DAOs](/primitives/dao), [Linkdrops](/primitives/linkdrop/linkdrop), [Oracles](/primitives/oracles), and [Decentralized Exchanges](/primitives/dex). + +Every page is full of snippets that explain how to leverage each primitive from any tool that you are using, be it the bash terminal, a web application, or from within a smart contract. + +### Chain Abstraction + +We also added a section about [Chain Abstraction](/chain-abstraction/what-is), which explains how NEAR accounts can be used to control accounts on other chains. + +![alt text](/assets/blog/2024-review/2024-blog-4.jpg) +_Did you know you can control Ethereum and Bitcoin accounts from NEAR?_ + +We expect to make this section grow in 2025, as we plan to add more tutorials and examples on interacting with chains like Base, Solana, and Polygon. + +### New Beginner's Guide + +In 2024 we also released a brand new [Step-by-Step Guide to Mastering Near](/web3-apps/tutorials/mastering-near/0-intro). This guide is perfect for beginners, as it explains everything from creating an account to deploying a smart contract, creating a web application for it, and even how to monitor the contract's activity! + +![Beginner's Guide](/assets/blog/2024-review/2024-blog-5.jpg) + +It is our most complete guide yet! But stay tuned, as we are planning to add more tutorials and examples to it in 2025. + +### NEAR API + +We also released a new version of our [API documentation](/tools/near-api), which now includes all API flavors - JavaScript, Rust, and Python. + +![API](/assets/blog/2024-review/2024-blog-6.jpg) + +In this new version, we added a lot of examples on how to use the API in the most common scenarios, as well as linked all the code to a single [GitHub repository](https://github.com/near-examples), to make it easier for us to test it, and for you to copy and paste the code. + +### Near Examples + +An important part of our documentation is the examples it references. We have been working hard to make sure that all examples are up-to-date and working. + +For example, we have updated all our canonical examples (Hello Near, Counter, Donations, NFT, FT) to use the latest version of core libraries (`near-api`, `near-sdk` and `wallet-selector`) + +## Looking Forward + +We are excited to start 2025 with a lot of new ideas and projects in mind. We are planning to add new examples about how to build complex DeFi applications on NEAR, as well as adding community projects such as [Pikespeak](https://doc.pikespeak.ai/), [FastNear](https://github.com/fastnear/explorer-api), and [NearBlocks](https://api.nearblocks.io/api-docs/) + +More importantly, we expect 2025 to be the year of AI, focusing on building docs showing how easy is to use [NEAR AI](https://near.ai) to build and deploy machine learning models on NEAR. + +By focusing on AI, we also expect to bring new ways to engage with our documentation, such as a chatbot that can help you find the right page! + +Of course, everything is being developed using open-source tools and libraries, so you can easily replicate what we are doing. + +We are excited to start this new year, and hope you are too! 🚀 diff --git a/blog/2025-03-14-benefits-of-multiple-keys.mdx b/blog/2025-03-14-benefits-of-multiple-keys.mdx new file mode 100644 index 00000000000..a78c95cca0e --- /dev/null +++ b/blog/2025-03-14-benefits-of-multiple-keys.mdx @@ -0,0 +1,61 @@ +--- +title: "Benefits of Function-Call Keys" +description: "NEAR has a unique key management system that allows each account to have multiple access keys. Each of these keys can be one of two types: Full-Access…" +date: 2025-03-14 +author: "Guille" +tags: [articles] +--- + +{/* BYLINE:start */} +_**Guille** · March 14, 2025_ +{/* BYLINE:end */} + +NEAR has a unique key management system that allows each account to have multiple access keys. Each of these keys can be one of two types: `Full-Access Keys` and `Function-Call Keys`. + +`Full-Access Keys` are the traditional type of key you might be used to, which provide complete control over an account, allowing the holder to perform any action, including transferring funds, deploying contracts, and managing other keys. + +On the other hand, `Function Call Keys` allows you to provide **restricted access** to third parties. This key type, unique to NEAR, enables several use-cases worth discussing. + +Let's explore some of the main benefits of `Function-Call Keys`. + +--- + +## Enhancing User Experience +The most common use case for `Function-Call` keys is to allow an application to sign transactions on the user's behalf. + +Imagine you are developing a game that records the user's score on a smart contract. On other chains, you would have to disrupt the user's experience to request transaction signatures each time the game needs to update the score. + +With NEAR, you can request the user to generate a `Function-Call` key for the game's contract and share it with the game. This way, the game can sign transactions in the user's name, eliminating gameplay interruptions. + +Sharing this key is safe for the user, because even in the case of somebody stealing it, they would only be able to call the score-keeping method, and nothing else. + +--- + +## Simple Onboarding + +Another common use-case of `Function-Call` keys is to simplify the **onboarding** process for new users. + +It works as follows: + +1. Create a contract that has a method called `create_account` + - This method should only be callable by the contract itself and + - When executed, the method should create a new account and transfer some tokens to it + +2. Add multiple `Function Call Keys` in the contract's account, that **only allow to call `create_account`** + +3. Give these keys to your friends! They will be able to call the method, and easily create an account with some tokens + +Your main account and your funds will never be at risk, as the keys can only be used to call the `create_account` method. + + +This is the basic principle behind [NEAR Drops](/primitives/linkdrop/linkdrop), a way to distribute assets to a large number of users + +--- + +## Key Rotation and Recovery + +The presence of multiple keys allows for easy **rotation** and **recovery**. If you suspect a key might be compromised, you can promptly remove it or replace it with a new one, similar to changing your password on a website. + +You can also establish a key-recovery contract in your account and generate a "recovery key" for a trusted party. This key would only be used to initiate the recovery process. + +In case of necessity, the trusted party can trigger the recovery process, assisting in the creation of a new full-access key for you. diff --git a/blog/2025-06-21-near-for-backend-devs.mdx b/blog/2025-06-21-near-for-backend-devs.mdx new file mode 100644 index 00000000000..282bee4545f --- /dev/null +++ b/blog/2025-06-21-near-for-backend-devs.mdx @@ -0,0 +1,482 @@ +--- +title: "NEAR for Backend Devs: A Familiar Frontier" +description: "As an backend developer you are adept at building robust services, managing databases, and ensuring system reliability. When you hear \"blockchain\" it…" +date: 2025-06-21 +author: "Vlad Frolov" +tags: [articles] +--- + +{/* BYLINE:start */} +_**Vlad Frolov** · June 21, 2025_ +{/* BYLINE:end */} + +As an backend developer you are adept at building robust services, managing databases, and ensuring system reliability. When you hear "blockchain" it might sound like a completely different paradigm. However, platforms like [NEAR Protocol](/getting-started/what-is-near) are designed to be surprisingly accessible, offering a new kind of backend infrastructure that leverages many concepts you are already familiar with. + +In this article will guide you through understanding NEAR from a backend perspective, exploring how NEAR is a platform where: + +* **The Backend Logic** lives in small programs know as ["smart contracts"](/smart-contracts/what-is) which you can write in [languages that compile to WebAssembly](/tools/sdk) like Rust or Javascript +* **The Application State** is managed per program, with global availability and data integrity ensure by the network +* **User Identity and Permissions** are cryptographically secured and can be reliably checked within your application logic using [Accounts](/protocol/accounts-contracts/account-model) +* **Data Replication** is handled by the network, providing something akin to a master-master replication setup with eventual consistency, typically reaching [finality](/protocol/transactions/transaction-execution#receipts--finality) (undisputed agreement) in about 1-2 seconds + +We will build a simplified Twitter-like application using Rust to demonstrate these concepts in action. Let's explore how your backend skills translate to this decentralized frontier. + +## NEAR as Your Decentralized Backend Platform + +Imagine building a backend service that doesn't run on a specific server you manage, but on a global network of computers. This is the essence of NEAR. Let's break down how familiar backend concepts map to NEAR. + +**1. Application State: Your Own Namespace, Globally Replicated** + +On NEAR, each application lives on its own account [Account](/protocol/accounts-contracts/account-model) (e.g., `your-app.near`, `twitter-clone.your-account.near`). Think of this `Account` as a namespace for your application's dedicated state. + +* **Isolated State:** All data for your application is stored within the context of its `Account` using a dedicated key-value store database. Only the account's program can change its stored data. + +* **Auditable changes:** The history of **changes** to your application's state is securely stored in the blockchain, making it immutable and cryptographically verifiable. + +* **Data Replication & Availability:** This application state isn't just on one machine. The NEAR network, composed of many independent ["validators"](/protocol/network/validators), replicates this state. This is analogous to a distributed database system with master-master replication. If some nodes go offline, the network continues to operate, and your application's state remains available. + +* **Eventual Consistency with Fast Finality:** When a user interacts with your application validators process the request. Within 1-2 seconds the network reaches consensus and the change is [final](/protocol/transactions/transaction-execution). After this, the new state is an undisputed part of the global record. This is a form of eventual consistency, but with a very short window to reach that consistent, final state. + +**2. Backend Logic: Smart Contracts** + + +The code that defines how the account's state can be read and modified is known as a "[smart contract](/smart-contracts/what-is)". +* **Your Business Logic:** This is where you write your application's rules. For our Twitter example, this logic will define how a tweet is created, who can post it, how tweets are retrieved, etc. + +* **Execution Environment:** Contracts are compiled into WebAssembly (Wasm), a highly efficient and sandboxed binary format. This binary is stored in the NEAR platform under your application's `Account` and executed by the validator nodes. + +* **Multiple Languages:** The use of Wasm means you can write this logic in several familiar languages, with [Rust](/tools/sdk) being a primary and robust choice offering strong safety and performance. + +* **Millions of Contracts:** The NEAR blockchain can host millions of contracts, each operating within its own account namespace, managing its own state, and exposing its own set of functions. + +**3. User Identity and Authorization: Cryptographic Certainty** + +In traditional backends, you manage user authentication (e.g., passwords, OAuth) and then use sessions or tokens to identify users for subsequent requests. NEAR has a built-in, cryptographically secure way to identify who is initiating an action + +* **Transactions and Signatures:** Every interaction that attempts to change your application's state must be initiated as a "[transaction](/protocol/transactions)" signed by a NEAR account. This signature proves ownership of that account + +* **`predecessor_account_id`:** When your smart contract code is executed, it has access to [`env::predecessor_account_id()`](https://docs.rs/near-sdk/latest/near_sdk/env/fn.predecessor_account_id.html), which reliably tells which NEAR account triggered the current function call + +* **Built-in Access Control:** You can use `predecessor_account_id` to implement powerful access control (e.g. assert that only specific accounts call certain functions). This is like having `@isAuthenticated` and `@hasPermission` checks, but grounded in cryptographic proof tied to the user's account, not just a session token your server issued + +By combining these elements – namespaced and replicated state, Wasm-compiled business logic (smart contracts), and cryptographic user identity – NEAR provides a robust platform for building decentralized applications with familiar backend engineering principles. + +## Smart Contracts in Rust: The Twitter Example + +Now, lets see how this translates into code. Your backend logic on NEAR is encapsulated in a smart contract. As mentioned, these contracts are compiled to WebAssembly (Wasm), allowing you to use languages like [Rust](/tools/sdk). Rust is a popular choice due to its performance, safety features, and strong tooling support within the NEAR ecosystem. + +We will build a simplified Twitter-like application. Users will be able to post tweets, view all tweets, view tweets by a specific author, and like tweets. The core idea is that each tweet is undeniably linked to its author via their NEAR account ID. + +Here's the Rust code for our contract: + +```rust +// ================================================================================================ +// NEAR SMART CONTRACT: Twitter-like Social Media Platform +// ================================================================================================ +// +// This smart contract implements a Twitter-like platform on the NEAR blockchain. +// For backend engineers new to blockchain, think of this as a REST API service that: +// - Stores data permanently on a distributed database (the blockchain) +// - Has no central server - it runs on hundreds of nodes worldwide +// - Charges small fees (gas) for write operations to prevent spam +// - Is immutable once deployed (like deploying code that can't be changed) +// +// Key NEAR/Blockchain Concepts for Backend Engineers: +// - Smart Contract = Your backend service logic that runs on blockchain +// - Account ID = User identifier (like username, but globally unique) +// - Gas = Computational cost (like AWS Lambda pricing, but for blockchain operations) +// - Storage = Persistent data (like a database, but decentralized and permanent) +// - View Methods = Read operations (free, like GET requests) +// - Call Methods = Write operations (cost gas, like POST/PUT/DELETE requests) + +// Import NEAR SDK components - think of this as importing your web framework +use near_sdk::store::IterableMap; // Like HashMap but optimized for blockchain storage +use near_sdk::{env, near, AccountId, PanicOnDefault, Timestamp}; + +// ================================================================================================ +// DATA STRUCTURES +// ================================================================================================ + +// Tweet represents a single tweet in our social media platform +// The #[near] attribute automatically handles serialization/deserialization +// Think of this as your API response/request DTOs, but for blockchain +#[near(serializers = [borsh, json])] +#[derive(Clone, Debug, PartialEq)] +pub struct Tweet { + // Unique identifier for this tweet (like auto-increment ID in SQL) + pub id: u64, + + // NEAR account that created this tweet (like user_id in traditional apps) + // AccountId is NEAR's version of a username/user identifier + pub author: AccountId, + + // The actual tweet content (like message body) + pub text: String, + + // When this tweet was created (NEAR provides nanoseconds since Unix epoch) + // Think of this as created_at timestamp in your database + pub timestamp: Timestamp, + + // Number of likes this tweet has received (like a counter field) + pub likes: u64, +} + +// ================================================================================================ +// SMART CONTRACT STATE +// ================================================================================================ + +// TwitterContract is the main contract state - think of this as your application's +// in-memory state that persists between requests (like instance variables in a service class) +// +// In traditional backend: +// - You'd have a database to store tweets +// - You'd have application state in memory/cache +// +// In NEAR: +// - Contract state IS your database (stored on blockchain) +// - State persists between function calls +// - State is automatically loaded/saved by NEAR runtime +#[near(contract_state)] +#[derive(PanicOnDefault)] // Prevents accidental initialization without proper setup +pub struct TwitterContract { + // Storage for all tweets - like your main tweets table + // IterableMap is NEAR's version of HashMap optimized for blockchain storage + // Key: tweet_id, Value: Tweet object + tweets: IterableMap, + + // Counter for generating unique tweet IDs (like auto-increment in SQL) + // This ensures each tweet gets a unique identifier + next_tweet_id: u64, +} + +// ================================================================================================ +// CONTRACT IMPLEMENTATION +// ================================================================================================ + +// The #[near] attribute marks this implementation block as containing contract methods +// Think of these as your REST API endpoints, but they run on the blockchain +#[near] +impl TwitterContract { + // ============================================================================================ + // INITIALIZATION METHOD + // ============================================================================================ + + // Contract constructor - called once when the contract is first deployed + // Similar to database migrations or initial setup in traditional backends + // The #[init] attribute marks this as the initialization method + #[init] + pub fn new() -> Self { + Self { + // Initialize tweet storage with a unique storage prefix + // "b't'" is a byte string prefix to avoid storage conflicts + // Think of this as creating a table in your database + tweets: IterableMap::new(b"t"), + + // Start tweet IDs from 0 + next_tweet_id: 0, + } + } + + // ============================================================================================ + // WRITE METHODS (Cost gas, modify state) + // ============================================================================================ + + // Post a new tweet - equivalent to POST /tweets endpoint + // This is a "call" method that modifies state and costs gas + pub fn post_tweet(&mut self, text: String) -> Tweet { + // Get the account that called this method (like extracting user from JWT token) + // env::predecessor_account_id() returns who made the transaction + let author = env::predecessor_account_id(); + + // Get current blockchain timestamp (like System.currentTimeMillis() in Java) + // NEAR provides nanoseconds since Unix epoch + let timestamp = env::block_timestamp(); + + // Generate unique ID for this tweet (like auto-increment primary key) + let tweet_id = self.next_tweet_id; + + // Create the tweet object (like building your entity/model) + let new_tweet = Tweet { + id: tweet_id, + author: author.clone(), + text, + timestamp, + likes: 0, // New tweets start with 0 likes + }; + + // Store the tweet in our "database" (contract storage) + // This is like INSERT INTO tweets (...) VALUES (...) + self.tweets.insert(tweet_id, new_tweet.clone()); + + // Increment ID counter for next tweet (like auto-increment) + self.next_tweet_id += 1; + + // Log the action - similar to application logging + // These logs are stored on blockchain and can be queried + env::log_str(&format!( + "Tweet #{} posted by @{} at {}", + tweet_id, author, timestamp + )); + + // Return the created tweet (like returning the entity in REST API) + new_tweet + } + + // Like a tweet - equivalent to POST /tweets/{id}/like endpoint + // This modifies state (increments like counter) so it costs gas + pub fn like_tweet(&mut self, tweet_id: u64) -> Option { + // Try to get a mutable reference to the tweet + // This is like: SELECT * FROM tweets WHERE id = ? FOR UPDATE + if let Some(tweet) = self.tweets.get_mut(&tweet_id) { + // Increment the like counter (like UPDATE tweets SET likes = likes + 1) + tweet.likes += 1; + + // Log the like action for transparency/debugging + env::log_str(&format!( + "Tweet #{} liked by @{}. Total likes: {}", + tweet_id, + env::predecessor_account_id(), // Who liked the tweet + tweet.likes + )); + + // Return the updated tweet (clone because we need to return owned data) + Some(tweet.clone()) + } else { + // Tweet doesn't exist - log the attempt + // In REST API, this would be a 404 Not Found + env::log_str(&format!( + "Attempt to like non-existent tweet #{} by @{}", + tweet_id, + env::predecessor_account_id() + )); + None + } + } + + // Delete a tweet - equivalent to DELETE /tweets/{id} endpoint + // Only the tweet author can delete their own tweets (authorization check) + pub fn delete_tweet(&mut self, tweet_id: u64) { + // Get who's trying to delete the tweet (like checking JWT/session) + let caller = env::predecessor_account_id(); + + // Check if tweet exists and verify ownership + // This is like: SELECT author FROM tweets WHERE id = ? + if let Some(tweet) = self.tweets.get(&tweet_id) { + // Authorization check - only author can delete their tweet + // Similar to checking if user owns the resource in REST API + if tweet.author == caller { + // Delete the tweet from storage + // Like: DELETE FROM tweets WHERE id = ? + self.tweets.remove(&tweet_id); + env::log_str(&format!("Tweet #{} deleted by @{}", tweet_id, caller)); + } else { + // Unauthorized deletion attempt - log security event + // In REST API, this would be 403 Forbidden + env::log_str(&format!( + "User @{} attempted to delete tweet #{} but is not the author.", + caller, tweet_id + )); + } + } else { + // Tweet doesn't exist - log the attempt + // In REST API, this would be 404 Not Found + env::log_str(&format!( + "Attempt to delete non-existent tweet #{} by @{}", + tweet_id, caller + )); + } + } + + // ============================================================================================ + // READ METHODS (Free, don't modify state) + // ============================================================================================ + // These are "view" methods - they don't cost gas and don't modify contract state + // Think of these as GET endpoints in your REST API + + // Get all tweets with pagination - like GET /tweets?offset=0&limit=10 + // from_index: starting position (like OFFSET in SQL) + // limit: maximum number of tweets to return (like LIMIT in SQL) + pub fn get_all_tweets(&self, from_index: Option, limit: Option) -> Vec { + // Set default values if not provided (common REST API pattern) + let start = from_index.unwrap_or(0); + let limit_val = limit.unwrap_or(10); + + // Query tweets with pagination (like SELECT * FROM tweets LIMIT x OFFSET y) + self.tweets + .iter() // Iterate over all tweets + .skip(start as usize) // Skip 'start' number of tweets (OFFSET) + .take(limit_val as usize) // Take only 'limit_val' tweets (LIMIT) + .map(|(_key, tweet)| tweet.clone()) // Extract tweet objects (ignore keys) + .collect() // Collect into Vector to return + } + + // Get specific tweet by ID - like GET /tweets/{id} + pub fn get_tweet_by_id(&self, tweet_id: u64) -> Option { + // Simple lookup by primary key + // Like: SELECT * FROM tweets WHERE id = ? + self.tweets.get(&tweet_id).cloned() + } + + // Get tweets by specific author with pagination - like GET /users/{id}/tweets + // This demonstrates filtering in blockchain storage (no SQL WHERE clause available) + pub fn get_tweets_by_author( + &self, + author_id: AccountId, + from_index: Option, + limit: Option, + ) -> Vec { + let start = from_index.unwrap_or(0); + let limit_val = limit.unwrap_or(10); + + // We need to manually filter since blockchain storage doesn't have SQL-like queries + // This is like doing: SELECT * FROM tweets WHERE author = ? LIMIT x OFFSET y + // But we have to iterate through all tweets and filter manually + let mut author_tweets = Vec::new(); + let mut count = 0; + let mut current_index = 0; + + // Iterate through all tweets to find matches + for (_id, tweet) in self.tweets.iter() { + // Check if this tweet belongs to the requested author + if tweet.author == author_id { + // Apply pagination logic + if current_index >= start && count < limit_val { + author_tweets.push(tweet.clone()); + count += 1; + } + current_index += 1; + } + + // Optimization: stop early if we've found enough tweets + if count >= limit_val && current_index > start { + break; + } + } + + author_tweets + } +} + +// ================================================================================================ +// KEY DIFFERENCES FROM TRADITIONAL BACKEND: +// ================================================================================================ +// +// 1. STATE PERSISTENCE: +// - Traditional: Use database, cache, session storage +// - NEAR: Contract state IS your database, automatically persisted +// +// 2. USER AUTHENTICATION: +// - Traditional: JWT tokens, sessions, OAuth +// - NEAR: Cryptographic signatures, account-based auth built-in +// +// 3. SCALABILITY: +// - Traditional: Horizontal scaling, load balancers, microservices +// - NEAR: Automatic scaling across blockchain network +// +// 4. COSTS: +// - Traditional: Server costs, database costs, bandwidth +// - NEAR: Gas fees for computations, storage costs per byte +// +// 5. DEPLOYMENT: +// - Traditional: CI/CD pipelines, blue-green deployments +// - NEAR: Deploy once, immutable (or upgradeable with special patterns) +// +// 6. DATA CONSISTENCY: +// - Traditional: ACID transactions, eventual consistency +// - NEAR: Atomic transactions guaranteed by blockchain consensus +// +// 7. QUERYING DATA: +// - Traditional: SQL, NoSQL query languages +// - NEAR: Manual iteration, no complex queries (design for simple access patterns) +``` + +This Rust smart contract ([here is the full version](https://github.com/frol/near-twitter-example-rs)) acts as the backend for our Twitter application. It defines the data structures, the initial state, and the functions that users can call to interact with the application. The use of `predecessor_account_id` is central to associating tweets with their authors. + +## Interacting with Your NEAR Backend (Smart Contract) + +Once your Rust smart contract is compiled to Wasm and deployed to a NEAR account (e.g., `twitter-app.your-account.near`), it's live and ready for interaction. So, how do you or your users "call" these backend functions? + +Think of it like interacting with a standard web API, but instead of HTTP requests to a server you own, you are sending transactions or making RPC calls to the NEAR network, targeting your specific contract account and method. + +**1. Calling Methods that Change State (e.g., `post_tweet`, `like_tweet`):** + +These are "call" methods (marked `&mut self` in Rust) because they modify the contract's state. + +* **Transactions:** To execute these, a user (or an application acting on their behalf) constructs a [transaction](/protocol/transactions). This transaction specifies: + * The `receiver_id`: Your contract's account ID (e.g., `twitter-app.your-account.near`). + * The `method_name`: The function to call (e.g., `"post_tweet"`). + * `args`: The arguments for the function, typically as a JSON string (e.g., `{"text": "My first NEAR tweet!"}`). + * `signer_id`: The NEAR account ID of the user initiating the action. The transaction must be signed with this account's private key. This signature is how `env::predecessor_account_id()` in your contract gets populated. + * `attached_deposit`: If the method is `#[payable]`, users can attach NEAR tokens to the call. (Not used in our Twitter example's `post_tweet`). + * `gas`: An amount of "[gas](/protocol/transactions/gas)" to pay for the computation and storage resources used by the transaction. Gas is a fee mechanism on the network. +* **Tools:** + * **[NEAR CLI](/tools/cli):** A command-line interface for interacting with NEAR. Example: + ```bash + near call twitter-app.your-account.near post_tweet '{"text": "Hello from CLI!"}' --useAccount user1.near + ``` + * **NEAR SDKs (JavaScript, etc.):** For web or mobile frontends, you'd use a JavaScript library (like [`near-api-js`](/tools/near-api)) to construct and send these transactions through a user's NEAR Wallet (which handles the signing). + +**2. Calling Methods that Only Read State (e.g., `get_all_tweets`, `get_tweet_by_id`):** + +These are "view" methods (marked `&self` in Rust) because they only read state and don't modify it. + +* **RPC Calls:** These can be made directly to a NEAR [RPC node](/api/rpc/introduction) without needing to send a full transaction and without requiring gas from the caller (though the RPC provider might have its own rate limits or fees for heavy usage). +* **Tools:** + * **[NEAR CLI](/tools/cli):** + ```bash + near view twitter-app.your-account.near get_all_tweets '{"from_index": 0, "limit": 5}' + ``` + * **NEAR SDKs (JavaScript, etc.):** Libraries like [`near-api-js`](/tools/near-api) provide straightforward ways to make these view calls. + +**In essence:** + +* **Modifying state:** Requires a signed transaction, costs gas, involves the whole network consensus. This is your `POST`, `PUT`, `DELETE` equivalent. +* **Reading state:** Can be done with a lighter-weight RPC view call, generally free at the contract level. This is your `GET` equivalent. + +Your frontend application (web, mobile) or other backend services would use these mechanisms to interact with the smart contract, which acts as the secure, decentralized backend logic and data store. The key is that the user always initiates and authorizes state-changing actions via their own NEAR account and cryptographic signatures. + +## Benefits for Backend Developers: Why Consider NEAR? + +As an experienced backend developer, you might be wondering what advantages building on a platform like NEAR offers compared to your traditional stacks. Here are a few key benefits: + +1. **Enhanced Data Integrity and Auditability:** + * Every state change is a transaction recorded on an immutable ledger. This provides an automatic, transparent audit trail. For applications where provenance, history, or verifiability is critical, this is a built-in feature, not something you need to painstakingly architect. + * The rules for state changes are defined in the smart contract code, which is itself auditable on the blockchain. + +2. **Reduced Need for Trust / Trustless Interactions:** + * Because the backend logic (smart contract) and state are managed by a decentralized network with consensus, users (and other services) don't need to trust a single central operator to execute logic correctly or maintain data integrity. The "code is law" principle reduces counterparty risk. + * This is powerful for multi-party applications where participants might not fully trust each other but can trust the neutral execution environment of the blockchain. + +3. **Built-in User Account System and Cryptographic Security:** + * NEAR's [account model](/protocol/accounts-contracts/account-model) provides a ready-made, secure user identity system. You don't need to build and maintain your own user database, password hashing, or session management for core identity. + * The use of `predecessor_account_id` based on cryptographic signatures provides strong guarantees about who initiated an action, simplifying authorization logic within your contract. + +4. **High Availability and Resilience:** + * Being a decentralized network, NEAR is inherently resilient to single points of failure. Your application's backend logic and state remain accessible as long as the NEAR network itself is operational, which is designed for high uptime. This is like getting a globally distributed, fault-tolerant deployment out of the box. + +5. **Censorship Resistance:** + * Once deployed, your smart contract logic cannot be easily shut down or tampered with by a single entity, including the original developer (unless specific upgrade mechanisms are built in and governed by clear rules). This provides a degree of censorship resistance for applications and their data. + +6. **Fast Finality and Scalable by Design:** + * NEAR's ~1-2 second [finality](/protocol/transactions/transaction-execution) means transactions are quickly confirmed and irreversible, providing a responsive user experience for a decentralized system. + * The sharding architecture ([Nightshade](https://near.org/assets/blog/near-launches-nightshade-sharding-paving-the-way-for-mass-adoption)) is designed for scalability, allowing the network to handle an increasing number of transactions as more applications and users join the ecosystem. This addresses a common concern with older blockchain technologies. + +7. **Interoperability and Composability (Advanced):** + * Smart contracts on NEAR can call each other, allowing for complex applications to be built by composing functionalities from different contracts. This opens up possibilities for creating ecosystems of interconnected services. + +While NEAR (and blockchain in general) introduces new considerations like [gas fees](/protocol/transactions/gas) for transactions and on-chain [storage costs](/protocol/storage/storage-staking), it offers a unique set of benefits for specific types of applications. If your application requires high degrees of transparency, user control over their data, verifiable logic, or interactions between multiple distrusting parties, NEAR provides a compelling backend infrastructure that complements your existing skillset. + +## Conclusion: Your Backend Skills, Decentralized on NEAR + +Transitioning from traditional web2 backend development to building on NEAR isn't about discarding your expertise; it's about applying it in a new context. We've seen how NEAR can be understood as a decentralized backend platform where: + +* **Application-specific state** is managed securely and replicated globally, akin to a highly available, namespaced database. +* **Smart contracts**, written in languages like Rust, serve as your backend logic, defining all rules for state interaction. +* **User identity** is cryptographically enforced, with `predecessor_account_id` offering a reliable way to manage permissions and ownership. +* The platform provides **fast finality** (~1-2 seconds) and is designed for **scalability**. + +The Twitter example, though simplified, illustrates how you can build applications where data ownership and control are transparently handled by the logic you deploy. Concepts like managing state, defining APIs (contract methods), and ensuring data integrity are all directly transferable. + +NEAR offers a robust environment for building applications that benefit from decentralization – whether for enhanced transparency, user empowerment, or creating new forms of multi-party collaboration. With your existing backend development skills, you are well-equipped to explore this powerful platform and build the next generation of applications. The learning curve is more about understanding the decentralized paradigm and NEAR's specific APIs rather than learning programming from scratch. + +Ready to dive deeper? Check out the [NEAR Documentation](/) and the [Rust SDK examples](https://github.com/near-examples?q=&type=all&language=rust&sort=) to start your journey. diff --git a/blog/2025-12-11-blockchain-finality-benchmark.mdx b/blog/2025-12-11-blockchain-finality-benchmark.mdx new file mode 100644 index 00000000000..195bd0330cb --- /dev/null +++ b/blog/2025-12-11-blockchain-finality-benchmark.mdx @@ -0,0 +1,190 @@ +--- +title: "Benchmarking Blockchain" +description: "While each blockchain has its own theoretical finality and transaction price, we wanted to know: how long does my app actually need to wait for a…" +date: 2025-12-11 +author: "Matias Benary" +tags: [benchmark, performance, finality] +--- + +{/* BYLINE:start */} +_**Matias Benary** · December 11, 2025_ +{/* BYLINE:end */} + +While each blockchain has its own theoretical finality and transaction price, +we wanted to know: how long does my app *actually* need to wait for a transaction +to be final, and how much will it pay? + +To answer these questions, we sent transactions across 6 different chains to +compare both finality times and transaction fees. + +## Understanding Finality in Blockchain + +When you send a transaction on a blockchain, how long does it take to be truly irreversible? +This question is critical for developers building applications, especially those handling DeFi. + +When talking about finality, it is important to remember that generally there are two types of finality: + +- **Soft Finality (Optimistic)**: The transaction is included in a block and is *highly unlikely* to be reversed +- **Hard Finality**: The transaction is irreversibly committed to the blockchain with cryptographic guarantees + +For example, here are the **theoretical `optimistic` and `final` finality times** for 6 popular blockchains, +ordered from fastest to slowest (theoretically) in Hard Finality: + +| Blockchain | Optimistic Finality | Hard Finality | +|------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| Sui | 500ms | [500ms](https://docs.sui.io/concepts/sui-architecture/consensus#transaction-throughput) | +| Aptos | 130ms | [650ms](https://blockchain.news/flashnews/aptos-sets-industry-record-with-130ms-block-times-and-650ms-finality-implications-for-crypto-traders) | +| NEAR Protocol | 600ms | [1.2 seconds](https://pages.near.org/blog/blink-and-its-final-near-launches-600ms-blocks-and-1-2s-finality/) | +| Solana | 400-600ms | [13 seconds](https://solana.com/developers/guides/advanced/confirmation) | +| Arbitrum | [250ms](https://docs.arbitrum.io/launch-arbitrum-chain/faq-troubleshooting/troubleshooting-building-arbitrum-chain#what-is-the-max-theoretical-tps-for-an-arbitrum-chain) | [~15 minutes](https://docs.arbitrum.io/how-arbitrum-works/inside-arbitrum-nitro#step-4-finality) | +| Ethereum Sepolia | [2.4 minutes (12 blocks)](https://ethereum.stackexchange.com/questions/319/what-number-of-confirmations-is-considered-secure-in-ethereum) | [~15 minutes](https://ethereum.org/roadmap/single-slot-finality/) | + +Despite what these theoretical numbers say, real-world performance can differ based on different factors, such as: +- Overhead from the RPC: free RPCs are expected to have higher delays +- Overhead from the network: chances are that your transaction will fall in-between blocks and need to wait for it to be processed + +Because of this, we decided to run an empirical benchmark to measure actual finality times and transaction fees across these blockchains. + +## Benchmarking the Chains + +To measure the **empirical** finality of the six blockchains mentioned above (NEAR, Aptos, Solana, Sui, Ethereum Sepolia, Arbitrum), we +built a simple benchmarking script which makes **30 transactions** per network, and computes how much - on average - a transaction takes +to settle when using both **optimistic** and **hard finality**. + +To be as fair as possible, we: + +- Used the `mainnet` network of all chains +- Used the simplest possible operation: a native token transfer +- Used free and public RPC endpoints + +### Defining Empirical Finalities + +It is important to remark that there is not a single definition on what optimistic finality means, and it can vary between blockchains. Here is how each blockchain in our benchmark defines optimistic finality: + +#### NEAR Protocol +On NEAR, optimistic finality is reached when the transactions reaches [`EXECUTED_OPTIMISTIC`](https://docs.near.org/api/rpc/transactions) finality, +which means the transaction is [included in a block and all non-refund receipts have finished their execution](https://docs.near.org/protocol/transactions/transaction-execution). + +For hard finality, one can simply wait for the transaction to reach [`FINAL`](https://docs.near.org/api/rpc/transactions). + +#### Aptos +For Aptos, optimistic finality is measured as the time when the transaction is submitted and the transaction hash is returned, without waiting for confirmation. +This represents the fastest possible response but with the least guarantees. + +For hard finality, we use [`waitForTransaction`](https://aptos.dev/build/sdks/ts-sdk/building-transactions) which waits until the transaction is committed to the blockchain and execution succeeds. + +#### Solana +Solana uses the [`confirmed` commitment level](https://docs.solanalabs.com/consensus/commitments) for optimistic finality, which means 66%+ of the validator stake +has voted on the block. For hard finality, the [`finalized` commitment level](https://solana.com/docs/advanced/confirmation) requires 31+ confirmed blocks +to be built on top of the transaction's block, making it economically irreversible. + +#### Sui +On Sui, their API exposes a function `WaitForLocalExecution` which waits for the local node to execute the transaction. + +For hard finality, the method [`WaitForEffectsCert`](https://docs.sui.io/concepts/sui-architecture/transaction-lifecycle) waits for an effects certificate, +which is a guarantee that the transaction will be included in a checkpoint and cannot be reverted. + +#### Ethereum +We did not find consensus on what defines optimistic finality in Ethereum, but multiple forums suggested to use 12 confirmations. + +For hard finality we can simply wait until the block is tagged as [`finalized`](https://ethereum.org/developers/docs/blocks/), which indicates the block has been accepted +as canonical by more than 2/3 of validators, typically occurring after two epochs (~12-13 minutes for Ethereum). + +#### Arbitrum + +Arbitrum is a layer 2 solution on Ethereum, meaning that it processes transactions off-chain and submits them to Ethereum for finality. For optimistic finality, +we simply measured the time it takes for a transaction to be included in an Arbitrum block (i.e. waited for `1 confirmation`). + +For hard finality, Arbitrum relies on Ethereum's finality guarantees, meaning that it will take as long as Ethereum to reach hard finality (~15 minutes), plus some +time for the API to reflect the finality status. + +## Results + +### Finality Times +Here is a table with the average finality times observed during our benchmark, ordered from fastest to slowest in Hard Finality: + +| Blockchain | Optimistic Finality | Hard Finality | Theoretical Hard Finality | +|---------------|---------------------|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------| +| Aptos | 0.20s ± 0.01s | 0.62s ± 0.04s | [650ms](https://blockchain.news/flashnews/aptos-sets-industry-record-with-130ms-block-times-and-650ms-finality-implications-for-crypto-traders) | +| Sui | 1.49s ± 0.08s | 3.15s ± 0.03s | [500ms](https://docs.sui.io/concepts/sui-architecture/consensus#transaction-throughput) | +| NEAR Protocol | 2.35s ± 0.31s | 3.50s ± 0.24s | [1.2 seconds](https://pages.near.org/blog/blink-and-its-final-near-launches-600ms-blocks-and-1-2s-finality/) | +| Solana | 0.94s ± 0.25s | 12.97s ± 0.28s | [13 seconds](https://solana.com/developers/guides/advanced/confirmation) | +| Ethereum | 36.62s ± 15.05s | 1150.56s ± 5.92s | [~15 minutes](https://ethereum.org/roadmap/single-slot-finality/) | +| Arbitrum | 3.21s ± 0.31s | 1440.02s ± 161.90s | [~15 minutes](https://docs.arbitrum.io/how-arbitrum-works/inside-arbitrum-nitro#step-4-finality) | + +We can see that Aptos was the closest to its theoretical finality times, while for the rest of the chains there is an overhead +cause by the network and RPC layers. + +### Transaction Fees + +Here is a summary of the average transaction fees observed, ordered from cheapest to most expensive in USD: + +| Blockchain | Avg Fee (Native) | Avg Fee* (USD)| Fee Documentation | +|------------|------------------|---------------|--------------------------------------------------------------------| +| Arbitrum | 0.00000021 | $0.00000004 | [Docs](https://docs.arbitrum.io/how-arbitrum-works/gas-fees) | +| Aptos | 0.000012 | $0.00002 | [Docs](https://aptos.dev/network/blockchain/gas-txn-fee) | +| NEAR | 0.000045 | $0.00007 | [Docs](https://docs.near.org/protocol/transactions/gas#cost-for-common-actions) | +| Solana | 0.0000050 | $0.0006 | [Docs](https://solana.com/docs/core/fees) | +| Sui | 0.0015028 | $0.002 | [Docs](https://docs.sui.io/concepts/tokenomics/gas-in-sui) | +| Ethereum | 0.0000035 | $0.01 | [Docs](https://ethereum.org/en/developers/docs/gas/) | + +_* Based on token prices at the time of the benchmark_ + +It is important to note that transaction fees can vary based on network congestion, gas price, and of course the token price at the time of the transaction. +However, they will not vary based on the finality model used, since both optimistic and hard finality transactions pay the same fee structure. + +
+ + Token Prices at Benchmark Time + +| Blockchain | Token Price | +|------------|-------------| +| Ethereum | $3070 | +| Sui | $1.49 | +| Solana | $129.00 | +| Aptos | $1.59 | +| NEAR | $1.56 | +| Arbitrum | $0.20 | + +
+ +## Finality and Hardware Requirements + +Finally, we looked into the hardware requirements needed to run a full node or validator for each blockchain. Here is a summary of the minimum recommended hardware specs: + +| Blockchain | Hardware Requirements | +|------------------|----------------------------------------------------------------------------------------------------| +| Aptos | [32 cores, 64GB RAM, 3TB SSD](https://aptos.dev/network/nodes/validator-node/node-requirements) | +| Sui | [24 cores, 128GB RAM, 4TB NVMe](https://docs.sui.io/guides/operator/validator/validator-config) | +| Solana | [12 cores, 256GB RAM, 2TB SSD, 1Gbps](https://docs.solanalabs.com/operations/requirements) | +| NEAR Protocol | [8 cores, 8GB RAM, 1TB SSD](https://near-nodes.io/validator/hardware-validator) | +| Arbitrum | [4 cores, 16GB RAM, NVMe SSD](https://docs.arbitrum.io/run-arbitrum-node/run-full-node) | +| Ethereum Sepolia | [4 cores, 16GB RAM, 2TB SSD](https://geth.ethereum.org/docs/getting-started/hardware-requirements) | + +Interestingly, there is a correlation between **higher hardware requirements** and **better performance** (lower finality times). +This explains how Aptos and Sui achieved the fastest finality times, as they both require significantly more powerful hardware +for their validators - with the exception of Solana, which despite its high hardware requirements, has a slower hard finality due to its consensus design. + +## Summary + +| Blockchain | Hard Finality | Soft Finality | Cheapest Fees | Lowest Hardware | +|------------|---------------|---------------|---------------|-----------------| +| Aptos | 1st | 1st | 2nd | 6th | +| Sui | 2nd | 3rd | 5th | 5th | +| NEAR | 3rd | 4th | 3rd | 3rd | +| Solana | 4th | 2nd | 4th | 4th | +| Ethereum | 5th | 6th | 6th | 2nd | +| Arbitrum | 6th | 5th | 1st | 1st | + +## Resources + +The complete benchmark data and analysis tools are open source and available on GitHub: + +- **Benchmark Data**: [matiasbenary/benchmarks](https://github.com/matiasbenary/benchmarks) - Raw benchmark results and histograms + + +While conducting this benchmark, we discovered that Aptos performed [similar testing](https://medium.com/aptoslabs/sub-second-latency-aptos-delivers-instant-transactions-4f6e8113c788) against Arbitrum, Avalanche, Base, Near, Optimism, Polygon, Solana, and Sui. + +--- + +*Want to build on NEAR? Check out our [developer documentation](/smart-contracts/what-is) to get started.* diff --git a/blog/2026-01-06-near-rust-devtools-2025.mdx b/blog/2026-01-06-near-rust-devtools-2025.mdx new file mode 100644 index 00000000000..614cdec2ffa --- /dev/null +++ b/blog/2026-01-06-near-rust-devtools-2025.mdx @@ -0,0 +1,145 @@ +--- +title: "Rust Tooling: Status and Evolution on 2025" +description: "Some important changes are coming to the Rust tooling ecosystem, learn more in this blogpost!" +date: 2026-01-06 +author: "Vlad Frolov" +tags: [articles] +--- + +{/* BYLINE:start */} +_**Vlad Frolov** · January 6, 2026_ +{/* BYLINE:end */} + +Some important changes are coming to the Rust tooling ecosystem, learn more in this blogpost! + +# 1. Executive Summary & Strategic North Star + +The primary objective for the evolution of the Rust tooling ecosystem is **Stabilization and Ergonomics**. + +Currently, many tools still rely on `nearcore` internal crates. Because `nearcore` releases frequently bump `0.x` versions, this triggers a cascade of breaking changes across the ecosystem. + +* **The Goal:** Reach **1.x Stable Releases** for our core primitives and API clients. +* **The Method:** Migrate away from direct `nearcore` dependencies in favor of standalone, stable crates (e.g., `omni-transaction-rs`, `near-api-rs`). + +## The "Decoupling" + +To achieve independence from `nearcore`, we must migrate the tooling stack in this specific order: + +1. **`omni-transaction-rs`** + **`near-account-id-rs`** + **`near-gas-rs`** (standalone primitives) +2. new **`near-jsonrpc-client-rs`** (currently known as `near-openapi-client-rs` - the client generated from OpenAPI spec generated from nearcore types) +3. **`near-api-rs`** +4. **`near-cli-rs`** & **`cargo-near`** + +# 2. Component Status Overview + +| Crate | Status | Priority | Key Action Item | +| --- | --- | --- | --- | +| **near-sdk-rs** | 🚀 Active Dev | High | Prepare v6.x release | +| **near-api-rs** | 🛠 Evolving | High | Absorb `near-cli-rs` logic; 1.x stabilization. | +| **omni-transaction-rs** | 🗝 Key | High | "Final Boss" for decoupling types. | +| **near-cli-rs** | ♻️ Refactor | Medium | Migrate `common.rs` to `near-api-rs`. | +| **near-openapi-client-rs** | 📦 Migration | Medium | Rename, Move to Org, Release 1.0. | +| **near-workspaces-rs** | 🛑 Deprecating | Low | Deprecate in favor of `near-api-rs` + `near-sandbox-rs`. | +| **bos-cli-rs** | 💀 EOL | None | End of Life. | + +--- + +# 3. Core SDKs & APIs + +## `near-sdk-rs` [Active Development] + +* **Status:** High activity. Preparing for **v6.x** release. +* **Key Focus:** + * Incorporating breaking changes like [structured errors support](https://github.com/near/near-sdk-rs/pull/1165), `impl Into<>` and `impl AsRef<>` arguments for improved usability, and [Promise API changes](https://github.com/near/near-sdk-rs/pull/1459). + * Reviewing PRs with strict scrutiny regarding ABI compatibility. + +## `near-api-rs` [Strategic Core] + +* **Status:** Stable design, but evolving ergonomics. +* **Strategic Goal:** This is the primary replacement for `nearcore` dependencies when it comes to off-chain development for NEAR. It must reach a **1.x stable release** to stop the cascade of breaking changes. +* **Action Items:** + * **Migration:** Make sure that the common helpers logic from `near-cli-rs/common.rs` can be implemented with `near-api-rs` high-level APIs. + * **Features:** Audit for missing latest protocol features. + * **Ergonomics:** Make final pressure testing of the developer experience before locking in v1.0, e.g. migrating existing projects from `near-workspaces-rs` to `near-api-rs`. + +## `near-openapi-client-rs` (becoming `near-jsonrpc-client-rs`) + +* **Status:** Migration pending. +* **Notes**: There is already a `near-jsonrpc-client-rs` crate, which depends on `nearcore` crates. The OpenAPI spec that was introduced to `nearcore` and is automatically generated from the `nearcore` types. It is now used to automatically generate the clients in Rust, TypeScript, Python, Kotlin, Swift, and we want to migrate all the downstream tooling to leverage the generated client instead of manually maintain it. +* **Migration Strategy:** + * Take the current manual `near-jsonrpc-client-rs`, branch it as `0.20.x`. + * Merge the currently separate `near-openapi-client-rs` codebase as the new `main`. + * Make sure that the enums/structs that could change over time are marked as `#[non_exhaustive]` to prevent breaking changes in the future. + * Release as **1.0**. + * Update `near-api-rs` to use the released version (it already depends on `near-openapi-client-rs` instead of `near-jsonrpc-client-rs`, so the migration should be smooth) + +### `near-sandbox-rs` [Stable] + +* **Status:** Stable code, but high friction for new users. +* **Issues:** Documentation and examples are too simple or too complex, and not designed for users' usecase in mind. +* **Action Item:** Improve documentation. Cross-link heavily with `near-api-rs` examples to show how they work together as the replacement for workspaces. + +# 4. CLI Tools + +## `near-cli-rs` [Feature Complete / Refactoring] + +* **Status:** Functionally complete. +* **Maintenance:** Routine dependency updates, bug fixes, and minor UX improvements. +* **Major Refactor:** Identify general-purpose functions in `common.rs` and migrate them to `near-api-rs`. + * Eventually, `near-cli-rs` should be a thin wrapper around `near-api-rs`. + +## `cargo-near` [Feature Complete] + +* **Status:** Maintenance mode. +* **Tasks:** Ensure compatibility with latest `near-sdk-rs` and `near-cli-rs`. + +## `cargo-near-new-project-template` + +* **Status:** Low maintenance. +* **Tasks:** Update `cargo-near` version occasionally. + +## `near-validators-cli-rs` + +* **Status:** Maintenance mode. +* **Tasks:** Keep lockstep with `near-cli-rs` releases. + +# 5. Primitives & Types (The Foundation) + +## `omni-transaction-rs` + +* **Status:** Mostly up-to-date. +* **Context:** This crate is the key to decoupling from `nearcore` types. +* **Roadmap:** We must aggressively migrate the rest of the stack to use this crate. + * *Flow:* `near-openapi-client-rs` → `near-api-rs` → `near-cli-rs` → `cargo-near`. + +## `near-account-id-rs` [Stable] + +* **Status:** Stable (v2.0). +* **Note:** Recently bumped to v2.0 due to the introduction of "0s" accounts. + +## `near-gas-rs` [Stable] + +* **Status:** Stable. +* **⚠️ Implementation Note:** `nearcore` uses a wrapper type over this crate for backward compatibility. + * `nearcore`: Serializes gas (`u64`) as JSON **numbers**. + * `near-gas-rs`: Serializes gas as JSON **strings**. + * *Both* can deserialize from either number or string. + +## `near-sdk-abi` [Stable / Critical] + +* **Status:** Frozen / High Caution. +* **Warning:** Any change here is likely a breaking change for the whole ecosystem. Modify only if absolutely necessary. + +## `borsh-rs` [Stable] + +* **Status:** Stable. +* **Maintenance:** Review occasional PRs from community contributors. + +# 6. Deprecation & EOL + +* **`near-workspaces-rs`**: **DEPRECATE.** Users should be directed to the combination of `near-api-rs` (for interaction) + `near-sandbox-rs` (for environment). +* **`bos-cli-rs`**: **EOL.** No maintenance. + +# 7. Future Considerations + +* **`near-cryptohash-rs`**: Assess the need for a standalone crate for `CryptoHash` to avoid duplication (currently, there are at least 3 copies: `nearcore`, `near-sdk-rs`, `near-api-rs`/`near-openapi-client-rs`) diff --git a/blog/2026-01-24-near-intents-2026.mdx b/blog/2026-01-24-near-intents-2026.mdx new file mode 100644 index 00000000000..785fc11f075 --- /dev/null +++ b/blog/2026-01-24-near-intents-2026.mdx @@ -0,0 +1,175 @@ +--- +title: "Deep Dive into NEAR Intents" +description: "Let's take a deep dive into the architecture of cross-chain swaps on NEAR Protocol, exploring how NEAR Intents and the PoA Bridge work together to…" +date: 2026-01-24 +author: "denbite" +tags: [articles] +--- + +{/* BYLINE:start */} +_**denbite** · January 24, 2026_ +{/* BYLINE:end */} + +Let's take a deep dive into the architecture of cross-chain swaps on NEAR Protocol, exploring how NEAR Intents and the PoA Bridge work together to enable secure and efficient asset transfers across blockchains. + +--- + +## Introduction + +Given the bast amount of chains and assets that have surged, it is now common for users to need to swap assets across chains (e.g. swap USDT on Ethereum for SOL on Solana). + +Since **each blockchain is a separate and isolated system** - indeed, blockchains do not have any inherent way to communicate with each other - different off-chain services emerged to enable cross-chain swaps. + +Today, I want to take a deep dive into the technical foundations on how cross-chain swaps work on NEAR Protocol, and understand which features of the protocol enabled it to be robust and secure. + +{/* + +Particularly, we will focus on two components: + +1. NEAR Intents, a relatively new product which enables intent-based swaps +2. The PoA Bridge, which handles cross-chain asset transfers + +Particularly, I want to focus on the technical foundations behind them. For that, we will look at which features of NEAR Protocol make this architecture possible, and why they allow it to be built in a robust and secure way. We will go a bit deeper technically and break down how the system is structured, and what exactly made this design feasible in the first place. */} + +But before, let's briefly review how cross-chain swaps have traditionally worked, and what challenged they faced, to better understand why NEAR's approach is unique and powerful. + +--- + +## The problem with cross-chain swaps + +{/* At a high level, cross-chain swap usually combines two things: bridging assets from one blockchain to another, and exchanging them along the way. + +Bridges are an essential part of any cross-chain swap, but at the same time they are also its weakest point. */} + +Let's take a simple example: you want to swap `100 USDT` on Ethereum for some amount of native `Solana` tokens. There are two main approaches to achieve this: + +#### 1. Bridge, then swap +You send `100 USDT` from your `Ethereum` account to a `Solana` wallet that you control using a **multi-chain** bridge. Once the funds arrive, you go to any swap in `Solana` to convert your `USDT` into `SOL`. + +The main point of trust here is in the **bridge itself**. You need to trust that the bridged assets will arrive in the target chain, and that the bridge is secure enough to prevent theft or loss of funds. + +#### 2. Use a Counterparty +Instead of bridging the tokens, you find a counterparty who already has `SOL` and wants `USDT` on `Ethereum`. You agree on a swap rate, send them your `100 USDT` on `Ethereum`, and they send you `SOL` tokens to your `Solana` wallet in return. + +From a user's perspective this can feel faster, but it immediately raises a security question: **how do you make this operation atomic?** You do not want to send your `USDT` and never receive `SOL`, and the counterparty does not want to send `SOL` without a guarantee that they will receive your `USDT`. + +Achieving atomicity across multiple blockchains is **extremely difficult** because each chain has its own execution model, timing, and finality. + +--- + +## The best of both worlds + +NEAR combines both bridge and counterpart approaches into a single, seamless experience that leverages the strengths of each while mitigating their weaknesses. + +For this, NEAR relies on two key components: + +1. The PoA Bridge, a bridge built by [Defuse Labs](https://defuse.org/) (the team behind NEAR Intents) that moves assets from and to NEAR via a treasury-based model +2. NEAR Intents, that **finds a counterparty** and **executes the swap** atomically on NEAR + +For the user, the experience is simple and intuitive: + +1. Tell NEAR Intents that you want to swap `100 USDT` from `Ethereum` and receive `SOL` on a specific `Solana` address (that you control) +2. NEAR Intents finds a counterparty who is willing to take the opposite side of the swap, and gives you a quote +3. If you agree to the quote, NEAR Intents provides you with an address on `Ethereum` where to send your `100 USDT` +4. Once you send the funds on `Ethereum`, you get the `SOL` tokens on `Solana` + +Behind this simple user experience, there is a complex architecture that makes it all possible. The key to understanding it is to look at the technical foundations that NEAR Protocol provides, and how they enable this design in a way that is secure, efficient, and user-friendly. + +--- + +## Technical Foundations + +The core technical foundation that makes all of this possible is the combination of [**chain signatures**](/chain-abstraction/chain-signatures) (multi-party computation), the protocol's ability to handle true **asynchronous execution**, the **yield and resume** mechanism of smart contracts to handle long-lived flows without excessive costs, and **callback-based token standards**. + +### Chain Signatures +[Chain Signatures](/chain-abstraction/chain-signatures) allows **smart contracts to sign transactions** for NEAR and **other chains** in a secure and deterministic way. It is based on multi-party computation (MPC), where a group of participants collectively generates a signature without any single party ever owning the full private key. + +While MCP is a powerful primitive that exists on other chains, in NEAR it is naturally integrated into the on-chain execution thanks to the fact that smart contracts can yield and resume computation. + +### Yield and Resume + +Signature generation is not instantaneous, it is an interactive process that takes time and unfolds over multiple blocks. On NEAR, this is not an issue, because smart contracts can [**yield and resume computation**](/blog/2024-05-30-yield-resume). This is, they can pause their execution, wait for an external event (like a signature being ready), and then continue from where they left off once the event occurs. + +Another advantage of yielding and resuming is that contracts do not pay gas while they are waiting, which makes it economically viable to wait for signatures that can take maybe seconds to be generated, without worrying about the cost of keeping the contract alive during that time. + +### Asynchronous Execution + +It is important to remark that, contracts can yield and resume computation **without blocking the blockchain** or **even themselves**! Indeed, thanks to the asynchronous nature of NEAR, contracts can have multiple flows in flight at the same time, each waiting for different signatures or events, and the chain can process them all in parallel without any bottlenecks. + +### Mature Token Standards +NEAR Intents builds on [NEP-245](https://github.com/near/NEPs/blob/master/neps/nep-0245.md) (analogue of ERC-1155 on Ethereum). This Multi-Token standard allows a single contract to manage balances for many different tokens, instead of deploying a separate contract per asset. This significantly simplifies intent execution - swaps can involve multiple assets, partial fills can be aggregated, and state can be tracked in one place without unnecessary cross-contract calls. + +--- + +## Overview of the swap flow + +Now that we have covered the technical foundations, let's see how they come together in practice to enable a cross-chain swap. We will use the example of swapping `100 USDT` from `Ethereum` for some amount of `SOL` on `Solana`, but the same principles apply to any other asset and chain supported by NEAR Intents. + + + + +In this post, we will explain in detail the manual process of using intents, for production apps the 1-Click API abstracts away all the complexity and allows you to execute the entire flow with a single API call. You can read more about it in the [docs](https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api). + +### Step 1: Deposit funds from Ethereum to NEAR + +Since we want to make a cross-chain swap, the first step that we need to perform is deposit the funds in NEAR Intents. For this, the user can call the [`get_address`](https://docs.near-intents.org/near-intents/market-makers/passive-deposit-withdrawal-service) endpoint in the NEAR Intents API, which will return a native `Ethereum` address into which the user can send their `USDT`. + + + +Chain Signatures allow NEAR to deterministically derive ECDSA keys (and EDDSA) that can sign arbitrary payloads. `Ethereum` uses ECDSA keys, for which NEAR Intents can get a unique key and derive a valid `Ethereum` address from it. + +#### Starting the Swap + +From the user's point of view, the action is simple - they send their `USDT` to this `Ethereum` address. Once the transaction is included and finalized on `Ethereum`, the deposit is automatically detected by the PoA Bridge. + +The PoA Bridge then instructs the corresponding token contract on NEAR to mint the bridged tokens. For `USDT`, this is the `eth-0xdac17f958d2ee523a2206206994597c13d831ec7.omft.near` contract, which mints the same amount that was deposited on Ethereum. + +These newly minted tokens are then transferred directly to the NEAR Intents contract at `intents.near`. As a result, the bridged tokens end up in the `intents.near` contract. + +{/* The NEAR Intents contract plays two important roles. First, it will later act as the verifier for intents, which we will cover in the next step. Second, it implements both the NEP-141 Fungible Token and the NEP-245 Multi-Token standards. The last one allows a single contract to manage balances of many different assets, which is exactly what NEAR Intents needs. + +As a result, the bridged tokens end up held by the `intents.near` contract, but its internal state records that they belong to your NEAR account. */} + +#### What happens to the funds sent to the deposit address? + +Since the address was controlled via Chain Signatures, NEAR Intents can generate valid transactions to move funds out of them. After the deposit is finalized, the funds are automatically transferred into a shared treasury address for that chain. + +There is one treasury per supported chain, and all deposits are consolidated there. + +### Step 2: Executing the swap inside NEAR Intents + +Once the funds are available on NEAR, the actual exchange happens inside the NEAR Intents contract. At a high level, this contract exists for one reason - to make intent-based operations verifiable and atomic. Every intent-based swap ultimately goes through this contract, and nothing is executed unless it passes all of its checks. + +Before any swap can happen, the user must register a public key with the `intents.near` contract. This key will later be used to sign intents and is stored on-chain so the contract can verify that future intents are authorized. It can be registered either by calling the contract directly, or by submitting a dedicated `add_public_key` intent via the [Solver Bus API](https://docs.near-intents.org/near-intents/market-makers/bus/solver-relay). + +Once the key is registered, the swap flow becomes straightforward. In our case, the user now holds bridged USDT on NEAR `eth-0xdac17f958d2ee523a2206206994597c13d831ec7.omft.near`, which represents USDT originally deposited from Ethereum. The user wants to swap this USDT for SOL, represented on NEAR as `sol.omft.near`, which is the bridged representation of native SOL. + +The first step is requesting a quote. The user calls the Solver Bus API and specifies either: + +- Exact amount in: "I am willing to spend 100 USDT, how much SOL can I get?", or + +- Exact amount out: "I want to receive 1 SOL, how much USDT do I need to spend?" + +The Solver Bus queries active solvers and within a few seconds returns one or more quotes, each quote represents a solver's willingness to take the opposite side of the trade. If the user is satisfied with the offer provided by the solver, they can sign a token swap intent (i.e. a `TokenDiff` intent) and send it to the Solver Bus for execution along with the solver's quote hash(es) using `publish_intent` method. + +From there, user's signed intent is being aggregated with others to form a single execution batch, and then it's relayed to the Intents contract for execution. As a result, the API returns a hash that can be used to track the execution status. + +### Step 3: Withdrawing funds from NEAR to Solana + +The final step is moving the result of the swap out of NEAR and into Solana, which - just as the swap - is driven by intents. + +To start the withdrawal, a user creates the `FtWithdraw` intent, that is signed with the same registered public key and includes a memo field that specifies the destination account. Because in our case the token being withdrawn is `sol.omft.near`, it's clear that the destination address must be a Solana address (since `sol.omft.near` represents bridged SOL tokens). + +The signed intent is submitted to the Solver Bus API and then is relayed to `intents.near` contract for execution. Its execution triggers a cross-contract call to the token contract itself, in this case, `sol.omft.near`. Concretely, the `intents.near` contract makes a cross-contract call to `ft_transfer` method on `sol.omft.near`, transferring the tokens to the token contract itself. For this contract, such a transfer is interpreted as a burn operation. As a result, the specified amount of tokens is burned, and a corresponding on-chain event is emitted. + +This burn event is automatically detected by the NEAR Intents infrastructure. A cryptographic proof is generated that confirms the tokens were indeed burned on NEAR. Once this proof is available, using Chain Signatures, NEAR Intents constructs and signs a transaction that transfers the real assets from the Solana-side treasury directly to the destination address specified in the intent. The transfer is executed on Solana, completing the withdrawal. + +## Further Exploration + +If you're interested in integrating cross-chain swaps into your own service, the recommended entry point is the [1Click API](https://docs.near-intents.org/near-intents/integration/distribution-channels/1click-api). It provides a single, high-level interface that executes the entire flow described above — deposit, swap, and withdrawal — with one request. In practice, this acts as a thin abstraction over NEAR Intents and the PoA Bridge and removes the need to manually orchestrate each step. + +To see the flow end to end from a user perspective, the main [NEAR Intents UI](https://near-intents.org/) is a good place to start. It walks through the same stages described in this article, but through an interactive interface, which helps build intuition. + +If you want to understand how NEAR Intents works in a concrete implementation, there is [example repository](https://github.com/near-examples/near-intents-examples) that demonstrate how the system is wired together in practice. It's useful when you want to trace real requests, intent construction, and execution paths. + +Finally, the full technical documentation lives at [docs.near-intents.org](https://docs.near-intents.org). It covers the protocol concepts, APIs, intent types, solver interaction, and integration details in depth, and is the best reference when you want to go deeper or build something on top of NEAR Intents. diff --git a/blog/2026-02-23-shade-agent-framework-2.0.mdx b/blog/2026-02-23-shade-agent-framework-2.0.mdx new file mode 100644 index 00000000000..ba496e79253 --- /dev/null +++ b/blog/2026-02-23-shade-agent-framework-2.0.mdx @@ -0,0 +1,128 @@ +--- +title: "Shade Agent Framework 2.0" +description: "The biggest update to the Shade Agent Framework has been released since launch. It aims to enable more production-ready builds, a more flexible…" +date: 2026-02-23 +author: "Owen Hassall" +tags: [updates, ai, shade-agents] +--- + +{/* BYLINE:start */} +_**Owen Hassall** · February 23, 2026_ +{/* BYLINE:end */} + +The biggest update to the Shade Agent Framework has been released since launch. It aims to enable more production-ready builds, a more flexible developer experience, and it comes with significant architectural changes. + + +The previous version of the Shade Agent Framework has **known critical vulnerabilities**. You should upgrade your agent to 2.0 as soon as possible. + +## A Shift in Mental Model + +Shade Agent 2.0 is not a small iteration. It reflects a different way of building and deploying Shade Agents. + +**Previously**, the framework leaned on global, abstract agent contracts and a separate API service. That made early development straightforward but production use harder: you had less control over contract behavior, deployment was split across env vars and flags, and the API lived in its own Docker image. + +**In Shade Agent Framework 2.0**, the **Shade Agent API** is a single TypeScript library that runs **inside your agent’s codebase** instead of a separate service. The **agent contract** is included in your repo so you can change and extend it for your use case. The **CLI** is built around a single config file and has built-in credential management, making deploy and whitelist flows are predictable and easier to script. + +The result is a framework that’s easier to reason about, easier to customize, and better suited to production. Below is a summary of the main changes for the API, CLI, and agent contract, with links to the docs so you can get started. + +--- + +## Shade Agent API + +The Shade Agent API no longer offers multi-language support. It has been consolidated into a single **TypeScript/JavaScript** library (`@neardefi/shade-agent-js`) that runs within your agent’s codebase instead of a separate Docker image. + +### How the API Has Changed + +Previously, the API was a separate Docker image (and HTTP service); you called standalone functions that talked to that service. In 2.0, you create a client in your code and use it for everything. Registration and funding now explicit methods instead of automatic on boot. + +**Before (1.x):** No client—you installed the package and called functions that hit the API internally (or HTTP in other languages): + +```ts +import { agentAccountId, agent, agentCall, agentView } from '@neardefi/shade-agent-js'; +// API assumed to be running (Docker / localhost:3140); env vars for config +``` + +**After (2.0):** One client, created once with your config: + +```ts +import { ShadeClient } from "@neardefi/shade-agent-js"; + +const agent = await ShadeClient.create({ + networkId: "testnet", + agentContractId: process.env.AGENT_CONTRACT_ID, + sponsor: { accountId: process.env.SPONSOR_ACCOUNT_ID, privateKey: process.env.SPONSOR_PRIVATE_KEY }, + rpc: provider, +}); +// Then: await agent.register(), await agent.fund(0.3), etc. +``` + +**Account ID:** Same idea, different shape, you now use the client instance and get the value directly (no response object). + +```ts +// Before: const res = await agentAccountId(); const accountId = res.accountId +const accountId = agent.accountId(); +``` + +**Balance:** Balance is now a method on the client and returns human-readable NEAR (e.g. `1` = one NEAR), not yoctoNEAR. + +```ts +// Before: const res = await agent("getBalance"); const balance = res.balance // yoctoNEAR +const balance = await agent.balance(); // human-readable, e.g. 0.3 +``` + +**Call and view:** Call and view have stayed the same but are accessible via the client instance instead of a standalone function. + +```ts +// Before: agentCall({ methodName, args, gas }) / agentView({ methodName, args }) +const result = await agent.call({ + methodName: "example_call_function", + args: { arg1: "value1", arg2: "value2" }, + gas: BigInt("300000000000000"), + deposit: "0", +}); +const viewResult = await agent.view({ + methodName: "example_view_function", + args: { arg1: "value1" }, +}); +``` + +**Request signature:** The old API had a dedicated `requestSignature({ path, payload, keyType })` helper. In 2.0, this has been deprecated, now if you want to call a function of the contract called `request_signature`, call it like any other function: + +```ts +// Before: requestSignature({ path, payload, keyType }) +const result = await agent.call({ + methodName: "request_signature", + args: { path, payload, key_type }, + deposit: "1", +}); +``` + +New methods include `agent.register()`, `agent.fund()`, `agent.isWhitelisted()`, and `agent.getAttestation()` for explicit control over registration, funding, and attestation; see the API reference for details. + +To learn how to install, configure, and use the API, see the **[Shade Agent API reference](/ai/shade-agents/reference/api)**. + +--- + +## Shade Agent CLI + +The Shade Agent CLI had a **total revamp**. Instead of being configured with a mix of environment variables and flags, it now centers on a **single `deployment.yaml` file**, with built-in credential management and command routing, taking inspiration from the NEAR CLI. + +You run `shade auth` to configure NEAR and Phala credentials, then use the commands `shade deploy` to deploy your Shade Agent, `shade plan` to preview the deployment, and `shade whitelist` to whitelist an agent's account ID. The `deployment.yaml` file drives contract deployment (including from source or WASM), measurement and PPID approval, Docker image build and publish, and deployment to Phala Cloud, so all deployment options live in one place. + +To learn how to install the CLI, use each command, and configure `deployment.yaml`, see the **[Shade Agent CLI reference](/ai/shade-agents/reference/cli)**. + +--- + +## Agent Contract + +Previously, the framework used **global agent contracts** that were abstract and easy to start with, but made production development and customization difficult. In 2.0, by default, a reference agent contract is included in the `shade-agent-template` repo, so you can edit and extend it to your needs (e.g. custom agent-gated functions, guardrails, and initialization). + +The reference agent contract also now uses a more robust external library for attestation verification (the [shade-attestation crate](https://github.com/NearDeFi/shade-agent-framework/tree/main/shade-attestation)). Instead of approving the codehash of a single Docker image, the contract now requires you to approve a set of measurements for more in-depth verification and a list of PPIDs that set the physical hardware the agent can run on. Local mode now requires you to whitelist the account ID of the agent you want to run locally, blocking any other account ID from controlling the contract for more consistent behavior when testing. + +To walk through the contract flow, initialization, attestation verification, and how to add your own agent-gated functions, see the **[Agent Contract reference](/ai/shade-agents/reference/agent-contract)**. + +--- + +## Next Steps + +Start your migration by **cloning the template** in the [quickstart](/ai/shade-agents/getting-started/quickstart/deploying) to explore the new setup. diff --git a/blog/overview.mdx b/blog/overview.mdx new file mode 100644 index 00000000000..e60f4a3b63b --- /dev/null +++ b/blog/overview.mdx @@ -0,0 +1,99 @@ +--- +title: "Blog" +description: "Latest posts from the NEAR docs team" +--- + +{/* AUTO-GENERATED by scripts/build-blog-index.js — do not edit by hand. */} + + + + The biggest update to the Shade Agent Framework has been released since launch. It aims to enable more production-ready builds, a more flexible… + + _2026-02-23 · Owen Hassall_ + + + Let's take a deep dive into the architecture of cross-chain swaps on NEAR Protocol, exploring how NEAR Intents and the PoA Bridge work together to… + + _2026-01-24 · denbite_ + + + Some important changes are coming to the Rust tooling ecosystem, learn more in this blogpost! + + _2026-01-06 · Vlad Frolov_ + + + While each blockchain has its own theoretical finality and transaction price, we wanted to know: how long does my app actually need to wait for a… + + _2025-12-11 · Matias Benary_ + + + As an backend developer you are adept at building robust services, managing databases, and ensuring system reliability. When you hear \"blockchain\" it… + + _2025-06-21 · Vlad Frolov_ + + + NEAR has a unique key management system that allows each account to have multiple access keys. Each of these keys can be one of two types: Full-Access… + + _2025-03-14 · Guille_ + + + 2024 was a great year for NEAR Docs! Let's take a look at what we achieved together + + _2025-01-01 · Guille_ + + + You can now login using MetaMask, WalletConnect and +400 Ethereum Wallets on Near! + + _2024-11-07 · Guille, Slava Karkunov_ + + + You might have noticed that a new tutorial has been added to the docs! This multi-part series is all about learning to build full applications on NEAR;… + + _2024-10-24 · Owen Hassall_ + + + As the NEAR ecosystem continues to decentralize, Pagoda will cease operations within the next six months and decentralize its functions into NEAR… + + _2024-08-13 · Eric Winer_ + + + From Thursday, July 11 to Saturday, July 13, many visitors to near.org and its subdomains (like dev.near.org and docs.near.org) were unable to reach… + + _2024-07-18 · Eric Winer_ + + + After careful consideration, Pagoda has decided to discontinue its active efforts to improve the B.O.S. Web Engine + + _2024-07-01 · Josh Ford_ + + + We have consolidated all our documentation in a single section, so you don't need to go searching around for it + + _2024-06-28 · Guille_ + + + In this article, we will cover how to install WSL and setup a NEAR development environment on Windows. + + _2024-06-05 · Lyudmil_ + + + dary! Legendary! NEAR protocol is getting updated with the ability to yield and resume computations + + _2024-05-30 · Guille_ + + + Chain signatures enable you to implement multichain and cross-chain workflows in a simple way. Let's take a look at a few possible use cases + + _2024-05-15 · Damian_ + + + We released a mayor reorganization of our repository, so we can improve docs for everyone... including us + + _2024-04-24 · Guille_ + + + Check check check. Is this thing on? Hello, world! + + _2024-04-23 · Guille_ + + diff --git a/docs.json b/docs.json index f7d7b803765..ce8a2a28399 100644 --- a/docs.json +++ b/docs.json @@ -681,6 +681,36 @@ ] } ] + }, + { + "tab": "Blog", + "icon": "newspaper", + "groups": [ + { + "group": " ", + "pages": [ + "blog/overview", + "blog/2026-02-23-shade-agent-framework-2.0", + "blog/2026-01-24-near-intents-2026", + "blog/2026-01-06-near-rust-devtools-2025", + "blog/2025-12-11-blockchain-finality-benchmark", + "blog/2025-06-21-near-for-backend-devs", + "blog/2025-03-14-benefits-of-multiple-keys", + "blog/2025-01-01-a-year-in-docs", + "blog/2024-11-07-hello-ethereum-wallets", + "blog/2024-10-24-new-tutorial", + "blog/2024-08-13-pagoda-services", + "blog/2024-07-18-near-org-outage", + "blog/2024-07-01-bos-web-engine-sunset", + "blog/2024-06-28-sdks-unified", + "blog/2024-06-05-getting-started-on-windows", + "blog/2024-05-30-yield-resume", + "blog/2024-05-15-chain-signatures-use-cases", + "blog/2024-04-24-reorganizing-docs", + "blog/2024-04-23-we-have-a-blog" + ] + } + ] } ] },