Soroban Reverse Auction
Tags: rust, soroban, stellar
Published: 2023-12-22 22:42:52

The past week, I have been tinkering with a new Soroban project.
It's been quite a learning experience, both in Soroban and in frontend.
I'll talk you through how I built my app, and share some of my lessons and thoughts.

The code (and a large readme) can be found on [github](https://github.com/Row-Bear/soroban_reverse_auction)

**Reverse Dutch Auction**
What I've made is a Reverse Dutch Auction.
I am still missing a few cards from my RPCiege collection, so I want to find a way to acquire the missing ones.

With a Reverse Auction, a buyer can:
-Set a (low) starting price
-Define how much and how often the price will increase over time

A seller can then interact with the auction, to sell their card/asset when the price is high enough for them.
However, if they wait too long, someone else may take the offer!

**Soroban**
To set this up in Soroban, I've made a contract with 5 functions.

**setup_auction**
The first function is for setting up the auction.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/lyho11tc90adzz0xq46b.png)
It takes in some arguments, and returns a Status (or an error)
The arguments define what's being bought and sold, and how the price behaves.
For example: I (host) will buy 1 RPCiege card (auction_asset) and pay in XLM (counter_asset). My starting bid will be 20 XLM (starting_bid), and I will increase it with 10 XLM (bid_incr_amount) every 17000 ledgers (about 1x per day) (bid_incr_interval).
I will increase it 10 times (bid_incr_times).

That means I will pay at least 20 XLM, up to 120 XLM after 10 days.

The function starts out with some sanity checks:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/sv8ubj3gypiv1gzjv4k7.png)
The host must be authorised: in effect, that means the address/account we provide must sign the transaction. After all, they will provide the 'money' to buy the asset with.

Then we check if the contract was already initialised/started.
We do that by seeing if there is already a Datakey for State set in storage.
If there is, we return an Status::AuctionAlreadyInitialised.
This lets users know what's up, without a full error.

Then, we check if the bid is actually positive. We don't want any weird negative prices being paid.

![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/j8iczw8v0sobq7mrz1dx.png)
Next, we ensure that the contract will have it's rent paid for the duration of the auction.
In Soroban, entries need to pay rent to stay on the ledger.
This avoids bloating the ledger with old and irrelevant data.
In this case, I've put all the contract's data in the `.instance()` storage.
That means any bump/extend_ttl operation will pay the rent for our data and the contract itself.

Then, we transfer the counter_asset from the buyer to the contract:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/u4z2gfeeiwoha0meboxc.png)
That means the contract acts as broker, and the funds are guaranteed to be available for a seller.
Note that we use the `try_transfer` method. If it were to fail, we can catch that error.

Then, we save all the information we have received and calculated.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ekw9t3vzhae41xyv56wc.png)
I've made a custom struct AuctionData to hold all that information.
That makes it easier to pass that object around, for example into and out of storage. It's probably not the most efficient way though.
We store that AuctionData struct into the `instance()` storage.
We also store a datakey to show that the auction is now Running.

Next, we emit an event.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tyo7du6jvy78uxkphm5y.png)
Events can be monitored via the Soroban RPC servers.
We emit all information needed to calculate how the bid changes over time, so that sellers don't need to invoke the contract.

Then finally, we return a Status to the user, to let them know the auction has started.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/qdv9n5tvn6mke0c02pec.png)

Since a Soroban contract/transaction will execute atomically, any errors will result in the whole function failing/reverting.
No need to worry whether any funds were transferred if the contract fails to save it's data. It's all or nothing!

**get_bid_info**
The second function in the auction contract is get_bid_info().
This one doesn't take any parameters!
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4j3uccx3mxaqiup1b135.png)
It does return another custom struct: BidInfo.
This functions does the basic arthritics to determine what the price is at this moment.
The price increase happens not strictly on a time base, but on the closing of ledgers. A ledger will generally close every 5 or 6 seconds.

First, we do a bit of state checking:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/pc1gmqpi4v0dosqcj5la.png)
If there is no State datakey set, the auction has not been setup, so we throw an error.
And similar, if the State is anything other than Running, we also throw an error.

