v1rc

[fallen-icarus]

This PR supersedes the offer-branch PR (it includes the addition of the offer beacons). This PR is meant to be the official beta version.

One-Way Swaps

Adds offer and ask beacons for more expressive off-chain querying of swaps.

• [x] Change protocol to use a single swap address for all swaps. Every user effectively gets their own DEX address.
• [x] Change protocol to use a single beacon policy for all swaps. Each swap will get a trading pair beacon and an offer beacon where the asset name distinguishes the two beacons.
• [x] Remove ability to merge swap outputs. This was found to dramatically simplify logic and improve performance by over 2x in the worst case scenario (5 swaps per tx -> 12 swaps per tx) and almost 2x in the best case scenario (9 swaps per tx -> 15 swaps per tx).
• [x] Testing.
• [x] Benchmarks.

Two-Way Swaps - credit to N8iveToEarth on X/Twitter for the idea

Adds a new reversible swap type that can be used to provide liquidity in a profitable way. In essence, Alice can create a swap for ADA <-> ERGO and set two prices, one for ADA -> ERGO and one for ERGO -> ADA. By setting both of these prices at slightly above market rates, Alice can profit from Bob using her swap regardless of trade direction. This potential for pure profit naturally incentivizes users to provide liquidity. The main advantage of this over the one-way swap is that the swap UTxO does not need to be reset after each usage. For users that just want to swap assets, the one-way swap is still available.

• [x] Introduce a separate validator/policy pair for a reversible swap. Each users gets a single address that houses all of their reversible swaps. This address is distinct from the user's one-way swap address. Each trading pair gets a unique trading pair beacon and two offer beacons (since it can go in either direction).
• [x] Testing.
• [x] Benchmarks.

Off-Chain

• [x] Update CLI to facilitate use of both swap types.
• [x] Expand CLI to enable interacting with swaps without relying on a local node.
• [x] Update template bash scripts.

Docs

• [x] Update Readme.
• [x] Update GettingStarted.
• [x] Update Changelog.

[fallen-icarus]

@rphair @TerminadaPool

Would you two mind taking a look at the new README? I would like to get some more perspectives on it aside from myself and @zhekson1. I've seen you two talk about this protocol elsewhere which is why I am singling you out. This invite for constructive feedback is open to anyone though!

It is okay if you cannot comment on the spec/code. I am actually more interested in the feedback on the higher level aspects. Specifically, I am looking for feedback on: 1) Is the README approachable? 2) Are there any factually incorrect statements? 3) Do the arguments conceptually make sense? 4) Grammar

[rphair]

sure @fallen-icarus, I'd be happy to help & have scheduled myself to give it a good read & feed back when things settle down in next couple of days 🙃

[rphair]

p.s. I planned to go over it tonight but material is a lot longer than I remember... you've made a lot of progress since my last read. 🤓 I forked the repo & of course didn't realise I was basing on the old README so instead I'll submit any comments as a markup on the branch here... hopefully that was the intention.

Next day I have a block of free time I'll give a complete read & review, but also if you have a target date to merge this release please let us know so I can at least submit a best effort by then.

[fallen-icarus]

I'll submit any comments as a markup on the branch here... hopefully that was the intention.

Yes, that was the intention. Sorry, I should have specified that. I find reviewing PRs has a nice workflow for something like this since you can easily comment on specific lines.

if you have a target date to merge this release please let us know so I can at least submit a best effort by then.

There is no target date. I will be finishing up some tweaks to the off-chain code today. Once that is done, the only thing left is the README. The plan is to merge this branch into main once all of the feedback is addressed and then announce the launch of the beta version of Cardano-Swaps. So it is more of a "as soon as it is done" situation. That being said, I can wait a week or two for feedback. I'd rather quality feedback over rushed feedback.

[fallen-icarus]

best known current document with an ELI5 type description of the function and application of Beacon Tokens.

I don't think there is one. I'll give it a shot here. It would be good practice for me anyway.

Consider the CIPs website. Being able to filter proposals by topic (eg, Ledger, Plutus, etc.) is an extremely useful feature. How do these tags work? The way they work comes down to how constrained their use is. Imagine if any CIP could claim the Ledger tag even if it had nothing to do with the Ledger. If there were a bunch of these mis-tagged CIPs, filtering by the Ledger tag would give meaningless results. Because of this, part of the job of CIP editors is to make sure the tags are not misused to protect the integrity of the filtered results.

The same is true for literally any tag in literally any context. If you want to be able to filter by a specific tag, the most important thing is to make sure the tags are never misused. Cardano allows tagging UTxOs although, by default, only the address is typically used.

