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, and the Aurora Labs team 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 Translator API, that translates Ethereum RPC calls into NEAR RPC calls
2. A "Wallet Contract" deployed on Near, that can process Ethereum transactions

Login​

Imagine your account on Metamask is 0xD79...314, and you want to login on a Near application.

The first time you login, ethereum-wallets.near will create the Near account 0xD79...314 for you.

Your new Near account already has a Wallet Contract deployed on it, which can translate ethereum transactions into account actions.

Using your Account​

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.

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 our tutorial and working example hello world frontend.

Resources​

1. Integration Tutorial

2. Hello World Example

3. Recording of the Ethereum Wallet Presentation

4. NEP-518, the proposal that started it all

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.

Start the tutorial here

Let's keep building! 🚀

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 (Request for Proposals)
• NEAR Lake (Request for Proposals)
• BigQuery Public Dataset (Request for Proposals)
• Node Snapshots
• State Sync
• Undocumented but critical services:
  • KitWallet Indexer API (Request for Proposals)
  • 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 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, Multichain Gas Relayer, and FastAuth 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 administration, the recently rebooted Security Assessment Program, and management of the near.org website will move under the purview of NEAR Foundation.
• Bug bounty 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
• Chain Hosted UI
• Modularization and Refactor 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 or the Infrastructure Committee.

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.

Our Use of Squarespace DNS​

The near.org domain is operated by Pagoda, 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. 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, 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. 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, 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 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 and 3DNS (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

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 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, 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, 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) 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.

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 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, near.social, dapdap or 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. 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 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 or Discord and we will be happy to assist you or answer any questions you have.

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
• /build/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: /build/smart-contracts/what-is.

Meanwhile, we have transformed the SDK page to be a simple landing page with links to:

• The Rust SDK reference docs
• The JS SDK reference docs
• The Smart Contract Section

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, 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) 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! 🚀

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).

Start WSL and Install Ubuntu​

Now we will spend some time in either PowerShell or Windows Terminal, which is a modern terminal application that supports various command-line tools and shells.

# 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

Enter the following commands to install all the packages that Rust and Node might need later:

apt-get update
apt-get install gcc make libudev-dev openssl pkg-config unzip -y

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.

Bellow 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, 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

Rust​

Rust 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 to run on the NEAR blockchain.

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

That's It​

At this point, we are ready to install the relevant tooling and start building on NEAR. Head over to the Quickstart section of the docs for more information or jump right into the examples.

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, 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.

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.

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.

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, 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​

// 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, PromiseError>,
) -> 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!

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.

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

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

Cross-chain Zero-friction onboarding​

Using unique features of the NEAR account model, Keypom 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

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 (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 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.

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.

In the beginning, our docs only needed to explain how to create smart contracts, and how to interact with them through a frontend. Fast forward to today, and we have more than 200 pages of documentation, covering topics such as chain abstraction, on-chain components, data infrastructure, and primitives such as NFT, FT.

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 (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/build/smart-contracts/what-is.md has the id: what-is, so it ends being served in the URL https://docs.near.org/build/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 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 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) 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.

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! 🚀

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.

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!

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! 🚀