Repository files navigation

This repo contains the source for a Plutus NFT auction smart contract. The source for the smart contract is located insrc/Canonical/Auction.hs.

The repo also contains an executable for compiling the smart contract inapp/Main.hs.

The compile the code to a Plutus smart contract, run:

cabal run create-auction-sc

This will write a file toscripts/auction.plutus

Ashell.nix is also providing for nix users.

After compiling the smart contract, it is necessary to make a script address.

First source either the testnet or mainnet environment variables.

For testnet

$ source scripts/envars/testnet-env.envvars

For mainnet

$ source scripts/envars/mainnet-env.envvars

The environment variable files setCARDANO_NODE_SOCKET_PATH to the path of the appropriate Daedalus socket file (either Testnet Daedalus or the regular mainnet Daedalus). It you run acardano-node on your own you should set this environment variable to your socket file location after sourcing the environment variable file.

Next, run:

scripts/hash-plutus.sh

This will make the filestestnet/auction.addr ormainnet/auction.addr.

Example transactions can be found inscripts/core. The scripts are used by other scripts inscripts/happy-path which demonstrates how to start, bid and close the auction.

Example redeemers are found inscripts/testnet/redeemers and example datums are found inscripts/datums.

Here is the Haskell type of the Datum

dataAuction=Auction{aSeller::!PubKeyHash  ,aStartTime::!POSIXTime  ,aDeadline::!POSIXTime  ,aMinBid::!Integer  ,aCurrency::!CurrencySymbol  ,aToken::!TokenName  ,aPayoutPercentages::!(A.MapPubKeyHashInteger)  ,aHighBid::!(MaybeBid)}

A crucial note is theaPayoutPercentages field which is used to determine how to distribute the winning bid. Instead of going entirely to seller it is split up using the percentages in the map, as described in detail below.

When the auction is finished, assuming there is winning bid, the funds are distributed to multiple parties as described by the percentages map.

The map is collection of pairs of public key hash and percentage. The percentages are stored as integers times 1000, so 2.5% would be stored as 25.

The calculation to determine how much to give each party is not as straightforward as one would imagine because of minimum Ada UTxO requirements.

Regardless of the percentage, every participant recieves a minimum of 1 Ada.

For example, if there were three (seller, marketplace and royalty) users and percentages were 95%, 2.5% and 2.5%, 10,000,000 lovelaces would distributed as follows:

seller: 8,000,000marketplace: 1,000,000royalty: 1,000,000

This is in contrast to the split as dicated by the percentages directly, which would have been:

seller: 9,500,000marketplace: 250,000royalty: 250,000

Here is another example with percentages were 80%, 15% and 5% with 10,000,000 lovelaces:

seller: 7,578,948marketplace: 1,421,052royalty: 1,000,000

The extra 500,000 that was needed to give the royalty user 1 Ada, was taken equally from the seller and marketplace portions.

The exact calculation is as follows.

The percentages are sorted least to greatest. For each percentage the percentage is multiplied times the current total amount and divided by 1000 (remember the percentages are multiplied times a 10 so 2.5% is 25). If the portion is less than 1 Ada it is set to 1 Ada. The portion for this user is subtracted from the current total and their percentage is subtracted from the total percentages.

The loop starts again, with a new current total and a new current total percentages. The next percentage is adjusted by dividing by the new total percentage.

This process continues until the last element, which just get's whatever is left over.

Let's revisit our example above to see how it works.

The first time through the loop we multiple 50 * 10,000,000 and divide by 1,000 to get 500,000. This is less than 1 Ada (1,000,000) so we set the portion this user gets to 1 Ada. We subtract 1 Ada from the total to get 9 Ada and subtract 50 from the total percent (times 10) to get 950.

For the next iteration we multiple 150 * 9,000,000 and divide by 950 to get 1,421,052. This is greater than 1 Ada so we don't have to adjust it. We subtract 1,421,052 from 9,000,000 to get 7,578,947. We subtract 150 from 950 to get 800.