Then, we ask the Soroban env what the current ledger is. We also retrieve our AuctionData from storage:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/srpcmqtijeszeab6z6ek.png)

After some basic calculations, we stumble on some mildly interesting (to me) Rust.
I want to have two different flows, based on if the price has reached its maximum or not.
But if we declare the variables inside the scope of the if, we can't use them outside it.
So, we declare (but don't assign values to) the variables first.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/o1uvz30j63nyqp6w9d79.png)

Then, we go on to calculate what the price is now, when it will increase, and when it will reach the maximum:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/y7mmma363c9g3v9wezoy.png)

Finally, we create a BidInfo struct with all this information, and return that.
We also emit an event, for anyone interested. It saves them a contract invoke.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/adhhi3bqwamuz31xolel.png)

**sell_asset**
Next up is the function to be used by a seller.
They call the sell_asset function, which requires their address as parameter:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/wwwcmc940hdmzjyei7x4.png)

We then make sure the state of the auction is right, and that the seller is authorised (has signed the transaction):
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/jaw3zbe2b4newzshmhag.png)

To proceed with the sale, we retrieve the auction data, but we also need to know what the current bid is.
Good thing we already wrote a function to get that bid information!
We call the contracts own get_bid_info() function with `Self::get_bid_info(env.clone()).unwrap().current_bid;`
We pass it a clone of the current env, then take the current bid value out.
It's not the most efficient way. We spend some cycles to calculate things we don't need, we only use the `.current_bid`
But, it saves me from writing that specific part of code.
And this function will only rarely be used: once per auction. So, I accept that overhead.

We go on to transfer the funds:
The seller sends 1 stroop of the NFT asset to to contract, and the contract returns the current price.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2xg0s0iqbx5j5nu4on3b.png)
Again, this happens all at once, or not at all.
The way Soroban is built ensures that execution can not stop after the first transfer. If the second transfer fails, none of the operations take place.

We emit an event with the sell price, set the auction state to Fulfilled and return a Status message to the seller, and that's it for this function.

**close_auction**
The organiser of the auction (the buyer) has the option to close the auction down again.
They can do this before or after a seller sells their asset.
If it's done before, the auction is Aborted, the funds return to the buyer and the auction becomes inactive.
If it's done after the sale took place, it goes slightly different.
The NFT is transferred to the buyer, along with any left-over funds.
Then, the auction is set to Closed

We start again with some checks on the state of the auction:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/l40g9kbkalnz6gghjvpc.png)
Then, we load the auction data and make sure the host/organiser is signing the transaction:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/phq27o0h2yevq9jqba5b.png)

If the auction is running, we return all the funds to the buyer, before setting the status to Aborted.
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/ecfyvc100pe74gpx6sqn.png)
Notice how we get the balance: we cross contract call the contract of the funds, and ask it for the balance of our contract.
It's possible to avoid this by keeping track of the balance ourselves.
But, that also opens up chances for errors and bugs.
Again, I'll take that overhead cost and use this method of getting the balance.

If the auction was Fulfilled, we use two transfers.
One for the NFT, and one for any remaining funds (if any, we check to see if that is > 0).
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/n22ulko2hd64o25kf6ss.png)

All that remains is to set the state to Closed and return the buyer the good news:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/juyah1zzafjxmeijddun.png)

**reset_auction**
For demonstration purposes, I've added a reset function to the auction.
If it has been closed, we remove the storage information.
Effectively, this means the auction contract can be reset again.
For here, the interesting part is to show how we clear the storage:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/tmgt7s9xjm5rgvro412d.png)
We only have the two datakeys, one for State and one for AuctionData.
We simply remove them.
Note though, the information can still be found by people going back through ledger histories. So don't put any secrets in a public ledger, thinking you can remove them later :)

That concludes the Rust code used in the Soroban Reverse Auction.
The readme on [github](https://github.com/Row-Bear/soroban_reverse_auction) has a detailed step-by-step guide on how to compile(build), deploy and interact with this contract yourself.
It also has files and instructions for hosting a local copy of the interactive demo, so you can experiment with your own auction contract.

I'll spare you the details of the many hours spent getting that demo working. I'll summarize:
![Image description](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/2u4x0x4xx9jycbfpvwg6.png)

 Happy coding!