Skip to content

Commit 9a72a76

Browse files
bucanerothisisjoshford
bucanero
and
thisisjoshford
authored
intents docs migration (#2458)
* intents * api files * api * add diagrams * openapi json * clean up * spell fix * 2455 suggestions (#2459) * fix: update intents layer to NEAR Intents * fix: update chain abst. overview to use near intents * fix: remove solver bus API & defuse SDK * feat: enhance intents overview and add diagram * feat: add intent creation & solvers * fix: update how it works and add solver compete to diagram * fix: update intro * fix: combine intent execution & settlement in overview * fix: remove architecture & rename POA bridge * clean up * fix: update intent example * fix: update solvers, execution, & examples * fix: create bridge section & update solver intro * fix: add solver diagram TODO * fix: update bridge * fix: add omni TODO * Apply suggestions from code review * change folder * Update website/sidebars.js * Update docs/2.build/1.chain-abstraction/what-is.md * Update overview.md * Update solvers.md --------- Co-authored-by: Josh Ford <[email protected]>
1 parent d677752 commit 9a72a76

File tree

8 files changed

+452
-3
lines changed

8 files changed

+452
-3
lines changed

‎docs/2.build/1.chain-abstraction/what-is.md

+3-3
Original file line numberDiff line numberDiff line change
@@ -41,15 +41,15 @@ With chain abstraction, both you and your users just focus on the core experienc
4141

4242
NEAR's chain abstraction framework consists of three core technologies that work together to create seamless cross-chain experiences:
4343

44-
1. [**Intent / Solver Layer**](#intent--solver-layer): A decentralized system where users express desired outcomes (like "swap Token A for Token B at the best price") without specifying technical details. A network of solvers then competes to fulfill these intents optimally, handling complex cross-chain operations behind the scenes.
44+
1. [**NEAR Intents**](#NEAR-Intents): A decentralized system where users express desired outcomes (like "swap Token A for Token B at the best price") without specifying technical details. A network of solvers then competes to fulfill these intents optimally, handling complex cross-chain operations behind the scenes.
4545

4646
2. [**Chain Signatures**](#chain-signatures): Enables NEAR accounts, including smart contracts, to sign and execute transactions on other blockchains (like Bitcoin or Ethereum), allowing cross-chain interactions.
4747

4848
3. [**OmniBridge**](#omnibridge): A multi-chain asset bridge that combines Chain Signatures with chain-specific verification methods for secure and efficient cross-chain transfers. Using a hybrid approach of MPC-based signatures and light clients, it significantly reduces verification times from hours to minutes while lowering gas costs across supported chains. The bridge serves as both a token factory and custodian, managing native and bridged tokens through a unified interface.
4949

50-
### Intent / Solver Layer
50+
### NEAR Intents
5151

52-
The Intent / Solver Layer (aka [NEAR Intents](https://pages.near.org/blog/introducing-near-intents/)) is a new type of transaction that allows information, requests, assets, and actions to be exchanged between users, services, and AI agents.
52+
[NEAR Intents](../../chain-abstraction/intents/overview.md) are a new transaction type that allows information, requests, assets, and actions to be exchanged between users, services, and AI agents.
5353

5454
This represents a paradigm shift in how users and AI agents interact with blockchain networks. Instead of directly executing complex transactions across multiple chains, users simply declare what they want to achieve, and the network determines how to make it happen.
5555

‎docs/chain-abstraction/intents/faq.md

+47
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
---
2+
description: Frequently Asked Questions
3+
---
4+
5+
# FAQs
6+
7+
### Is there a testnet deployment?
8+
9+
There's no `testnet` deployment and no plans for it. We recommend testing on NEAR `mainnet` with using separate dev/test NEAR accounts.
10+
11+
### Is there support for native NEAR deposits?
12+
13+
Only `ft_transfer_call` can be used to deposit NEP-141 tokens from Near to `intents.near`:
14+
15+
16+
```
17+
<TOKEN_ACCOUNT_ID>::ft_transfer_call({
18+
"receiver_id": "intents.near",
19+
"amount": "1234",
20+
"msg": "{\"receiver_id\": \"<ACCOUNT_ID>\"}"
21+
})
22+
```
23+
24+
Here is an example [receipt](https://nearblocks.io/txns/EwmeXzZJStA6e5JB49vgxNYJDemqeYCFGvPH7zapP1Fw#execution#4tyaF4MnMcNQVqrg3kXzsH9277ErDeCXS9g3c2keV38G) for that.\
25+
Parameter `msg` can also be empty, so that funds will be deposited to `sender_id` (i.e. caller of `ft_transfer_call`). Here is an example of such [transaction](https://nearblocks.io/txns/HoWpAR8dF5azsUVaQWrBW5VsRve5X4dwr9GGiHWj3R1P#execution).
26+
27+
### `tx_hash` in the `recent_deposit` response for all SOL deposits is empty
28+
29+
This information is not available for Solana because the mechanism of deposit tracking works a bit differently there.
30+
31+
### Is there a reason why my UTXOs aren't being swept on the BTC ? I sent 5,000 sats
32+
33+
This is a very small amount that is considered to be "dust" and there is a special business logic to process such small amount.
34+
35+
### How does the deposit process work?
36+
37+
The deposit process begins once the transfer transaction on the foreign network has been completed. When the balance of the user's unique deposit address has become positive our indexer generates a deposit event and assigns it a `PENDING` status.
38+
39+
The next step is collecting the current tokens in storage. The result of this process will be either a `COMPLETED` or `FAILED` status. Deposits with a `FAILED` status are currently handled manually and eventually updated to the `COMPLETED` status.
40+
41+
On EVM networks, deposits can bypass the `PENDING` status due to faster processing and transfer completion times.
42+
43+
The data structure for the `PENDING` and `FAILED` statuses is identical to that of the `COMPLETED` status.
44+
45+
Regarding BTC deposits: If you want to make a deposit to an account that hasn’t yet been connected to the application - this is possible but requires extreme caution. You can request a deposit address by calling the bridge API (`deposit_address`) and specifying the `account_id` parameter. The `account_id` can be a NEAR account, an EVM address, or a SOL address to which you have access.
46+
47+
It is recommended starting with a small amount for experimentation. After the deposit is completed, you can connect wallet and check the tokens.

‎docs/chain-abstraction/intents/intents-bridge.md

+66
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,66 @@
1+
---
2+
id: intents-bridge
3+
title: Intents Bridge
4+
sidebar_label: Intents Bridge
5+
---
6+
7+
8+
NEAR Intents utilizes multichain bridges for cross-chain settlement. Currently the following bridges are supported:
9+
10+
1. [Omni Bridge](#omni-bridge)
11+
2. [PoA Bridge](#poa-bridge)
12+
13+
---
14+
15+
## Omni Bridge
16+
17+
<!-- TODO: incoming omnibridge docs that will be added after this PR is merged. Once those are merged update this section. -->
18+
19+
The [Omni Bridge](../omnibridge/overview.md) is the primary bridge solution supporting multiple networks and deposit options.
20+
21+
### Supported Networks
22+
23+
- Bitcoin
24+
- Ethereum
25+
- Arbitrum
26+
- Base
27+
- Solana
28+
- TON
29+
30+
### Features
31+
- Support for `ft_transfer_call()` with `msg` field (active deposit)
32+
- Passive deposit functionality through:
33+
- NEAR-side smart contract owning deposit addresses
34+
- Protocol for bridging type correspondence (`ft_transfer` or `ft_transfer_call`)
35+
- Parameter-based derivation paths for deposit addresses
36+
37+
### Deposits & Withdrawals
38+
39+
The Omni Bridge handles deposits and withdrawals between other chains and NEAR FTs. For assets not yet supported by Omni Bridge, the [PoA Bridge](#poa-bridge) serves as an alternative.
40+
41+
#### Why Deposits are Required
42+
Users need to deposit funds into NEAR Intents accounts to trade, which differs from traditional AMMs. This design choice is based on:
43+
44+
1. The necessity of bridging external crypto to NEAR
45+
2. Single-transaction atomic settlement benefits
46+
3. Centralized risk comparable to existing NEP-141 tokens
47+
48+
Future migration to a fully sharded architecture will occur once sharded FT standards are developed.
49+
50+
---
51+
52+
## PoA Bridge
53+
54+
The Proof of Authority (PoA) Bridge provides an alternative solution for transferring assets between blockchain networks and NEAR Intents.
55+
56+
![bridge diagram](/docs/assets/intents/poa-bridge-user-docs.jpg)
57+
58+
### Usage Guide
59+
60+
The PoA Bridge API provides a JSON-RPC interface for managing deposits and withdrawals between supported networks and NEAR Intents. See the [official documentation](https://docs.near-intents.org/near-intents/poa-bridge#json-rpc-endpoint) for more details.
61+
62+
1. **Check Asset Support**: Verify your token is supported
63+
2. **Get Deposit Address**: Request a deposit address and transfer tokens
64+
3. **Monitor Deposits**: Track recent deposits via API
65+
4. **Manage Withdrawals**: Initiate and monitor withdrawals through contract or frontend
66+

‎docs/chain-abstraction/intents/overview.md

+152
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,152 @@
1+
---
2+
id: overview
3+
title: Intents
4+
sidebar_label: Overview
5+
---
6+
7+
In NEAR, an `intent` is a high level declaration of what a user wants to achieve. Think of it as telling the blockchain "what" you want to do, not "how" to do it. For example, instead of manually:
8+
- Finding the best DEX for a token swap
9+
- Calculating optimal routes
10+
- Executing multiple transactions
11+
12+
You simply express: "I want to swap Token A for Token B at the best price."
13+
14+
[NEAR Intents](https://near.org/blog/introducing-near-intents/) is a revolutionary transaction framework that simplifies blockchain interactions for:
15+
- Users
16+
- Services
17+
- AI agents
18+
19+
The key innovation is that users & developers no longer need to handle complex cross-chain transactions themselves. Instead, they declare their desired outcome, and a specialized network of solvers (including both AI agents and traditional market participants) competes to execute that intent in the most optimal way possible.
20+
21+
:::info
22+
The NEAR intents protocol and the documentation are under active development.
23+
24+
The protocol has been renamed from _Defuse_ to **NEAR Intents**.
25+
Any mentions of _Defuse_ in the source code and documentation are to be replaced.
26+
:::
27+
28+
## How It Works
29+
30+
1. [**Intent Creation**:](#intent-creation) A user or AI agent expresses a desired outcome _(ex: Swap Token A for Token B)_ and broadcasts the intent to a Solver Network of their choice.
31+
32+
2. [**Solvers Compete**:](#solvers) A off-chain decentralized network of solvers compete to fulfill the request in the most optimal way. When the solver network finds the best solution, it presents it as a quote to the originating user/agent for approval.
33+
34+
4. [**Intent Execution**:](#intent-execution) If the quote from the Solver Network is accepted, the intent begins execution. This is done by the solver performing a contract call (`execute_intents`) to the Intents smart contract on NEAR ([`intents.near`](https://nearblocks.io/address/intents.near)) and passing the intent details. This contract then fullfills the request and (if needed) uses a [cross-chain bridge](/concepts/intents/intents-bridge) to broadcast the intent to the destination chain. The NEAR Intent smart contract also verifies state changes and ensures the intent is settled correctly, reporting the outcome to the originating user/agent.
35+
36+
Here is a sequence diagram of the intent flow:
37+
38+
```mermaid
39+
sequenceDiagram
40+
participant User/Agent
41+
participant Solver Network
42+
participant NEAR Blockchain
43+
44+
User/Agent->>Solver Network: Broadcasts intent
45+
note right of Solver Network: Solvers compete to <br> find the best solution
46+
Solver Network-->>Solver Network:
47+
Solver Network-->>User/Agent: Return quote from a solver
48+
User/Agent->>Solver Network: User accepts quote and <br> solver executes intent
49+
Solver Network->>NEAR Blockchain: Solver calls NEAR <br> Intent smart contract
50+
51+
52+
note over NEAR Blockchain: NEAR smart contract <br> verifies and settles intent
53+
NEAR Blockchain->>User/Agent:
54+
note right of User/Agent: Intent Fulfilled! ✅
55+
```
56+
57+
---
58+
59+
## Intent Creation
60+
61+
Users and AI agents can create various types of intents to interact with assets across different chains. Each intent represents a specific desired outcome while abstracting away the complexity of execution.
62+
63+
The main intent types supported by the `intents.near` contract are:
64+
65+
1. **Swap Intent**: Exchange one token for another at the best available rate
66+
2. **Transfer Intent**: Move tokens between addresses or chains
67+
3. **FT Withdraw Intent**: Withdraw fungible tokens from the protocol
68+
4. **NFT Withdraw Intent**: Withdraw non-fungible tokens from the protocol
69+
5. **MT Withdraw Intent**: Withdraw multiple tokens in a single transaction
70+
6. **Native Withdraw Intent**: Withdraw native blockchain tokens (e.g., NEAR)
71+
72+
Each intent follows a standard structure that includes:
73+
- The NEAR account ID of the initatior
74+
- Type of intent they want to execute
75+
- Source assets and amounts
76+
- Desired outcome parameters
77+
- Unique identifiers for tracking and authentication
78+
- Optional constraints (e.g., minimum output amount, deadline)
79+
80+
Here is an example of a native NEAR swap intent structure ready to be broadcasted to a Solver Network:
81+
82+
```js
83+
{
84+
intent_type: "atomic_near", // Type of intent - in this case for atomic swaps on NEAR
85+
intent_creation_hash: "Hx7b2270616...", // Unique hash of the intent for authenticity
86+
intent_id: "intent_1234567890", // Unique identifier for this specific intent
87+
intent_initiator: "alice.near", // The NEAR account ID of the user initiating the swap
88+
defuse_asset_identifier_in: "near:wrap.near", // inpute token (what you are swapping)
89+
defuse_asset_identifier_out: "near:usdc.near", // output token (what you want to receive)
90+
amount_in: "1000000000000000000000000", // Numbber of $NEAR in yoctoNEAR (1 NEAR = 10^24 yoctoNEAR)
91+
amount_out_desired: "1000000" // Number of desired USDC (6 decimals)
92+
}
93+
```
94+
95+
<!-- TODO: add example of a cross-chain swap intent & and where to get the asset identifiers -->
96+
97+
---
98+
99+
## Solvers
100+
101+
NEAR Intents uses decentralized networks of solvers to fulfill intents. Each solver network is an off-chain message bus that facilitates:
102+
103+
1. Communication between users and solvers
104+
2. Exchange of `permits` (signed state changes) between participants
105+
3. Competition between solvers to provide the best quote possible for the intent originator
106+
107+
When an intent is broadcast, the solver network communicates with multiple solvers simultaneously. Each solver analyzes the intent and proposes their solution, including execution path and pricing. The solver network then aggregates these responses and selects the most optimal solution before presenting a final quote to the intent originator.
108+
109+
<!-- TODO: add diagram of the solver network -->
110+
111+
Solver networks are typically specific to a single distribution channel (like a DeFi application) and may contain authorized/trusted solvers for that channel. These solvers:
112+
113+
- Monitor for new intent broadcasts
114+
- Calculate optimal execution paths
115+
- Compete to provide the best quotes
116+
- Execute approved intents through the NEAR smart contract
117+
- Handle cross-chain coordination when needed
118+
119+
The decentralized nature of solver networks ensures:
120+
121+
- Competitive pricing through solver competition
122+
- Redundancy and reliability
123+
- Specialized solvers for different types of intents
124+
125+
:::tip
126+
See [Create a Solver](solvers.md) for more details on how these solvers work.
127+
:::
128+
---
129+
130+
## Intent Execution
131+
132+
When a user accepts a quote from the Solver Network, the intent begins execution. This is done by the solver performing a contract call (`execute_intents`) to the Intents smart contract on NEAR ([`intents.near`](https://nearblocks.io/address/intents.near)) and passing the intent details.
133+
134+
The NEAR Intents contract fullfills the request and (if needed) uses multi-chain bridge to settle an intent cross-chain. The Intent smart contract also verifies state changes and ensures the intent is settled correctly, reporting the outcome to the originating user/agent.
135+
136+
<!-- TODO: add link to smart contract docs -->
137+
138+
---
139+
140+
## Examples
141+
142+
Here are examples of NEAR Intents in action. Please note that this protocol is still under development and source code is available for learning purposes.
143+
144+
- [Defuse Frontend](https://github.com/defuse-protocol/defuse-frontend): `near-intents.org` fronted sourcecode
145+
- [Defuse SDK](https://github.com/defuse-protocol/defuse-sdk): Typescript SDK powering `near-intents.org` [WIP]
146+
- [AMM Solver](https://github.com/defuse-protocol/near-intents-amm-solver): Sample solver with AMM functionality
147+
- [Python Client](https://github.com/referencedev/test-intent): A Python example of interacting with the Solver Bus
148+
- [NEAR Intents AI Agent Example](https://github.com/near-examples/near-intents-agent-example): A Python example of an AI agent that uses NEAR Intents
149+
150+
:::warning
151+
Currently there is no `testnet` deployment.
152+
:::

0 commit comments

Comments
 (0)