{"id":19345936,"url":"https://github.com/tolitius/bb8","last_synced_at":"2025-10-16T07:36:41.939Z","repository":{"id":57515444,"uuid":"118869858","full_name":"tolitius/bb8","owner":"tolitius","description":"a command line interface to Stellar networks","archived":false,"fork":false,"pushed_at":"2018-06-28T13:48:55.000Z","size":4948,"stargazers_count":36,"open_issues_count":8,"forks_count":3,"subscribers_count":4,"default_branch":"master","last_synced_at":"2025-04-23T04:44:36.000Z","etag":null,"topics":["blockchain","cli","cryptocurrency","stellar"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"epl-1.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tolitius.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-01-25T06:03:16.000Z","updated_at":"2024-04-04T21:15:31.000Z","dependencies_parsed_at":"2022-09-26T18:00:47.162Z","dependency_job_id":null,"html_url":"https://github.com/tolitius/bb8","commit_stats":null,"previous_names":["tolitius/stellar-mc"],"tags_count":19,"template":false,"template_full_name":null,"purl":"pkg:github/tolitius/bb8","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolitius%2Fbb8","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolitius%2Fbb8/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolitius%2Fbb8/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolitius%2Fbb8/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tolitius","download_url":"https://codeload.github.com/tolitius/bb8/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tolitius%2Fbb8/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":279166181,"owners_count":26117985,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-16T02:00:06.019Z","response_time":53,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["blockchain","cli","cryptocurrency","stellar"],"created_at":"2024-11-10T04:08:23.675Z","updated_at":"2025-10-16T07:36:41.910Z","avatar_url":"https://github.com/tolitius.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Beebee Ate\n\n\u003cimg src=\"doc/img/stellar-bb8-logo.png\" width=\"150px\"\u003e\n\n[![Release Version](https://img.shields.io/github/release/tolitius/bb8.svg)](https://github.com/tolitius/bb8/releases/latest)\n[![Build Status](https://travis-ci.org/tolitius/bb8.svg?branch=master)](https://travis-ci.org/tolitius/bb8)\n\nA command line interface to [Stellar](https://www.stellar.org/) networks.\n\n- [Why](#why)\n- [Installation](#installation)\n  - [Homebrew](#homebrew)\n    - [Updating to the latest release](#updating-to-the-latest-release)\n  - [Download, Unpack, Go](#download-unpack-go)\n  - [Or just Go](#or-just-go)\n- [Choose Stellar Network](#choose-stellar-network)\n  - [Point to a Custom Network](#point-to-a-custom-network)\n- [Buttons to Push](#buttons-to-push)\n- [Create Account Keys](#create-account-keys)\n  - [Vanity Address](#vanity-address)\n- [Create Account](#create-account)\n  - [Funding Test Account](#funding-test-account)\n  - [Creating New Account](#creating-new-account)\n- [Account Details](#account-details)\n- [Issue a New Token](#issue-a-new-token)\n  - [Issuer and Distributor](#issuer-and-distributor)\n  - [Creating and funding accounts](#creating-and-funding-accounts)\n  - [Do You Trust Me?](#do-you-trust-me)\n  - [Limit Trustline](#limit-trustline)\n- [Send Payments](#send-payments)\n  - [Send Non Native Assets](#send-non-native-assets)\n  - [Send Native Assets](#send-native-assets)\n  - [Add Memo](#add-memo)\n- [Account Merge](#account-merge)\n- [Transaction Options](#transaction-options)\n  - [Add Discoverablity and Meta Information](#add-discoverablity-and-meta-information)\n  - [Inflation Destination](#inflation-destination)\n  - [Set and Clear Flags](#set-and-clear-flags)\n  - [Thresholds](#thresholds)\n  - [Master Weight](#master-weight)\n  - [Add and Remove Signers](#add-and-remove-signers)\n- [Composing Transaction Operations](#composing-transaction-operations)\n  - [Issue Token and Set Options](#issue-token-and-set-options)\n  - [Decoding Base64 XDR](#decoding-base64-xdr)\n- [Manage Data](#manage-data)\n  - [Add Data](#add-data)\n  - [Remove Data](#remove-data)\n- [Stream Stellar Events](#stream-stellar-events)\n- [Set Default Address and Seed](#set-default-address-and-seed)\n  - [Standalone Transactions](#standalone-transactions)\n  - [Composed Transactions](#composed-transactions)\n- [Federation](#federation)\n  - [Lookup Account or Address](#lookup-account-or-address)\n  - [Federation Address in Transactions](#federation-address-in-transactions)\n- [Help Flag](#help-flag)\n- [Donate](#donate)\n- [License](#license)\n\n## Why\n\nThere are already multiple ways to interact with Stellar:\n\n* [REST API](https://www.stellar.org/developers/horizon/reference/index.html)\n* [SDK libraries](https://www.stellar.org/developers/reference/#libraries) in several languages\n* [Stellar Laboratory](https://www.stellar.org/laboratory/)\n\nBB-8 adds command line / terminal capabilities to the Stellar family of tools. This is useful for exploration as well as the real world interaction with Stellar networks.\n\nCommand line shells are interactive by design and have a very rich and familiar set of tools that could be applied to Stellar API directly, ranging from simple account details:\n\n```sh\n$ bb load-account GADGVH6PHMF2UGVHO446SHQR2WUJEELRBSDPRQBP7K63WJBKMV5MFX2F |\n                  jq '.inflation_destination, .balances'\n\n\"GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT\"\n{\n  \"balance\": \"42.0000000\",\n  \"limit\": \"42.0000000\",\n  \"asset_type\": \"credit_alphanum4\",\n  \"asset_code\": \"YUM\",\n  \"asset_issuer\": \"GDK5BSGYV2XFMO6H7OFTZDLJ2LFXTGMZLC4267OJQ4EASOFDBCELGBOA\"\n},\n{\n  \"balance\": \"10041.9999400\",\n  \"asset_type\": \"native\"\n}\n```\n\nto transaction operation composition:\n\n```sh\n$ bb change-trust '{\"source_account\": \"seed\",\n                    \"code\": \"YUM\",\n                    \"issuer\": \"address\"}' | xargs \\\n  bb set-options  '{\"home_domain\": \"stellar.org\",\n                    \"max_weight\": 1}' | xargs \\\n  bb sign '[\"seed\"]' | xargs \\\n  bb submit\n```\n\nand runtime rollups:\n\n```sh\n$ bb stream --transactions bob*stellar.org |\n            grep --line-buffered fee_paid |\n            awk -F\" \" '{rollup+=$2; print \"total fees paid: \"rollup}'\n\ntotal fees paid: 100\ntotal fees paid: 300\ntotal fees paid: 500\ntotal fees paid: 700\ntotal fees paid: 900\ntotal fees paid: 1000\ntotal fees paid: 1100\n```\n\nStellar has great API, command line shells have Turing complete power, they make a lovely couple.\n\n## Installation\n\nThere are multiple ways to install BB-8. The easiest one is with [Homebrew](https://brew.sh/):\n\n### Homebrew\n\n```sh\n$ brew tap tolitius/bb8\n```\n\n```sh\n$ brew install bb8\n==\u003e Downloading https://github.com/tolitius/bb8/releases/download..\n######################################################################## 100.0%\n🍺  /usr/local/Cellar/bb8[version]: 4 files, 7.7MB, built in 3 seconds\n```\n\nand BB-8 is ready to rock:\n\n```sh\n$ bb --help\n```\n\n#### Updating to the latest release\n\n```sh\n$ brew update\n$ brew upgrade bb8\n```\n\n### Download, Unpack, Go\n\nIf Homebrew is not an option grab a BB-8 release from [here](https://github.com/tolitius/bb8/releases) that matches your operating system.\n\nUnpack it:\n\n```sh\ntar -xvzf bb8_[version]_[OS].tar.gz\n```\n\nand go:\n\n```sh\n$ ./bb --help  ##  or \"bb.exe --help\" on Windows\n```\n\n### Or just Go\n\nIf you have Golang installed, you could simply:\n\n```sh\n$ go get -u github.com/tolitius/bb8\n```\n\na runnable `bb` will be under `$GOBIN`:\n\n```sh\n$ $GOBIN/bb --help\n```\n\nOr clone the repo and `go build` it if you prefer a bare minimum.\n\n## Choose Stellar Network\n\nBy default BB-8 uses the Stellar [test network](https://www.stellar.org/developers/guides/concepts/test-net.html) a.k.a. testnet.\n\nIn case the work needs to be done on the Stellar public network a `STELLAR_NETWORK` environment variable should be set to \"`public`\":\n\n```sh\n$ export STELLAR_NETWORK=public\n```\n\nIf `STELLAR_NETWORK` is unset or is set to \"`test`\" a testnet will be used.\n\n### Point to a Custom Network\n\nTo use a custom Stellar network add it to a BB-8 configuration file in a form of:\n\n```json\n{\"network\":{\n    \"my-custom-stellar\":{\n        \"name\":\"friendly official name of the network\",\n        \"passphrase\":\"the passphrase of the network\",\n        \"horizon\":{\n            \"entries\":{\n                \"one-name\":{\n                    \"url\":\"https://my-horizon.domain.dom/\"\n                },\n                \"other-name\":{\n                    \"url\":\"https://otherdomain.tld/horizon/\"\n                },\n                \"one-more\":{\n                    \"url\":\"https://horizon-backup.domain.dom\"\n                }\n            },\n            \"default\":\"one-name\"\n        }\n    }\n  }\n}\n```\n\nHere is an [example](examples/sample-config.json) of such a configuration file. This file usually lives in a user home directory as `home.dir/.bb8/bb8.json`.\n\nThen you can specify a network by name via `--network` flag:\n\n```sh\n$ bb --network my-custom-stellar command ...\n2018/02/28 12:17:40 running on horizon: https://my-horizon.domain.dom/\n```\n\nYou can also specify `--horizon` and `--horizon-url` to specify horizon entry by name or a Horizon URL that is not in config:\n\n```sh\n$ bb --network my-custom-stellar --horizon one-more command ...\n2018/02/28 12:17:40 running on horizon: https://my-horizon.domain.dom/\n```\n\nHere are all the flags:\n\n```sh\n      --horizon string       horizon server name from the BB8 config file. by default BB8 would look in \"home.dir/.bb8/bb8.json\" file\n      --horizon-url string   horizon server URL to use for \"this\" transaction\n  -n, --network string       network name from the BB8 config file. by default BB8 would look in \"home.dir/.bb8/bb8.json\" file\n```\n\n## Buttons to Push\n\n``` sh\n$ bb --help\n```\n```\nBB-8 is a command line interface to Stellar (https://www.stellar.org/) networks.\n\nUsage:\n  bb [command]\n\nAvailable Commands:\n  account-merge  merges two native (XLM) accounts\n  change-trust   create, update, or delete a trustline\n  create-account creates a new account\n  decode         decodes a base64 encoded transaction\n  fund           fund a test account\n  gen-keys       create a pair of keys (in two files \"file-name.pub\" and \"file-name\")\n  help           Help about any command\n  load-account   load and return account details\n  manage-data    set, modify or delete a Data Entry (name/value pair)\n  send-payment   send payment from one account to another\n  set-options    set options on the account\n  sign           sign a base64 encoded transaction\n  stream         stream \"ledger\", \"payment\" and \"tranasaction\" events\n  submit         submit a base64 encoded transaction\n  version        print the version number of bb\n\nFlags:\n  -h, --help                 help for bb\n      --horizon string       horizon server name from the BB8 config file. by default BB8 would look in \"home.dir/.bb8/bb8.json\" file\n      --horizon-url string   horizon server URL to use for \"this\" transaction\n  -n, --network string       network name from the BB8 config file. by default BB8 would look in \"home.dir/.bb8/bb8.json\" file\n\nUse \"bb [command] --help\" for more information about a command.\n```\n\nCommands that create transaction operations (create-account, change-trust, send-payment, set-options, etc.) are by default _composable_, which means the output of one command may be piped as an input to another. In order to run them stand alone there is an `-s`/`--sign-and-submit` flag which will be used in most of the examples below to run commands individually.\n\nThe \"[Composing Transaction Operations](#composing-transaction-operations)\" section talks about composing commands together and piping composed transactions to `sign` and `submit` commands.\n\n## Create Account Keys\n\nEvery Stellar account has a pair of keys:\n\n* a public key that is also known as account's `address`\n* a private key that is also known as `seed`\n\nBB-8 has a `gen-keys` command to generate this pair of keys:\n\n``` sh\n$ bb gen-keys foo\n2018/01/30 15:15:46 keys are created and stored in: foo.pub and foo\n```\n\n`foo` in this case is a path to a pair of files where these keys will be stored:\n\n```sh\n$ echo address: $(cat foo.pub); echo seed: $(cat foo)\naddress: GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY\nseed: SAWDCNZF7Y67RWT5FC6YSAHFRH23OFU2OFYFXFNWYETL7S7J72CWK6JG\n```\n\nAn account `seed` should be kept private, hence the \"`private`\" key.\nIt is later used to _sign_ Stellar transactions to confirm that it is \"_really you_\" and \"_you approve_\" the transaction.\n\n### Vanity Address\n\nSometimes it is desired to have a recognizable Stellar address. There are a couple of ways to do that:\n\n* using a federation server, then an address can be used as `john_malkovich*lestercorp.com`\n* generating a \"vanity address\", which is a pair of keys, where a public key has a predefined pattern\n\n[Federation](#Federation) section talks more about the first approach.\n\nA new \"vanity address\" can be generated with `gen-keys` command by giving it a desired suffux (`--suffix`/`-s`) or prefix (`--prefix`/`-p`) or both.\n\nFor example, BB-8 has an old friend [R2-D2](https://en.wikipedia.org/wiki/R2-D2) who found out about Stellar and is itching to try it. As a true friend, BB-8 can generate a vanity address for R2-D2 that ends with \"`ARTOO`\" characters so there is less confusion when looking at the key:\n\n```sh\n$ bb gen-keys --suffix ARTOO r2d2\n\n2018/04/19 18:10:33 asking 8 CPU cores to find keys with ARTOO suffix. stand by.\nwent through 1,006,713 keys\t| rate 100,671/s\t| still looking\nwent through 2,035,593 keys\t| rate 102,829/s\t| still looking\nwent through 3,060,833 keys\t| rate 102,400/s\t| still looking\nwent through 4,086,549 keys\t| rate 102,571/s\t| still looking\nwent through 5,105,370 keys\t| rate 101,881/s\t| still looking\n+----------------------------------------------------------+--------+--------------+-------------------+\n|                         ADDRESS                          | SUFFIX | TOOK SECONDS | WENT THROUGH KEYS |\n+----------------------------------------------------------+--------+--------------+-------------------+\n| GASORP4RN4YWUTO64VLCM7CSQSMASMG53LPHXO5YHG4TPU6FMTGARTOO | ARTOO  |           50 |           5549842 |\n+----------------------------------------------------------+--------+--------------+-------------------+\n2018/04/19 18:11:28 keys are created and stored in: r2d2.pub and r2d2\n```\n\nAs you can see BB-8 looked up the number of CPU cores available and gently asked these cores to generate new Stellar addresses until one of them has an `ARTOO` suffix.\n\n```sh\n$ bb gen-keys -p DRO -s ID r2d2\n\n2018/04/20 20:47:38 asking 8 CPU cores to find keys with \"DRO\" prefix and \"ID\" suffix. stand by.\nwent through 1,017,108 keys\t| rate 101,710/s\t| still looking\nwent through 2,029,680 keys\t| rate 101,254/s\t| still looking\nwent through 3,040,313 keys\t| rate 101,062/s\t| still looking\nwent through 4,064,337 keys\t| rate 102,401/s\t| still looking\nwent through 5,065,131 keys\t| rate 100,078/s\t| still looking\n+----------------------------------------------------------+--------+--------+--------------+-------------------+\n|                         ADDRESS                          | PREFIX | SUFFIX | TOOK SECONDS | WENT THROUGH KEYS |\n+----------------------------------------------------------+--------+--------+--------------+-------------------+\n| GDRORLZZTD7SPFZ3SOV53KMYKGHBII6ZV32B5KRZI6GXRBNMSXRFLTID | DRO    | ID     |           50 |           5499735 |\n+----------------------------------------------------------+--------+--------+--------------+-------------------+\n2018/04/20 20:48:33 keys are created and stored in: r2d2.pub and r2d2\n```\n\ngenerated a key with both prefix and suffix: G**DRO**RLZZTD7SPFZ3SOV53KMYKGHBII6ZV32B5KRZI6GXRBNMSXRFLT**ID**\n\n## Create Account\n\nOnce the account keys are generated there are two ways to create / record an account in the Stellar ledger:\n\n* Using Stellar's Friendbot to fund a new _test_ account address on the testnet\n* Using an existing account by sending a small token amount to a new account address\n\n### Funding Test Account\n\nStellar has a friendly utility called [Friendbot](https://www.stellar.org/developers/horizon/reference/tutorials/follow-received-payments.html#funding-your-account) that funds a new account on the Stellar test network. When a new account is created (e.g. a pair of keys we created above), this account has no balance and does not exist in the ledger until it is funded. Friendbot fixes that problem.\n\nBB-8 has `fund` command that takes an account's address and funds it a good amount of lumens:\n\n``` sh\n$ bb fund $(cat foo.pub)\n```\n\nhere we used a `foo.pub` address that we generated above. We'll look at this account on the real, distributed Stellar ledger in the [Account Details](#account-details) section.\n\n### Creating New Account\n\nBB-8 has `create-account` command that takes a source account's seed, a new account address, an initial amount and creates a new account.\n\nSince a new account needs an address before it can be created, let's generate keys for it:\n\n```sh\n$ bb gen-keys bar\n2018/01/30 15:17:12 keys are created and stored in: bar.pub and bar\n```\n\nAt this moment this new account \"bar\" does _not yet exist_ on the Stellar ledger, and would need to be \"created\".\n\nSince account \"foo\" was funded lumens in the step above it could be used as a source account to create \"bar\":\n\n```sh\n$ bb create-account -s '{\"source_account\":\"'$(cat foo)'\", \"new_account\":\"'$(cat bar.pub)'\", \"amount\":\"1.5\"}'\n```\n\nthis would create a new \"bar\" account by sending 1.5 XLM to it from an account \"foo\".\n\n## Account Details\n\nIn order to look at the account in the ledger BB-8 provides an `load-account` command that takes an account address and returns all the details known to Stellar:\n\n```sh\n$ bb load-account $(cat foo.pub)\n```\n```json\n{\n  \"_links\": {\n    \"self\": {\n      \"href\": \"https://horizon-testnet.stellar.org/accounts/GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY\"\n    },\n    \"transactions\": {\n      \"href\": \"https://horizon-testnet.stellar.org/accounts/GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY/transactions{?cursor,limit,order}\",\n      \"templated\": true\n    },\n    \"operations\": {\n      \"href\": \"https://horizon-testnet.stellar.org/accounts/GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY/operations{?cursor,limit,order}\",\n      \"templated\": true\n    },\n    \"payments\": {\n      \"href\": \"https://horizon-testnet.stellar.org/accounts/GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY/payments{?cursor,limit,order}\",\n      \"templated\": true\n    },\n    \"effects\": {\n      \"href\": \"https://horizon-testnet.stellar.org/accounts/GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY/effects{?cursor,limit,order}\",\n      \"templated\": true\n    },\n    \"offers\": {\n      \"href\": \"https://horizon-testnet.stellar.org/accounts/GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY/offers{?cursor,limit,order}\",\n      \"templated\": true\n    }\n  },\n  \"id\": \"GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY\",\n  \"paging_token\": \"\",\n  \"account_id\": \"GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY\",\n  \"sequence\": \"30170921188720640\",\n  \"subentry_count\": 0,\n  \"thresholds\": {\n    \"low_threshold\": 0,\n    \"med_threshold\": 0,\n    \"high_threshold\": 0\n  },\n  \"flags\": {\n    \"auth_required\": false,\n    \"auth_revocable\": false\n  },\n  \"balances\": [\n    {\n      \"balance\": \"10000.0000000\",\n      \"asset_type\": \"native\"\n    }\n  ],\n  \"signers\": [\n    {\n      \"public_key\": \"GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY\",\n      \"weight\": 1,\n      \"key\": \"GBTG5ZSVAG6LNKA5ZGMD4SJYJX4AQI347WYURPHZV7A6DC7FCG44DOMY\",\n      \"type\": \"ed25519_public_key\"\n    }\n  ],\n  \"data\": {}\n}\n```\n\nnotice the `balances` section:\n\n```sh\n$ bb load-account $(cat foo.pub) | jq '.balances'\n```\n\n```json\n{\n  \"balance\": \"10000.0000000\",\n  \"asset_type\": \"native\"\n}\n```\n\nit is telling us that the Friendbot from the step above did what we asked and funded this account with `10,000` lumens (a.k.a. as \"native\" Stellar currency).\n\n## Issue a New Token\n\n\u003e _One of Stellar’s most powerful features is the ability to trade any kind of asset, US dollars, Nigerian naira, bitcoins, special coupons, ICO tokens or just about anything you like. ([Stellar Developers Guide](https://www.stellar.org/developers/guides/issuing-assets.html))_\n\n### Issuer and Distributor\n\nThere are usually at least two accounts that participate in issuing a new token (a.k.a. \"asset\"):\n\n* an issuer account which \"signs a new asset into existence\"\n* a distribution account that sets a [trustline](https://www.stellar.org/developers/guides/concepts/assets.html#trustlines) for both: this \"asset\" and this \"issuer\", and is later used as an account that would distribute this asset to other accounts\n\nA distribution account is just a concept, and does not have to exist. Once the issuer signs an asset, any other account on the Stellar network can create a trustline: a declaration that it trusts a particular asset from a particular issuer.\n\nBut usually keeping a separate distribution account works well: it is easier to track funds since the money sent back to it won't disappear and would still remain in circulation while any money sent back directly to the issuer account would disappear.\n\nThe official name for the distribution account is [specialized issuing account](https://www.stellar.org/developers/guides/issuing-assets.html#specialized-issuing-accounts) as per Stellar documentation.\n\n### Creating and funding accounts\n\nIn this example we would assume no accounts exist so we'll generate issuer and distributor key pairs:\n\n``` sh\n$ bb gen-keys issuer\n2018/01/30 15:42:48 keys are created and stored in: issuer.pub and issuer\n\n$ bb gen-keys distributor\n2018/01/30 15:42:52 keys are created and stored in: distributor.pub and distributor\n```\n\nIn order to process transactions these accounts need to have a few `XLM`s for minimum balances, creating a trustline and transaction fees. We'll use Stellar's Friendbot to fund these accounts:\n\n``` sh\n$ bb fund $(cat issuer.pub)\n$ bb fund $(cat distributor.pub)\n```\n\nLet's make sure it worked by checking their balances:\n\n```sh\n$ bb load-account $(cat issuer.pub) | jq '.balances'\n```\n```json\n{\n  \"balance\": \"10000.0000000\",\n  \"asset_type\": \"native\"\n}\n```\n\n```sh\n$ bb load-account $(cat distributor.pub) | jq '.balances'\n```\n```json\n{\n  \"balance\": \"10000.0000000\",\n  \"asset_type\": \"native\"\n}\n```\n\n### Do You Trust Me?\n\nNow we are ready to issue a new token, let's call it `YUM`.\n\nIn order to do that we'd use a `change-trust` command to setup a trustline between the distribution account and the issuer:\n\n``` sh\n$ bb change-trust -s '{\"source_account\": \"'$(cat distributor)'\",\n                       \"code\": \"YUM\",\n                       \"issuer\": \"'$(cat issuer.pub)'\"}'\n```\n\n`change-trust` does several things:\n\n* creates a new asset (in this case `YUM`)\n* creates a new transaction where it sets a trustline between the receiving account (\"distributor\") and this asset\n* signs this transaction with distributor's seed\n* submits this transaction to Stellar\n\nLet's check that `YUM` is now an existing token that was issued by issuer's address and that the distributor has successfully _created a trustline_ for it:\n\n```sh\n$ bb load-account $(cat distributor.pub) | jq '.balances'\n```\n\n```json\n{\n  \"balance\": \"0.0000000\",\n  \"limit\": \"922337203685.4775807\",\n  \"asset_type\": \"credit_alphanum4\",\n  \"asset_code\": \"YUM\",\n  \"asset_issuer\": \"GBW2U2GEWVD7GDTQPPJSDGE4SRYXN3USYZKNNI6EPVHUHROS47S6NUZJ\"\n},\n{\n  \"balance\": \"9999.9999800\",\n  \"asset_type\": \"native\"\n}\n```\n\nNice! We have established a trustline for YUMs and almost ready to distribute them to other accounts. Notice the native balance is no longer 10,000 lumens. This is due to the fees the distribution account had to pay: 100 [stroops](https://www.stellar.org/developers/guides/concepts/assets.html#one-stroop-multiple-stroops) for the transaction processing and another 100 stroops for setting up a trustline which is one of the transaction operations.\n\nSetting up a trustline is done via a \"[Change Trust](https://www.stellar.org/developers/guides/concepts/list-of-operations.html#change-trust)\" operation in Stellar speak. By default this operation would allow a source account to receive up to `922337203685.4775807` (`MaxInt64  = 1\u003c\u003c63 - 1`) YUMs. But it has an additional `limit` parameter that sets a cap on how much YUMs an account may get.\n\n### Limit Trustline\n\nThe `change-trust` command takes an optional `limit` parameter to set such a cap. For example let's set a cap of `42` YUMs for the distribution account:\n\n``` sh\n$ bb change-trust -s '{\"source_account\": \"'$(cat distributor)'\",\n                       \"code\": \"YUM\",\n                       \"issuer\": \"'$(cat issuer.pub)'\",\n                       \"limit\": \"42.0\"}'\n```\n\n```sh\n$ bb load-account $(cat distributor.pub) | jq '.balances'\n```\n```json\n{\n  \"balance\": \"0.0000000\",\n  \"limit\": \"42.0000000\",\n  \"asset_type\": \"credit_alphanum4\",\n  \"asset_code\": \"YUM\",\n  \"asset_issuer\": \"GBW2U2GEWVD7GDTQPPJSDGE4SRYXN3USYZKNNI6EPVHUHROS47S6NUZJ\"\n},\n{\n  \"balance\": \"9999.9999600\",\n  \"asset_type\": \"native\"\n}\n```\n\nnotice the `\"limit\": \"42.0000000\"` for YUMs.\n\nAll the YUMmy details could be seen on any ledger interface. For example this is the distribution account on [testnet.stellarchain.io](http://testnet.stellarchain.io/address/GDPKQGOY33DYUPC3PXX222FRZOLQD4L6CMXGJV5I4W2GB4UOT4MCJCO5):\n\n\u003cimg src=\"doc/img/yum-42.png\"\u003e\n\nnotice a \"Change Trust\" operation and a zero balance (for now).\n\n## Send Payments\n\n### Send Non Native Assets\n\nIn order to send a payment of a non native assset, which is any token on a Stellar network besides `XLM`, we need to know several things:\n\n* sender's private key in order to sign this payment transaction\n* address of the recepient (i.e. receiving account's public key)\n* token code\n* amount\n* token issuer (i.e. issuer's public key)\n\nTo continue the [issuing a new token](#issuing-a-new-token) example, we'll send `42.0` YUMs from the issuer to distributor.\n\nBB-8 has a `send-payment` command that is capable of sending XLM as well as any other token, in this case YUM:\n\n```sh\n$ bb send-payment -s '{\"from\": \"'$(cat issuer)'\",\n                       \"to\": \"'$(cat distributor.pub)'\",\n                       \"token\": \"YUM\",\n                       \"amount\": \"42.0\",\n                       \"issuer\": \"'$(cat issuer.pub)'\"}'\n\n2018/01/30 16:11:56 sending 42.0 YUM from GBW2U2GEWVD7GDTQPPJSDGE4SRYXN3USYZKNNI6EPVHUHROS47S6NUZJ to GDPKQGOY33DYUPC3PXX222FRZOLQD4L6CMXGJV5I4W2GB4UOT4MCJCO5\n```\n\nLet's check the balance now:\n\n```sh\n$ bb load-account $(cat distributor.pub) | jq '.balances'\n```\n```json\n{\n  \"balance\": \"42.0000000\",\n  \"limit\": \"42.0000000\",\n  \"asset_type\": \"credit_alphanum4\",\n  \"asset_code\": \"YUM\",\n  \"asset_issuer\": \"GBW2U2GEWVD7GDTQPPJSDGE4SRYXN3USYZKNNI6EPVHUHROS47S6NUZJ\"\n},\n{\n  \"balance\": \"9999.9999600\",\n  \"asset_type\": \"native\"\n}\n```\n\nHere is the prettier version of `42.0` YUMs on [testnet.stellarchain.io](http://testnet.stellarchain.io/address/GDPKQGOY33DYUPC3PXX222FRZOLQD4L6CMXGJV5I4W2GB4UOT4MCJCO5):\n\n\u003cimg src=\"doc/img/yum-42-42.png\"\u003e\n\nSource (i.e. `\"from\"`) of the payment could be any account, not just the issuer, as long as this account has YUMs to send. The reason it was the issuer in the example above is that it was the only account that had YUMs. The issuer's public key though should still be used to identify the asset: \"this YUM token you are getting was indeed signed by me\".\n\nExcellent, we are now ready to distribute YUMs. We can use the same `send-payment` command with different account addresses to do that.\n\n### Send Native Assets\n\nIn order to send XLM (a.k.a. lumens) from one account to another `send-payment` command needs 3 things:\n\n* source account seed to sign the transaction\n* receiving account address\n* amount of XLM to send\n\nSince we funded the issuer account with XLMs in the example above, we'll use it as a source account, but of course any account that has lumens can be used instead:\n\n```sh\n$ bb send-payment -s '{\"from\": \"'$(cat issuer)'\",\n                       \"to\": \"'$(cat distributor.pub)'\",\n                       \"amount\": \"42.0\"}'\n\n2018/01/30 16:12:19 sending 42.0 XLM from GDK5BSGYV2XFMO6H7OFTZDLJ2LFXTGMZLC4267OJQ4EASOFDBCELGBOA to GADGVH6PHMF2UGVHO446SHQR2WUJEELRBSDPRQBP7K63WJBKMV5MFX2F\n```\n\nWe just sent 42 lumens from the issuer to the distribution account. Let's check the distribution account's balance:\n\n```sh\n$ bb load-account $(cat distributor.pub) | jq '.balances'\n```\n```json\n{\n  \"balance\": \"42.0000000\",\n  \"limit\": \"42.0000000\",\n  \"asset_type\": \"credit_alphanum4\",\n  \"asset_code\": \"YUM\",\n  \"asset_issuer\": \"GBW2U2GEWVD7GDTQPPJSDGE4SRYXN3USYZKNNI6EPVHUHROS47S6NUZJ\"\n},\n{\n  \"balance\": \"10041.9999600\",\n  \"asset_type\": \"native\"\n}\n```\n\nnotice it went from `9999.9999600` to `10041.9999600` and is now up by 42 lumens.\n\n### Add Memo\n\nTransactions also take an optional [memo](https://www.stellar.org/developers/guides/concepts/transactions.html#memo) field that is used for custom metadata.\nFor example if you are a bank that is receiving or sending payments on behalf of other people, you might include the actual person the payment is meant for here.\n\nIn order to include memo into a payment transaction add a `\"memo\"` key to `send-payment` arguments:\n\n```sh\n$ bb send-payment -s '{\"from\": \"'$(cat issuer)'\",\n                       \"to\": \"'$(cat distributor.pub)'\",\n                       \"amount\": \"42.0\",\n                       \"memo\": \"forty two\"}'\n```\n\n## Account Merge\n\nStellar allows to merge two accounts by transferring the native balance (the amount of XLM an account holds) from the source account to another (destination) account and removing the source account from the ledger.\n\nBB-8 has a `account-merge` command that takes a \"destination account\" to merge _to_, and optionally takes a \"source account\" that needs to be merged. If the source account is not provided, BB-8 will use an account that is set as [default](#set-default-address-and-seed):\n\n\n```sh\n$ bb gen-keys bar\n2018/03/03 21:54:16 keys are created and stored in: bar.pub and bar\n\n$ bb fund $(cat bar.pub)\n```\n\nmerging `bar` XLMs to account `foo` requires bar's signature and foo's address:\n\n```sh\n$ bb account-merge -s '{\"source_account\": \"'$(cat bar)'\",\n                        \"destination\":\"'$(cat foo.pub)'\"}'\n```\n\nonce these two accounts are merged, `foo` would get all the `bar`'s XLM balance (`- 100` stroops fee for this transaction).\n`bar` would no longer exist and would be removed from the ledger.\n\n## Transaction Options\n\nWhen submitting a transaction to Stellar there are several [transaction options](https://www.stellar.org/developers/guides/concepts/list-of-operations.html#set-options) that could be set.\n\nBB-8 has a `set-options` command that takes an account and these options as JSON and sets them on a transaction before it is submitted.\n\nThere is also a `--set-options` _flag_ that is available for all transaction commands such as `send-payment`, `change-trust`, `new-tx` and others.\n\n`set-options` command and `--set-options` flag have exactly the same syntax, hence the examples below are all valid for `--set-options` as well.\n\n### Add Discoverablity and Meta Information\n\nTo continue the [issue a new token](#issue-a-new-token) example, whenever a new token/asset is introduced to Stellar network it is important to provide clear information about what this token/asset represents. This info can be discovered and displayed by clients so users know exactly what they are getting when they hold your asset. Here is [more about it](https://www.stellar.org/developers/guides/issuing-assets.html#discoverablity-and-meta-information) from Stellar documentation.\n\nIn order to discover information about a particular token Stellar would look at the \"home domain\" property of an account and then it will try to read a \"[stellar.toml](https://www.stellar.org/developers/guides/concepts/stellar-toml.html)\" file at \"`https://home-domain/.well-known/stellar.toml`\".\n\nSince we issued a brand new `YUM` token, we can create a \"`stellar.toml`\" file to describe it make it reachable at \"`https://home-domain/.well-known/stellar.toml`\", and let Stellar know to look for it there by setting a \"home domain\" transaction option on the issuer's account with the `set-options` command:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat issuer)'\",\n                      \"home_domain\": \"dotkam.com\"}'\n```\n\nand now the issuer account is linked to its home domain where Stellar can find more details about it:\n\n```sh\n$ bb load-account $(cat issuer.pub) | jq '.home_domain'\n\"dotkam.com\"\n```\n### Inflation Destination\n\nAnother example of using Stellar transaction options would be setting an inflation destination on the account.\n\n\u003e _The Stellar distributed network has a built-in, fixed, nominal inflation mechanism. New lumens are added to the network at the rate of 1% each year. Each week, the protocol distributes these lumens to any account that gets over .05% of the “votes” from other accounts in the network_ (from [Stellar documentation](https://www.stellar.org/developers/guides/concepts/inflation.html))\n\nInflation destination can be set via `set-options`. For example let's set an inflation destination on the distribution account from the examples above:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat distributor)'\",\n                      \"inflation_destination\": \"GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT\"}'\n```\n\nWe can combine other options, let's add a home domain as well:\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat issuer)'\",\n                      \"inflation_destination\": \"GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT\",\n                      \"home_domain\": \"dotkam.com\"}'\n```\n\nand we can check that both options were set successfully:\n\n```sh\n$ bb load-account $(cat distributor.pub) | jq '.home_domain, .inflation_destination'\n\"dotkam.com\"\n\"GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT\"\n```\n\nHere is a prettier version of the options that were set in this transaction on [testnet.stellarchain.io](http://testnet.stellarchain.io/address/GDPKQGOY33DYUPC3PXX222FRZOLQD4L6CMXGJV5I4W2GB4UOT4MCJCO5):\n\n\u003cimg src=\"doc/img/tx-options.png\"\u003e\n\n### Set and Clear Flags\n\nThere are 3 different flags that can be set on the account that are set on issuers of assets:\n\n\n* Authorization required: Requires the issuing account to give other accounts permission before they can hold the issuing account’s credit.\n* Authorization revocable: Allows the issuing account to revoke its credit held by other accounts.\n* Authorization immutable: If this is set then none of the authorization flags can be set and the account can never be deleted.\n\nThese flags can be set or cleared with `\"set_flags\"` and `\"clear_flags\"` transaction options. Here are some examples:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"set_flags\": [\"auth_revocable\", \"auth_required\"]}'\n```\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"clear_flags\": [\"auth_immutable\", \"auth_required\"]}'\n```\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"set_flags\": [\"auth_revocable\"],\n                      \"clear_flags\": [\"auth_required\"]}'\n```\n\nBB-8 would validate these flags and will let you know when they are invalid:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"set_flags\": [\"auth_revocable\", \"auth_immu\"]}'\n```\n```\n\u003e\u003e unknown flag to set: \"auth_immu\". possible flag values: [auth_required auth_revocable auth_immutable]\n```\n\n### Thresholds\n\nTransaction operations fall under a specific threshold category: _low_, _medium_, or _high_. The threshold for a given level can be set to any number from 0-255. This threshold is the amount of signature weight required to authorize an operation at that level. Here is [more about thresholds](https://www.stellar.org/developers/guides/concepts/multi-sig.html#thresholds) from Stellar documentation.\n\nThreshold could be set with `set-options` via a `thresholds` map:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"thresholds\": {\"low\": 42, \"high\": 3}}'\n```\n\n### Master Weight\n\nA master key weight can be changed with a `\"master_weight\"` option:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"master_weight\": 42}'\n```\n\nNote that:\n\n\u003e _If the weight of the master key is ever updated to 0, the master key is considered to be an invalid key and you cannot sign any transactions with it (even for operations with a threshold value of 0). If there are other signers listed on the account, they can still continue to sign transactions._\" (Stellar [docs](https://www.stellar.org/developers/guides/concepts/multi-sig.html#additional-signing-keys))\n\n### Add and Remove Signers\n\nIf a transaction is composed out of [operations on multiple accounts](https://www.stellar.org/developers/guides/concepts/operations.html#transactions-involving-multiple-accounts) it would need signatures of all these accounts. Signer could be added or later removed with `\"add_signer\"` and `\"remove_signer\"` options:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"add_signer\": {\"address\": \"'$(cat bar.pub)'\", \"weight\": 3}}'\n```\n\nnotice the `\"weight\"` option, it could later be changed. Setting it to `0` would remove a signer, or it can be removed with the `\"remove_signer\"` option:\n\n```sh\n$ bb set-options -s '{\"source_account\": \"'$(cat foo)'\",\n                      \"remove_signer\": {\"address\": \"'$(cat bar.pub)'\"}}'\n```\n\n## Composing Transaction Operations\n\nA single Stellar transaction consists of an arbitrary list of [operations](https://www.stellar.org/developers/guides/concepts/operations.html). Transactions are ACID: when one transaction is submitted all its operations are executed in order and atomically: either all of them are applied or none.\n\nThere is a [limit](https://github.com/stellar/go/blob/333387f23a0f205a3c00bdc33cb454e0fda32095/xdr/xdr_generated.go#L2680) on how many of these operations can be included.\n\nComposition is a great way to support building a single Stellar transaction with multiple operations. Since BB-8 is a command line interface, it relies on command line composition tools such as [pipline](https://en.wikipedia.org/wiki/Pipeline_(Unix)) and [xargs](https://en.wikipedia.org/wiki/Xargs):\n\n```sh\n$ command | xargs command | xargs command ...\n```\n\nBB-8 commands are composable by default, in fact to make them not composable and to process them individually there is a separate `-s/--sign-and-submit` flag which is used in the examples above.\n\nOnce all the operations are composed a Stellar transaction needs to be signed and submitted. This is done with piping commands to `sign` and `submit` commands:\n\n```sh\n$ bb command | xargs \\\n  bb command | xargs \\\n  bb command | xargs \\\n  ...\n  bb sign '[seed1, seed2..]' | xargs \\\n  bb submit\n```\n\n### Issue Token and Set Options\n\nLet's issue a composition token `COMP` by composing \"change-trust\", \"set-options\", \"sign\" and \"submit\" commands:\n\n```sh\n$ bb change-trust '{\"source_account\": \"'$(cat distributor)'\",\n                    \"code\": \"COMP\",\n                    \"issuer\": \"'$(cat issuer.pub)'\"}' | xargs \\\n  bb set-options  '{\"home_domain\": \"dotkam.com\",\n                    \"max_weight\": 1}' | xargs \\\n  bb sign '[\"'$(cat distributor)'\"]' | xargs \\\n  bb submit\n```\n\n### Decoding Base64 XDR\n\nIf transaction command chain does not end with \"submit\", it would return a base64 encoded transaction:\n\n```sh\n$ bb change-trust '{\"source_account\": \"'$(cat distributor)'\",\n                    \"code\": \"CMP\",\n                    \"issuer\": \"'$(cat issuer.pub)'\"}' | xargs \\\n  bb set-options  '{\"home_domain\": \"dotkam.com\",\n                    \"max_weight\": 1}' | xargs \\\n  bb sign '[\"'$(cat distributor)'\"]'\n```\n```\nAAAAAG7sk5IccafeFhmT8BMrJHqIIVwvR0Tf1FQIaQoiihO9AAAAyABtjagAAAAQAAAAAAAAAAAAAAACAAAAAAAAAAYAAAABQ01QAAAAAACmTMqnWvpmw3VsrJZTdtuGwNp3CM6i4nQIX5YWWB9hdX//////////AAAAAAAAAAUAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAQAAAApkb3RrYW0uY29tAAAAAAAAAAAAAAAAAAEiihO9AAAAQIXduMIFMEZY+dEg+zpwle0vO+nxRsDTPtrIfret2i1nw9WAZlS4qtUtIKhWmmRTnr5/598oVUd4rqiKpvNYtgQ=\n```\n\nBB-8 has a `decode` command that decodes this into a readable [XDR](https://www.stellar.org/developers/horizon/reference/xdr.html):\n\n```sh\n$ bb change-trust '{\"source_account\": \"'$(cat distributor)'\",\n                    \"code\": \"COMP\",\n                    \"issuer\": \"'$(cat issuer.pub)'\"}' | xargs \\\n  bb set-options  '{\"home_domain\": \"dotkam.com\",\n                    \"max_weight\": 1}' | xargs \\\n  bb sign '[\"'$(cat distributor)'\"]' | xargs \\\n  bb decode\n```\n```xdr\n{\n  \"Tx\": {\n    \"SourceAccount\": ...,\n    \"Fee\": 200,\n    \"SeqNum\": 30836525155483664,\n    \"Operations\": [\n      {\n        \"Body\": {\n          \"Type\": 6,\n          \"ChangeTrustOp\": {\n            \"Line\": {\n              \"AlphaNum4\": {\n                \"AssetCode\": \"COMP\",\n                \"Issuer\": ...\n              },\n            },\n            \"Limit\": 9223372036854775807\n          },\n        }\n      },\n      {\n        \"Body\": {\n          \"Type\": 5,\n          \"SetOptionsOp\": {\n            ...\n            \"HomeDomain\": \"dotkam.com\"\n          },\n        }\n      }\n    ],\n  },\n  \"Signatures\": [\n    {\n      \"Hint\": ...,\n      \"Signature\": \"hd24wgUwRlj50SD7OnCV7S876fFGwNM+2sh+t63aLWfD1YBmVLiq1S0gqFaaZFOevn/n3yhVR3iuqIqm81i2BA==\"\n    }\n  ]\n}\n```\n\nnotice `ChangeTrustOp` and `SetOptionsOp`.\n\n\"decode\" command is useful for looking at single commands as well:\n\n```sh\n$ bb send-payment '{\"from\": \"'$(cat issuer)'\",\n                    \"to\": \"'$(cat distributor.pub)'\",\n                    \"amount\": \"42.0\",\n                    \"memo\": \"forty two\"}' | xargs bb decode\n```\n```xdr\n...\n    \"Memo\": {\n      \"Type\": 1,\n      \"Text\": \"forty two\",\n      \"Id\": null,\n      \"Hash\": null,\n      \"RetHash\": null\n    },\n    \"Operations\": [\n      {\n          \"PaymentOp\": {\n            \"Destination\": ...,\n            \"Asset\": {\n              \"Type\": 0,\n              \"AlphaNum4\": null,\n              \"AlphaNum12\": null\n            },\n            \"Amount\": 420000000\n          },\n...\n```\n\n## Manage Data\n\nOne of the most underrated transaction operation is [Manage Data](https://www.stellar.org/developers/guides/concepts/list-of-operations.html#manage-data).\n\nAs documentation suggests it allows you to set, modify or delete a Data Entry (name/value pair) that is attached to a particular account. An account can have an arbitrary amount of DataEntries attached to it. Each DataEntry increases the minimum balance needed to be held by the account.\n\nDataEntries can be used for application specific things. They are not used by the core Stellar protocol.\n\nKeys are string that are up to 64 bytes long and values (a.k.a. names) are bytes that are 64 bytes long.\n\n### Add Data\n\n`BB-8` has a `manage-data` command that creates a \"Manage Data\" transaction operation:\n\n```sh\n$ bb manage-data -s '{\"source_account\": \"'$(cat seed)'\",\n                      \"name\": \"answer to the ultimate question\",\n                      \"value\": \"42\"}'\n```\n\n\u003cimg src=\"doc/img/manage-data-op.png\"\u003e\n\nLet's look at the transaction it creates:\n\n```sh\n$ bb manage-data '{\"source_account\": \"'$(cat seed)'\",\n                   \"name\": \"answer to the ultimate question\",\n                   \"value\": \"42\"}' | xargs \\\n  bb decode\n```\n\n```json\n{\n   \"Tx\":{\n      \"SourceAccount\":\"GBDGNI...WOG6\",\n      \"Fee\":100,\n      \"SeqNum\":30915131646935045,\n      ...\n    \"Operations\":[\n         {\n            ...\n       \"ManageDataOp\":{\n               \"DataName\":\"answer to the ultimate question\",\n               \"DataValue\":\"NDI=\"\n       ...}}]}}\n```\n\n`DataValue` was converted to bytes, but no worries, it is still `42`.\n\n\n### Remove Data\n\nProviding just the name (a.k.a. key) without the value (a.k.a. data) would _remove_ this \"name, value\" pair from the account:\n\n```\n$ bb manage-data -s '{\"source_account\": \"'$(cat seed)'\",\n                      \"name\": \"answer to the ultimate question\"}'\n```\n\nJSON `null` is also supported (would remove this \"name,value\" pair):\n\n```\n$ bb manage-data -s '{\"source_account\": \"'$(cat seed)'\",\n                      \"name\": \"answer to the ultimate question\",\n                      \"value\": null}'\n```\n\n## Stream Stellar Events\n\nBB-8 has a `stream` command that will latch onto a Stellar network and will listen to ledger, account transaction and payment events. Here are more details from its `--help` section:\n\n```sh\n$ bb stream --help\nstream \"ledger\", \"payment\" and \"tranasaction\" events.\nevents are streamed in JSON and will do so forever or for a period of time specified by a --seconds flag.\n\nexample: stream --ledger\n         stream -t GCYQSB3UQDSISB5LKAL2OEVLAYJNIR7LFVYDNKRMLWQKDCBX4PU3Z6JP --seconds 42 --cursor now\n         stream -p GCYQSB3UQDSISB5LKAL2OEVLAYJNIR7LFVYDNKRMLWQKDCBX4PU3Z6JP -s 42\n\nUsage:\n  bb stream [flags]\n\nFlags:\n  -c, --cursor string         a paging token, specifying where to start returning records from. When streaming this can be set to \"now\" to stream object created since your request time. examples: -c 8589934592, -c now\n  -h, --help                  help for stream\n  -l, --ledger                stream ledger events\n  -p, --payments string       stream account payment events. example: --payments account-address\n  -s, --seconds int           number of seconds to stream events for\n  -t, --transactions string   stream account transaction events. example: --transactions account-address\n```\n\nEvents are streamed in JSON and can be filtered by `jq`, `grep`, and alike. As any streaming data these events could also be rolled up on the fly. Command line is perfect for this since it is extremely interactive and command rich.\n\nFor example let's look at all the fees a certain account paid:\n\n```sh\n$ bb stream --transactions $(cat bar.pub) | grep fee_paid\n```\n\nthe fees are going to show up on the terminal as new transaction events are coming to a Stellar network:\n\n```json\n  \"fee_paid\": 100,\n  \"fee_paid\": 200,\n  \"fee_paid\": 200,\n  \"fee_paid\": 100,\n  \"fee_paid\": 200,\n  \"fee_paid\": 200,\n  \"fee_paid\": 100,\n  \"fee_paid\": 100,\n  \"fee_paid\": 100,\n  \"fee_paid\": 100,\n  \"fee_paid\": 100,\n  \"fee_paid\": 200,\n  \"fee_paid\": 200,\n  \"fee_paid\": 200,\n  \"fee_paid\": 200,\n  \"fee_paid\": 200,\n```\n\nNow let's roll them up to current totals:\n\n```sh\n$ bb stream --transactions $(cat bar.pub) |\n            grep --line-buffered fee_paid |\n            awk -F\" \" '{rollup+=$2; print \"total fees paid: \"rollup}'\n```\n```json\ntotal fees paid: 100\ntotal fees paid: 300\ntotal fees paid: 500\ntotal fees paid: 600\ntotal fees paid: 800\ntotal fees paid: 1000\ntotal fees paid: 1100\ntotal fees paid: 1200\ntotal fees paid: 1300\ntotal fees paid: 1400\ntotal fees paid: 1500\ntotal fees paid: 1700\ntotal fees paid: 1900\ntotal fees paid: 2100\ntotal fees paid: 2300\ntotal fees paid: 2500\n```\n\nbeautiful!\n\nThis and much more is brought to you by the power of command line.\n\n## Set Default Address and Seed\n\nBesides specifying account source addresses via `\"source_address\"` / `\"from\"`, etc. and seeds via `\"sign [\"seed1\", \"seed2\"]\"` there is a way to set default account address and account seed via `STELLAR_ACCOUNT_ADDRESS` and `STELLAR_ACCOUNT_SEED_FILE` environment variables.\n\nIf they are set BB-8 will use those values which would allow to not specify them while building transactions. In case both evironment variables and explicit addresses / seeds are provided BB-8 will use the explicit values.\n\n### Standalone Transactions\n\nHere is an example of a standalone transaction that does not specify account address / seed:\n\n```sh\n$ bb manage-data -s '{\"name\": \"answer to the ultimate question\", \"value\": \"42\"}'\n2018/02/28 10:44:27 can't resolve Stellar account address (a.k.a. source account).\n                    you can set it via STELLAR_ACCOUNT_ADDRESS environment variable\n                    or provide it as a \"source_account\" field of the transaction\n```\n\n```sh\n$ export STELLAR_ACCOUNT_ADDRESS=$(cat foo.pub)\n```\n\nnow address is resolved, but this transaction still needs to be signed before it is submitted, hence it would need a seed:\n\n```sh\n$ bb manage-data -s '{\"name\": \"answer to the ultimate question\", \"value\": \"42\"}'\n2018/02/28 10:44:47 could not submit transaction: can't find the account seed.\n                    you can either provide it explicitely in the transaction or set \"STELLAR_ACCOUNT_SEED_FILE\"\n                    environment variable that points to a file with a seed\n```\n\n`STELLAR_ACCOUNT_SEED_FILE` points to a file rather than a seed value directly for security purposes: i.e. not to leave shell history trails or reveal env variable values (via for exampe `docker inspect` and alike):\n\n```sh\n$ mkdir ~/.bb8/account/\n$ cp foo ~/.bb8/account/\n$ export STELLAR_ACCOUNT_SEED_FILE=~/.bb8/account/foo\n```\n\nhere we copied `foo` seed to an arbitrary directory and pointed `STELLAR_ACCOUNT_SEED_FILE` to this seed file.\n\n```sh\n$ bb manage-data -s '{\"name\": \"answer to the ultimate question\", \"value\": \"42\"}'\n## great success\n```\n\n### Composed Transactions\n\nIn case of composed transactions, the `sign` command will auto resolve the seed from the file `STELLAR_ACCOUNT_SEED_FILE` points to:\n\n```sh\n$ bb manage-data '{\"name\": \"answer to the ultimate question\", \"value\": \"42\"}' | xargs \\\n  bb sign\n\n## AAAAAEZmoJ4/4yKi60D9d2zHo94r9CFP0pDG6g+GGXQ6rIlLAAAAZABt1SYAAAAMAAAAAAAAAAAAAAABAAAAAAAAAAoAAAAfYW5zd2VyIHRvIHRoZSB1bHRpbWF0ZSBxdWVzdGlvbgAAAAABAAAAAjQyAAAAAAAAAAAAATqsiUsAAABA4R8YMtT8FeV4zCHUGqK0wOYyAK7CAtQfima8Ym90tg49cXkjMWXfyzeghbLE8gPum0AkQG9faz0l8uU/G7RLCQ==\n```\n\nor signers can be provided explicitly:\n\n```sh\n$ bb manage-data '{\"name\": \"answer to the ultimate question\", \"value\": \"42\"}' | xargs \\\n  bb sign '[\"'$(cat foo)'\"]'\n\n## AAAAAEZmoJ4/4yKi60D9d2zHo94r9CFP0pDG6g+GGXQ6rIlLAAAAZABt1SYAAAANAAAAAAAAAAAAAAABAAAAAAAAAAoAAAAfYW5zd2VyIHRvIHRoZSB1bHRpbWF0ZSBxdWVzdGlvbgAAAAABAAAAAjQyAAAAAAAAAAAAATqsiUsAAABAcXDv/QoDC52wqimZtm1bGNaRbiIbKC0wzYZvWUZ+YzMeym+JKWgkvAmqzOcDH0PjGmE4KbHmO0xDx5HKJPBXAA==\n```\n\nGiven that an address and a seed are set as environment variables transactions might become less verbose and a little more secure since for a single signature there no explicit seed:\n\n```sh\nbb send-payment '{\"to\": \"'$(cat foo.pub)'\", \"amount\": \"42.0\"}' | xargs \\\nbb sign | xargs \\\nbb submit\n\n## 2018/02/28 10:48:29 sending 42.0 XLM from GBDGNIE6H7RSFIXLID6XO3GHUPPCX5BBJ7JJBRXKB6DBS5B2VSEUWOG6 to GDQM2SJ2HSFPNPS2EQC6V3OF3RBJHX3WMFC2CWVIFJH6MGIWZG4DNMJK\n```\n## Federation\n\n\u003e The Stellar federation protocol maps Stellar addresses to more information about a given user. It’s a way for Stellar client software to resolve email-like addresses such as name*yourdomain.com into account IDs like: GCCVPYFOHY7ZB7557JKENAX62LUAPLMGIWNZJAFV2MITK6T32V37KEJU. (_more from [Stellar docs](https://www.stellar.org/developers/guides/concepts/federation.html)_)\n\nIn short whenever BB-8 sees an address such as `luke_skywalker*dotkam.com` instead of a public key / account address, it would:\n\n* reach out to \"dotkam.com\" to ask where the federation server is by looking at \"https://dotkam.com/.well-known/stellar.toml\"\n* then it would go to that federation server and ask it to map `luke_skywalker*dotkam.com` to an account address such as `GDQM2SJ2HSFPNPS2EQC6V3OF3RBJHX3WMFC2CWVIFJH6MGIWZG4DNMJK`.\n\n### Lookup Account or Address\n\nBB-8 has a `federation` command to lookup accounts and addresses.\n\nfederation address to account:\n\n```\n$ bb federation --address \"bob*dotkam.com\"\nGCPZIJCYNMJNVXWUCS52AKIB5MRVRR4GCKX5CYGSFCTWOIRL2FZ5IECZ\n\n$ bb federation --address \"alice*dotkam.com\"\nGDDDAGQE7KM2ECZWIQ4HA4CK56NKDI4UD6636HRYTAKCBVKW6JQVHN4X\n```\n\naccount to federation address:\n\n```\n$ bb federation --account GCPZIJCYNMJNVXWUCS52AKIB5MRVRR4GCKX5CYGSFCTWOIRL2FZ5IECZ\nbob*dotkam.com\n\n$ bb federation --account GDDDAGQE7KM2ECZWIQ4HA4CK56NKDI4UD6636HRYTAKCBVKW6JQVHN4X\nalice*dotkam.com\n```\n\n### Federation Address in Transactions\n\nOf course what makes federation so useful is an ability to run Stellar commands based on human readable addresses. BB-8 will accept federation addresses in transactions and it would map them to the real Stellar accounts automatically when processing these transactions:\n\n```\n$ bb send-payment -s '{\"from\": \"'$(cat distributor)'\",\n                       \"to\": \"alice*dotkam.com\",\n                       \"amount\": \"42.0\"}'\n\n2018/03/17 13:31:09 sending 42.0 XLM from GBDGNI....EUWOG6 to alice*dotkam.com\n```\n\n```\n$ bb load-account \"alice*dotkam.com\" | jq '.balances'\n{\n  \"balance\": \"10041.9999900\",\n  \"asset_type\": \"native\"\n}\n```\n\nBB-8 will translate federation addresses for issuer's addresses as well:\n\n```\n$ bb change-trust -s '{\"source_account\": \"'$(cat foo)'\",\n                       \"code\": \"TIL\",\n                       \"issuer\": \"bb8*dotkam.com\"}'\n```\n\nor\n\n```\n$ bb send-payment -s '{\"to\": \"alice*dotkam.com\",\n                       \"token\": \"TIL\",\n                       \"amount\": \"42\",\n                       \"issuer\": \"bb8*dotkam.com\"}'\n```\n\n## Help Flag\n\nAll BB-8 commands and options have descriptions and examples that are available with a `--help` / `-h` flag.\n\nFor example here is how to get more details about the `send-payment` command:\n\n```sh\n$ bb send-payment --help\n\nsend payment of any asset from one account to another. this command takes parameters in JSON.\n\nexample: send-payment '{\"from\": \"seed\", \"to\": \"address\", \"amount\": \"42.0\"}'\n         send-payment '{\"from\": \"seed\", \"to\": \"address\", \"amount\": \"42.0\", \"memo\": \"forty two\"}'\n         send-payment '{\"from\": \"seed\", \"to\": \"address\", \"token\": \"BTC\", \"amount\": \"42.0\", \"issuer\": \"address\"}'\n\n         notice there is no issuer when sending XLM since it's a native asset.\n\nUsage:\n  bb send-payment [args] [flags]\n\nFlags:\n  -h, --help              help for send-payment\n  -s, --sign-and-submit   sign and submit transaction. will use source account's seed to sign it\n\n      example: send-payment -s '{\"from\": \"seed\", \"to\": \"address\", \"amount\": \"42.0\"}'\n               create-account -s '{\"source_account\":\"seed\", \"new_account\":\"address\", \"amount\":\"1.5\"}'\n```\n\nhere is more about `set-options` command:\n\n```sh\n$ bb set-options -h\nset options on the account. this command takes parameters in JSON.\ngiven a \"source_account\" sets options on it. supported options are:\n\n  * inflation_destination\n  * home_domain\n  * master_weight\n  * thresholds\n  * set_flags\n  * remove_flags\n  * add_signer\n  * remove_signer\n\nexample: set-options '{\"source_account\": \"seed\"\n                       \"home_domain\": \"stellar.org\"}'\n\n         set-options '{\"source_account\": \"seed\"\n                       \"home_domain\": \"stellar.org\",\n                       \"max_weight\": 1,\n                       \"inflation_destination\": \"GCCD6AJOYZCUAQLX32ZJF2MKFFAUJ53PVCFQI3RHWKL3V47QYE2BNAUT\"}'\n\n         set-options '{\"source_account\": \"seed\"\n                       \"thresholds\": {\"low\": 1, \"high\": 1},\n                       \"set_flags\": [\"auth_revocable\", \"auth_required\"]}'\n\n         set-options '{\"source_account\": \"seed\"\n                       \"add_signer\": {\"address\": \"GCU2XASMVOOJCUAEPOEL7SHNIRJA3IRSDIE4UTXA4QLJHMB5BFXOLNOB\",\n                                      \"weight\": 3}}'\n\nUsage:\n  bb set-options [args] [flags]\n\nFlags:\n  -h, --help              help for set-options\n  -s, --sign-and-submit   sign and submit transaction. will use source account's seed to sign it\n\n      example: send-payment -s '{\"from\": \"seed\", \"to\": \"address\", \"amount\": \"42.0\"}'\n               create-account -s '{\"source_account\":\"seed\", \"new_account\":\"address\", \"amount\":\"1.5\"}'\n```\n\nand so on. This kind of help is available for all the commands. Feel free to submit an issue in case it is missing, or more details about the command, option, flag would be helpful.\n\n## Donate\n\nBB-8 lives on the public Stellar network at its home address:\n\n\u003cp align=\"center\"\u003e\nGAUYQY4TB22GPRXXLVLK24ZVPTAGGQM7FQNYVXNZMMKX65UJVX6\u003cb\u003eDROID\u003c/b\u003e\n\u003c/p\u003e\n\nTo show support, given that your [defaults are set](#set-default-address-and-seed), and the [network is chosen](#choose-stellar-network), you could:\n\n```\n$ bb send-payment -s '{\"to\": \"GAUYQY4TB22GPRXXLVLK24ZVPTAGGQM7FQNYVXNZMMKX65UJVX6DROID\",\n                       \"amount\": \"1.0\"}'\n```\n\nor if you are the first one to donate you can create this BB-8 account with:\n\n```\n$ bb create-account -s '{\"new_account\":\"GAUYQY4TB22GPRXXLVLK24ZVPTAGGQM7FQNYVXNZMMKX65UJVX6DROID\",\n                         \"amount\":\"1.0\"}'\n```\n\nIf you [include a memo](https://github.com/tolitius/bb8#add-memo) in your contribution BB-8 will use it to thank you publicly.\n\n## License\n\nCopyright © 2018 tolitius\n\nDistributed under the Eclipse Public License either version 1.0 or (at\nyour option) any later version.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolitius%2Fbb8","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftolitius%2Fbb8","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftolitius%2Fbb8/lists"}