added support for broadcast format versioning

docs/BTNS-420.md

@@ -24,12 +24,13 @@ BTNS-420 `ACTION` `PARAMS` will not be considered finalized until `ACTIVATION_BL
 # Definitions
 - `ACTIVATION_BLOCK` - A specific block height when a BTNS `ACTION` becomes usable
 - `ACTION` - A specific type of command performed on a `token`
-- `ASSET` - A token created via a `issuance` transaction on the Counterparty platform
+- `ASSET` - A token created via `issuance` transactions on the `counterparty` platform
+- `VERSION` - A specific `ACTION` command `broadcast` format version
 - `JSON` - A text-based way of representing JavaScript object literals, arrays, and scalar data
 - `PARAMS` - Parameters specified along with an `ACTION` command
 - `XCP` - A specific `ASSET` on the `counterparty` platform
 - `GAS` - A specific `token` on the `BTNS` platform
-- `broadcast` - A general purpose transaction type which allows broadcasting of a message to the Counterparty platform
+- `broadcast` - A general purpose transaction type which allows broadcasting of a message to the `counterparty` platform
 - `counterparty` - A token platform on Bitcoin (BTC) which was created in 2014 ([counterparty.io](https://counterparty.io))
 - `issuance` - A transaction type which allows for creation of `ASSET` and issuing of supply on the Counterparty platform
 - `token` - A token created in the BTNS via a `MINT` or `ISSUE` `ACTION` `broadcast` transaction
@@ -43,6 +44,11 @@ The default BTNS prefix which should be used for BTNS transactions is `BTNS` and
 ## Project Versioning
 The default BTNS version is `0` when no `broadcast` `value` is specified
 
+## Format Versioning
+Establishing a `VERSION` in each BTNS `ACTION` command, allows for easier expansion and parsing of `PARAMS` in various standardized formats.
+
+The default BTNS format version is `0` when no `VERSION` is given
+
 ## `ACTION` and `PARAMS` commands
 By establishing pre-defined `broadcast` commands with `ACTION` and `PARAMS` for each, one is able to create `tokens` and perform various actions them.
 

docs/actions/AIRDROP.md

@@ -2,23 +2,37 @@
 This command airdrops `token` supply to one or more `BTNS` lists.
 
 ## PARAMS
-| Name     | Type   | Description                         |
-| -------- | ------ | ----------------------------------- |
-| `TICK`   | String | 1 to 250 characters in length       |
-| `AMOUNT` | String | Amount of `tokens` to airdrops      |
-| `LIST`   | String | `TX_HASH` of a BTNS `LIST` commands |
+| Name      | Type   | Description                         |
+| --------- | ------ | ----------------------------------- |
+| `VERSION` | String | Broadcast Format Version            |
+| `TICK`    | String | 1 to 250 characters in length       |
+| `AMOUNT`  | String | Amount of `tokens` to airdrops      |
+| `LIST`    | String | `TX_HASH` of a BTNS `LIST` commands |
 
 ## Formats
-- `AIRDROP|AMOUNT|LIST`
-- `AIRDROP|AMOUNT|LIST|LIST`
-- `AIRDROP|AMOUNT|LIST|AMOUNT|LIST`
+
+### Version `0`
+- `AIRDROP|VERSION|TICK|AMOUNT|LIST|LIST`
+
+### Version `1`
+- `AIRDROP|VERSION|TICK|AMOUNT|LIST|TICK|AMOUNT|LIST`
 
 ## Examples
+```
+bt:AIRDROP|0|GAS|1|LIST
+This example airdops 1 GAS to every holder on a list
+```
+
+```
+bt:AIRDROP|1|GAS|1|LIST|BRRR|2|LIST
+This example airdops 1 GAS to every holder on a list and 2 BRRR to every holder on a list
+```
 
 ## Rules
 
 ## Notes
-- The same `AMOUNT` is distributed to all airdrip recipients
-- `AIRDROP` to a address `LIST` sends `AMOUNT` of `token` to each address on the list
-- `AIRDROP` to a `token` `LIST` sends `AMOUNT` of `token` to holders of each `token` on the list
-
+-  Use format `0` to send the same `AMOUNT`  of `token` to one or more `LIST`
+-  Use format `1` to send multiple `AMOUNT` of multiple `token` to different `LIST`
+- `AIRDROP` to `address` `LIST` sends `AMOUNT` of `token` to each address on the list
+- `AIRDROP` to `token` `LIST` sends `AMOUNT` of `token` to holders of each `token` on the list
+- `AIRDROP` to `ASSET` `LIST` sends `AMOUNT` of `token` to holders of each `ASSET` on the list

docs/actions/BATCH.md

@@ -4,18 +4,22 @@ This command batch executes multiple `BTNS` `ACTION` commands in a single transa
 ## PARAMS
 | Name      | Type   | Description                            |
 | --------- | ------ | -------------------------------------- |
-| `TICK`    | String | 1 to 250 characters in length          |
+| `VERSION` | String | Broadcast Format Version               |
 | `COMMAND` | String | Any valid BTNS `ACTION` with `PARAMS`  |
 
 ## Formats
-- `BATCH|COMMAND;COMMAND`
+
+### Version `0`
+- `BATCH|VERSION|COMMAND;COMMAND`
 
 ## Examples
 ```