Side note: From the perspective of the blockchain, UTxOs are not located anywhere. The idea that UTxOs are located at an address is not accurate. Instead, the UTxOs are tagged by an address. When a user looks up their wallet's balance, implicitly, the software is filtering the UTxOs by those tagged with the target address. Since the address tag is set by the blockchain, and therefore impossible to misuse, filtering by the address tag provides meaningful results.

There are three possible things that can be used as UTxO tags (excluding the address since it is set by the blockchain): 1) An asset 2) A datum 3) A reference script

Of the three choices, the asset option is the easiest to implement. Cardano's infrastructure already supports filtering UTxOs by asset. For example, Koios and Blockfrost both allow this.

So we need an asset to tag UTxOs with to provide custom filtering options. ADA cannot be used since it is found in literally every UTxO. So that leaves a native token. But remember the number one requirement of a tag: it must be impossible to misuse it. This scenario is perfect for smart contracts. You can fundamentally tie a minting policy's logic with a spending script's logic to do this. The minting policy ensures that a new tag can only be created if it is stored with a UTxO in the proper context and the spending script ensures that the tag is never moved to an inappropriate context when the original UTxO is consumed.

Here is a simple example. Imagine you want to be able to tag a UTxO with a ref_script tag if it has a reference script. These tags should only ever be found in UTxOs that actually have a reference script. To guarantee this constraint, the minting policy should only allow minting ref_script tags if the tags are stored in a UTxO that has a reference script. The problem is now what do you do after the ref_script tag is minted? The minting policy does not control how the tags are spent. What if a UTxO with a ref_script tag is consumed and the ref_script tag is sent to a UTxO that does not have a reference script? This would ruin the filtering.

In order to ensure proper use of the ref_script tag after the initial mint, a spending script is required. To actually use the spending script though, the ref_script tags should only ever be located at an address using the spending script. This means, to properly use the tags, the minting policy needs to ensure the ref_script tags are only minted to an address using the required spending script. So the actual requirements to mint a new ref_script tag are: it must stored in a UTxO that has a reference script AND the UTxO must be stored at an address using the required spending script as the payment credential. This is what it means to "tie a minting policy to a spending script".

The spending script just needs to carry this constraint forward: whenever a UTxO with a ref_script tag is consumed, either the ref_script tag must be moved to another UTxO with a reference script, or it must be burned. The idea is similar to if CIP tags could move. You would want to make sure that the new location is appropriate and if it isn't, you would want to delete the tag. Smart contracts allow automating these checks for certain scenarios.

There is a bit more to beacon tokens than this but this is the high-level explanation. If I were to defined beacon tokens at this point, it would be: native tokens whose utility is heavily constrained so that they can serve as tags for filtering UTxOs. Creating dApps with full delegation control requires giving users their own dApp addresses. By tagging all UTxOs relevant to the dApp with a beacon token, users can still find and interact with each other since they can filter UTxOs by the relevant tags.

[fallen-icarus]

I don't think there is a need for you to do a second pass. I appreciate the first pass.

fully review the swap implementation to ensure it's comprehensive and error resistant.

I do not think there is a need for this. Any issues should come up when users are actually testing it or during a security audit. As long as you philosophically satisfied with the overall arguments, that is enough for me at this stage.

[fallen-icarus]

@rphair @TerminadaPool I appreciate the help! The new readme has been added. You can see the diff here. The rendered readme is here.

I added pretty much all of your suggestions. I also expanded on certain sections based of your questions. While I was experimenting with the flash swaps, I also added ask beacons to the one-way swaps; there was no performance degradation so I didn't see a reason not to.

I will be targeting this coming weekend to release the beta. The latest commit in this branch is feature complete if either of you would like to try it out. I will be testing it more throughout the week so don't feel pressured to provide feedback; you two have done enough. As always though, any feedback is welcome.

[TerminadaPool]

I am keen to help you with this awesome project any way I can. Unfortunately I am not enough of a programming guru that can just be pointed at the code so I might need training wheels before I can be much help.

If you are building searching software or a decentralised order book viewer then I might be able to help with writing user documentation or with building deb packages so it is easy for users to install. I have both ARM64 and AMD64 machines that I can build and test on. Please let me know if there is some way I can help and I will try.

[fallen-icarus]

@TerminadaPool I actually don't think I need help with the code at this stage. To me, the beta does not need to be 100% bug free (although it would be nice :smile:). Instead, it is meant to grow community interest and inspire people to get involved. My bigger concern is the CLI since it is currently the only way to try it out. But even with that, I am more concerned with the UX than the code. What would really help is for you to just follow the GettingStarted and try it out. Try to do a round trip: create a swap, update the price, maybe convert it to a new trading pair, swap with it (pretending to be another user), and finally close it.

