Welcome to Boson Protocol. Please find a set of Solidity smart contracts that implement Boson Protocol. You are invited to learn more about the project through its code and perhaps test locally how you might use it within your own project.

This is version 1 of the Protocol. You will find the addresses of the deployed contracts on Ethereum's main net and Ropsten test net here.

This version of Boson Protocol is a stepping stone on the way to the release of version 2 of the Protocol next year, which will be accompanied with SDKs and plug-ins to make it easy to integrate. While you may prefer to wait until the new features that will be released in version 2 before building dApps using the Protocol, we encourage you to use the contracts locally and to participate in our bug bounty.

For more details about how Boson Protocol works and how you might make use of it, please see the documentation site.

Table of Contents

• Local Development
  • Prerequisites
  • Installation
    • Forking Rinkeby to localnode
    • Special deployments
  • Test
    • Testing with DAI
    • Unit Tests
    • Coverage
  • Code Linting & Formatting
• Documentation
• Contributing
• License

Local Development

Prerequisites

For local development of the contracts, your development machine will need a few tools installed.

You'll need:

• Node (12.20.x)
• NPM (7.15.x)
• Git

For instructions on how to get set up with these specific versions:

• See the OS X guide if you are on a Mac.
• See the Linux guide if you use a Linux distribution.

Installation

To install dependencies:

npm install

Configuration

Before you can start interacting with the contracts, via hardhat, please make a copy of the .env.example file and call it .env.

Build

All of the available commands can be found in package.json.

To compile:

npm run contracts:compile

Run

npm run contracts:run

Note that: This command starts up built-in Hardhat Network and migrates all contracts to the Hardhat Network instance. The .env file has a hard-coded value for the BOSON_TOKEN address, which points to account #9 of the local hardhat network. This isn't an actual BOSON token address but just a valid address that will allow the deployment scripts to work. When deploying to a public network, this value should be replaced by the address of the Boson Token on the network you are deploying to. When deploying locally (env == hardhat), a mock Boson Token will be deployed. The unit tests deploy their own contracts and do not rely on the deploy.ts script.

If preferred by those who are familiar with Hardhat, the standard Hardhat commands can be used.

In a separate terminal, contracts can be deployed using

npx hardhat deploy

The above command deploys to the built-in hardhat EVM.

Forking Rinkeby to localnode

It is possible to fork the state of the Rinkeby chain to have it deployed locally. The following hardhat commands will achieve this:

npx hardhat node --fork https://eth-rinkeby.alchemyapi.io/v2/<<alchemy key>>

Note that: Alchemy is recommended by Hardhat over Infura because its free accounts provide archived data, which is required for successful forking.

You can then deploy from a separate terminal using the command:

npx hardhat deploy --network localhost

This makes the BOSON test token deployed on Rinkeby (0xEDa08eF1c6ff51Ca7Fd681295797102c1B84606c) and the official DAI token deployed on Rinkeby (0x6A9865aDE2B6207dAAC49f8bCba9705dEB0B0e6D) available to your local hardhat chain.

Special deployments

The following instructions assume you have started a hardhat node (forked or not) using the local node instructions above. If you want to deploy the contracts to testnets or mainnet just replace localhost with the desired network. Calling npx hardhat deploy will deploy the protocol contracts. Beside that we provide addtional utility script for the following deployment cases:

• Deploy all protocol contracts and ERC1155NonTransferable (equivalent to v1.0 deployment script)

  npx hardhat deploy-with-erc1155 --network localhost

• Deploy only ERC1155NonTransferable and set the metadata uri defined in .env file

  npx hardhat deploy-erc1155-only --network localhost

• Deploy a set of mock token contracts ERC20, ERC721, ERC1155 and ERC1155NonTransferable which can be used to test conditional commit

  npx hardhat deploy-mocks --network localhost

• Deploy a Gate contract on a provided network

  • First run the deploy task to deploy the Boson Protocol contracts to your local node, as described above
  • Then run deploy-mocks, as described above
  • Provide values for the folowing properties in your .env file

    BOSON_ROUTER_ADDRESS=0000000000000000000000000000000000000000
    CONDITIONAL_TOKEN_ADDRESS=0000000000000000000000000000000000000000
    #Must be 0 (FUNGIBLE_TOKEN - ERC20), 1 (NONFUNGIBLE_TOKEN - ERC721), or 2 (MULTI_TOKEN - ERC1155)
    CONDITIONAL_TOKEN_TYPE=x

    The Boson Router address and conditional token mock addresses can be found in the corresponding file in the addresses directory. For local deployments, the Boson Router address will be written to a file called 1.json (deploy). The mock conditional token addresses can be found in 1-mocks.json
  • Then run

    npx hardhat deploy-gate --network localhost

Test

Testing with DAI

There is no faucet for getting DAI tokens on a testnet. If you deploy the Boson Protocol contracts to a testnet or a local forked instance, you may want to use DAI test tokens for testing purposes. The easiest way to do this is to deploy your own DAI test token instance. See here for instructions.

Unit Tests

All contracts are thoroughly unit tested using Hardhat's testing framework support.

To run the unit tests:

npm run tests:unit

By default, the build system automates starting and stopping Hardhat Network on port http://localhost:8545 in the background ready for each test run.

Coverage

We use solidity-coverage to provide test coverage reports.

To check the test coverage:

npm run tests:coverage

solidity-coverage runs its own instance of the hardhatEVM internally, as well as instrumenting contracts before running, note that the contracts are not run through an optimiser when calculating the code coverage, so please do ignore any warnings about contract size when calculating the code coverage.

Code Linting & Formatting

Both the contracts themselves and the tests are linted and formatted as part of the build process.

For the contracts, we use:

• solhint for linting
• prettier-solidity for formatting

For the tests, we use:

• eslint for linting
• prettier for formatting

To lint the Solidity code:

npm run contracts:lint

This will check if the linter is satisfied. If instead you want to attempt to automatically fix any linting issues:

npm run contracts:lint-fix

To format the Solidity code:

npm run contracts:format

To attempt to automatically fix any formatting issues:

npm run contracts:format-fix

Similarly, for the tests, to perform the same tasks:

npm run tests:lint
npm run tests:lint-fix
npm run tests:format
npm run tests:format-fix

Documentation

For an overview of the contracts and their responsibilities, see Overview.

The whitepaper is available through the project's website.

Contributing

We welcome contributions! Until now, Boson Protocol has been largely worked on by a small dedicated team. However, the ultimate goal is for all of the Boson Protocol repositories to be fully owned by the community and contributors. Issues, pull requests, suggestions, and any sort of involvement are more than welcome.

If you have noticed a bug, please follow the bug bounty procedure.

Questions and feedback are always welcome, we will use them to improve our offering.

All PRs must pass all tests before being merged.

By being in this community, you agree to the Code of Conduct. Take a look at it, if you haven't already.

License

Licensed under LGPL v3.