-bt:BATCH|ISSUE|JDOG;ISSUE|TEST
-This example issues the JDOG and TEST tokens
+bt:BATCH|0|MINT|0|GAS|1000;ISSUE|0|JDOG
+This example mints 1000 GAS tokens and reserves the JDOG token
 ```
 
 ## Rules
+- Can only use one `MINT` command in a `BATCH` command
+- Can only use one `ISSUE` command in a `BATCH` command
 
-## Notes
+## Notes

docs/actions/BET.md

@@ -4,6 +4,7 @@ This command bets a `token` on a `broadcast` oracle feed
 ## PARAMS
 | Name                  | Type   | Description                                                                              |
 | --------------------- | ------ | ---------------------------------------------------------------------------------------- |
+| `VERSION`             | String | Broadcast Format Version                                                                 |
 | `FEED_ADDRESS`        | String | The address that hosts the feed to be bet on.                                            |
 | `BET_TYPE`            | String | 0 for Bullish CFD, 1 for Bearish CFD, 2 for Equal, 3 for NotEqual.                       |
 | `DEADLINE`            | String | The time at which the bet should be decided/settled, in Unix time (seconds since epoch). |
@@ -17,11 +18,13 @@ This command bets a `token` on a `broadcast` oracle feed
 
 
 ## Formats
-- `BET|FEED_ADDRESS|BET_TYPE|DEADLINE|WAGER_TICK|WAGER_AMOUNT|COUNTERWAGER_TICK|COUNTERWAGER_AMOUNT|EXPIRATION|LEVERAGE|TARGET_VALUE`
+
+### Version `0`
+- `BET|VERSION|FEED_ADDRESS|BET_TYPE|DEADLINE|WAGER_TICK|WAGER_AMOUNT|COUNTERWAGER_TICK|COUNTERWAGER_AMOUNT|EXPIRATION|LEVERAGE|TARGET_VALUE`
 
 ## Examples
 ```
-bt:BET|1BetXQ5w9mMmJosZ21jUtrebdpgMhYQUaZ|3|1497625200|TEST|100|BACON|100|604|5040|7
+bt:BET|0|1BetXQ5w9mMmJosZ21jUtrebdpgMhYQUaZ|3|1497625200|TEST|100|BACON|100|604|5040|7
 This example places a bet on the feed at 1BetXQ5w9mMmJosZ21jUtrebdpgMhYQUaZ and wagers 100 TEST for 100 BACON that the final value will be 7.
 ```
 

docs/actions/CALLBACK.md

@@ -2,16 +2,19 @@
 This command performs a callback on a `token`. 
 
 ## PARAMS
-| Name     | Type   | Description                   |
-| -------- | ------ | ----------------------------- |
-| `TICK`   | String | 1 to 250 characters in length |
+| Name      | Type   | Description                   |
+| --------- | ------ | ----------------------------- |
+| `VERSION` | String | Broadcast Format Version      |
+| `TICK`    | String | 1 to 250 characters in length |
 
 ## Formats
-- `CALLBACK|TICK`
+
+### Version `0`
+- `CALLBACK|VERSION|TICK`
 
 ## Examples
 ```