Currently, the most pressing questions for me are:

1. Are there any issues installing the cardano-swaps CLI?
2. Is the GettingStarted clear enough for a user to actually use the DEX? Similarly, are the template bash scripts helpful for this?
3. Does the CLI feel intuitive?
4. Should the query results be formatted differently?
5. Does something not work the way you think it should?
6. Does the documentation get you to the point where you can start creating/using more complicated swaps?

[TerminadaPool]

Yeah sorry, I wasn't really offering any coding help because I already know that I am not in the same league as you that I could provide any meaningful help. I might even have trouble just compiling / using your github code. However, I will get onto trying it out over the next week and doing some testing.

I will also have another read and think about the readme.md file but after quickly reading it just now, it looks good.

[rphair]

@fallen-icarus https://github.com/fallen-icarus/cardano-swaps/pull/10#issuecomment-1798581334 - ... There is a bit more to beacon tokens than this but this is the high-level explanation.

Thanks for writing this & giving me time to fully understand what you've written. I've finally been able to go back to https://github.com/cardano-foundation/CIPs/pull/466 and read your draft & the comments you've made on top of my own & other reviewers' comments (cc @zhekson1).

Therefore I'll make any further general comments about Beacon Tokens there, and will comment here in this repo about the particular applications... until the point when these apps are referred to as reference implementations in CIP and CPS documents. 🤓 https://github.com/cardano-foundation/CIPs/pull/466#pullrequestreview-1728742868

[TerminadaPool]

They need to deliberately create an arbitrage opportunity.

Of course, since that is how an order book works. It is only when the prices meet with a degree of overlap, more than the transaction fee, that the trade will be profitable to execute. Arbitragers will only execute trades that are risk free profit. Otherwise, if they were to provide liquidity to execute trades not independently profitable, then they would be taking on directional risk. Arbitragers will also have accounts with centralised exchanges and will be watching the prices in all locations. As soon as there is an arbitrage opportunity worthwhile they will execute the trade.

I am not an expert, but I understand the role of a market maker in the TradFi world of a stock exchange broker, is expanded beyond being simply an arbitrager, to include a requirement to provide a level of liquidity. These market makers may take on directional risk for periods of time but they usually hedge this risk using options and other strategies. They pay for privileged access to the broker's order book which allows them to preferentially order their trades. They also get to set the price spread, manipulate prices through high frequency trading, and snipe all arbitrage opportunities for themselves.

If we view cardano-swaps as an isolated market then there would be no incentive for a market maker to provide extra liquidity beyond executing arbitrage opportunities because he can't gain any privileged access to front run other people. This is good and means that the real cost of transacting is transparent.

By contrast, platforms like Robinhood are not transparent. They say they have "free" transaction fees but really this is because they are selling privileged access to their order book so that market makers can front run, and high frequency trade against, the ordinary users.

[zhekson1]

thank you @rphair and @TerminadaPool for your feedback! I will be combing through these documents as well as writing others in the future and your input is a great help in the process!

[fallen-icarus]

Thanks again for the help @rphair and @TerminadaPool! Your perspectives helped me realized things about this protocol that I hadn't noticed before (like the fee market). I hope you will be willing to help us out again for the other protocols. Loans is almost there. I am hoping to release it by EOY.

[TerminadaPool]

@fallen-icarus I messaged you privately on Matrix about my testing attempt with a copy of my steps undertaken.

[TerminadaPool]

@fallen-icarus I can read your message on matrix OK. Perhaps you can't see the content posted before you joined the room. I have reposted what I previously wrote, so hopefully you can see it now. I invited you @rphair to the matrix room also.

[TerminadaPool]

@fallen-icarus I can see your posts on Matrix. Could you try creating a matrix private chat yourself with my handle and then I will attempt to join your invite? I find Element on Linux seems to be a pretty functional Matrix client: https://element.io/download

To create a private chat I just click the + sign under "people" and then enter the user handle.

I could post the log of my testing problem here but I was worried it would pollute your GitHub repository.

I agree that the number of disparate social media apps is overwhelming. Though at least Matrix is freedom preserving and doesn't require a govt registered mobile phone number linking everything. The AI algorithms in the future are going to love getting inside peoples heads.

[fallen-icarus]

I just created a room. I'd prefer to use the web app if possible since it requires less privilege. If it doesn't work, I can try the desktop app.