Hello world: launching our core repo and developer docs v0.1

It’s an exciting day for the engineering team here at Boson Protocol as it marks our biggest tech launch to date.

We have been working hard and recently announced the successful audit of our smart contract for the $BOSON token by blockchain security specialists CertiK. The audit means we can look forward to building a great product on the most solid foundations.

Today we are proud to announce:

1. The launch of our Documentation Website
2. The Github repository release of our Core Smart Contracts (v0.1)

Boson Protocol Documentation Site Launch

We have developed a documentation site which provides both technical and non-technical documentation about our core contracts, how developers might start using them and how to integrate them.

The Doc site covers:

• Protocol overview
• Core concepts
• Advanced topics
• Governance
• Roadmap
• FAQs
• How to contribute
• Code of Conduct.

These areas are just a starting point and as we release more content, it will be regularly updated.

>> You can now visit the site here: https://Bossonprotocol.co

v0.1 release of the core Boson Protocol smart contracts

Today, we released v0.1 of the core Boson Protocol smart contracts. Below is a brief description of the smart contracts used in Boson Protocol. They are based on two NFT standards, ERC-1155 and ERC-721.

Main contracts:

• BosonRouter: user interface of Boson Protocol
• Cashier: escrow and funds management
• ERC1155ERC721: token factory
• FundLimitsOracle: restrictions on the allowed escrowed amounts
• VoucherKernel: main business logic
• UsingHelpers: common utilities

A control graph of the contracts is available here.

There are three types of funds in Boson Protocol, one for the payment and two for security deposits:

• The price of the asset
• The Seller’s deposit
• The Buyer’s deposit

Supported currencies are currently: ETH and $BOSON tokens.

Exchange mechanism

The journey through the NFT lifecycle is presented on a simplified diagram below.

A detailed game tree is available here, showcasing the actions that Sellers and Buyers can make. The order of some of these transactions is not prescribed, e.g. a Seller can do a CancelOrFault transaction independently of any Buyer action.

Process

Step 1: The process starts when the Seller makes an offer to sell something. He is making a promise to execute the exchange of his non-monetary asset for a monetary asset of a Buyer at a later point in time. He has some skin in the game, pressuring him to deliver what was promised, as a Seller’s deposit. The offer can be for an arbitrary amount of items, thus the Seller specifies the quantity of available things that all bear similar properties, we say such an offer is a Voucher Set.

Step 2: The Buyer discovers the offer and decides to purchase a single Voucher. In doing so, she commits to redeem that voucher in the future by putting the Buyer’s amount of security deposit in escrow, alongside the payment amount.

Step 3: The Buyer can then choose to “redeem” the voucher and exchange the payment amount for the item received, or can choose to “refund” the voucher, thus getting the payment back, but also potentially losing the deposit, or can choose not to do anything (she can just forget about it), in which case the voucher “expires”.

Step 4: The Buyer can then “complain”, signaling dissatisfaction with the promise execution. When this happens, the Seller is penalized.

Step 5: The Seller can at any time, independently of the Buyer, issue a “cancelOrFault” transaction, which can cancel the current offer and/or admit fault in a quality delivery, thus admitting part of his deposit to be sent to the Buyer as a recourse.

Sept 6: Wait periods start ticking at various points in the game tree. Once passed, they are marked for each Voucher and ultimately the Voucher is “finalized”, meaning neither the Buyer nor the Seller can use it any more.

Step 7: Finally, funds in escrow are released according to the Voucher’s status.

Wait periods

There are three different wait periods, also visible in the game tree diagram:

• the Voucher’s validity period: the start and end dates when the voucher can be redeemed
• the complain period: during which the Buyer can complain
• the cancelOrFault period: during which the Seller can issue a cancel-or-fault transaction

The validity period is set by the Seller when creating an offer. The complain and cancelOrFault periods are global for the whole Boson Protocol in the “VoucherKernel” contract.

Voucher lifecycle

A Voucher’s status is defined in 7 bits that are set depending on the path in its lifecycle (defined in UsingHelpers.sol):

• Committed
• Redeemed
• Refunded
• Expired
• Complained
• Cancel or Fault
• Final

There are also a few additional, more technical flags that record the status of the funds of a particular vouchers and that also record the timestamps of wait periods triggering.

Services in the background

A scheduled process is running in the back end that flags the vouchers when redemption was made and when wait periods expire. Anybody could execute these functions, marked as external — the back end is currently running them for convenience: “VoucherKernel.triggerExpiration”, “VoucherKernel.triggerFinalizeVoucher”, “Cashier.withdraw”.

Happy path

The process starts with the Seller making an offer — minting a VoucherSet, which is represented as an ERC-1155 token: “BosonRouter.requestCreateOrder”. The Seller sets the expiration period of the whole VoucherSet.

Then the Buyer purchases the Voucher, i.e. is committing to redeem it at some point later — this means an ERC-721 token is extracted from a VoucherSet: “BosonRouter.requestVoucher”.

The Buyer redeems the voucher, thus releasing the payment amount to the Seller: “BosonRouter.redeem”.

After the two wait periods pass (the period within which the Buyer can complain and the period within which the Seller can admit cancel/fault), the Seller’s deposit can be returned to the Seller and Buyer’s deposit can be returned to the Buyer.

You can dive into our Core Repo here.

You can read more at Documentation website here.

About Boson Protocol

Boson Protocol’s vision is to enable a decentralized commerce ecosystem by funding and enabling the development of a stack of specialist applications to disrupt, demonopolize and democratize commerce.

Keen to learn more?

Enjoy our Lightpaper.

In a hurry?

Check out our One Pager.

Want to dive deeper?

Read our whitepaper.

Builders, we have news for you:

Our Core Repo is open on GitHub and here’s the Documentation website.

Lastly, if you’re a decentralization enthusiast, please follow us here, on Medium. We will post frequently about our dCommerce journey and would love to hear your comments!