Broke each ACTION off to it’s own document

jdogresorg · May 31, 2023 · 773cc14 · 773cc14
1 parent f9d5397
commit 773cc14
Show file tree

Hide file tree

Showing 15 changed files with 517 additions and 461 deletions.
diff --git a/docs/BTNS-420.md b/docs/BTNS-420.md
diff --git a/docs/actions/AIRDROP.md b/docs/actions/AIRDROP.md
@@ -0,0 +1,24 @@
+# AIRDROP command
+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 |
+
+## Formats
+- `AIRDROP|AMOUNT|LIST`
+- `AIRDROP|AMOUNT|LIST|LIST`
+- `AIRDROP|AMOUNT|LIST|AMOUNT|LIST`
+
+## Examples
+
+## 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
+
diff --git a/docs/actions/BATCH.md b/docs/actions/BATCH.md
@@ -0,0 +1,21 @@
+# BATCH command
+This command batch executes multiple `BTNS` `ACTION` commands in a single transaction
+
+## PARAMS
+| Name      | Type   | Description                            |
+| --------- | ------ | -------------------------------------- |
+| `TICK`    | String | 1 to 250 characters in length          |
+| `COMMAND` | String | Any valid BTNS `ACTION` with `PARAMS`  |
+
+## Formats
+- `BATCH|COMMAND;COMMAND`
+
+## Examples
+```
+bt:BATCH|ISSUE|JDOG;ISSUE|TEST
+This example issues the JDOG and TEST tokens
+```
+
+## Rules
+
+## Notes
diff --git a/docs/actions/BET.md b/docs/actions/BET.md
@@ -0,0 +1,34 @@
+# BET command
+This command bets a `token` on a `broadcast` oracle feed
+
+## PARAMS
+| Name                  | Type   | Description                                                                              |
+| --------------------- | ------ | ---------------------------------------------------------------------------------------- |
+| `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). |
+| `WAGER_TICK`          | String | 1 to 5 characters in length (required)                                                   |
+| `WAGER_AMOUNT`        | String | The quantityof `token` to wager (integer, in satoshis).                                  |
+| `COUNTERWAGER_TICK`   | String | 1 to 5 characters in length (required)                                                   |
+| `COUNTERWAGER_AMOUNT` | String | The minimum quantity of `token` to be wagered against, for the bets to match.            |
+| `EXPIRATION`          | String | The number of blocks after which the bet expires if it remains unmatched.                |
+| `LEVERAGE`            | String | Leverage, as a fraction of 5040 (integer, default=5040)                                  |
+| `TARGET_VALUE`        | String | Target value for Equal/NotEqual bet (float, default=null)                                |
+
+
+## Formats
+- `BET|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
+This example places a bet on the feed at 1BetXQ5w9mMmJosZ21jUtrebdpgMhYQUaZ and wagers 100 TEST for 100 BACON that the final value will be 7.
+```
+
+## Rules
+- Bet `token` funds are escrowed until the bet is settled or expires
+- Oracle fee is collected at time when bet is settled or expires
+
+## Notes
+- The betting system uses the Counterparty oracle system
+- Oracles require BTC to operate, and as such, collect a percentage (%) fee, which is determined by the `broadcast` `fee` value (0.01 = 1%)
diff --git a/docs/actions/CALLBACK.md b/docs/actions/CALLBACK.md
@@ -0,0 +1,24 @@
+# CALLBACK command
+This command performs a callback on a `token`. 
+
+## PARAMS
+| Name     | Type   | Description                   |
+| -------- | ------ | ----------------------------- |
+| `TICK`   | String | 1 to 250 characters in length |
+
+## Formats
+- `CALLBACK|TICK`
+
+## Examples
+```
+bt:CALLBACK|JDOG
+This example calls back the JDOG token to the token owner address
+```
+
+## Rules
+- `token` can only be called back after `CALLBACK_BLOCK`
+- All `token` supply will be returned to `token` owner address
+- All `token` supply holders will receive `CALLBACK_AMOUNT` of `CALLBACK_TICK` `token` per unit
+
+## Notes
+
diff --git a/docs/actions/DESTROY.md b/docs/actions/DESTROY.md
@@ -0,0 +1,23 @@
+# DESTROY command
+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 |
+
+## Formats
+- `DESTROY|TICK|AMOUNT`
+- `DESTROY|TICK|AMOUNT|TICK|AMOUNT`
+
+## Examples
+```
+bt:DESTROY|BRRR|1
+This example destroys 1 BRRR token from the broadcasting address
+```
+
+## Rules
+- Any destroyed `token` supply should be debited from broadcasting address balances
+
+## Notes
diff --git a/docs/actions/DISPENSER.md b/docs/actions/DISPENSER.md
@@ -0,0 +1,56 @@
+# DISPENSER command
+This command creates a vending machine to dispense `tokens` when triggered
+
+## PARAMS
+| Name             | Type   | Description                                                                          |
+| ---------------- | ------ | ------------------------------------------------------------------------------------ |
+| `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                                       |
+| `TRIGGER_TICK`   | String | 1 to 250 characters in length  (default=BTC)                                         |
+| `TRIGGER_AMOUNT` | String | Quantity of `TRIGGER_TICK` required per dispense                                     |
+| `STATUS`         | String | The state of the dispenser. (0=Open, 10=Closed)                                      |
+| `ADDRESS`        | String | Address that you would like to open the dispenser on. (default=broadcasting address) |
+| `ORACLE_ADDRESS` | String | address that you would like to use as a price oracle for this dispenser.             |
+| `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`
+
+## Examples
+```
+bt:DISPENSER|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
+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
+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
+This example closes the dispenser in example 3 and credits any escrowed BRRR to the address 1BrrrrLLzVq8ZP1nE3BHKQZ14dBXkRVsx4
+```
+
+
+## Rules
+- Dispensers can only be closed by the dispenser address
+
+## Notes
+- Can create a dispenser on any valid address (no new/empty address limitation like CP)
+- `STATUS` changes to `10` when a dispener is closed
+- `STATUS` changes to `10` automatically when a dispenser runs out of `tokens` to dispense
+- `ORACLE_ADDRESS` option only works when `TRIGGER_TICK` is `BTC`
+- When specifying an `ORACLE_ADDRESS`, `TRIGGER_AMOUNT` format becomes X.XX (fiat)
+- The `ORACLE_ADDRESS` option uses the Counterparty oracle system
+- Oracles require BTC to operate, and as such, collect a percentage (%) fee, which is determined by the `broadcast` `fee` value (0.01 = 1%)
+- BTNS Dispensers that use `ORACLE_ADDRESS` pay the oracle the entire percentage (%) fee, at time of dispenser creation
+- Dispenser payment can only trigger up to `25` sub-dispenses (dispenses that trigger additional dispenses)
diff --git a/docs/actions/DIVIDEND.md b/docs/actions/DIVIDEND.md
@@ -0,0 +1,25 @@
+# DIVIDEND command
+This command pays a dividend to `token` holders of a `token`.
+
+## PARAMS
+| Name            | Type   | Description                                      |
+| --------------- | ------ | ------------------------------------------------ |
+| `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`
+
+## Examples
+```
+bt:DIVIDEND|BRRR|BACON|1
+This example pays a dividend of 1 BACON to every holder of 1 BRRR
+```
+
+## Rules
+- Dividends may only be paid out by the current `token` owner
+
+## Notes
+- `UNIT` - A specific unit of measure (1 or 1.0)
+- To send large amounts of `tokens` to users, see the `AIRDROP` or `SEND` commands
diff --git a/docs/actions/ISSUE.md b/docs/actions/ISSUE.md
@@ -0,0 +1,99 @@
+# ISSUE command
+This command creates or issues a `BTNS` `token`
+
+## PARAMS
+| Name               | Type   | Description                                                                                 |
+| ------------------ | ------ | ------------------------------------------------------------------------------------------- |
+| `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                                     |
+| `DECIMALS`         | String | Number of decimal places token should have (max: 18, default: 0)                            |
+| `DESCRIPTION`      | String | Description of token (250 chars max)                                                        |
+| `MINT_SUPPLY`      | String | Amount of token supply to mint in immediately (default:0)                                   |
+| `TRANSFER`         | String | Address to transfer ownership of the `token` to (owner can perform future actions on token) |
+| `TRANSFER_SUPPLY`  | String | Address to transfer `MINT_SUPPLY` to (mint initial supply and transfer to address)          |
+| `LOCK_SUPPLY`      | String | Lock `MAX_SUPPLY` permanently (cannot increase `MAX_SUPPLY`)                                |
+| `LOCK_MINT`        | String | Lock `MAX_MINT` permanently (cannot edit `MAX_MINT`)                                        |
+| `LOCK_DESCRIPTION` | String | Lock `token` against `DESCRIPTION` changes                                                  |
+| `LOCK_RUG`         | String | Lock `token` against `RUG` command                                                          |
+| `LOCK_SLEEP`       | String | Lock `token` against `SLEEP` command                                                        |
+| `LOCK_CALLBACK`    | String | Lock `token` `CALLBACK` info                                                                |
+| `CALLBACK_BLOCK`   | String | Enable `CALLBACK` command after `CALLBACK_BLOCK`                                            |
+| `CALLBACK_TICK`    | String | `TICK` `token` users get when `CALLBACK` command is used                                    |
+| `CALLBACK_AMOUNT`  | String | `TICK` `token` amount that users get when `CALLBACK` command is used                        |
+| `MINT_ALLOW_LIST`  | String | `TX_HASH` of a BTNS `LIST` of addresses to allow minting from                               |
+| `MINT_BLOCK_LIST`  | String | `TX_HASH` of a BTNS `LIST` of addresses to NOT allow minting from                           |
+
+
+## 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`
+
+## Examples
+```
+bt:ISSUE|JDOG
+This example issues a JDOG token 
+```
+
+```
+bt:ISSUE|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
+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
+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
+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!
+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
+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
+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
+```
+
+## Rules
+- First `TICK` `ISSUE` will be considered as valid.
+- `token` may be issued if `counterparty` `ASSET` of same name does not exist
+- `token` may be issued if issuing address is the owner of the `counterparty` `ASSET` of the same name
+- Additional `TICK` `ISSUE` transactions after first valid `TICK` `ISSUE`, will be considered invalid and ignored, unless broadcast from `token` owners address
+- `DECIMALS` can not be changed after `token` supply is issued
+- If `TICK` contains any unicode characters, then `TICK` should be `base64` encoded
+- Allowed characters in `TICK`:
+   - Any word character (alphanumeric characters and underscores)
+   - Special characters: ~!@#$%^&*()_+\-={}[\]\\:<>.?/
+   - Most printable emojis in U+1F300 to U+1F5FF
+- Special characters pipe `|` and semicolon `;` are **NOT** to be used in `TICK` names 
+- `TEXT` can contain a URL to a an icon to use for this token (48x48 standard size)
+- `TEXT` can contain a URL to a JSON file with additional information
+
+## Notes
+- `ISSUE` `TICK` with `MAX_SUPPLY` set to `0` to reserve the `token` name (reserve name)
+- `ISSUE` `TICK` with `MAX_SUPPLY` and `MINT_SUPPLY` set to any non `0` value, to mint supply until `MAX_SUPPLY` is reached (owner can mint beyond `MAX_MINT`)
+- `ISSUE` `TICK` with `MAX_SUPPLY` and `MAX_MINT` set to any non `0` value, to enable user minting (fair minting)
+- `ISSUE` `TICK` with `LOCK_SUPPLY` set to `1` to permanently lock `MAX_SUPPLY` (irreversible)
+- `ISSUE` `TICK` with `LOCK_MINT` set to `1` to permanently lock `MAX_MINT` (irreversible)
+- `ISSUE` `TICK` with `LOCK_RUG` set to `1` to permanently prevent use of the `RUG` command
+- `ISSUE` `TICK` with `LOCK_SLEEP` set to `1` to permanently prevent use of the `SLEEP` command
+- `ISSUE` `TICK` with `LOCK_CALLBACK` set to `1` to permanently lock `CALLBACK_BLOCK`, `CALLBACK_TICK`, and `CALLBACK_AMOUNT` (irreversible)
+- `CALLBACK_BLOCK`, `CALLBACK_TICK`, and `CALLBACK_AMOUNT` can be edited via `ISSUE` action until `LOCK_CALLBACK` is set to `1`
+- `DEPLOY` `ACTION` can be used for backwards-compatability with BRC20/SRC20 `DEPLOY`
+- `DESCRIPTION` field can not contain any pipe `|` or semi-colon `;` characters, as these are reserved
+- By default any address can `MINT`, to change this behavior use `MINT_ALLOW_LIST` and `MINT_BLOCK_LIST`
diff --git a/docs/actions/LIST.md b/docs/actions/LIST.md
@@ -0,0 +1,35 @@
+# LIST command
+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  |
+
+
+## Formats
+- `LIST|TYPE|ITEM|ITEM|ITEM`
+
+## Examples
+```
+bt:LIST|1|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev|1FWDonkMbC6hL64JiysuggHnUAw2CKWszs|bc1q5jw436vef6ezsgggk93pwhh9swrdxzx2e3a7kj
+This example creates a list of addresses
+```
+
+```
+bt:LIST|2|JDOG|BRRR|TEST
+This example creates a list of BTNS token tickers
+```
+
+```
+bt:LIST|3|XCP|RAREPEPE|JPMCHASE|A4211151421115130001
+This example creates a list of counterparty assets
+```
+
+## Rules
+- In order for a `LIST` to be considered `valid`, all tickers or addresses must be valid.
+- A `TICK` list contain only BTNS `TICK` items
+- A `ASSET` list contains only Counterparty `ASSET` items
+
+## Notes
diff --git a/docs/actions/MINT.md b/docs/actions/MINT.md
@@ -0,0 +1,30 @@
+# MINT command
+This command mints `BTNS` `token` supply
+
+## PARAMS
+| Name          | Type   | Description                            |
+| ------------- | ------ | -------------------------------------- |
+| `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`
+
+## Examples
+```
+bt:MINT|JDOG|1
+This example mints 1 JDOG `token` to the broadcasting address
+```
+
+```
+bt:MINT|BRRR|10000000000000|1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev
+This example mints 10,000,000,000,000 BRRR tokens and transfers them to 1JDogZS6tQcSxwfxhv6XKKjcyicYA4Feev 
+```
+
+## Rules
+- `broadcast` `status` must be `valid`
+- `token` supply may be minted until `MAX_SUPPLY` is reached.
+- Transactions that attempt to mint supply beyond `MAX_SUPPLY` shall be considered invalid and ignored.
+
+## Notes