Cashing Out

As your Bee forwards and serves chunks to its peers, it is rewarded in gBZZ in the form of cheques. Once these cheques accumulate sufficient value, you may cash them out using Bee's API. This process transfers money from your peer's chequebooks into your own, which you can then withdrawal to your wallet to do with as you please!

important

PLEASE! Do not cash out your cheques too regularly! Once a week is more than sufficient! This prevents and relieves unneccesary congestion on the blockchain. ๐Ÿ’ฉ

info

Learn more about how SWAP and other accounting protocols work by reading

The Book of Swarm .

Bee contains a rich set of features to enable you to query the current accounting state of your node. First, let's query our node's current balance by sending a POST request to the balances endpoint.

curl localhost:1635/chequebook/balance | jq
{
"totalBalance": 10000000,
"availableBalance": 9640360
}

It is also possible to examine your per-peer balances.

curl localhost:1635/balances | jq
{
"balances": [
//...
{
"peer": "d0bf001e05014fa036af97f3d226bee253d2b147f540b6c2210947e5b7b409af",
"balance": -85420
},
{
"peer": "f1e2872581de18bdc68060dc8edd3aa96368eb341e915aba86b450486b105a47",
"balance": -75990
}
//...
]
}

In Swarm, these per-peer balances represent trustful agreements between nodes. Tokens only actually change hands when a node settles a cheque. This can either be triggered manually or when a certain threshold is reached with a peer. In this case, a settlement takes place. You may view these using the settlements endpoint.

More info can be found by using the chequebook api.

curl localhost:1635/chequebook/cheque | jq
{
"totalreceived": 0,
"totalsent": 718030,
"settlements": [
//...
{
"peer": "dce1833609db868e7611145b48224c061ea57fd14e784a278f2469f355292ca6",
"received": 0,
"sent": 89550
}
//...
]
}

As our node's participation in the network increases, we will begin to see more and more of these balances arriving. In the case that we have received a settlement from another peer, we can ask our node to perform the relevant transactions on the blockchain, and cash our earnings out.

To do this, we simply POST the relevant peer's address to the cashout endpoint.

curl -XPOST http://localhost:1635/chequebook/cashout/d7881307e793e389642ea733451db368c4c9b9e23f188cca659c8674d183a56b
{"transactionHash":"0xba7b500e21fc0dc0d7163c13bb5fea235d4eb769d342e9c007f51ab8512a9a82"}

You may check the status of your transaction using Goerli Etherscan

Finally, we can now see the status of the cashout transaction by sending a GET request to the same URL.

curl http://localhost:1635/chequebook/cashout/d7881307e793e389642ea733451db368c4c9b9e23f188cca659c8674d183a56b | jq
{
"peer": "d7881307e793e389642ea733451db368c4c9b9e23f188cca659c8674d183a56b",
"chequebook": "0xae315a9adf0920ba4f3353e2f011031ca701d247",
"cumulativePayout": 179160,
"beneficiary": "0x21b26864067deb88e2d5cdca512167815f2910d3",
"transactionHash": "0xba7b500e21fc0dc0d7163c13bb5fea235d4eb769d342e9c007f51ab8512a9a82",
"result": {
"recipient": "0x312fe7fde9e0768337c9b3e3462189ea6f9f9066",
"lastPayout": 179160,
"bounced": false
}
}

Success, we earned our first gBZZ! ๐Ÿ

Now we have earnt tokens, to withdraw our gBZZ from the chequebook contract back into our node's own wallet, we simply POST a request to the chequebook withdraw endpoint.

curl -XPOST http://localhost:1635/chequebook/withdraw\?amount\=1000 | jq

And conversely, if we have used more services than we have provided, we may deposit extra gBZZ into the chequebook contract by sending a POST request to the deposit endpoint.

curl -XPOST http://localhost:1635/chequebook/deposit\?amount\=1000 | jq
{"transactionHash":"0x60fd4be6c1db4552ecb5cd3c99f6a4906089277f592593cccd1fee0dbf501085"}

You may then use Etherscan to track your transaction and make sure it completes successfully.

https://goerli.etherscan.io/tx/0xedc80ebc89e6d719e617a50c6900c3dd5dc2f283e1b8c447b9065d7c8280484a`

Managing uncashed cheques#

For the Bee process, the final step of earning BZZ is cashing a cheque. It is worth noting that a cheque is not yet actual gBZZs. In Bee, a cheque, just like a real cheque, is a promise to hand over money upon request. In real life, you would present the cheque to a bank. In swarm life, we present the cheque to a smart-contract. Holding on to a swap-cheque is risky; it is possible that the owner of the chequebook has issued cheques worth more gBZZ than is contained in their chequebook contract. For this reason, it is important to cash out your cheques every so often. With the set of API endpoints, as offered by Bee, it is possible to develop a script that fully manages the uncashed cheques for you. As an example, we offer you a very basic script, where you can manually cash out all cheques with a worth above a certain value. To use the script:

  1. Download and save the script:
wget -O cashout.sh https://gist.githubusercontent.com/ralph-pichler/3b5ccd7a5c5cd0500e6428752b37e975/raw/cashout.sh
  1. Make the file executable
chmod +x cashout.sh
  1. List all uncashed cheques and cash out your cheques above a certain value
  • List:
./cashout.sh
info

If running ./cashout.sh returns nothing, you currently have no uncashed cheques.

  • Cashout all cheques worth more than 5 BZZ
./cashout.sh cashout-all 5
info

Are you a Windows-user who is willing to help us? We are currently missing a simple cashout script for Windows. Please see the issue

info

Please find the officially deployed smart-contract by the Swarm team in the swap-swear-and-swindle repository