Announcing The Bee Payment Protocol
We’re happy to announce, the P in the PAR protocols, the Bee Payment Protocol.
In this technical article — join our Senior Software Engineer Vic Woeltjen on a brief tour through the inner workings of smart contracts and solidity.
Learn what a protocol is; how payments work; and what’s been improved upon since the last release.
—
What is a Protocol?
A protocol is a way of coordinating behavior. Communications protocols, as an example, tell you how to derive semantics from a raw message, and set expectations for how entities will act in response to particular messages.
A protocol isn’t necessarily technical; when we begin a conversation with a greeting and end with a farewell, we use a social protocol to establish expectations about where our attention is oriented.
In commerce, protocols coordinate the exchange of goods and services. In a retail setting, a cashier will summarize a purchase and request a total for payment, then follow additional protocols for handling distinct payment types, off-nominal situations like refunds, and so on.
Smart contracts provide an opportunity to handle these protocols in a more well-defined, deterministic fashion.
Once participants in a transaction agree to use a protocol defined by a smart contract, the set of expectations associated with the protocol become very firmly grounded: The contract can only do what it says it does.
The “Payments Problem”
The Bee Token engineering team has been hard at work designing, implementing, and integrating a new approach to handling payments on Beenest.
Specifically, we’ve been working to streamline token payments, which sit at the center of our fee-free accommodation model pictured below:
Prior to these changes, we accepted BEE token payments using a privileged backend service running an Ethereum node with some custom API to handle the payment steps.
This provided a nice baseline of functionality, calling into smart contracts to manage tokenized funds from guest to host, but it also came with some drawbacks.
In the older model, we handled payments with a smart contract deployed with an address controlled by our Ethereum node designated as a privileged owner. While contract execution and interactions with our token were all handled on-chain, most of these steps could only be triggered by our privileged address.
The New Approach
Bee Protocol payments are still a contract deployed to the Ethereum blockchain, but we’ve factored out the privileged backend.
There is still an administrator address as a failsafe, and to support administrative functions like refunds.
However, for nominal transactions, interactions with the contract can all be made directly from the Ethereum wallets of hosts or guests. With this contract, it is possible to complete payment for a booking without any intervention from Beenest.
As you can see in the above diagram, details about listings and bookings are still kept off-chain in a database, just like a more typical web commerce platform.
When payments are made, a unique identifier is provided to the contract corresponding to a booking in our database. This allows Beenest to recognize which payments correspond with which bookings, creating a more seamless experience for the end user.
Why do this?
One of the main benefits on our end is a reduction in engineering complexity; we no longer need to write and maintain custom API or administer an Ethereum node just to support these interactions, as they are now initiated directly from our guests and hosts using MetaMask or other browser-integrated wallet software.
To a guest or host using Beenest, the change is largely transparent, but does come with some tangible benefits.
By minimizing the actions of an administrator (the most we can do is refund a payment when we detect fraud or error) we reduce the role of trust in our system.
Payment outcomes are determined by contract: Trust becomes deterministic.
What does the new protocol look like?
The new protocol defines five actions which represent unique steps in the progress of a payment.
Invoice
After a guest requests a booking, a host issues a corresponding invoice. This is handled as a call to a contract on an Ethereum blockchain, but to the host it looks like a button click and a MetaMask transaction. After invoicing, the guest’s funds (which are approved for transfer when the booking is requested) are held in the payments contract until a future outcome. This includes both the price of the listing, and a security deposit, used in cases of dispute.
Cancel
When a guest decides to cancel a booking, that is also as simple as a call to the contract. Assuming that the call is made before the cancellation deadline, the contract will dutifully transfer a cancellation fee to the host, and the rest of the funds back to the guest.
Dispute
When a host or guest feels that the exchange has not happened and agreed, the host or guest may make a dispute call to the payments contract, up until a dispute deadline. This moves funds (both the listing price and deposit) into our arbitration workflow, where arbiters subsequently decide on an outcome: Which amounts get transferred to whom?
Refund
In the event that something goes wrong on our end, we as administrators have the option to simply refund a payment to a guest. This transfers the full price and deposit back to the guest, like the movement of funds never happened!
Payout
The cancel and dispute deadlines are both determined by the guest’s booking dates. After the dispute deadline has passed, the host is able to make a payout call. This transfers the deposit back to the guest, and transfers the price of the booking on to the host.
An invoice — is used to initiate a payment; the rest of the verbs all represent outcomes. Each emits a corresponding event to allow off-chain monitoring of the status of all payments handled by the contract. Our backend observes these events to keep our database up-to-date with the state of our contract on the Ethereum blockchain.
As an example, the Solidity source code for the invoice call (with code from most modifiers in-lined and rote validation removed for clarity) looks like:
Here, we perform some validations on inputs, primarily to ensure that a sufficient time period is provided for cancellation or disputes. After that, we record the details associated with this payment for later use, and then transfer funds from the purchaser to the Payments contract to hold until a payment outcome is reached.
Finally, we emit an event to notify off-chain components (like our backend) that the payment has progressed to this step.
What does a “new” nominal payment flow look like?
- A guest completes a booking via beenest.com and issues an associated approve call to our Token contract, which we treat as roughly analogous to providing credit card information in a fiat-payment paradigm. The approved amount includes both the price of the booking and a security deposit.
- We notify the host, who logs into beenest.com to accept the new booking, and makes an invoice call to our Payments contract to initiate the transfer of approved funds.
- Our backend observes this event and compares it to the booking details in our database. If there is a mismatch, we receive an internal notification for follow-up (e.g. to refund erroneous invoice attempts).
- The guest receives check-in details and completes their trip.
- After cancellation and dispute deadlines have passed, the host logs into beenest.com and makes a payout call. The Payments contract transfers funds to the host’s wallet, and returns the security deposit to the guest’s wallet.
What’s Comes Next
Our new Payments contract represents a step in a broader maturation process of three core protocols.
Concurrently, we’ve been implementing our first-generation Arbitration contract: When a dispute is made, it is this contract (as operated by arbiters) which will handle decisions about who receives the associated funds.
Arbitration will in turn integrate with a Reputation contract to establish confidence in the quality of arbiter decisions.
Taken as a whole, these contracts represent a complete (yet simple!) peer-to-peer payment system to empower new levels of transparency for market platforms like Beenest.
If you would like to learn more about protocols or vacation rentals on blockchain — please visit our website at beenest.com!
Thanks for reading!
—
Vic Woeltjen
Senior Software Engineer| The Bee Token | Beenest
Email: vic@beenest.com
Join the Conversation!
