DIP-0003

intents/dip-0003.md

@@ -0,0 +1,71 @@
+## Overview
+
+This new intent type is designed to offer better prices for swaps by adding a competition stage
+where solvers can compete for offering the best price for tokens being swapped.
+
+### Intent Creation
+
+To create an intent, one should call `ft_transfer_call` on a `asset_in` token contract.
+The `receiver_id` should be the contract of this intent.
+`msg` field should contain `Action` encoded in JSON:
+
+```json
+{
+    "create": {
+        "id": "1",
+        "asset_out": {
+            "ft": {
+                "token": "usdt.tether-token.near",
+                "amount": "500"
+            }
+        },
+        "deadline": { "timestamp": 1720613080 }
+    },
+}
+```
+
+
+### Intent competition
+
+To place an offer a solver should call `ft_transfer_call` on a `asset_out` token contract with
+recipient of this intent contract and a following `msg` encoded in JSON:
+
+```json
+{ "offer": { "id": "1" } }
+```
+
+The main problem is in the basic scenatio solvers are most likely to postpone sending their offers
+closer to the deadline of the intent. This would happen due to lack of incentive to lock their funds
+without having a guarantee that their offer will be executed. Instead, when a solver sends his offer,
+by doing so he announces the price he is willing to pay to other solvers, who can now calculate an
+exact number of tokens needed, so that a new offer that would outperform this one. Of course, the
+first solver would receive his funds back as soon as his offer was outperformed, but it also means
+that this solver did not gain any profit from his action and moreover, he just spent some gas on it.
+That means that all solvers would mostly like to postpone sending their offers until the last block
+before the deadline.
+
+Let's consider a following situation:
+
+> A user wants to trade `NEAR` for `USDT`. He creates an intent offering `100 NEAR` and asking for
+> minimum `500 USDT` in return with a deadline of 30 seconds.  
+> Let's suppose that current market price is `1 NEAR ~= 5.1 USDT`.
+
+Due to reasons exaplained above, all solvers would wait and start sending their offers only after 27
+seconds pass. Let's say we have only two solvers competing with each other. Both of them would send
+their offers on-chain, and the winner would be the one with the best offer. Since, these offers were
+published on-chain close to the `deadline`, this leaves almost no time for the "loser" solver to
+re-announce a better offer that would outperform the winner's one. So, in this scenario, solvers can
+only predict what offers other solvers would send. It may disincentivises solvers to place any
+offers since there is no guarantee that they would win.
+
+### Intent Settlement
+
+In this approach, one additional transaction is required to settle the intent based on the best price
+offered.
+
+```json
+{ "settle": { "id": "1" } }
+```
+
+While this transaction can be permission-less, it still complicates UX for either user
+or a solver and increases the amount of blocks needed for the whole lifetime of the intent.