For the final iteration through the loop we just give the user the rest which is 7,578,947.

Because the divided up the price to various participants is so complicated there are unit tests to cover this logic specifically.

Run the unit tests by calling:

$ cabaltest

Before testing you need to make sure you havecardano-cli installed and on your path, and it must be version 1.31.0 or greater. You will also need the json utilityjq as well ascardano-cli helpercardano-cli-balance-fixer which can be downloaded here:https://github.com/Canonical-LLC/cardano-cli-balance-fixer

First create the wallets and get the protocol parameters.

$ ./scripts/wallets/make-all-wallets.sh$ ./scripts/query-protocol-parameters.sh

We will walk through the process of manually testing a start, bid, outbid and close flow.

After following the setup steps above, first make sure that the~/$BLOCKCHAIN_PREFIX/seller.addr has Ada.

Start by minting a token for the auction:

$ scripts/mint-0-policy.sh

Wait for the next slot:

$ scripts/wait/until-next-block.sh

You can now view the minted token in theseller's wallet:

$ scripts/query/seller.sh

Now start the auction by calling:

$ scripts/happy-path/lock-tx.sh 400000 0

This will create a auction that expires in 400 seconds. The0 is namespace so we can have more than one auction going at a time.

Wait for the next slot:

$ scripts/wait/until-next-block.sh

You can now view the token at the smart contract address:

$ scripts/query/sc.sh

Make sure that the~/$BLOCKCHAIN_PREFIX/seller.addr has over 11 Ada.

Now create a bid:

$ scripts/happy-path/bid-1-tx.sh

Wait for the next slot, and query the script address

$ scripts/query/sc.sh

It should show the additional 10 Ada bid is now stored there.

Make sure that the~/$BLOCKCHAIN_PREFIX/buyer1.addr has over 33 Ada.

Now create a bid, that replaces the first bid:

$ scripts/happy-path/bid-2-tx.sh

Wait for the next slot, and query the script address

$ scripts/query/sc.sh

This should show the new bid's Ada.

Query thebuyer address:

$ scripts/query/buyer.sh

This should show the old bid Ada has been returned.

At this wait for the auction to expire.

Make sure that the~/$BLOCKCHAIN_PREFIX/marketplace.addr has over 3 Ada.

When the time is right, call close:

$ scripts/happy-path/close-tx.sh

Wait for the next slot, and then check that the token is inbuyer1's wallet:

$ scripts/query/buyer-1.sh

and the bid is in the sellers wallet:

$ scripts/query/seller.sh

and the marketplace:

$ scripts/query/marketplace.sh

and

$ scripts/query/royalty.sh

There are three large system tests that cover the main use cases and potential vulnerabilities we are aware of. The tests can be run on mainnet or testnet.

They take a long time to run, around 20 minutes, and can fail if the testnet is overloaded.

Luckily running them is easy:

$ ./scripts/tests/all.sh

The tests will start running. If the script errors one of the tests has failed.

If the scripts pass one must still verify that assets were transfered correctly at each step.

In thetemp/accounts/diff directory, there will be subdirectories for each test flow. Within these directories are folders for each test step. If assets were transfer, there will bejson files the account difference.

For instance after the first step to lock assets at the script address, the followingjson files are written:

$ cat temp/accounts/diffs/start-bid1-bid2-close.sh/0-1/sc.json{"":{"":1758582},"d6cfdbedd242056674c0e51ead01785497e3a48afbbb146dc72ee1e2":{"123456":1}}$ cat temp/accounts/diffs/start-bid1-bid2-close.sh/0-1/seller.json{"":{"":-1942827},"d6cfdbedd242056674c0e51ead01785497e3a48afbbb146dc72ee1e2":{"123456":-1}}

This shows that the smart contract (sc), received a non-native token (d6cfdbedd242056674c0e51ead01785497e3a48afbbb146dc72ee1e2.123456) and 1758582 lovelaces.

As expected, the seller lostat least this much. Notice it lost more Ada, because of fees.