From b0be4058a15f513324ea1f31f0dc2fe246316a49 Mon Sep 17 00:00:00 2001 From: 0xneves Date: Thu, 7 Dec 2023 16:19:11 -0300 Subject: [PATCH] docs: better readme --- README.md | 134 ++++++++++++++++++++---------------------------------- 1 file changed, 49 insertions(+), 85 deletions(-) diff --git a/README.md b/README.md index 11d6724..9894ba6 100644 --- a/README.md +++ b/README.md @@ -1,120 +1,84 @@ # Swaplace -## Context +[![Tests](https://github.com/blockful-io/swaplace-contracts/actions/workflows/tests.yml/badge.svg)](https://github.com/blockful-io/swaplace-contracts/actions/workflows/tests.yml) +[![Fuzz Testing](https://github.com/blockful-io/swaplace-contracts/actions/workflows/fuzz-testing.yml/badge.svg)](https://github.com/blockful-io/swaplace-contracts/actions/workflows/fuzz-testing.yml) -In this new project, Blockful is a P2P Ownerless and Feeles MarketPlace: +This repository contains the core smart contracts for the Swaplace Protocol; The lightest Swap protocol in the market. -Summarized: +## Incentives -A) Users propose a Swap of any asset. +This repository is subjected to incentives for the community to contribute to the project. The incentive distribution and amount are being discussed but the eligibility has already started. -B) Users accept available Swaps. - -Detailed: - -A) User calls public pure function `composeSwap`. - -B) User provides allowances for the biding assets. - -C) Returned Swap struct is used to call `createSwap`. - -D) Swap acceptee provides allowances for asked assets. - -D) `swapId` is used to accept the Swap. +## Setup -E) Assets are swapped and the Swap becomes unavailable. +You should install the dependencies using Yarn to deploy this code to a local testnet. The project uses Hardhat as a development environment. Which relies on Node.js (Recommended v18.16.0). -### TLDR: +``` +npm install --global yarn +yarn --version +``` -- The contracts cannot be upgraded. -- The contracts have no ownership. -- The contracts don't charge fees. -- Complex mechanics should be built by the community using the interface of Swaplace. -- There are no external contract dependencies. -- The protocol operates using allowances. +Later on, install the dependencies using Yarn. -## System Actors +``` +yarn install +``` -### Users and Contracts +### Environment Variables -Both EOA and Contracts can access all functions in the contract. +The project comes with a `.env.example` file. You should rename it to `.env` and fill the variables with your own values. Most RPC providers offer free testnet nodes. You can use [Alchemy](https://www.alchemy.com/) or [Infura](https://infura.io/) to get a free node. -## Features +WARNING: The private keys used in the `.env` file are from hardhat accounts. They are not meant to be used in production. -- Create Swap -- Accept Swap -- Cancel Swap -- Make Asset -- Make Swap -- Compose Swap -- GetSwap +### Testing and Deploying -### Create Swap +Run the tests in `localhost` or try the contracts in a desired network by specifying the network name in `hardhat.config.js`. -The caller can store a Swap request in the contract. One must give the contract allowance when transferring assets. Nevertheless, Swaps require a minimum expiration of 1 day. +``` +yarn test +yarn testnet +``` -### Accept Swap +Deploy the contracts in the desired network according to the networks available in `hardhat.config.js`. -The caller can accept any Swap if the asked assets match the sender's ownership. The `swapId` must be provided and the allowances of the sender must be in place. +``` +yarn deploy +``` -### Cancel Swap +### TLDR: -Provide the `swapId` and be the Swap owner to cancel a Swap at will. It sets the Swap as expired. Notice that the allowances won't dismiss, but new ones can take their place. +- Contracts cannot be upgraded. +- Contracts have no ownership. +- Contracts don't charge fees. +- There are no external contract dependencies. +- The protocol operates using available allowances. -### Make Asset +### Making Assets -Easily create and return the Asset type to use in your Swap by calling this function. An Asset is a struct holding an address, an amount or id and an asset type, which can be ERC20 or ERC721. +An `Asset` is a struct that stores the contract address and the amount or ID of ERC20 or ERC721. -```solidity +``` struct Asset { address addr; uint256 amountOrId; } ``` -### Make Swap - -A Swap carries two arrays of Asset types, an owner and the expiry period in seconds. One can call `makeAsset` method to return the Asset types and use them as input when calling `makeSwap`, which will return the Swap struct used when proposing a Swap. - -The usage is on-chain focused, but when working with off-chain, the Swap struct should be built using methods not involving calling the blockchain multiple times. +### Making Swaps -### Compose Swap +A Swap also has an `owner` and an `allowed` address. The `owner` is the one that can cancel the swap while the `allowed` address is the one that can execute the swap but anyone can accept if +it`s set as the Zero Address. -Similar to `makeSwap`, compose Swap will build the entire Swap in a single function and return the Swap struct. Different from the make Swap function, which requires pre-built assets, `composeSwap` will receive as parameters all the data from the assets involved in the Swap in three arrays of data, corresponding to the Asset struct requirement. +A Swap also has an `expiry` period in seconds. The Swap can only be executed before the expiry period is reached. -To avoid having six arrays as parameters for both assets bid or asked, both of them should be placed in the same array and then specify the `uint256` integer representing the place at the index where the assets bid will flip assets asked. The variable `indexFlipToAsking` is the length of bid assets and also the beginning index of the assets being asked to fulfill the Swap. +The `Asset` type represents in one hand the asset being bidded and the other for the asset being asked. -```solidity -function composeSwap( - address owner, - uint256 expiry, - address[] memory addrs, - uint256[] memory amountsOrIdsOrCalls, - uint256 indexFlipToAsking -) public pure returns (Swap memory) ``` - -### Get Swap - -Return the Swap struct info by providing the `swapId`. - -## Setup - -Install dependencies. - + struct Swap { + address owner; + address allowed; + uint256 expiry; + Asset[] biding; + Asset[] asking; + } ``` -yarn -npm i -``` - -### Test - -The project is being tested in localhost. - -``` -npx hardhat test -``` - -## Team Contact - -[Blockful](https://blockful.io)