From a4f6bc72cea7e4778adfdcc8659efdfe1d36a03a Mon Sep 17 00:00:00 2001 From: John Villar Date: Tue, 2 Oct 2018 00:40:52 -0400 Subject: [PATCH] Added new api limits, updated the spec for new api messages and removed/tagged some old documentation --- Basics/FAQ-SmartContracts.md | 6 +- Basics/assets.md | 16 +-- Developers/API.md | 201 +++++++++++++++------------ Developers/protocol_specification.md | 34 +++-- Installation/bitcoin_core.md | 51 +------ Installation/federated_node.md | 40 +++--- 6 files changed, 170 insertions(+), 178 deletions(-) diff --git a/Basics/FAQ-SmartContracts.md b/Basics/FAQ-SmartContracts.md index 1a04080e..a58c1d72 100644 --- a/Basics/FAQ-SmartContracts.md +++ b/Basics/FAQ-SmartContracts.md @@ -1,6 +1,8 @@ Smart Contracts/EVM FAQ ==================== +**WARNING: this page is kept for historical purposes and does not represent the current state of coutnerparty. A new proposal is being built for a specific Counterparty VM.** + [TOC] ### What is a smart contract? @@ -70,7 +72,7 @@ Thus, the block time limit is overall rather minor, and only affects the initial Not currently. With the EVM, when a contract’s "state" (i.e. storage data) is modified via an execution operation, all nodes on the Counterparty network must perform the operation at the same time. This is because all contract state must be identical and shared across all nodes. -Payment channels, on the other hand, are essentially a private negotiation between two parties, who, once they agree, will finalize their agreement on the blockchain. This is done via utilizing Bitcoin’s internal scripting language in a certain clever way (i.e. intentional non-broadcast double-spends). The EVM, on the other hand, relies on all nodes updating their state as a contract runs (i.e. no "private negotiations") and does not utilize Bitcoin script directly. Instead, all EVM operations are embedded inside Counterparty protocol data. +Payment channels, on the other hand, are essentially a private negotiation between two parties, who, once they agree, will finalize their agreement on the blockchain. This is done via utilizing Bitcoin’s internal scripting language in a certain clever way (i.e. intentional non-broadcast double-spends). The EVM, on the other hand, relies on all nodes updating their state as a contract runs (i.e. no "private negotiations") and does not utilize Bitcoin script directly. Instead, all EVM operations are embedded inside Counterparty protocol data. So while, technically, the parties could "negotiate" an EVM publish or execute operation, it would not yet be broadcast, and thus, not have any impact on the EVM’s global contract state. @@ -100,7 +102,7 @@ So to reiterate, the vulnerability that occurred is due to these bugs in the DAO Not if you don’t send those funds to the smart contract (which allows it to control the funds via its code). -Unlike with Ethereum, where smart contracts are a fundamental and required component of most any action beyond sending Ether, our system is designed so that our core feature-set is completely independent of any smart contract functionality. This means that anyone can use Counterparty’s well-tested asset creation, transfer and decentralized trading features without having to interact with or otherwise touch smart contracts. +Unlike with Ethereum, where smart contracts are a fundamental and required component of most any action beyond sending Ether, our system is designed so that our core feature-set is completely independent of any smart contract functionality. This means that anyone can use Counterparty’s well-tested asset creation, transfer and decentralized trading features without having to interact with or otherwise touch smart contracts. ### What are the differences between the current EVM and the one announced in 2014? diff --git a/Basics/assets.md b/Basics/assets.md index 4253927a..7d90515a 100644 --- a/Basics/assets.md +++ b/Basics/assets.md @@ -6,7 +6,7 @@ With Counterparty, users can create their own assets (also known as "tokens", "c Among other features, Counterparty adds the ability *create*, *send*, *trade*, and *pay distributions on* assets, in a fully decentralized and trustless manner. While Counterparty has its own internal currency (XCP), trading and creating assets does not require anything apart from regular Bitcoin transaction fees. -Many of the features described below can be accessed using the Web-based Counterwallet. Especially casual users and those without a `counterparty-cli` setup can benefit from the convenience of Counterwallet. +Many of the features described below can be accessed using the Web-based Counterwallet. Especially casual users and those without a `counterparty-cli` setup can benefit from the convenience of Counterwallet. # Creating assets @@ -15,7 +15,7 @@ Counterparty allows users to *issue assets*. An asset that is created within the Counterparty protocol is often called a *user-created token*. User-created tokens are just as real as XCP or even BTC. With the asset issuance function, every user has the ability to create a new currency project inside -the Bitcoin and Counterparty ecosystem. +the Bitcoin and Counterparty ecosystem. *You can create two different types of assets:* @@ -49,7 +49,7 @@ callable) with every issuance thereafter. A divisible user-created asset is, like, Bitcoin and XCP, divisible up to 8 decimal places. A callable asset is an asset which the issuer can call back (i.e. repurchase) from its owners at a date (`call-date`) and for a price (`call-price`) -specified at the initial issuance. +specified at the initial issuance. # Sending assets (`send`) @@ -64,7 +64,7 @@ To send an asset in Counterparty, one must specify: It is possible to distribute funds proportionally among asset holders using the `distribution` function. This feature is also also known as `dividend payments`, depending on their desired purpose. Distributions are paid in in any `distribution_asset` to everyone who -holds the asset in proportion to how many units he holds; specifically: +holds the asset in proportion to how many units he holds; specifically: Let `total` equal the total distribution paid out, and `quantity` be the total amount of asset, then: `quantity-per-unit = total/quantity` @@ -167,12 +167,6 @@ address with `give_asset`. This feature is enabled on the CLI, and disabled on [ Below are just a few of the many uses of assets, feel free to propose new uses if you find them. -## Programmable Smart Contracts - -Turing-complete smart contracts scripting is one of the most powerful Counterparty features. Users can write their own custom financial instruments and decentralized applications (Dapp). Counterparty contracts are 100% compatible with Ethereum scripting, and pretty much all contracts can be run on both platforms without code changes. - -## Currency Peg - ## Betting Counterparty turns the Bitcoin blockchain into a betting platform and prediction market. Oracles can create broadcasts of information, and users can then place bets on these broadcasts. Funds are escrowed automatically by the protocol, and benefit from being stored securely inside the Bitcoin blockchain. Funds placed on bets are be provably inaccessible until the bet is resolved or expires. Oracles can set a fee fraction to receive for their betting feeds, providing incentive to run their broadcasts. @@ -191,7 +185,7 @@ Using broadcasts, users can publish timestamped information onto the Bitcoin blo ## Crowdfunding -Counterparty assets can be used for crowdfunding. You can issue a certain amount of assets and sell these to start your project. Due to the high amount of trust involved, it is better to use a Counterparty-based crowdfunding platform which can perform due-diligence on your project. This will provide your users trust, and demonstrate the legitimacy of your project. There is nothing stopping you from doing this on your own, but users may rightfully be suspicious about your project. +Counterparty assets can be used for crowdfunding. You can issue a certain amount of assets and sell these to start your project. Due to the high amount of trust involved, it is better to use a Counterparty-based crowdfunding platform which can perform due-diligence on your project. This will provide your users trust, and demonstrate the legitimacy of your project. There is nothing stopping you from doing this on your own, but users may rightfully be suspicious about your project. ## Derivatives diff --git a/Developers/API.md b/Developers/API.md index 00aed869..e0cfba15 100644 --- a/Developers/API.md +++ b/Developers/API.md @@ -30,7 +30,7 @@ in the future, and listens on the same port as JSON RPC one. ##Getting Started By default, the server will listen on port ``4000`` (if on mainnet) or port ``14000`` (on testnet) for API -requests. +requests. Note that the main API is built on JSON-RPC 2.0, not 1.1. JSON-RPC itself is pretty lightweight, and API requests are made via a HTTP POST request to ``/api/`` (note the trailing slash), with JSON-encoded data passed as the POST body. @@ -56,7 +56,7 @@ All requests must have POST data that is JSON encoded. Here's an example of the The ``jsonrpc`` and ``id`` properties are requirements under the JSON-RPC 2.0 spec. -You should note that the data in ``params`` is a JSON object (e.g. mapping), not an array. In other words, +You should note that the data in ``params`` is a JSON object (e.g. mapping), not an array. In other words, **the API only supports named arguments, not positional arguments** (e.g. use {"argument1": "value1", "argument2": "value2"} instead of ["value1", "value2"]). This is the case for safety and bug-minimization reasons. @@ -78,7 +78,7 @@ if a password is set. **The default user is ``'rpc'``.** The following examples have authentication enabled and the `user` set to its default value of `'rpc'`. The password is not set (default: `'rpc'`). Ensure -these values correspond to values in your counterparty-server's configuration +these values correspond to values in your counterparty-server's configuration file `'server.conf'`. Submissions of examples in additional languages are welcome! @@ -88,11 +88,11 @@ Submissions of examples in additional languages are welcome! import json import requests from requests.auth import HTTPBasicAuth - + url = "http://localhost:4000/api/" headers = {'content-type': 'application/json'} auth = HTTPBasicAuth('rpc', PASSWORD) - + payload = { "method": "get_running_info", "params": {}, @@ -113,11 +113,11 @@ library. use JsonRPC\Client; $client = new Client('http://localhost:4000/api/'); $client->authentication('rpc', PASSWORD); - + $result = $client->execute('get_balances', array('filters' => array('field' => 'address', 'op' => '==', 'value' => '1NFeBp9s5aQ1iZ26uWyiK2AYUXHxs7bFmB'))); print("get_balances result:\n"); var_dump($result); - + $result2 = $client->execute('get_running_info'); print("get_running_info result:\n"); var_dump($result2); @@ -125,7 +125,7 @@ library. ###curl -Remember to surround non-numeric parameter values with the double quotes, as per [JSON-RPC 2.0 examples](http://www.jsonrpc.org/specification#examples). For example, `"order_by": "tx_hash"` is correct and will work, `"order_by": 'tx_hash'` won't. +Remember to surround non-numeric parameter values with the double quotes, as per [JSON-RPC 2.0 examples](http://www.jsonrpc.org/specification#examples). For example, `"order_by": "tx_hash"` is correct and will work, `"order_by": 'tx_hash'` won't. ####Linux @@ -154,34 +154,34 @@ Authorization string in the example below is based on the default username/passw Authorization string in the example below is based on the default username/password. package main - + import ( "fmt" "strings" "net/http" "io/ioutil" ) - + func main() { - + url := "http://127.0.0.1:4000/api/" - + payload := strings.NewReader("{\r\n \"method\": \"get_running_info\",\r\n \"params\": {},\r\n \"jsonrpc\": \"2.0\",\r\n \"id\": 1\r\n}") - + req, _ := http.NewRequest("POST", url, payload) - + req.Header.Add("content-type", "application/json") req.Header.Add("authorization", "Basic cnBjOjEyMzQ=") req.Header.Add("cache-control", "no-cache") - + res, _ := http.DefaultClient.Do(req) - + defer res.Body.Close() body, _ := ioutil.ReadAll(res.Body) - + fmt.Println(res) fmt.Println(string(body)) - + } ###Ruby (Net::HTTP) @@ -190,17 +190,17 @@ Authorization string in the example below is based on the default username/passw require 'uri' require 'net/http' - + url = URI("http://127.0.0.1:4000/api/") - + http = Net::HTTP.new(url.host, url.port) - + request = Net::HTTP::Post.new(url) request["content-type"] = 'application/json' request["authorization"] = 'Basic cnBjOjEyMzQ=' request["cache-control"] = 'no-cache' request.body = "{\r\n \"method\": \"get_running_info\",\r\n \"params\": {},\r\n \"jsonrpc\": \"2.0\",\r\n \"id\": 1\r\n}" - + response = http.request(request) puts response.read_body @@ -212,12 +212,12 @@ The following examples don't use authentication as with default settings. ###Python import requests - + url = "http://localhost:4000/rest/" headers = {'content-type': 'application/json'} query = 'sends/get?source=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc&destination=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns&op=AND' - + response = requests.get(url + query, headers=headers) print("Response: ", response.text) @@ -228,7 +228,7 @@ These examples use the default username/password combination in URL. ####Linux - curl "http://rpc:rpc@127.0.0.1:4000/rest/sends/get?source=1B6ahDHnKtZ5GXqytHSxfcXgNoxm1q1RsP&destination=14fAoS9FPD9jx36hjCNoAqFVLNHD1NQVN5&op=AND" -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" + curl "http://rpc:rpc@127.0.0.1:4000/rest/sends/get?source=1B6ahDHnKtZ5GXqytHSxfcXgNoxm1q1RsP&destination=14fAoS9FPD9jx36hjCNoAqFVLNHD1NQVN5&op=AND" -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json" ####Windows @@ -266,7 +266,7 @@ This example was created with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10. Fo "jsonrpc": "2.0", "id": 0 } - + * Fetch all debits for > 2 XCP between blocks 280537 and 280539, sorting the results by quantity (descending order) payload = { @@ -282,7 +282,7 @@ This example was created with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10. Fo "id": 0 } - + * Send 1 XCP (specified in satoshis) from one address to another. payload = { @@ -296,7 +296,7 @@ This example was created with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10. Fo "jsonrpc": "2.0", "id": 0 } - + * Issuance (indivisible) payload = { @@ -345,7 +345,7 @@ This example was created with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10. Fo **Note:** Before v9.49.4, the counterparty server API provided an interface to Bitcoin Core's signing functionality through the `do_*`, `sign_tx` and `broadcast_tx` methods, which have all since been removed. -All ``create_`` API calls return an *unsigned raw transaction serialization* as a hex-encoded string (i.e. the same format that ``bitcoind`` returns with its raw transaction API calls). This raw transaction's inputs may be validated and then must be signed (i.e. via Bitcoin Core, a 3rd party Bitcoin library like Bitcore, etc) and broadcast on the Bitcoin network. +All ``create_`` API calls return an *unsigned raw transaction serialization* as a hex-encoded string (i.e. the same format that ``bitcoind`` returns with its raw transaction API calls). This raw transaction's inputs may be validated and then must be signed (i.e. via Bitcoin Core, a 3rd party Bitcoin library like Bitcore, etc) and broadcast on the Bitcoin network. The process of signing and broadcasting a transaction, from start to finish, depends somewhat on the wallet software used. Below are examples of how one might use a wallet to sign and broadcast an unsigned Counterparty transaction *created* with this API. @@ -441,7 +441,7 @@ Anywhere where an quantity is specified, it is specified in **satoshis** (if a d Examples: - 4381030000 = 43.8103 (if divisible asset) -- 4381030000 = 4381030000 (if indivisible asset) +- 4381030000 = 4381030000 (if indivisible asset) **NOTE:** XCP and BTC themselves are divisible assets. @@ -511,17 +511,18 @@ For example: ``get_balances``, ``get_credits``, ``get_debits`` are all valid API be specified as well. See [filtering](#filtering-read-api-results) for more information. * **order_by ** (*string*): If sorted results are desired, specify the name of an attribute of the appropriate table to order the results by (e.g. ``quantity`` for [balance object](#balance-object), if you called ``get_balances``). - If left blank, the list of results will be returned unordered. + If left blank, the list of results will be returned unordered. * **order_dir** (*string*): The direction of the ordering. Either ``ASC`` for ascending order, or ``DESC`` for descending order. Must be set if ``order_by`` is specified. Leave blank if ``order_by`` is not specified. - * **start_block** (*integer*): If specified, only results from the specified block index on will be returned + * **start_block** (*integer*): If specified, only results from the specified block index on will be returned * **end_block** (*integer*): If specified, only results up to and including the specified block index on will be returned * **status** (*string/list*): return only results with the specified status or statuses (if a list of status strings is supplied). See the [status list](#status). Note that if ``null`` is supplied (the default), then status is not filtered. Also note that status filtering can be done via the ``filters`` parameter, but doing it through this parameter is more flexible, as it essentially allows for situations where ``OR`` filter logic is desired, as well as status-based filtering. - * **limit** (*integer*): (maximum) number of elements to return. Can specify a value less than or equal to 1000. For more results, use - a combination of ``limit`` and ``offset`` parameters to paginate results. + * **limit** (*integer*): (maximum) number of elements to return. Can specify a value less than or equal to the instance's max limit (default 1000). + For more results, use a combination of ``limit`` and ``offset`` parameters to paginate results. If the instance has a limit of 0 you can specify + any limit for the row results, even 0 to get the full dataset. * **offset** (*integer*): return results starting from specified ``offset`` **Special Parameters:** @@ -567,9 +568,9 @@ Gets information on an issued asset. ``null`` if the asset was not found. Otherwise, a list of one or more objects, each one with the following properties: - - **asset** (*string*): The [assets](#assets) of the asset itself + - **asset** (*string*): The [assets](#assets) of the asset itself - **asset_longname** (*string*): The [subasset](#subassets) longname, if any - - **owner** (*string*): The address that currently owns the asset (i.e. has issuance rights to it) + - **owner** (*string*): The address that currently owns the asset (i.e. has issuance rights to it) - **divisible** (*boolean*): Whether the asset is divisible or not - **locked** (*boolean*): Whether the asset is locked (future issuances prohibited) - **total_issued** (*integer*): The [quantities](#quantities-and-balances) of the asset issued, in total @@ -600,7 +601,7 @@ Gets information on an issued asset. **Return:** - A list of the names of all existing Counterparty assets, ordered alphabetically. + A list of the names of all existing Counterparty assets, ordered alphabetically. ###get_holder_count @@ -633,15 +634,15 @@ Gets information on an issued asset. **get_messages(block_index)** -Return message feed activity for the specified block index. The message feed essentially tracks all +Return message feed activity for the specified block index. The message feed essentially tracks all database actions and allows for lower-level state tracking for applications that hook into it. - + **Parameters:** * **block_index** (*integer*): The block index for which to retrieve activity. -**Return:** - +**Return:** + A list of one or more [message object](#message-object) if there was any activity in the block, otherwise ``[]`` (empty list). @@ -650,12 +651,12 @@ database actions and allows for lower-level state tracking for applications that **get_messages_by_index(message_indexes)** Return the message feed messages whose ``message_index`` values are contained in the specified list of message indexes. - + **Parameters:** - * **message_indexes** (*list*): An array of one or more ``message_index`` values for which the cooresponding message feed entries are desired. + * **message_indexes** (*list*): An array of one or more ``message_index`` values for which the cooresponding message feed entries are desired. -**Return:** +**Return:** A list containing a `message <#message-object>`_ for each message found in the specified ``message_indexes`` list. If none were found, ``[]`` (empty list) is returned. @@ -670,13 +671,13 @@ Gets basic information for a specific block. * **block_index** (*integer*): The block index for which to retrieve information. -**Return:** +**Return:** If the block was found, an object with the following properties: - - - **block_index** (*integer*): The block index (i.e. block height). Should match what was specified for the *block_index* input parameter). + + - **block_index** (*integer*): The block index (i.e. block height). Should match what was specified for the *block_index* input parameter). - **block_hash** (*string*): The block hash identifier - - **block_time** (*integer*): A UNIX timestamp of when the block was processed by the network + - **block_time** (*integer*): A UNIX timestamp of when the block was processed by the network ###get_blocks @@ -696,7 +697,7 @@ is much quicker than using multiple ``get_block_info()`` and ``get_messages()`` A list of objects, one object for each valid block index specified, in order from first block index to last. Each object has the following properties: - - **block_index** (*integer*): The block index (i.e. block height). Should match what was specified for the *block_index* input parameter). + - **block_index** (*integer*): The block index (i.e. block height). Should match what was specified for the *block_index* input parameter). - **block_hash** (*string*): The block hash identifier - **block_time** (*integer*): A UNIX timestamp of when the block was processed by the network - **_messages** (*list*): A list of one or more [message object](#message-object) if there was any activity in the block, otherwise ``[]`` (empty list). @@ -712,7 +713,7 @@ Gets some operational parameters for the server. None -**Return:** +**Return:** An object with the following properties: @@ -725,6 +726,7 @@ Gets some operational parameters for the server. - **version_major** (*integer*): The major version of counterparty-server running - **version_minor** (*integer*): The minor version of counterparty-server running - **version_revision** (*integer*): The revision version of counterparty-server running + - **api_limit_rows** (*integer*): The max amount of rows any call will return. If ``0`` there's no limit to calls. Defaults to ``1000``. ###get_element_counts @@ -737,7 +739,7 @@ Gets the number of records for each entity type None -**Return:** +**Return:** An object with a property for each element type (e.g. `transactions`, `blocks`, `bets`, `order_matches`, etc.) with the value of each property being the record count of that respective entity in the database. @@ -754,10 +756,10 @@ Get a listing of UTXOs for the specified address. * **unconfirmed** (*boolean*): Set to `true` to include unconfirmed UTXOs (e.g. those in the mempool) * **unspent_tx_hash** (*boolean*): Specify a specific transaction hash to only include UTXOs from that transaction -**Return:** +**Return:** A list of objects, with each entry in the dict having the following properties: - + - **amount**: The amount of the UTXO - **confirmations**: Number of confirmations since the UTXO was created - **scriptPubKey**: The UTXO's scriptPubKey, encoded in hex format @@ -777,7 +779,7 @@ Gets raw data for a single transaction. * **verbose** (*boolean*): Include some additional information in the result data * **skip_missing** (*boolean*): If set to `false`, and the transaction hash cannot be found, return `null`, otherwise if `true`, throw an exception. -**Return:** +**Return:** If found, a raw transaction objects having the same format as the [bitcoind getrawtransaction API call](https://chainquery.com/bitcoin-api/getrawtransaction). If not found, `null`. @@ -794,7 +796,7 @@ Gets raw data for a list of transactions. * **verbose** (*boolean*): Include some additional information in the result data for each transaction * **skip_missing** (*boolean*): If set to `false`, and one or more transaction hash cannot be found, the missing txhash data will not be included in the result set, otherwise if `true`, throw an exception. -**Return:** +**Return:** A list of raw transaction objects having the same format as the [bitcoind getrawtransaction API call](https://chainquery.com/bitcoin-api/getrawtransaction). @@ -810,7 +812,7 @@ Gets raw transaction objects for the specified address. * **address** (*string*): The address for which to receive the raw transactions * **unconfirmed** (*boolean*): Set to `true` to include unconfirmed transactions (e.g. those in the mempool) -**Return:** +**Return:** A list of raw transaction objects, with each object having the same format as the [bitcoind getrawtransaction API call](https://chainquery.com/bitcoin-api/getrawtransaction). @@ -826,10 +828,10 @@ Get transaction info, as parsed by `counterparty-server`. * **tx_hex** (*string*): The canonical hexadecimal serialization of the transaction (not its hash) * **block_index** (*integer*) -**Return:** +**Return:** A list with the following items (in order as listed below): - + - `source` - `destination` - `btc_amount` @@ -848,7 +850,7 @@ For the specified pubkeyhash (i.e. address), return the public key. Note that th * **pubkeyhash** (*string*): The pubkeyhash/address * **provided_pubkeys** (*list*): A list of supplied pubkeys. If one of these pubkeys matches the pubkeyhash, used if one of the supplied pubkey hashes to the pubkeyhash. (Can be useful if the pubkeyhash has not sent out at least one transaction and you have a list of pubkeys that may match it.) -**Return:** +**Return:** A string with the specified pubkey. If the pubkey cannot be found, an exception will be generated and returned. @@ -880,7 +882,7 @@ Issue a bet against a feed. **Parameters:** * **source** (*string*): The address that will make the bet. - * **feed_address** (*string*): The address that hosts the feed to be bet on. + * **feed_address** (*string*): The address that hosts the feed to be bet on. * **bet_type** (*integer*): 0 for Bullish CFD (deprecated), 1 for Bearish CFD (deprecated), 2 for Equal, 3 for NotEqual. * **deadline** (*integer*): The time at which the bet should be decided/settled, in Unix time (seconds since epoch). * **wager_quantity** (*integer*): The [quantities](#quantities-and-balances) of XCP to wager (*in satoshis*, hence integer). @@ -890,7 +892,7 @@ Issue a bet against a feed. * **leverage** (*integer, default=5040*): Leverage, as a fraction of 5040 * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -910,7 +912,7 @@ Broadcast textual and numerical information to the network. * **value** (*float*): Numerical value of the broadcast. * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -919,14 +921,14 @@ Broadcast textual and numerical information to the network. **create_btcpay(order_match_id)** -Create and (optionally) broadcast a BTCpay message, to settle an Order Match for which you owe BTC. +Create and (optionally) broadcast a BTCpay message, to settle an Order Match for which you owe BTC. **Parameters:** * **order_match_id** (*string*): The concatenation of the hashes of the two transactions which compose the order match. * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -943,7 +945,7 @@ Burn a given quantity of BTC for XCP (**on mainnet, possible between blocks 2783 * **quantity** (*integer*): The [quantities](#quantities-and-balances) of BTC to burn (1 BTC maximum burn per address). * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -960,10 +962,27 @@ Cancel an open order or bet you created. * **source** (*string*): The source address of the order or bet. * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. +###create_destroy + +**create_destroy(source, asset, quantity, tag)** + +Destroy XCP or a user defined asset. + +**Parameters:** + + * **source** (*string*): The address that will be sending (must have the necessary quantity of the specified asset). + * **asset** (*string*): The [asset](#assets) or [subasset](#subassets) to destroy. + * **quantity** (*integer*): The [quantities](#quantities-and-balances) of the asset to destroy. + * **tag** (*string, optional*): The tag (which works like a [Memo](../protocol_specification#memos) ) associated with this transaction. + * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* + +**Return:** + + The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. ###create_dividend @@ -979,7 +998,7 @@ Issue a dividend on a specific user defined asset. * **dividend_asset** (*string*): The [asset](#assets) or [subasset](#subassets) that the dividends are paid in. * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -1000,7 +1019,7 @@ Issue a new asset, issue more of an existing asset, lock an asset, or transfer t * **transfer_destination** (*string, default=null*): The address to receive the asset (only used when *transferring* assets -- leave set to ``null`` if issuing an asset). * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -1031,7 +1050,7 @@ Issue an order request. * **expiration** (*integer*): The number of blocks for which the order should be valid. * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -1040,7 +1059,7 @@ Issue an order request. **create_send(source, destination, asset, quantity)** -Send XCP or a user defined asset. +Send XCP or a user defined asset. **Parameters:** @@ -1053,7 +1072,7 @@ Send XCP or a user defined asset. * **use_enhanced_send** (*boolean, optional*): If this is false, the construct a legacy transaction sending bitcoin dust. Defaults to true. * *NOTE: Additional (advanced) parameters for this call are documented [here](#advanced-create_-parameters).* -**Return:** +**Return:** The unsigned transaction, as an hex-encoded string. Must be signed before being broadcast: see [here](#signing-transactions-before-broadcasting) for more information. @@ -1103,11 +1122,11 @@ The REST API documentation is hosted both on our webiste and on a new API docume Query table_name in the database using filters concatenated using filterop. -URL format: +URL format: `/rest//get?&op=` -Example query: +Example query: `/rest/sends/get?source=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc&destination=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns&op=AND` @@ -1123,7 +1142,7 @@ Example query: **Headers:** * **Accept** (*string, optional*): The format of return data. Can be either `application/json` or `application/xml`. Defaults to JSON. -**Return:** +**Return:** Desired database rows from table_name sieved using filters. @@ -1134,11 +1153,11 @@ Example query: Compose a `message_type` transaction with `transaction_params` as data. -URL format: +URL format: `/rest//compose?` -Example query: +Example query: `/rest/send/compose?source=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc&destination=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns&asset=BTC&quantity=1` @@ -1151,7 +1170,7 @@ Example query: **Headers:** * **Accept** (*string, optional*): The format of return data. Can be either `application/json` or `application/xml`. Defaults to JSON. -**Return:** +**Return:** The hex data of composed transaction. @@ -1184,7 +1203,7 @@ An object that describes a specific bet: * **wager_quantity** (*integer*): The [quantities](#quantities-and-balances) of XCP to wager * **counterwager_quantity** (*integer*): The minimum [quantities](#quantities-and-balances) of XCP to be wagered by the user to bet against the bet issuer, if the other party were to accept the whole thing * **wager_remaining** (*integer*): The quantity of XCP wagered that is remaining to bet on -* **odds** (*float*): +* **odds** (*float*): * **target_value** (*float*): Target value for Equal/NotEqual bet * **leverage** (*integer*): Leverage, as a fraction of 5040 * **expiration** (*integer*): The number of blocks for which the bet should be valid @@ -1209,13 +1228,13 @@ An object that describes a specific occurance of two bets being matched (either * **tx1_expiration** (*integer*): The number of blocks over which the matching bet was valid * **tx1_bet_type** (*string*): The type of the counter bet (0 for Bullish CFD (deprecated), 1 for Bearish CFD (deprecated), 2 for Equal, 3 for Not Equal) * **feed_address** (*string*): The address of the feed that the bets refer to -* **initial_value** (*integer*): +* **initial_value** (*integer*): * **deadline** (*integer*): The timestamp at which the bet match was made, in Unix time. * **target_value** (*float*): Target value for Equal/NotEqual bet * **leverage** (*integer*): Leverage, as a fraction of 5040 * **forward_quantity** (*integer*): The [quantities](#quantities-and-balances) of XCP bet in the initial bet * **backward_quantity** (*integer*): The [quantities](#quantities-and-balances) of XCP bet in the matching bet -* **fee_multiplier** (*integer*): +* **fee_multiplier** (*integer*): * **validity** (*string*): Set to "valid" if a valid order match. Any other setting signifies an invalid/improper order match @@ -1227,7 +1246,7 @@ An object that describes a specific occurance of a broadcast event (i.e. creatin * **tx_hash** (*string*): The transaction hash * **block_index** (*integer*): The block index (block number in the block chain) * **source** (*string*): The address that made the broadcast -* **timestamp** (*string*): The time the broadcast was made, in Unix time. +* **timestamp** (*string*): The time the broadcast was made, in Unix time. * **value** (*float*): The numerical value of the broadcast * **fee_multiplier** (*float*): How much of every bet on this feed should go to its operator; a fraction of 1, (i.e. 0.05 is five percent) * **text** (*string*): The textual component of the broadcast @@ -1241,7 +1260,7 @@ An object that matches a request to settle an Order Match for which BTC is owed: * **tx_index** (*integer*): The transaction index * **tx_hash** (*string*): The transaction hash * **block_index** (*integer*): The block index (block number in the block chain) -* **source** (*string*): +* **source** (*string*): * **order_match_id** (*string*): * **validity** (*string*): Set to "valid" if valid @@ -1291,7 +1310,7 @@ An object that describes an issuance of dividends on a specific user defined ass * **tx_hash** (*string*): The transaction hash * **block_index** (*integer*): The block index (block number in the block chain) * **source** (*string*): The address that issued the dividend -* **asset** (*string*): The [assets](#assets) that the dividends are being rewarded on +* **asset** (*string*): The [assets](#assets) that the dividends are being rewarded on * **quantity_per_unit** (*integer*): The [quantities](#quantities-and-balances) of XCP rewarded per whole unit of the asset * **validity** (*string*): Set to "valid" if a valid burn. Any other setting signifies an invalid/improper burn @@ -1307,7 +1326,7 @@ An object that describes a specific occurance of a user defined asset being issu * **asset_longname** (*string*): The [subasset](#subassets) longname, if any * **quantity** (*integer*): The [quantities](#quantities-and-balances) of the specified asset being issued * **divisible** (*boolean*): Whether or not the asset is divisible (must agree with previous issuances of the asset, if there are any) -* **issuer** (*string*): +* **issuer** (*string*): * **transfer** (*boolean*): Whether or not this objects marks the transfer of ownership rights for the specified quantity of this asset * **validity** (*string*): Set to "valid" if a valid issuance. Any other setting signifies an invalid/improper issuance @@ -1377,11 +1396,11 @@ to track state changes to the counterpartyd database on a block-by-block basis). * **block_index** (*integer*): The block index (block number in the block chain) this event occurred on * **category** (*string*): A string denoting the entity that the message relates to, e.g. "credits", "burns", "debits". The category matches the relevant table name in counterpartyd (see blocks.py for more info). -* **command** (*string*): The operation done to the table noted in **category**. This is either "insert", or "update". +* **command** (*string*): The operation done to the table noted in **category**. This is either "insert", or "update". * **bindings** (*string*): A JSON-encoded object containing the message data. The properties in this object match the columns in the table referred to by **category**. - + ###Bet Expiration Object An object that describes the expiration of a bet created by the source address. @@ -1451,9 +1470,9 @@ Here the list of all possible status for each table: This section documents any changes to the API, for version numbers where there were API-level modifications. -There will be no incompatible API pushes that do not either have: +There will be no incompatible API pushes that do not either have: -* A well known set cut over date in the future +* A well known set cut over date in the future * Or, a deprecation process where the old API is supported for an amount of time ##development (unreleased) @@ -1499,11 +1518,11 @@ There will be no incompatible API pushes that do not either have: ##9.43.0 * create_issuance: ``callable`` is also accepted -* create_*: ``null`` is used as default value for missing parameters +* create_*: ``null`` is used as default value for missing parameters ##9.32.0 -**Summary:** API framework overhaul for performance and simplicity +**Summary:** API framework overhaul for performance and simplicity * "/api" with no trailing slash no longer supported as an API endpoint (use "/" or "/api/" instead) * We now consistently reject positional arguments with all API methods. Make sure your API calls do not use positional @@ -1524,7 +1543,7 @@ There will be no incompatible API pushes that do not either have: ##9.24.1 -**Summary:** New API parsing engine added, as well as dynamic get method composition in ``api.py``: +**Summary:** New API parsing engine added, as well as dynamic get method composition in ``api.py``: * Added ``sql`` API method * Filter params: Added ``LIKE``, ``NOT LIKE`` and ``IN`` diff --git a/Developers/protocol_specification.md b/Developers/protocol_specification.md index c5e2da20..ccddb878 100644 --- a/Developers/protocol_specification.md +++ b/Developers/protocol_specification.md @@ -17,19 +17,19 @@ counterparty-lib [ChangeLog](https://github.com/CounterpartyXCP/counterpartyd/bl Transactions ------------ -Counterparty messages have the following components: +Counterparty messages have the following components: - Source addresses -- Destination addresses (optional) -- A quantity of bitcoins sent from the sources to the destinations, if it exists. -- A fee, in bitcoins, paid to the Bitcoin miners who include the transaction in a block. +- Destination addresses (optional) +- A quantity of bitcoins sent from the sources to the destinations, if it exists. +- A fee, in bitcoins, paid to the Bitcoin miners who include the transaction in a block. - Some ‘data’, imbedded in specially constructed transaction outputs. Every Bitcoin transaction carrying a Counterparty transaction has the -following possible outputs: +following possible outputs: -- zero or more destination outputs, -- zero or more data outputs, and optional change outputs. +- zero or more destination outputs, +- zero or more data outputs, and optional change outputs. All data outputs follow all destination outputs. Change outputs (outputs after the last data output) have no significance. @@ -109,7 +109,7 @@ uppercase Latin characters (inclusive) not beginning with ‘A’, or integers between 26^12 + 1 and 256^8 (inclusive), prefixed with ‘A’. Alphabetic asset names will carry a one‐time issuance fee (by burn) of 0.5 XCP and numeric asset names will be freely available. ‘BTC’ and -‘XCP’ are the only three‐character asset names. Example asset names: +‘XCP’ are the only three‐character asset names. Example asset names: BBBB, A100000000000000000. Assets may be either divisible or indivisible, and divisible assets are @@ -183,13 +183,13 @@ A **send** message sends a quantity of any Counterparty asset from the source address to the destination address. If the sender does not hold a sufficient quantity of that asset at the time that the send message is parsed (in the sequence of transactions), then the send is considered an -oversend. +oversend. Oversends are handled as follows: -1) Oversends using the legacy send transaction type are valid and filled +1) Oversends using the legacy send transaction type are valid and filled as much as they can be -2) Oversends using the new default enhanced send transaction type after +2) Oversends using the new default enhanced send transaction type after block 489956 are invalid and none of the asset is sent counterparty-lib supports sending bitcoins, for which no data output is @@ -279,7 +279,7 @@ Issuances of any non‐zero quantity, that is, issuances which do not merely change, e.g., the description of the asset, involve a debit (and destruction) of now 0.5 XCP. -Asset descriptions in enhanced asset information schema may be of +Asset descriptions in enhanced asset information schema may be of arbitrary length. ###Broadcast @@ -372,7 +372,7 @@ by ‘burning’ bitcoins in miners’ fees during a particular period of time using the a **burn** message type. The number of XCP earned per bitcoin is calculated thus: - XCP_EARNED = BTC_BURNED * (1000 * (1 + .5 * + XCP_EARNED = BTC_BURNED * (1000 * (1 + .5 * ((END_BLOCK - CURRENT_BLOCK) / (END_BLOCK - START_BLOCK)) )) @@ -395,3 +395,11 @@ Open offers may be cancelled, which cancellation is irrevocable. A *cancel* message contains only the hash of the Bitcoin transaction that contains the order or bet to be cancelled. Only the address which made an offer may cancel it. + +###Destroy + +A **destroy** message sends a quantity of any Counterparty asset from the +source address to the default burn address. If the sender does not hold a +sufficient quantity of that asset at the time that the destroy message is +parsed (in the sequence of transactions), then the destroy is considered +invalid. diff --git a/Installation/bitcoin_core.md b/Installation/bitcoin_core.md index 7eafdc09..2dd342b2 100644 --- a/Installation/bitcoin_core.md +++ b/Installation/bitcoin_core.md @@ -1,13 +1,13 @@ # Bitcoin Core with ``addrindex`` Patch -Bitcoin Core is used by Counterparty to interact with the Bitcoin blockchain. However, vanilla Bitcoin Core is insufficient---instead, a version patched to enable an 'address index' is required. +Bitcoin Core is used by Counterparty to interact with the Bitcoin blockchain. ## Download Depending on your OS and other preferences, download one of the binaries or source code from the link below. Optionally you can verify the file's checksum and author's PGP signature. These binaries are built deterministically. -[https://github.com/btcdrak/bitcoin/releases](https://github.com/btcdrak/bitcoin/releases) +[https://github.com/bitcoin/bitcoin/releases](https://github.com/bitcoin/bitcoin/releases) ## Installation @@ -23,7 +23,7 @@ Unlike the Linux binaries, the Windows packages are installers. Uninstall any ol ### Linux Binaries -The Linux binaries are precompiled executables + dependencies, and they're deployed by decompressing them into the desired location. Once that is done, they can be executed directly like so. +The Linux binaries are precompiled executables + dependencies, and they're deployed by decompressing them into the desired location. Once that is done, they can be executed directly like so. ./bitcoin-*/bin/bitcoind -help @@ -56,7 +56,7 @@ To run with the standard GUI interface, start Bitcoin Core (`./bitcoin-qt` on Li Use `bitcoin-cli` to interact with Bitcoin Core. -### Usage on Testnet +### Usage on Testnet For testnet use, add `testnet=1` to a separate copy of the above configuration file or run bitcoind with `-testnet` from a script or the console. Examples: * `./bitcoind -testnet` - start bitcoind on testnet using the default configuration file (blockchain data would be stored in the default data path under `testnet3` subdirectory) @@ -65,47 +65,10 @@ For testnet use, add `testnet=1` to a separate copy of the above configuration f To interact with a testnet instance of Bitcoin Core, use `bitcoin-cli` with the same `testnet` or `conf` options that were used to start it. -## Reindex - -If this is the first time you are running Bitcoin Core with `addrindex` on this computer and you have a full (non-pruned) copy of existing blockchain of the same or lower version as Bitcoin Core addrindex that you plan to use, after you've enabled addrindex and txindex in your new bitcoin.conf, you'll need to launch `bitcoind` (once only) as follows: - - bitcoind -reindex - -Add `-testnet` to reindex testnet blockchain. This will have `bitcoind` complete a one-time reindexing of the local blockchain. Windows users can do the same, or simply run Bitcoin-Core (`Start > Programs > Bitcoin Core > Bitcoin Core`) which will prompt them to reindex their blockchain if necessary. - -Even on a fast machine, reindexing of the entire mainnet blockchain takes hours. If the existing instance of Bitcoin has a wallet file, make a backup copy to be on the safe side. Once reindexing is done and you restart Bitcoin Core, you should see it load the two indexes. - -``` -$ cat /blockchain/bitcoin/debug*log | grep index -2016-10-21 13:00:15 init message: Loading block index... -2016-10-21 13:00:15 Opening LevelDB in /home/user/.bitcoin/blocks/index -2016-10-21 13:00:17 Using obfuscation key for /blockchain/bitcoin/blocks/index: 0000000000000000 -2016-10-21 13:00:52 LoadBlockIndexDB: transaction index enabled -2016-10-21 13:00:52 LoadBlockIndexDB(): address index enabled -``` - ### Leveraging existing blockchain data from a higher Bitcoin Core version -Existing Bitcoin Core users with blockchain data created by a *higher* version of the official Bitcoin Core may not be able to reuse their blockchain data from a lower version of Bitcoin Core because higher Bitcoin Core releases may have a database (or wallet, if used) format that older Bitcoin Core versions cannot recognize. - -This changes from one Bitcoin Core version to another, so please check Bitcoin Core Release Notes for database (and wallet, if applicable) format changes. The reason this (going from a higher release to a lower release) is common is Bitcoin Core addrindex releases are usually slightly behind the official release, so new Counterparty developers with existing full Bitcoin nodes may need to downgrade their Bitcoin Core if the addrindex version isn't out yet. - -In cases where an in-place change is not possible or desired, you can setup a separate Bitcoin Core (with addrindex) instance and add `adddnode=` to the new instance's bitcoin.conf, so that Bitcoin Core addrindex can quickly sync from your non-addrindex instance. - -### Leveraging existing blockchain data from the same version of Bitcoin Core - -Assuming you have another compatible but non-addrindex'ed copy of the blockchain on LAN, another way to save time is to copy the blockchain (normally `.dat` and `*.rev` files from the blocks subdirectory, as well as the entire chainstate subdirectory) over to the same directory on your Counterparty Server or Federated Node (default: `$HOME/federatednode/data/bitcoin/`). Then you would have to build addrinex from scratch by starting your new bitcoind once. An easy way to reindex the blockchain on Federated Node is to add `reindex=1` to the bitcoin (or bitcoin testnet) Docker configuration file, start the container, and then remove the line you just added. The addrindex option must remain enabled at all times. - -### Removing addrindex - -Bitcoin Core addrindex users who want to "go back" to the same or a higher version of Bitcoin Core without addrindex can simply uninstall the former and install the later. `addrindex` and `txindex` can be changed to 0 or removed from the configuration file. If the both are removed, then blockchain index data (see Bitcoin documentation for the details) can be deleted to save disk space, and potentially blockchain pruning (``prune``) can be (re)enabled as well. - -Prior to making changes make a backup of your wallet if you have one. Addrindex does not impact the wallet, but a migration to a different Bitcoin Core version may. - -#### How to remove Bitcoin Core with addrindex patch and switch to Bitcoin Core 0.15 while leaving txindex in place - -Please note that that counterparty-lib v9.55.4 and older cannot use Bitcoin Core without addrindex and that the reversing this upgrade may require significantly more time because reindexing would likely need to rebuild chainstate databases as well. Configuration of ZMQ related options may be reqired for external indexing based on ZMQ. +Existing Bitcoin Core users with blockchain data created by a *higher* version of the official Bitcoin Core may not be able to reuse their blockchain data from a lower version of Bitcoin Core because higher Bitcoin Core releases may have a database (or wallet, if used) format that older Bitcoin Core versions cannot recognize. -In order to change from existing Bitcoin Core with addrindex and txidnex to vanilla Bitcoin Core with txindex, uninstall Bitcoin Core with addrindex, make a backup of any wallets you may have, and install vanilla Bitcoin Core. Remove `addrindex=1` from your configuration file(s) or startup script(s) and run vanilla Bitcoin Core once with `-reindex` enabled. Once this deletes addrindex entries from your local data, only txindex will remain. +This changes from one Bitcoin Core version to another, so please check Bitcoin Core Release Notes for database (and wallet, if applicable) format changes. -Reindexing will take a number of hours. In order to minimize downtime, you may want to setup a new instance of vanilla Bitcoin Core (with `txindex=1`) running on a different server (or on the same server, but on different ports) and let it sync with existing node. Note that doing this on the same server requires nearly twice as many resources (CPU, RAM, disk), so it is not recommended for full nodes with modest system resources. +In cases where an in-place change is not possible or desired, you can setup a separate Bitcoin Core instance and add `adddnode=` to the new instance's bitcoin.conf. diff --git a/Installation/federated_node.md b/Installation/federated_node.md index 1e7eb2b1..a5866a75 100644 --- a/Installation/federated_node.md +++ b/Installation/federated_node.md @@ -6,7 +6,7 @@ This document describes how one can set up their own Counterparty "Federated Nod A Federated Node is a self-contained system that runs the some or all of the Counterparty software stack, via Docker. Each system operates as a Bitcoin and Counterparty "full node". Using this toolset, one can generally get started running the Counterparty software much quicker and more easily than a manual installation of the various components. -The document is primarily intended for power users and developers. +The document is primarily intended for power users and developers. ### Node Services @@ -15,7 +15,8 @@ Services run on a Federated Node include some or all of the following: * **counterparty-server**: `counterparty-lib` + `counterparty-cli`. Implements support for the core Counterparty protocol, via a provided REST API and command line interface. * **counterblock**: Provides additional services (required by `counterwallet` and potentially other services) beyond those offered in the API provided by `counterparty-server`. It features a full-fledged JSON RPC-based API, and has an extensible architecture to support custom plugins. * **counterwallet**: The reference Web wallet for Counterparty. This is a collection of HTML, CSS and javascript resources, served by `nginx`. -* **bitcoind**: Reference Bitcoin implementation, used by `counterparty-server` to sync to the Bitcoin blockchain. We use the [`addrindex`](https://github.com/btcdrak/bitcoin/tree/addrindex-0.12) branch, as it has additional functionality Counterparty requires. +* **bitcoind**: Reference Bitcoin implementation, used by `counterparty-server` to sync to the Bitcoin blockchain. +* **indexd-server**: Bitcoin addres index service. Maintains an updated database of UTXOs for usage in the counterparty services. * **armory_utxsvr**: A service used by ``counterblock`` with Counterwallet to support [Offline Armory transactions](http://counterparty.io/docs/create_armory_address/). This service requires Armory itself, which is automatically installed as part of the Federated Node setup procedure. * **nginx**: Reverse proxies `counterwallet` access. Not used with `counterparty-server`-only or `counterblock`-only nodes. * **mongodb and redis**: Used by `counterblock`. @@ -27,8 +28,8 @@ Please note that Federated Node should not be installed on a system which alread - **Memory**: 4GB RAM (`bitcoind`, `counterparty-server` only), 8GB+ RAM (full stack) - **Disk space:** The exact disk space required will be dependent on what services are run on the node: - - For ``bitcoin`` databases: **~120GB** (mainnet), **~10GB** (testnet) - - For ``counterparty`` and ``counterblock`` databases: **~1.5GB** each + - For ``bitcoin`` databases: **~250GB** (mainnet), **~29GB** (testnet) + - For ``counterparty`` and ``counterblock`` databases: **~4.2GB** each - For ``armory_utxsvr``: **~30GB** (mainnet), **~3GB** (testnet) - **OS:** *Please note that Ubuntu Linux is the recommended OS at this time, as most of our testing is performed on it. Windows and OS X support is considered in BETA.* - **Linux**: We recommend Ubuntu 16.04 64-bit, but other, modern versions of Linux should work, as long as they support the newest released version of Docker @@ -42,10 +43,10 @@ Please note that Federated Node should not be installed on a system which alread **NOTE**: Installation on Windows is still in *BETA* state, and we cannot promise a fully-working environment. [Please report](https://github.com/CounterpartyXCP/federatednode/issues) any bugs you find. * **Python 3.5.x**: [Download and install](https://www.python.org/downloads/) the latest Python 3.5.x release. Make sure you check the box "Add Python 3.5 to PATH" on the first page. (If you get an error during installation, make sure your windows system is fully updated via Windows Update.) -* **Docker**: If using Windows 10, we recommend to [install Docker for Windows](https://docs.docker.com/engine/installation/windows/). For all other versions of Windows, [install Docker Toolbox](https://docs.docker.com/toolbox/toolbox_install_windows/). +* **Docker**: If using Windows 10, we recommend to [install Docker for Windows](https://docs.docker.com/engine/installation/windows/). For all other versions of Windows, [install Docker Toolbox](https://docs.docker.com/toolbox/toolbox_install_windows/). * **Git**: Make sure `git` is installed. If not, install it from [here](https://git-scm.com/download/win) (note that if using Docker Toolbox, it will install it by default). -**If using Docker for Windows**: +**If using Docker for Windows**: * After installing Docker for Windows, launch the "Docker" application and allow it to set itself up (a reboot may be required). * Next, you will need to enable access to your host hard drive so that some of the shared volumes work properly. To do this, right click on the Docker Whale icon in your system tray. Then go to "Docker Settings" and then "Shared Drives". Turn on access to the drive on which the `federatednode` folder will reside (most likely your "C" drive). @@ -97,7 +98,7 @@ exit # leave root shell ## Installation -On Linux and OS X, install as a non-root sudo-er from home directory. +On Linux and OS X, install as a non-root sudo-er from home directory. **Clone and check out the code** @@ -150,9 +151,9 @@ fednode install base master # install a full configuration for the develop branch fednode install full develop ``` -In some cases (slow host, limited bandwidth), you may experience a failure to install due to download timeouts which happen because of . In that case consider changing Docker's `max-concurrent-downloads` value to 1 or 2 from default 3. To do that create a custom `/etc/docker/daemon.json` daemon options file and restart Docker service. +In some cases (slow host, limited bandwidth), you may experience a failure to install due to download timeouts which happen because of network unstability. In that case consider changing Docker's `max-concurrent-downloads` value to 1 or 2 from default 3. To do that create a custom `/etc/docker/daemon.json` daemon options file and restart Docker service. -As mentioned earlier, the install script may stop if ports used by Federated Node services are used by other applications. While it is not recommended to run Federated Node alongside production services, small changes can make the evaluation of Federated Node easier. For example you may change ports used by existing applications (or disable said applications) or run Federated Node inside of a virtual machine. +As mentioned earlier, the install script may stop if ports used by Federated Node services are used by other applications. While it is not recommended to run Federated Node alongside production services, small changes can make the evaluation of Federated Node easier. For example you may change ports used by existing applications (or disable said applications) or run Federated Node inside of a virtual machine. For example, the original mongodb can be reconfigured to listen on port 28018 and counterblock's mongodb can use the default port 27017. The Federated Node install script makes it possible to specify the interface used by its mongodb container (example below), but it currently does not have the ability to do this for other services or get around port conflicts. @@ -167,9 +168,9 @@ After installation, the services will be automatically started. To check the sta fednode ps ``` -If you have existing instances of Bitcoin Core (either mainnet or testnet), at this point you could stop all services listed in `fednode ps` output, change configuration files (of counterparty and counterblock, for example) and point them to your existing Bitcoin Core. Configuration files can be found in various service directories located under federatednode/config. +If you have existing instances of Bitcoin Core (either mainnet or testnet), at this point you could stop all services listed in `fednode ps` output, change configuration files (of counterparty and counterblock, for example) and point them to your existing Bitcoin Core. Configuration files can be found in various service directories located under federatednode/config. -Once the containers are installed and running, keep in mind that it will take some time for `bitcoind` to download the blockchain data. Once this is done, `counterparty-server` will fully start and sync, followed by `counterblock` (if in use). At that point, the server will be usable. +Once the containers are installed and running, keep in mind that it will take some time for `bitcoind` to download the blockchain data. Once this is done, `counterparty-server` will fully start and sync, followed by `counterblock` (if in use). At that point, the server will be usable. You may check the sync status by tailing the appropriate service logs, e.g. for Bitcoin Core and Counterparty server on mainnet: ``` @@ -228,11 +229,13 @@ Configuration files for the `bitcoin`, `counterparty` and `counterblock` service * `bitcoin`: See `federatednode/config/bitcoin/bitcoin.conf` * `bitcoin-testnet`: See `federatednode/config/bitcoin/bitcoin.testnet.conf` +* `indexd`: See `federatednode/config/indexd/indexd.env.default` +* `indexd-testnet`: See `federatednode/config/indexd/indexd.testnet.env.default` * `counterparty`: See `federatednode/config/counterparty/server.conf` * `counterparty-testnet`: See `federatednode/config/counterparty/server.testnet.conf` * `counterblock`: See `federatednode/config/counterblock/server.conf` * `counterblock-testnet`: See `federatednode/config/counterblock/server.testnet.conf` -* `redis`: shared service used for both mainnet and testnet +* `redis`: shared service used for both mainnet and testnet * `mongodb`: shared service used for both mainnet and testnet Remember: once done editing a configuration file, you must `restart` the corresponding service. Also, please don't change port or usernames/passwords if the configuration files unless you know what you are doing (as the services are coded to work together smoothly with specific values). @@ -244,6 +247,7 @@ For example, a user with base setup (Bitcoin Core & Counterparty Server) could m The various services use [Docker named volumes](https://docs.docker.com/engine/tutorials/dockervolumes/) to store data that is meant to be persistent: * `bitcoin` and `bitcoin-testnet`: Stores blockchain data in the `federatednode_bitcoin-data` volume +* `indexd` and `indexd-testnet`: Stores index data in the `federatednode_indexd-data` volume * `counterparty` and `counterparty-testnet`: Stores Counterparty databases in the `federatednode_counterparty-data` volume * `counterblock` and `counterblock-testnet`: Stores Counterblock asset info (images), etc in the `federatednode_counterblock-data` volume * `mongodb`: Stores the databases for `counterblock` and `counterblock-testnet` in the `federatednode_mongodb-data` volume @@ -267,10 +271,12 @@ fednode logs * `counterparty` (`counterparty-server` mainnet) * `counterblock` (`counterblock` mainnet) * `bitcoin` (`bitcoin` mainnet) +* `indexd` (`indexd` mainnet) * `armory_utxsvr` (`armory_utxsvr` mainnet) * `counterparty-testnet` * `counterblock-testnet` * `bitcoin-testnet` +* `indexd-testnet` * `armory_utxsvr-testnet` * `counterwallet` @@ -383,7 +389,7 @@ Instructions for doing that are detailed in the *Counterwallet Configuration Fil ### Getting a SSL Certificate -By default, the system is set up to use a self-signed SSL certificate. If you are hosting your services for others, +By default, the system is set up to use a self-signed SSL certificate. If you are hosting your services for others, you should get your own SSL certificate from your DNS registrar so that your users don't see a certificate warning when they visit your site. @@ -395,7 +401,7 @@ Once you have that certificate, create a nginx-compatible ``.pem`` file. Copy th To monitor the server, you can use a 3rd-party service such as [Pingdom](http://www.pingdom.com) or [StatusCake](http://statuscake.com). The federated node allows these (and any other monitoring service) to query the basic status of the Federated Node via making a HTTP GET call to one of the following URLs: -* ``/_api/`` (for mainnet) +* ``/_api/`` (for mainnet) * ``/_t_api/`` (for testnet) If all services are up, a HTTP 200 response with the following data will be returned: @@ -403,9 +409,9 @@ If all services are up, a HTTP 200 response with the following data will be retu {"counterparty-server": "OK", "counterblock_ver": "1.3.0", "counterparty-server_ver": "9.31.0", "counterblock": "OK", "counterblock_check_elapsed": 0.0039348602294921875, "counterparty-server_last_block": { "block_hash": "0000000000000000313c4708da5b676f453b41d566832f80809bc4cb141ab2cd", "block_index": 311234, - "block_time": 1405638212}, "local_online_users": 7, "counterparty-server_check_elapsed": 0.003687143325805664, + "block_time": 1405638212}, "local_online_users": 7, "counterparty-server_check_elapsed": 0.003687143325805664, "counterblock_error": null, "counterparty-server_last_message_index": 91865} - + Note the ``"counterparty-server": "OK"`` and ``"counterblock": "OK"`` items. If all services but ``counterparty-server`` are up, a HTTP 500 response with ``"counterparty-server": "NOT OK"``, for instance. @@ -424,7 +430,7 @@ sudo docker exec -it federatednode_counterwallet_1 vim /counterwallet/counterwal This file will contain a valid JSON-formatted object, containing an a number of possible configuration properties. For example:: - { + { "servers": [ "counterblock1.mydomain.com", "counterblock2.mydomain.com", "counterblock3.mydomain.com" ], "forceTestnet": true, "googleAnalyticsUA": "UA-48454783-2",