-
Notifications
You must be signed in to change notification settings - Fork 33
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #129 from 0xneves/update-readme
docs: updating readme and fixing minor issues
- Loading branch information
Showing
5 changed files
with
575 additions
and
173 deletions.
There are no files selected for viewing
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,120 +1,84 @@ | ||
| # Swaplace | ||
|
|
||
| ## Context | ||
| [](https://github.com/blockful-io/swaplace-contracts/actions/workflows/tests.yml) | ||
| [](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 <network> | ||
| ``` | ||
|
|
||
| ### 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 <network> | ||
| ``` | ||
|
|
||
| ### 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) |
File renamed without changes.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,36 +1,39 @@ | ||
| { | ||
| "name": "swaplace", | ||
| "dependencies": { | ||
| "hardhat": "^2.12.7" | ||
| }, | ||
| "devDependencies": { | ||
| "@nomicfoundation/hardhat-chai-matchers": "^1.0.0", | ||
| "@nomicfoundation/hardhat-network-helpers": "^1.0.8", | ||
| "@nomicfoundation/hardhat-toolbox": "^2.0.1", | ||
| "@nomiclabs/hardhat-etherscan": "^3.1.5", | ||
| "@nomiclabs/hardhat-ethers": "^2.2.2", | ||
| "@nomiclabs/hardhat-solhint": "^3.0.0", | ||
| "@openzeppelin/contracts": "^4.8.1", | ||
| "@typechain/ethers-v5": "^10.2.0", | ||
| "@typechain/hardhat": "^6.1.5", | ||
| "@types/chai": "^4.3.4", | ||
| "@types/mocha": "^10.0.1", | ||
| "chai": "^4.3.4", | ||
| "dotenv": "^16.0.3", | ||
| "ethers": "^5.6.1", | ||
| "hardhat-gas-reporter": "^1.0.9", | ||
| "solidity-coverage": "^0.8.2", | ||
| "solidity-docgen": "^0.6.0-beta.36", | ||
| "ts-node": "^10.9.1", | ||
| "typechain": "^8.1.1", | ||
| "typescript": "^4.9.5" | ||
| }, | ||
| "scripts": { | ||
| "clean": "npx hardhat clean", | ||
| "compile": "npx hardhat compile", | ||
| "test": "npx hardhat test", | ||
| "docs": "npx hardhat docgen", | ||
| "-t": "npx hardhat test --network $1", | ||
| "deploy": "npx hardhat run scripts/deploy.ts --network $1" | ||
| } | ||
| } | ||
| "name": "swaplace", | ||
| "dependencies": { | ||
| "hardhat": "^2.12.7" | ||
| }, | ||
| "devDependencies": { | ||
| "@nomicfoundation/hardhat-chai-matchers": "^1.0.0", | ||
| "@nomicfoundation/hardhat-network-helpers": "^1.0.8", | ||
| "@nomicfoundation/hardhat-toolbox": "^2.0.1", | ||
| "@nomiclabs/hardhat-etherscan": "^3.1.5", | ||
| "@nomiclabs/hardhat-ethers": "^2.2.2", | ||
| "@nomiclabs/hardhat-solhint": "^3.0.0", | ||
| "@openzeppelin/contracts": "^4.8.1", | ||
| "@typechain/ethers-v5": "^10.2.0", | ||
| "@typechain/hardhat": "^6.1.5", | ||
| "@types/chai": "^4.3.4", | ||
| "@types/mocha": "^10.0.1", | ||
| "chai": "^4.3.4", | ||
| "dotenv": "^16.0.3", | ||
| "ethers": "^5.6.1", | ||
| "hardhat-gas-reporter": "^1.0.9", | ||
| "solidity-coverage": "^0.8.2", | ||
| "solidity-docgen": "^0.6.0-beta.36", | ||
| "ts-node": "^10.9.1", | ||
| "typechain": "^8.1.1", | ||
| "typescript": "^4.9.5" | ||
| }, | ||
| "scripts": { | ||
| "clean": "npx hardhat clean", | ||
| "compile": "npx hardhat compile", | ||
| "test": "npx hardhat test", | ||
| "docs": "npx hardhat docgen", | ||
| "testnet": "npx hardhat test --network $1", | ||
| "deploy": "npx hardhat run scripts/deploy.ts --network $1", | ||
| "compile-echidna": "crytic-compile . && slither . --print echidna", | ||
| "fuzz-p": "echidna . --contract TestSwaplace --test-mode property --config echidna.config.yml", | ||
| "fuzz-a": "echidna . --contract TestSwaplace --test-mode assertion --config echidna.config.yml" | ||
| } | ||
| } |
Oops, something went wrong.