-bt:CALLBACK|JDOG
+bt:CALLBACK|0|JDOG
 This example calls back the JDOG token to the token owner address
 ```
 

docs/actions/DESTROY.md

@@ -2,21 +2,28 @@
 This command permanently destroys `token` supply
 
 ## PARAMS
-| Name     | Type   | Description                   |
-| -------- | ------ | ----------------------------- |
-| `TICK`   | String | 1 to 250 characters in length |
-| `AMOUNT` | String | Amount of `tokens` to destroy |
+| Name      | Type   | Description                   |
+| --------- | ------ | ----------------------------- |
+| `VERSION` | String | Broadcast Format Version      |
+| `TICK`    | String | 1 to 250 characters in length |
+| `AMOUNT`  | String | Amount of `tokens` to destroy |
 
 ## Formats
-- `DESTROY|TICK|AMOUNT`
-- `DESTROY|TICK|AMOUNT|TICK|AMOUNT`
+
+### Version `0`
+- `DESTROY|VERSION|TICK|AMOUNT|TICK|AMOUNT`
 
 ## Examples
 ```
-bt:DESTROY|BRRR|1
+bt:DESTROY|0|BRRR|1
 This example destroys 1 BRRR token from the broadcasting address
 ```
 
+```
+bt:DESTROY|0|BRRR|1|GAS|10
+This example destroys 1 BRRR token and 10 GAS tokens from the broadcasting address
+```
+
 ## Rules
 - Any destroyed `token` supply should be debited from broadcasting address balances
 

docs/actions/DISPENSER.md

@@ -4,6 +4,7 @@ This command creates a vending machine to dispense `tokens` when triggered
 ## PARAMS
 | Name             | Type   | Description                                                                          |
 | ---------------- | ------ | ------------------------------------------------------------------------------------ |
+| `VERSION`        | String | Broadcast Format Version                                                             |
 | `GIVE_TICK`      | String | 1 to 250 characters in length                                                        |
 | `GIVE_AMOUNT`    | String | Quantity of `GIVE_TICK` to dispense when triggered                                   |
 | `ESCROW_AMOUNT`  | String | Quantity of `GIVE_TICK` to escrow in dispenser                                       |
@@ -15,28 +16,29 @@ This command creates a vending machine to dispense `tokens` when triggered
 | `ALLOW_LIST`     | String | `TX_HASH` of a BTNS `LIST` of addresses to allow trigger dispenser                   |
 | `BLOCK_LIST`     | String | `TX_HASH` of a BTNS `LIST` of addresses to NOT allow to trigger a dispenser          |
 
-
 ## Formats
-- `DISPENSER|GIVE_TICK|GIVE_AMOUNT|ESCROW_AMOUNT|TRIGGER_TICK|TRIGGER_AMOUNT|STATUS|ADDRESS|ORACLE_ADDRESS|ALLOW_LIST|BLOCK_LIST`
+
+### Version `0`
+- `DISPENSER|VERSION|GIVE_TICK|GIVE_AMOUNT|ESCROW_AMOUNT|TRIGGER_TICK|TRIGGER_AMOUNT|STATUS|ADDRESS|ORACLE_ADDRESS|ALLOW_LIST|BLOCK_LIST`
 
 ## Examples
 ```
-bt:DISPENSER|JDOG|1|1|BTC|1.00000000|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
+bt:DISPENSER|0|JDOG|1|1|BTC|1.00000000|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 This example creates a dispenser and escrows 1 JDOG `token` in it, which will dispense when 1.00000000 BTC is sent to 1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 ```
 
 ```
-bt:DISPENSER|JDOG|1|1|BTC|1.00000000|10
+bt:DISPENSER|0|JDOG|1|1|BTC|1.00000000|10
 This example closes the dispenser in example 1 and credits any escrowed JDOG to the dispenser address 1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 ```
 
 ```
-bt:DISPENSER|BRRR|1000|1|TEST|1|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
+bt:DISPENSER|0|BRRR|1000|1|TEST|1|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 This example creates a dispenser and escrows 1000 BRRR `token` in it, which will dispense when 1 TEST `token` is sent to 1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 ```
 
 ```
