Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: updating readme and fixing minor issues #129

Merged
merged 5 commits into from
Dec 7, 2023
Merged

docs: updating readme and fixing minor issues #129

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
b0be405
docs: better readme
0xneves Dec 7, 2023
a2b86f9
style: renaming yaml to yml
0xneves Dec 7, 2023
5463a04
style: renaming yaml to yml
0xneves Dec 7, 2023
775c99c
fix: scripts for echidna were wrongly deleted
0xneves Dec 7, 2023
1dfd912
chore: updating yarn lock
0xneves Dec 7, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 .prettierrc.yaml → .prettierrc.yml
View file
Open in desktop
File renamed without changes.
134 changes: 49 additions & 85 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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 <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)
0 echidna_config.yaml → echidna.config.yml
View file
Open in desktop
File renamed without changes.
73 changes: 38 additions & 35 deletions package.json
View file
Open in desktop
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"
}
}
Loading
Loading