-bt:DISPENSER|BRRR|1000|1|TEST|1|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
+bt:DISPENSER|0|BRRR|1000|1|TEST|1|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 This example closes the dispenser in example 3 and credits any escrowed BRRR to the address 1BrrrrLLzVq8ZP1nE3BHKQZ14dBXkRVsx4
 ```
 

docs/actions/DIVIDEND.md

@@ -4,16 +4,19 @@ This command pays a dividend to `token` holders of a `token`.
 ## PARAMS
 | Name            | Type   | Description                                      |
 | --------------- | ------ | ------------------------------------------------ |
+| `VERSION`       | String | Broadcast Format Version                         |
 | `TICK`          | String | The `token` that dividends are being rewarded on |
 | `DIVIDEND_TICK` | String | The `token` that dividends are paid in           |
 | `AMOUNT`        | String | Amount of `tokens` to destroy                    |
 
 ## Formats
-- `DIVIDEND|TICK|DIVIDEND_TICK|AMOUNT`
+
+### Version `0`
+- `DIVIDEND|VERSION|TICK|DIVIDEND_TICK|AMOUNT`
 
 ## Examples
 ```
-bt:DIVIDEND|BRRR|BACON|1
+bt:DIVIDEND|0|BRRR|BACON|1
 This example pays a dividend of 1 BACON to every holder of 1 BRRR
 ```
 

docs/actions/ISSUE.md

@@ -4,6 +4,7 @@ This command creates or issues a `BTNS` `token`
 ## PARAMS
 | Name               | Type   | Description                                                                                 |
 | ------------------ | ------ | ------------------------------------------------------------------------------------------- |
+| `VERSION`          | String | Broadcast Format Version                                                                    |
 | `TICK`             | String | 1 to 250 characters in length (see rules below )                                            |
 | `MAX_SUPPLY`       | String | Maximum token supply (max: 18,446,744,073,709,551,615 - commas not allowed)                 |
 | `MAX_MINT`         | String | Maximum amount of supply a `MINT` transaction can issue                                     |
@@ -26,46 +27,48 @@ This command creates or issues a `BTNS` `token`
 
 
 ## Formats
-- `ISSUE|TICK|MAX_SUPPLY|MAX_MINT|DECIMALS|DESCRIPTION|MINT_SUPPLY|TRANSFER|TRANSFER_SUPPLY|LOCK_SUPPLY|LOCK_MINT|LOCK_DESCRIPTION|LOCK_RUG|LOCK_SLEEP|LOCK_CALLBACK|CALLBACK_BLOCK|CALLBACK_TICK|CALLBACK_AMOUNT|MINT_ALLOW_LIST|MINT_BLOCK_LIST`
+
+### Version `0`
+- `ISSUE|VERSION|TICK|MAX_SUPPLY|MAX_MINT|DECIMALS|DESCRIPTION|MINT_SUPPLY|TRANSFER|TRANSFER_SUPPLY|LOCK_SUPPLY|LOCK_MINT|LOCK_DESCRIPTION|LOCK_RUG|LOCK_SLEEP|LOCK_CALLBACK|CALLBACK_BLOCK|CALLBACK_TICK|CALLBACK_AMOUNT|MINT_ALLOW_LIST|MINT_BLOCK_LIST`
 
 ## Examples
 ```
-bt:ISSUE|JDOG
+bt:ISSUE|0|JDOG
 This example issues a JDOG token 
 ```
 
 ```
-bt:ISSUE|JDOG||||||||1
+bt:ISSUE|0|JDOG||||||||1
 This example issues a JDOG token with LOCK_SUPPLY set to 1 to permanently
 ```
 
 ```
-bt:ISSUE|JDOG|0|0|0|http://j-dog.net/images/JDOG_icon.png
+bt:ISSUE|0|JDOG|0|0|0|http://j-dog.net/images/JDOG_icon.png
 This example issues a JDOG token with a DESCRIPTION which points to an icon
 ```
 
 ```
-bt:ISSUE|JDOG|0|0|0|http://j-dog.net/images/JDOG_icon.png|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
+bt:ISSUE|0|JDOG|0|0|0|http://j-dog.net/images/JDOG_icon.png|0|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 This example issues a JDOG token with a DESCRIPTION which points to an icon, and transfers token ownership to 1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 ```
 
 ```
-bt:ISSUE|JDOG|1000|1|0
+bt:ISSUE|0|JDOG|1000|1|0
 This example issues a JDOG token with a max supply of 1000, and a maximum mint of 1 JDOG per mint
 ```
 
 ```
-bt:ISSUE|JDOG|1000|1|0|BTNS Tokens Are Cool!
+bt:ISSUE|0|JDOG|1000|1|0|BTNS Tokens Are Cool!
 This example issues a JDOG token with a max supply of 1000, and a DESCRIPTION of 'BTNS Tokens are Cool!'
 ```
 
 ```
-bt:ISSUE|BRRR|10000000000000000000|10000000000000|0|https://j-dog.net/json/JDOG.json|100
+bt:ISSUE|0|BRRR|10000000000000000000|10000000000000|0|https://j-dog.net/json/JDOG.json|100
 This example issues a BRRR token with a max supply of 1 Quandrillion supply and a maximum mint of 1 Trillion BRRR per mint, associates a JSON file with the token, and immediately mints 100 BRRR to the broadcasting address.
 ```
 
 ```
-bt:ISSUE|TEST|100|1|0||1|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
+bt:ISSUE|0|TEST|100|1|0||1|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 This example issues a TEST token with a max supply of 100, and a maximum mint of 1 TEST per mint. This also mints 1 TEST token, and transfers ownership AND initial token supply to 1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 ```
 

docs/actions/LIST.md

@@ -2,28 +2,31 @@
 This command creates a list of items for use in `BTNS` commands
 
 ## PARAMS
-| Name   | Type   | Description                            |
-| ------ | ------ | ---------------------------------------|
-| `TYPE` | String | List type (1=address, 2=TICK, 3=ASSET) |
-| `ITEM` | String | Any valid `TICK`, `ASSET`, or address  |
+| Name      | Type   | Description                            |
+| --------- | ------ | ---------------------------------------|
+| `VERSION` | String | Broadcast Format Version               |
+| `TYPE`    | String | List type (1=address, 2=TICK, 3=ASSET) |
+| `ITEM`    | String | Any valid `TICK`, `ASSET`, or address  |
 
 
 ## Formats
-- `LIST|TYPE|ITEM|ITEM|ITEM`
+
+### Version `0`
+- `LIST|VERSION|TYPE|ITEM|ITEM|ITEM`
 
 ## Examples
 ```
-bt:LIST|1|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev|1FWDonkMbC6hL64JiysuggHnUAw2CKWszs|bc1q5jw436vef6ezsgggk93pwhh9swrdxzx2e3a7kj
+bt:LIST|0|1|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev|1FWDonkMbC6hL64JiysuggHnUAw2CKWszs|bc1q5jw436vef6ezsgggk93pwhh9swrdxzx2e3a7kj
 This example creates a list of addresses
 ```
 
 ```
-bt:LIST|2|JDOG|BRRR|TEST
+bt:LIST|0|2|JDOG|BRRR|TEST
 This example creates a list of BTNS token tickers
 ```
 
 ```
-bt:LIST|3|XCP|RAREPEPE|JPMCHASE|A4211151421115130001
+bt:LIST|0|3|XCP|RAREPEPE|JPMCHASE|A4211151421115130001
 This example creates a list of counterparty assets
 ```
 

docs/actions/MINT.md

@@ -4,21 +4,24 @@ This command mints `BTNS` `token` supply
 ## PARAMS
 | Name          | Type   | Description                            |
 | ------------- | ------ | -------------------------------------- |
+| `VERSION`     | String | Broadcast Format Version               |
 | `TICK`        | String | 1 to 250 characters in length          |
 | `AMOUNT`      | String | Amount of `tokens` to mint             |
 | `DESTINATION` | String | Address to transfer minted `tokens` to |
 
 ## Formats
-- `MINT|TICK|AMOUNT|DESTINATION`
+
+### Version `0`
+- `MINT|VERSION|TICK|AMOUNT|DESTINATION`
 
 ## Examples
 ```
-bt:MINT|JDOG|1
+bt:MINT|0|JDOG|1
 This example mints 1 JDOG `token` to the broadcasting address
 ```
 
 ```
-bt:MINT|BRRR|10000000000000|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
+bt:MINT|0|BRRR|10000000000000|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
 This example mints 10,000,000,000,000 BRRR tokens and transfers them to 1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev 
 ```