├── static ├── .nojekyll ├── CNAME └── img │ ├── xcp.png │ ├── trade1.png │ ├── trade2.png │ ├── trade3.png │ ├── trade4.png │ ├── trade5.png │ ├── trade6.png │ ├── trade7.png │ ├── trade8.png │ ├── trade9.png │ ├── favicon.ico │ ├── sigmoid.png │ ├── trade10.png │ ├── trade11.png │ ├── trade12.png │ ├── trade13.png │ ├── trade14.png │ ├── trade15.png │ ├── broadcast1.png │ ├── broadcast2.png │ ├── broadcast3.png │ ├── broadcast4.png │ ├── components.png │ ├── docusaurus.png │ ├── create_token1.png │ ├── create_token2.png │ ├── create_token3.png │ ├── distribution1.png │ ├── distribution2.png │ ├── distribution3.png │ ├── distribution4.png │ ├── show_qr_code1.png │ ├── show_qr_code2.png │ ├── get_token_info1.png │ ├── get_token_info2.png │ ├── get_token_info3.png │ ├── get_token_info4.png │ ├── create_addresses1.png │ ├── create_addresses2.png │ ├── create_addresses3.png │ ├── create_addresses4.png │ ├── create_addresses5.png │ ├── create_addresses6.png │ ├── create_addresses7.png │ ├── getting_started_cw1.png │ ├── getting_started_cw2.png │ ├── getting_started_cw3.png │ ├── getting_started_cw4.png │ ├── getting_started_cw5.png │ ├── getting_started_cw6.png │ ├── getting_started_cw7.png │ ├── getting_started_cw8.png │ ├── getting_started_cw9.png │ ├── support │ ├── support_1.png │ ├── support_2.png │ ├── support_3.png │ ├── support_4.png │ ├── support_5.png │ ├── support_6.png │ └── support_7.png │ ├── voting_with_tokens1.png │ ├── getting_started_cw10.png │ ├── getting_started_cw11.png │ ├── getting_started_cw12.png │ ├── platform_architecture.png │ ├── change_token_settings1.png │ ├── change_token_settings2.png │ ├── change_token_settings3.png │ ├── change_token_settings4.png │ ├── change_token_settings5.png │ ├── counterparty_features1.png │ ├── counterparty_features2.png │ ├── create_armory_address1.png │ ├── create_armory_address10.png │ ├── create_armory_address11.png │ ├── create_armory_address12.png │ ├── create_armory_address13.png │ ├── create_armory_address14.png │ ├── create_armory_address2.png │ ├── create_armory_address3.png │ ├── create_armory_address4.png │ ├── create_armory_address5.png │ ├── create_armory_address6.png │ ├── create_armory_address7.png │ ├── create_armory_address8.png │ ├── create_armory_address9.png │ ├── create_support_ticket1.png │ ├── create_support_ticket2.png │ ├── create_support_ticket3.png │ ├── create_support_ticket4.png │ ├── counterparty-dex-select-sell-offer.jpg │ ├── counterparty-dex-find-asset-to-buy1.jpg │ ├── counterparty-dex-populate-buy-order.jpg │ ├── logo.svg │ └── undraw_docusaurus_tree.svg ├── babel.config.js ├── src ├── pages │ └── index.js ├── theme │ └── NotFound │ │ ├── index.js │ │ └── Content │ │ └── index.js ├── css │ └── custom.css └── redirections.js ├── docs ├── advanced │ ├── api-v2 │ │ ├── node-api.md │ │ └── v1-to-v2.md │ ├── how-to │ │ ├── gunicorn-server.md │ │ ├── sentry-integration.md │ │ ├── regtest-node.md │ │ └── atomic-swap.md │ ├── specifications │ │ ├── free-subassets.md │ │ ├── allow-subassets-on-numerics.md │ │ ├── lockable-issuance-descriptions.md │ │ ├── dispenser-must-be-created-by-source.md │ │ ├── utxo-support.md │ │ ├── gas-system.md │ │ ├── enable-dispense-tx.md │ │ └── fairminter.md │ ├── command-line-interface │ │ ├── multisig.md │ │ ├── sending-bulk.md │ │ └── usage.md │ ├── exchange-integration.md │ ├── api-v1 │ │ ├── api-v1-changelog.md │ │ └── api-v1-overview.md │ ├── bounties.md │ └── protocol.md └── basics │ ├── what-is-xcp.md │ ├── getting-started.md │ ├── usage.md │ ├── what-is-counterparty.md │ ├── assets │ ├── enhanced-asset.md │ ├── counterparty-assets.md │ └── enhanced-feed.md │ ├── manual-installation.md │ └── faq.md ├── package.json ├── README.md ├── LICENSE ├── sidebars.js ├── .gitignore └── docusaurus.config.js /static/.nojekyll: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /static/CNAME: -------------------------------------------------------------------------------- 1 | docs.counterparty.io -------------------------------------------------------------------------------- /static/img/xcp.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/xcp.png -------------------------------------------------------------------------------- /static/img/trade1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade1.png -------------------------------------------------------------------------------- /static/img/trade2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade2.png -------------------------------------------------------------------------------- /static/img/trade3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade3.png -------------------------------------------------------------------------------- /static/img/trade4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade4.png -------------------------------------------------------------------------------- /static/img/trade5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade5.png -------------------------------------------------------------------------------- /static/img/trade6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade6.png -------------------------------------------------------------------------------- /static/img/trade7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade7.png -------------------------------------------------------------------------------- /static/img/trade8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade8.png -------------------------------------------------------------------------------- /static/img/trade9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade9.png -------------------------------------------------------------------------------- /static/img/favicon.ico: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/favicon.ico -------------------------------------------------------------------------------- /static/img/sigmoid.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/sigmoid.png -------------------------------------------------------------------------------- /static/img/trade10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade10.png -------------------------------------------------------------------------------- /static/img/trade11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade11.png -------------------------------------------------------------------------------- /static/img/trade12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade12.png -------------------------------------------------------------------------------- /static/img/trade13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade13.png -------------------------------------------------------------------------------- /static/img/trade14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade14.png -------------------------------------------------------------------------------- /static/img/trade15.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/trade15.png -------------------------------------------------------------------------------- /babel.config.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | presets: [require.resolve('@docusaurus/core/lib/babel/preset')], 3 | }; 4 | -------------------------------------------------------------------------------- /static/img/broadcast1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/broadcast1.png -------------------------------------------------------------------------------- /static/img/broadcast2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/broadcast2.png -------------------------------------------------------------------------------- /static/img/broadcast3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/broadcast3.png -------------------------------------------------------------------------------- /static/img/broadcast4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/broadcast4.png -------------------------------------------------------------------------------- /static/img/components.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/components.png -------------------------------------------------------------------------------- /static/img/docusaurus.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/docusaurus.png -------------------------------------------------------------------------------- /static/img/create_token1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_token1.png -------------------------------------------------------------------------------- /static/img/create_token2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_token2.png -------------------------------------------------------------------------------- /static/img/create_token3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_token3.png -------------------------------------------------------------------------------- /static/img/distribution1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/distribution1.png -------------------------------------------------------------------------------- /static/img/distribution2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/distribution2.png -------------------------------------------------------------------------------- /static/img/distribution3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/distribution3.png -------------------------------------------------------------------------------- /static/img/distribution4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/distribution4.png -------------------------------------------------------------------------------- /static/img/show_qr_code1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/show_qr_code1.png -------------------------------------------------------------------------------- /static/img/show_qr_code2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/show_qr_code2.png -------------------------------------------------------------------------------- /static/img/get_token_info1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/get_token_info1.png -------------------------------------------------------------------------------- /static/img/get_token_info2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/get_token_info2.png -------------------------------------------------------------------------------- /static/img/get_token_info3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/get_token_info3.png -------------------------------------------------------------------------------- /static/img/get_token_info4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/get_token_info4.png -------------------------------------------------------------------------------- /static/img/create_addresses1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_addresses1.png -------------------------------------------------------------------------------- /static/img/create_addresses2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_addresses2.png -------------------------------------------------------------------------------- /static/img/create_addresses3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_addresses3.png -------------------------------------------------------------------------------- /static/img/create_addresses4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_addresses4.png -------------------------------------------------------------------------------- /static/img/create_addresses5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_addresses5.png -------------------------------------------------------------------------------- /static/img/create_addresses6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_addresses6.png -------------------------------------------------------------------------------- /static/img/create_addresses7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_addresses7.png -------------------------------------------------------------------------------- /static/img/getting_started_cw1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw1.png -------------------------------------------------------------------------------- /static/img/getting_started_cw2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw2.png -------------------------------------------------------------------------------- /static/img/getting_started_cw3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw3.png -------------------------------------------------------------------------------- /static/img/getting_started_cw4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw4.png -------------------------------------------------------------------------------- /static/img/getting_started_cw5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw5.png -------------------------------------------------------------------------------- /static/img/getting_started_cw6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw6.png -------------------------------------------------------------------------------- /static/img/getting_started_cw7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw7.png -------------------------------------------------------------------------------- /static/img/getting_started_cw8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw8.png -------------------------------------------------------------------------------- /static/img/getting_started_cw9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw9.png -------------------------------------------------------------------------------- /static/img/support/support_1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/support/support_1.png -------------------------------------------------------------------------------- /static/img/support/support_2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/support/support_2.png -------------------------------------------------------------------------------- /static/img/support/support_3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/support/support_3.png -------------------------------------------------------------------------------- /static/img/support/support_4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/support/support_4.png -------------------------------------------------------------------------------- /static/img/support/support_5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/support/support_5.png -------------------------------------------------------------------------------- /static/img/support/support_6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/support/support_6.png -------------------------------------------------------------------------------- /static/img/support/support_7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/support/support_7.png -------------------------------------------------------------------------------- /static/img/voting_with_tokens1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/voting_with_tokens1.png -------------------------------------------------------------------------------- /static/img/getting_started_cw10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw10.png -------------------------------------------------------------------------------- /static/img/getting_started_cw11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw11.png -------------------------------------------------------------------------------- /static/img/getting_started_cw12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/getting_started_cw12.png -------------------------------------------------------------------------------- /static/img/platform_architecture.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/platform_architecture.png -------------------------------------------------------------------------------- /static/img/change_token_settings1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/change_token_settings1.png -------------------------------------------------------------------------------- /static/img/change_token_settings2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/change_token_settings2.png -------------------------------------------------------------------------------- /static/img/change_token_settings3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/change_token_settings3.png -------------------------------------------------------------------------------- /static/img/change_token_settings4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/change_token_settings4.png -------------------------------------------------------------------------------- /static/img/change_token_settings5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/change_token_settings5.png -------------------------------------------------------------------------------- /static/img/counterparty_features1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/counterparty_features1.png -------------------------------------------------------------------------------- /static/img/counterparty_features2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/counterparty_features2.png -------------------------------------------------------------------------------- /static/img/create_armory_address1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address1.png -------------------------------------------------------------------------------- /static/img/create_armory_address10.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address10.png -------------------------------------------------------------------------------- /static/img/create_armory_address11.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address11.png -------------------------------------------------------------------------------- /static/img/create_armory_address12.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address12.png -------------------------------------------------------------------------------- /static/img/create_armory_address13.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address13.png -------------------------------------------------------------------------------- /static/img/create_armory_address14.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address14.png -------------------------------------------------------------------------------- /static/img/create_armory_address2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address2.png -------------------------------------------------------------------------------- /static/img/create_armory_address3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address3.png -------------------------------------------------------------------------------- /static/img/create_armory_address4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address4.png -------------------------------------------------------------------------------- /static/img/create_armory_address5.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address5.png -------------------------------------------------------------------------------- /static/img/create_armory_address6.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address6.png -------------------------------------------------------------------------------- /static/img/create_armory_address7.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address7.png -------------------------------------------------------------------------------- /static/img/create_armory_address8.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address8.png -------------------------------------------------------------------------------- /static/img/create_armory_address9.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_armory_address9.png -------------------------------------------------------------------------------- /static/img/create_support_ticket1.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_support_ticket1.png -------------------------------------------------------------------------------- /static/img/create_support_ticket2.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_support_ticket2.png -------------------------------------------------------------------------------- /static/img/create_support_ticket3.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_support_ticket3.png -------------------------------------------------------------------------------- /static/img/create_support_ticket4.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/create_support_ticket4.png -------------------------------------------------------------------------------- /static/img/counterparty-dex-select-sell-offer.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/counterparty-dex-select-sell-offer.jpg -------------------------------------------------------------------------------- /static/img/counterparty-dex-find-asset-to-buy1.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/counterparty-dex-find-asset-to-buy1.jpg -------------------------------------------------------------------------------- /static/img/counterparty-dex-populate-buy-order.jpg: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/Hardcoding-1992/Documentation/HEAD/static/img/counterparty-dex-populate-buy-order.jpg -------------------------------------------------------------------------------- /src/pages/index.js: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | 3 | import { RedirectedURL, HOME_PAGE } from '../redirections'; 4 | 5 | export default function Home() { 6 | const content = "0;url=" + HOME_PAGE; 7 | return ( 8 | 9 | ) 10 | } -------------------------------------------------------------------------------- /docs/advanced/api-v2/node-api.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API v2 3 | --- 4 | 5 | # Counterparty Core API 6 | 7 | The Counterparty Core API is the recommended way to query the state of a Counterparty node. All other methods have no official support. 8 | 9 | Please see [Apiary](https://counterpartycore.docs.apiary.io/) for interactive documentation. 10 | -------------------------------------------------------------------------------- /docs/advanced/how-to/gunicorn-server.md: -------------------------------------------------------------------------------- 1 | # Use Gunicorn WSGI server 2 | 3 | By default, `counterpart-server` uses the WSGI Waitress server. This server is production quality, uses only one processor and is multi-threaded. 4 | 5 | For servers with heavy traffic it is possible to use Gunicorn with the flag `--wsgi-server=gunicorn`. Gunicorn uses a different processors for each worker but can be problematic on some platforms (see https://docs.python.org/3/library/os.html#os.fork). -------------------------------------------------------------------------------- /src/theme/NotFound/index.js: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import {translate} from '@docusaurus/Translate'; 3 | import {PageMetadata} from '@docusaurus/theme-common'; 4 | import Layout from '@theme/Layout'; 5 | import NotFoundContent from '@theme/NotFound/Content'; 6 | export default function Index() { 7 | const title = translate({ 8 | id: 'theme.NotFound.title', 9 | message: 'Page Not Found', 10 | }); 11 | return ( 12 | <> 13 | 14 | 15 | 16 | 17 | 18 | ); 19 | } 20 | -------------------------------------------------------------------------------- /docs/advanced/how-to/sentry-integration.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Sentry Integration 3 | --- 4 | 5 | Counterparty Core allows for easy integration with [Sentry](http://sentry.io) for error reporting and performance monitoring. This feature is **opt-in** for each node operator. To enable the integration, simply export the [( Data Source Name )](https://docs.sentry.io/product/sentry-basics/concepts/dsn-explainer/) from your Sentry project as an environment variable before starting your node: 6 | 7 | ```bash 8 | export SENTRY_DSN= 9 | ``` 10 | 11 | You can find additional configuration options [here](https://docs.sentry.io/platforms/python/configuration/) (e.g. `SENTRY_ENVIRONMENT` and `SENTRY_RELEASE`). 12 | -------------------------------------------------------------------------------- /docs/advanced/specifications/free-subassets.md: -------------------------------------------------------------------------------- 1 | # Eliminate XCP for Subasset Issuances 2 | 3 | ## Motivation 4 | 5 | XCP fees for issuances are principally an *anti-squatting* mechanism (since the BTC fee is sufficient in this case to prevent true SPAM). For subassets, which are namespaced by the parent asset, there’s no need to limit the number of issuances in any way. 6 | 7 | ## Design 8 | 9 | Fees are calculated in the `issuances.validate()` function.[[1](https://github.com/CounterpartyXCP/counterparty-core/blob/master/counterparty-core/counterpartycore/lib/messages/issuance.py#L279)] A protocol change `free_subassets` will be added in the `protocol_changes.json` file. From this block on, the function `issuances.validate()` will return `fee=0` for all subasset issuances. 10 | 11 | ## API Changes 12 | 13 | *No API changes.* 14 | 15 | ## Database Changes 16 | 17 | *No database changes*. -------------------------------------------------------------------------------- /docs/advanced/specifications/allow-subassets-on-numerics.md: -------------------------------------------------------------------------------- 1 | # Subassets on Numeric Assets 2 | 3 | ## Motivation 4 | 5 | There is no particular reason to disallow subassets on numeric assets and there is a strong community demand to be able to do so (see for example https://github.com/mikeinspace/Glyphs/blob/main/README.md) 6 | 7 | ## Design 8 | 9 | Currently the `validate_subasset_parent_name` function checks that the parent asset is not numeric: https://github.com/CounterpartyXCP/counterparty-core/blob/master/counterparty-core/counterpartycore/lib/util.py#L238 This is the only place where this check is performed. 10 | 11 | A protocol change `allow_subassets_on_numerics` will be added in the `protocol_changes.json` file. From this block on, the verification will be removed from the function `validate_subasset_parent_name`. 12 | 13 | ## API Changes 14 | 15 | No API changes. 16 | 17 | ## Database Changes 18 | 19 | No database changes. -------------------------------------------------------------------------------- /src/css/custom.css: -------------------------------------------------------------------------------- 1 | /* stylelint-disable docusaurus/copyright-header */ 2 | /** 3 | * Any CSS included here will be global. The classic template 4 | * bundles Infima by default. Infima is a CSS framework designed to 5 | * work well for content-centric websites. 6 | */ 7 | 8 | /* You can override the default Infima variables here. */ 9 | :root { 10 | --ifm-color-primary: #ec1550; 11 | --ifm-color-primary-dark: rgb(33, 175, 144); 12 | --ifm-color-primary-darker: rgb(31, 165, 136); 13 | --ifm-color-primary-darkest: rgb(26, 136, 112); 14 | --ifm-color-primary-light: rgb(70, 203, 174); 15 | --ifm-color-primary-lighter: rgb(102, 212, 189); 16 | --ifm-color-primary-lightest: rgb(146, 224, 208); 17 | --ifm-code-font-size: 95%; 18 | } 19 | 20 | .docusaurus-highlight-code-line { 21 | background-color: rgb(72, 77, 91); 22 | display: block; 23 | margin: 0 calc(-1 * var(--ifm-pre-padding)); 24 | padding: 0 var(--ifm-pre-padding); 25 | } 26 | -------------------------------------------------------------------------------- /package.json: -------------------------------------------------------------------------------- 1 | { 2 | "name": "xcpdoc", 3 | "version": "1.0.0", 4 | "private": true, 5 | "scripts": { 6 | "docusaurus": "docusaurus", 7 | "start": "docusaurus start", 8 | "build": "docusaurus build", 9 | "swizzle": "docusaurus swizzle", 10 | "deploy": "docusaurus deploy", 11 | "clear": "docusaurus clear", 12 | "serve": "docusaurus serve", 13 | "write-translations": "docusaurus write-translations", 14 | "write-heading-ids": "docusaurus write-heading-ids" 15 | }, 16 | "dependencies": { 17 | "@docusaurus/core": "3.1.0", 18 | "@docusaurus/preset-classic": "3.1.0", 19 | "@mdx-js/react": "^3.0.1", 20 | "docusaurus": "^1.14.7", 21 | "prism-react-renderer": "^2.3.1", 22 | "react": "^18.3.1", 23 | "react-dom": "^18.3.1" 24 | }, 25 | "browserslist": { 26 | "production": [ 27 | ">0.5%", 28 | "not dead", 29 | "not op_mini all" 30 | ], 31 | "development": [ 32 | "last 1 chrome version", 33 | "last 1 firefox version", 34 | "last 1 safari version" 35 | ] 36 | } 37 | } 38 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Official Documentation of the Counterparty Project 2 | 3 | The markdown documentation in this repository is rerendered hourly and made available at the [Counterparty documentation site](http://counterparty.io/docs/). 4 | 5 | # Website 6 | 7 | This website is built using [Docusaurus 2](https://v2.docusaurus.io/), a modern static website generator. 8 | 9 | ## Installation 10 | 11 | ```console 12 | yarn install 13 | ``` 14 | 15 | ## Local Development 16 | 17 | ```console 18 | yarn start 19 | ``` 20 | 21 | This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server. 22 | 23 | ## Build 24 | 25 | ```console 26 | yarn build 27 | ``` 28 | 29 | This command generates static content into the `build` directory and can be served using any static contents hosting service. 30 | 31 | ## Deployment 32 | 33 | ```console 34 | GIT_USER= USE_SSH=true yarn deploy 35 | ``` 36 | 37 | If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the `gh-pages` branch. 38 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | MIT License 2 | 3 | Copyright (c) 2016-2021 Counterparty 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /docs/advanced/command-line-interface/multisig.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Using multisig with counterparty-server 3 | --- 4 | 5 | "Bare Multisig" (i.e. not P2SH) is supported with Counterparty. This document shows you how to use it with `counterparty-server` on testnet. 6 | 7 | ### Making a Multisig Tx 8 | 9 | An example testnet multi‐sig source transaction is tx hash _e06d22276699de6ed1c5322133b0968114067ce833120bb9126182a1ad19de83_ 10 | 11 | Here's how you can make a multisig transaction: 12 | 13 | ``` 14 | counterparty-client --unconfirmed --testnet --database-file=test.db send --source=1_mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc_mfzSPkV7kAYma5oxZ37pHkw9qtwAEQx8Wy_2 15 | --destination=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc --quantity=.1337 --asset=XCP 16 | ``` 17 | 18 | So that's a 1-of-2 multisig address that the 0.1337 XCP would be sent to.  19 | 20 | The multisig addresses are represented as such a string as `{m}_{address}_{address}_{address}_{n}`, where the addresses (pubkeyhashes) are sorted alphabetically/numerically.  21 | 22 | 1-of-2, 2-of-2, 1-of-3, 2-of-3 and 3-of-3 are supported at the moment.  23 | 24 | _**NOTE:** Each address in a multisig source must have already made **at least one non-multisig transaction** in the blockchain, for counterpartyd to be able to retrieve its pubkey from the blockchain._ 25 | 26 | You can sign transactions with `bitcoind signrawtransaction`; broadcast with `sendrawtransaction`. 27 | -------------------------------------------------------------------------------- /src/theme/NotFound/Content/index.js: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import clsx from 'clsx'; 3 | import Translate from '@docusaurus/Translate'; 4 | import Heading from '@theme/Heading'; 5 | 6 | import { RedirectedURL } from '../../../redirections'; 7 | 8 | export default function NotFoundContent({className}) { 9 | return ( 10 | 11 | 12 |
13 |
14 |
15 | 16 | 19 | Page Not Found. 20 | 21 | 22 |

23 | 26 | We could not find what you were looking for. 27 | 28 |

29 |

30 | 33 | Please contact the owner of the site that linked you to the 34 | original URL and let them know their link is broken. 35 | 36 |

37 |
38 |
39 |
40 | 41 | 42 | ); 43 | } 44 | -------------------------------------------------------------------------------- /docs/advanced/specifications/lockable-issuance-descriptions.md: -------------------------------------------------------------------------------- 1 | # Be Able to Lock Descriptions 2 | 3 | ## Motivation 4 | 5 | From a collectors point of view, it is often important to be sure that all characteristics of an asset are immutable to establish the permanency of the object being traded. For this reason there is a strong demand from the community to add the possibility to lock the description of an asset. This feature is easy to implement, without any side effects, and without any consequences for existing assets. 6 | 7 | ## Design 8 | 9 | To lock an asset, there are currently two possibilities: perform an `issuance` with the description equal to "lock" or directly pass the parameter `lock=True`. When an Asset is locked, however, it is still possible to modify the description. 10 | 11 | 1. Since there are two ways to lock an asset, the idea is to now use one of the two methods to specifically lock the description: 12 | 1. If `description=lock`, it means that the description should be locked. 13 | 2. If `lock=True`, we lock only the quantity (as it is done today). 14 | 2. A `description_locked` field will be added to the `issuances` table. 15 | 3. The `issuances.validate` function will be modified to check that if `description_locked` is equal to `True`, the description must be necessarily equal to `None`. 16 | 4. A protocol change `lockable_description` will be added in the `protocol_changes.json` file. 17 | 18 | ## API Changes 19 | 20 | No API changes, except for the documentation to indicate that `description=lock` causes description only to be locked. 21 | 22 | ## Database Changes 23 | 24 | A `description_locked` field will be added to the `issuances` table. -------------------------------------------------------------------------------- /docs/basics/what-is-xcp.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: What is XCP? 3 | --- 4 | 5 | XCP is the native token of Counterparty. It is used in all cases where the Bitcoin token is not capable of acting as the working currency, either as a denominational unit or for paying network fees. 6 | 7 | Because Bitcoin is not “aware” of the Counterparty protocol, BTC cannot be used except as a minimal anti-SPAM mechanism based on the overall size of the Bitcoin transactions that contain Counterparty data. 8 | 9 | 10 | ### Do all Counterparty transactions require the use of XCP? 11 | 12 | There are a few Counterparty transactions that do not require the use of the XCP token due to their simplicity, most notably straightforward asset transfers and issuances of numeric assets (Counterparty assets without a human-readable identifier), which create a low computational burden for Counterparty nodes. 13 | 14 | 15 | ### How was XCP created? 16 | 17 | The total supply of XCP was created in a process called 'proof-of-burn' that was active between January 2nd and February 3rd of 2014 (5,000 Bitcoin blocks). During this period, anyone was able to destroy bitcoins by sending them an **unspendable Bitcoin address** (`1CounterpartyXXXXXXXXXXXXXXXUWLpVr`), and this destruction triggered the creation of a corresponding quantity of XCP automatically. Burning each 1 BTC triggered the creation of between 1,000 and 1,500 XCP, with more being rewarded the earlier the burn took place (the ratio decreasing linearly), with each address being limited to 1 BTC burned in total. 18 | 19 | The proof-of-burn process created an equal opportunity for all potential Counterparty users to acquire XCP, with no centralization or trust at all. This method is relatively rare in the crypto space because it does not provide the founders with starting capital (as with a “pre-mine”). Proof-of-burn has the following advantages, however: 20 | 21 | * It avoids issues with regulatory uncertainty and legal liability 22 | * It incentivises developers and users equally 23 | * Funds are never in the control of any third party 24 | * There is full transparency into the process 25 | -------------------------------------------------------------------------------- /docs/advanced/how-to/regtest-node.md: -------------------------------------------------------------------------------- 1 | # Test Counterparty Server on Regtest network 2 | 3 | # Prerequisites 4 | 5 | You must have the following three applications installed and available in the $PATH: 6 | 7 | * Bitcoin Core 8 | * Addrindexrs 9 | * Counteparty Core 10 | 11 | You can follow the instructions here [https://docs.counterparty.io/docs/basics/manual-installation/](https://docs.counterparty.io/docs/basics/manual-installation/) to install them. 12 | 13 | You also need to install the following Python packages using pip: 14 | 15 | ``` 16 | $ pip3 install rich sh 17 | ``` 18 | 19 | # Start the regtest node 20 | 21 | ## Method 1 22 | 23 | Use the `regtestnode.py` script: 24 | 25 | ``` 26 | $ python3 counterpartycore/test/regtest/regtestnode.py 27 | ``` 28 | 29 | This script does the following: 30 | 31 | * Starts Bitcoin Core and Addrindexrs 32 | * Generates 10 addresses containing BTC 33 | * Starts `counterparty-server` 34 | * Uses the generated addresses to burn BTC and obtain XCP. 35 | 36 | Once finished you have a node ready to use. You can check with: 37 | 38 | ``` 39 | $ curl http://localhost:24000/v2/ 40 | $ bitcoin-cli -regtest -rpcuser rpc -rpcpassword rpc -getinfo 41 | ``` 42 | 43 | 44 | ## Method 2 45 | 46 | If you need a server containing sample data you can use: 47 | 48 | ``` 49 | $ python3 counterpartycore/test/regtest/testscenarios.py serve 50 | ``` 51 | 52 | This script performs the same operations as `regtestnode.py` but also executes all scenario transactions found in `counterpartcore/test/regtest/scenarios`. 53 | 54 | # Interact with the regtest node 55 | 56 | You can use `curl` and `bitcoin-cli` or the `tools/xcpcli.py` tool. 57 | This tool is very easy to use and the help contains complete documentation for each command. It allows: 58 | 59 | * To query the API 60 | * to compose, sign and send a transaction across the network in a single command. 61 | 62 | Examples: 63 | 64 | ``` 65 | $ python3 tools/xcpcli.py -h 66 | $ python3 tools/xcpcli.py get_asset_balances -h 67 | $ python3 tools/xcpcli.py get_asset_balances --asset XCP 68 | $ python3 tools/xcpcli.py send_send -h 69 | $ python3 tools/xcpcli.py send_send --address bcrt1qusq9znaxgfn8klvw77np3tchv2g0djzf6v3zfn --asset XCP --destination mjts5dr3JwF7U5MMNWkG8dYffEAXEhayFn --quantity 10 70 | ``` 71 | -------------------------------------------------------------------------------- /docs/advanced/specifications/dispenser-must-be-created-by-source.md: -------------------------------------------------------------------------------- 1 | # Require Dispenser to be `Source` Address 2 | 3 | # Motivation 4 | 5 | For an unknown reason, it has always been possible to open a dispenser on an address that you yourself do not own. Of course, this is a major security vulnerability as it can allow anyone on the network to force other users to sell assets without their consent (potentially with major legal consequences). Generally speaking, this is just a Bad Idea(TM). 6 | 7 | A hacky workaround was implemented in November 2023 (with the unhelpful ChangeLog entry "Redefined EMPTY address to mean no XCP or BTC history”) which prevents dispensers from being opened on any address that has any XCP or BTC history. This probably resolves the security issue but [that little patch](https://github.com/CounterpartyXCP/counterparty-core/pull/1255/files#diff-446a2aa52fd57fd6379f4732ae36f794df6f0fb1585494f798f4aa3f7b94fca2R136) unintentionally (and retroactively!) made the entirety of AddrIndexRs (and its ~200GB database) consensus-critical and mandatory for parsing. AddrIndexRs is a broken, unmaintained fork of a third-party codebase that is *not* deterministic and has been the cause of a [large number of critical bugs in Counterparty](https://github.com/CounterpartyXCP/counterparty-core/issues?q=is%3Aissue+addrindexrs+label%3Abug+), not to mention the fact that it makes Counterparty deployment a total PITA. Thankfully, once this protocol change goes into effect, we can kill AddrIndexRs, per [#1764](https://github.com/CounterpartyXCP/counterparty-core/issues/1764). 8 | 9 | # Design 10 | 11 | The implementation is straightforward, quick, and already done here: https://github.com/CounterpartyXCP/counterparty-core/pull/1792. 12 | 13 | A protocol change will be added `dispenser_must_be_created_by_source` to the `protocol_changes.json` file. From this block onwards, the `compose.validate` function will verify that `source == open_address`. 14 | 15 | The only known downside to this change is that it will require a moving tokens to a wallet (e.g. a cold wallet) before using that wallet as a dispenser. (By differentiating between `source` and `origin` you can simulate Ordinals-like fair minting; but we’re going to be implementing an *actual* [Fair Minting](https://www.notion.so/Fair-Minting-17033d5385ab4a61808dbf31ea33daf9?pvs=21) contract, so no functionality will be lost.) 16 | 17 | ## API Changes 18 | 19 | *No API changes*. 20 | 21 | ## Database Changes 22 | 23 | *No database changes*. 24 | -------------------------------------------------------------------------------- /docs/basics/getting-started.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Getting Started 3 | --- 4 | 5 | ## Install Counterparty Core 6 | 7 | The simplest way to get your Counterparty node up and running is to use **Docker Compose**, which may be installed as described [here](https://docs.docker.com/compose/install/). 8 | 9 | *Note: It is required that you use Docker Compose V2, and it is suggested that you install the plugin as opposed to the standalone `docker-compose` executable*. 10 | 11 | Clone the repo: 12 | 13 | ```bash 14 | git clone git@github.com:CounterpartyXCP/counterparty-core.git 15 | cd counterparty-core 16 | ``` 17 | 18 | Next, create the directory that will be used to store Counterparty data. 19 | **To run a node you must have at least 1.5TB free.** 20 | 23 | 24 | ```bash 25 | mkdir ~/.local/share/counterparty-docker-data 26 | ``` 27 | 28 | Now we can start the program. 29 | 30 | ```bash 31 | docker compose --profile mainnet up -d 32 | ``` 33 | 34 | Use `docker compose logs` to view output from services. For example: 35 | 36 | ```bash 37 | docker compose --profile mainnet logs --tail=10 -f bitcoind 38 | docker compose --profile mainnet logs --tail=10 -f addrindexrs 39 | docker compose --profile mainnet logs --tail=10 -f counterparty-core 40 | ``` 41 | 42 | You can use the `testnet` profile to run a `testnet` node: 43 | 44 | ``` 45 | docker compose --profile testnet up -d 46 | ``` 47 | 48 | NOTES: 49 | - By default, this Docker Compose script makes use of the `bootstrap` functionality. 50 | - When working with a low-memory system, you can tell AddrIndexRs to use JSON-RPC to communicate with Bitcoin Core using the environment variable `ADDRINDEXRS_JSONRPC_IMPORT`: `ADDRINDEXRS_JSONRPC_IMPORT=true docker compose up -d` 51 | 52 | ## Upgrade Counterparty Core 53 | 54 | Download the latest version of `counterparty-core` and restart `counterparty-server` 55 | 56 | ```bash 57 | cd counterparty-core 58 | git pull 59 | docker compose stop counterparty-core 60 | docker compose --profile mainnet up -d 61 | ``` 62 | 63 | NOTE: 64 | If you were using a custom version of `docker-compose.yml` that uses the `latest` or `develop` tag, it is recommended to delete the old image before restarting the server: 65 | 66 | ```bash 67 | docker compose stop counterparty-core 68 | docker rmi counterparty/counterparty:latest 69 | docker compose --profile mainnet up -d 70 | ``` 71 | -------------------------------------------------------------------------------- /sidebars.js: -------------------------------------------------------------------------------- 1 | module.exports = { 2 | basics: [ 3 | 'basics/what-is-counterparty', 4 | 'basics/what-is-xcp', 5 | 'basics/faq', 6 | { 7 | type: 'category', 8 | label: 'Running a Counterparty Node', 9 | items: [ 10 | 'basics/getting-started', 11 | 'basics/manual-installation', 12 | 'basics/usage', 13 | ], 14 | }, 15 | { 16 | type: 'category', 17 | label: 'Assets (Tokens/NFTs)', 18 | items: [ 19 | 'basics/assets/counterparty-assets', 20 | 'basics/assets/enhanced-asset', 21 | 'basics/assets/enhanced-feed', 22 | ], 23 | }, 24 | ], 25 | advanced: [ 26 | 'advanced/protocol', 27 | { 28 | type: 'category', 29 | label: 'Command Line Interface (CLI)', 30 | items: [ 31 | 'advanced/command-line-interface/usage', 32 | 'advanced/command-line-interface/sending-bulk', 33 | 'advanced/command-line-interface/multisig' 34 | ], 35 | }, 36 | { 37 | type: 'category', 38 | label: 'Node API', 39 | items: [ 40 | 'advanced/api-v2/node-api', 41 | 'advanced/api-v2/v1-to-v2', 42 | { 43 | type: 'category', 44 | collapsible: true, 45 | collapsed: true, 46 | label: 'API v1 (Deprecated)', 47 | items: [ 48 | 'advanced/api-v1/api-v1-overview', 49 | 'advanced/api-v1/api-v1-spec', 50 | 'advanced/api-v1/api-v1-changelog' 51 | ], 52 | }, 53 | ], 54 | }, 55 | { 56 | type: 'category', 57 | label: 'How-To', 58 | items: [ 59 | 'advanced/how-to/sentry-integration', 60 | 'advanced/how-to/atomic-swap', 61 | 'advanced/how-to/regtest-node', 62 | 'advanced/how-to/gunicorn-server', 63 | ], 64 | }, 65 | { 66 | type: 'category', 67 | label: 'Specifications', 68 | items: [ 69 | 'advanced/specifications/enable-dispense-tx', 70 | 'advanced/specifications/dispenser-must-be-created-by-source', 71 | 'advanced/specifications/fairminter', 72 | 'advanced/specifications/lockable-issuance-descriptions', 73 | 'advanced/specifications/free-subassets', 74 | 'advanced/specifications/allow-subassets-on-numerics', 75 | 'advanced/specifications/utxo-support', 76 | 'advanced/specifications/gas-system', 77 | ], 78 | }, 79 | 'advanced/bounties', 80 | 'advanced/exchange-integration' 81 | ], 82 | }; 83 | -------------------------------------------------------------------------------- /src/redirections.js: -------------------------------------------------------------------------------- 1 | import React from 'react'; 2 | import BrowserOnly from '@docusaurus/BrowserOnly'; 3 | 4 | export const HOME_PAGE = '/docs/basics/what-is-counterparty'; 5 | const WALLETS_URL = 'https://www.counterparty.io/wallets'; 6 | const SUPPORT_URL = 'https://www.counterparty.io/support'; 7 | const README_URL = 'https://github.com/CounterpartyXCP/counterparty-core/blob/master/README.md' 8 | 9 | const REDIRECTIONS = { 10 | '/' : HOME_PAGE, 11 | '/docs/basics/faq/smart-contracts/': HOME_PAGE, 12 | '/docs/basics/faq/lightning-network/': HOME_PAGE, 13 | '/docs/basics/support/': SUPPORT_URL, 14 | '/docs/wallets/counterwallet': WALLETS_URL, 15 | '/docs/wallets/counterwallet-tutorials/getting-started': WALLETS_URL, 16 | '/docs/wallets/counterwallet-tutorials/create-addresses': WALLETS_URL, 17 | '/docs/wallets/counterwallet-tutorials/dex-trade': WALLETS_URL, 18 | '/docs/wallets/counterwallet-tutorials/multisig': WALLETS_URL, 19 | '/docs/wallets/counterwallet-tutorials/show-qrcode': WALLETS_URL, 20 | '/docs/wallets/counterwallet-tutorials/get-token-info': WALLETS_URL, 21 | '/docs/wallets/counterwallet-tutorials/create-token': WALLETS_URL, 22 | '/docs/wallets/counterwallet-tutorials/change-token-settings': WALLETS_URL, 23 | '/docs/wallets/counterwallet-tutorials/pay-distribution': WALLETS_URL, 24 | '/docs/wallets/counterwallet-tutorials/broadcast': WALLETS_URL, 25 | '/docs/wallets/counterwallet-tutorials/voting': WALLETS_URL, 26 | '/docs/wallets/counterwallet-tutorials/buy-sell': WALLETS_URL, 27 | '/docs/wallets/counterwallet-tutorials/create-armory-addresses': WALLETS_URL, 28 | '/docs/wallets/counterwallet-notes': WALLETS_URL, 29 | '/docs/advanced/federated-node/getting-started/': README_URL, 30 | '/docs/advanced/federated-node/pre-installation/': README_URL, 31 | '/docs/advanced/federated-node/installation/': README_URL, 32 | '/docs/advanced/federated-node/administration/': README_URL, 33 | '/docs/advanced/federated-node/counterwallet/': README_URL, 34 | '/docs/advanced/installation/bitcoin-core/': README_URL, 35 | '/docs/advanced/installation/windows/': README_URL, 36 | '/docs/develop/counterblock/api/': README_URL, 37 | '/docs/develop/counterblock/modules/': README_URL, 38 | } 39 | 40 | export function RedirectedURL(props) { 41 | 42 | return ( 43 | 44 | {() => { 45 | const url = window.location.pathname; 46 | if (url in REDIRECTIONS) { 47 | const content = "0;url=" + REDIRECTIONS[url]; 48 | return ; 49 | } 50 | return props.children; 51 | }} 52 | 53 | ); 54 | } 55 | -------------------------------------------------------------------------------- /.gitignore: -------------------------------------------------------------------------------- 1 | build/ 2 | # Logs 3 | logs 4 | *.log 5 | npm-debug.log* 6 | yarn-debug.log* 7 | yarn-error.log* 8 | lerna-debug.log* 9 | .pnpm-debug.log* 10 | 11 | # Diagnostic reports (https://nodejs.org/api/report.html) 12 | report.[0-9]*.[0-9]*.[0-9]*.[0-9]*.json 13 | 14 | # Runtime data 15 | pids 16 | *.pid 17 | *.seed 18 | *.pid.lock 19 | 20 | # Directory for instrumented libs generated by jscoverage/JSCover 21 | lib-cov 22 | 23 | # Coverage directory used by tools like istanbul 24 | coverage 25 | *.lcov 26 | 27 | # nyc test coverage 28 | .nyc_output 29 | 30 | # Grunt intermediate storage (https://gruntjs.com/creating-plugins#storing-task-files) 31 | .grunt 32 | 33 | # Bower dependency directory (https://bower.io/) 34 | bower_components 35 | 36 | # node-waf configuration 37 | .lock-wscript 38 | 39 | # Compiled binary addons (https://nodejs.org/api/addons.html) 40 | build/Release 41 | 42 | # Dependency directories 43 | node_modules/ 44 | jspm_packages/ 45 | 46 | # Snowpack dependency directory (https://snowpack.dev/) 47 | web_modules/ 48 | 49 | # TypeScript cache 50 | *.tsbuildinfo 51 | 52 | # Optional npm cache directory 53 | .npm 54 | 55 | # Optional eslint cache 56 | .eslintcache 57 | 58 | # Optional stylelint cache 59 | .stylelintcache 60 | 61 | # Microbundle cache 62 | .rpt2_cache/ 63 | .rts2_cache_cjs/ 64 | .rts2_cache_es/ 65 | .rts2_cache_umd/ 66 | 67 | # Optional REPL history 68 | .node_repl_history 69 | 70 | # Output of 'npm pack' 71 | *.tgz 72 | 73 | # Yarn Integrity file 74 | .yarn-integrity 75 | 76 | # dotenv environment variable files 77 | .env 78 | .env.development.local 79 | .env.test.local 80 | .env.production.local 81 | .env.local 82 | 83 | # parcel-bundler cache (https://parceljs.org/) 84 | .cache 85 | .parcel-cache 86 | 87 | # Next.js build output 88 | .next 89 | out 90 | 91 | # Nuxt.js build / generate output 92 | .nuxt 93 | dist 94 | 95 | # Gatsby files 96 | .cache/ 97 | # Comment in the public line in if your project uses Gatsby and not Next.js 98 | # https://nextjs.org/blog/next-9-1#public-directory-support 99 | # public 100 | 101 | # vuepress build output 102 | .vuepress/dist 103 | 104 | # vuepress v2.x temp and cache directory 105 | .temp 106 | .cache 107 | 108 | # Docusaurus cache and generated files 109 | .docusaurus 110 | 111 | # Serverless directories 112 | .serverless/ 113 | 114 | # FuseBox cache 115 | .fusebox/ 116 | 117 | # DynamoDB Local files 118 | .dynamodb/ 119 | 120 | # TernJS port file 121 | .tern-port 122 | 123 | # Stores VSCode versions used for testing VSCode extensions 124 | .vscode-test 125 | 126 | # yarn v2 127 | .yarn/cache 128 | .yarn/unplugged 129 | .yarn/build-state.yml 130 | .yarn/install-state.gz 131 | .pnp.* -------------------------------------------------------------------------------- /docs/basics/usage.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Basic Usage 3 | --- 4 | 5 | ## Configuration 6 | 7 | Manual configuration is not necessary for most use cases, but example configuration files may be found in the `docker/` directory. 8 | 9 | By default, the **configuration files** are named `server.conf` and `client.conf` and are located in the following directories: 10 | 11 | * Linux: `~/.config/counterparty/` 12 | * Windows: `%APPDATA%\Counterparty\` 13 | 14 | Client and server log files are named `counterparty.client.[testnet.]log` and `counterparty.server.[testnet.]log` and are located in the following directories: 15 | 16 | * Linux: `~/.cache/counterparty/log/` 17 | * Windows: `%APPDATA%\Local\Counterparty\counterparty\Logs` 18 | 19 | Counterparty API activity is logged to `server.[testnet.]api.log` and `client.[testnet.]api.log`. 20 | 21 | Counterparty database files are by default named `counterparty.[testnet.]db` and are located in the following directories: 22 | 23 | * Linux: `~/.local/share/counterparty` 24 | * Windows: `%APPDATA%\Roaming\Counterparty\counterparty` 25 | 26 | All configurable parameters in the configuration file can also be passed as arguments to the `counterpart-server` command. Use `counterparty-server --help` to see the list of these options. 27 | 28 | ## Counterparty CLI 29 | 30 | * NOTE: The `counterparty-client` CLI is currently non-functional and unsupported. 31 | 32 | 33 | ## Quickly Catch Up with the Network 34 | 35 | You will not be able to run `counterparty-server` until `addrindexrs` has caught up (and its RPC server is running), which in turn requires `bitcoind` have caught up as well. The command to start the Counterparty server process is simply `counterparty-server start`. However, simply running this command requires a long time to catch up with the network, and Counterparty must have parsed all published blocks before being operational. 36 | 37 | There is a way to speed up the process of catching up with the network: 38 | 39 | `counterparty-server bootstrap` downloads a recent snapshot of a Counterparty database from a centralized server maintained by the Counterparty Core development team. Because this method does not involve verifying the history of Counterparty transactions yourself, **the `bootstrap` command should not be used for mission-critical, commercial or public-facing nodes.** 40 | 41 | ```bash 42 | counterparty-server bootstrap 43 | ``` 44 | 45 | ## Start the Server 46 | 47 | Once the Counterparty server has caught up with the network, you may start the server simply with `counterparty start`: 48 | 49 | ```bash 50 | counterparty-server start 51 | ``` 52 | 53 | Note: During database initialization, `counterparty-server` performs a database integrity check. Depending on your configuration, this operation may take more or less time. You can disable this check with the `--skip-db-check` flag. -------------------------------------------------------------------------------- /docs/advanced/specifications/utxo-support.md: -------------------------------------------------------------------------------- 1 | # UTXO Support 2 | 3 | # Motivations 4 | 5 | With UTXO support, it is possible to **attach** / **detach** Counterparty assets directly to / from Bitcoin UTXOs, so that they can be spent just like Colored Coins–based protocols (such as Ordinals and Runes) using any Bitcoin wallets with support for sat tracking. This featuer enables single-transaction, trustless atomic swaps between BTC and Counterparty assets, as well as Counterparty assets and other L2 protocols. Attaching assets to UTXOs uses the [new gas system](gas-system.md) that allows for a dynamic XCP fee for transactions to reduce the barrier to entry into Counterparty for new users. 6 | 7 | # Design 8 | 9 | ## Attach 10 | 11 | 1. It is possible to attach an arbitrary number of assets from an address to a UTXO. 12 | 13 | 1. Assets are attached from transaction source address to the first UTXO non-`OP_RETURN` output or, if provided, to the `destination_vout` output. 14 | 15 | 1. If `destination_vout` designates an invalid output (`OP_RETURN` or non-existent) or if the transaction contains only a single OP_RETURN output, the transaction is invalid. 16 | 17 | 1. Fees in XCP, calculated using the [new gas system](gas-system.md), will be paid by the `source` address for an `attach`. 18 | 19 | 1. For each `attach`, a row will be added to the `send` table, triggering the `ATTACH_TO_UTXO` event. 20 | 21 | 1. When assets are attached to a UTXO, it is impossible to use them for a Counterparty transaction (`order`, `send`, etc.), apart from `detach`. 22 | 23 | 1. The embedded data in a `attach` transaction is small enough that an `OP_RETURN` output is always sufficient. 24 | 25 | 26 | ## Detach 27 | 28 | 1. All inputs of every `detach` transaction are detached. 29 | 30 | 1. If no `destination` is provided, the assets are sent to the address corresponding to the detached input. 31 | 32 | 1. It is impossible to perform a `move` at the same time as a `detach`. 33 | 34 | 1. For each `detach`, a row will be added to the `send` table, triggering the `DETACH_FROM_UTXO` event. 35 | 36 | 1. The embedded data in a `detach` transaction is small enough that an `OP_RETURN` output is always sufficient. 37 | 38 | 39 | ## Move 40 | 41 | 1. `utxo.move_assets()` is executed before all Counterparty contracts, except for `attach` transaction. 42 | 43 | 1. When a UTXO is spent, a row is added to the `send` table for each asset attached to this UTXO, triggering a `UTXO_MOVE` event. 44 | 45 | 46 | # API 47 | 48 | 1. API routes 49 | 50 | ```python 51 | "/v2/addresses/
/compose/attach": compose.compose_attach, 52 | "/v2/utxos//compose/detach": compose.compose_detach, 53 | "/v2/utxos//compose/movetoutxo": compose.compose_movetoutxo, 54 | "/v2/compose/attach/estimatexcpfees": compose.get_attach_estimate_xcp_fee, 55 | ``` 56 | 57 | 1. To prevent assets from being moved unintentionally, the transaction composition API excludes UTXOs with assets attached by default. 58 | 59 | 1. Balances contain two fields for UTXO support: `utxo` and `utxo_address`. 60 | -------------------------------------------------------------------------------- /docs/advanced/specifications/gas-system.md: -------------------------------------------------------------------------------- 1 | # Gas System 2 | 3 | # Motivation 4 | 5 | When Counterparty was first created, the XCP fees for various transactions were hard-coded to low, constant values (e.g. 0.5 XCP for issuing a named asset). This system was chosen for its simplicity, but it creates significant friction when onboarding users to the Counterparty ecosystem (esp. since it is so hard to acquire XCP) and yet the fees are so low that they have little economic significance for market participants. A proper XCP fee system should be proportional to network traffic and transaction complexity without creating any unnecessary barriers to entry for users of the network. This protocol change will institute just such a system for the new [UTXO Support](https://www.notion.so/UTXO-Support-7f70fdd934f94e6086716ed33d189e2f?pvs=21) feature by dynamically calculating the fees required to send assets from an address to a UTXO and from a UTXO to an address based on network congestion for this type of transaction. 6 | 7 | # Design 8 | 9 | Fees are calculated based on the number of such transactions in the last difficulty period (2016 blocks) based on the average number of transactions per block in that period. 10 | 11 | ```python 12 | def calculate_fee(x, a, b, base_fee, k): 13 | """ 14 | Calculate the fee based on the number of transactions per block, 15 | ensuring continuity at the transition point. 16 | 17 | Parameters: 18 | x (float): Number of transactions per period 19 | a (float): Lower threshold (fee is zero below this) 20 | b (float): Upper threshold (transition point to exponential growth) 21 | base_fee (float): Base fee amount 22 | k (float): Sigmoid steepness factor 23 | 24 | Returns: 25 | float: Calculated fee 26 | """ 27 | def sigmoid(t): 28 | return 1 / (1 + math.exp(-k * (t - 0.5))) 29 | 30 | if x <= a: 31 | return 0 32 | elif x <= b: 33 | return base_fee * sigmoid((x - a) / (b - a)) 34 | else: 35 | # Calculate sigmoid value and derivative at x = b 36 | sigmoid_at_b = sigmoid(1) 37 | sigmoid_derivative_at_b = k * sigmoid_at_b * (1 - sigmoid_at_b) 38 | 39 | # Calculate parameters for the exponential part 40 | m = sigmoid_derivative_at_b * (b - a) / base_fee 41 | c = math.log(m) 42 | 43 | # Exponential function that matches sigmoid at x = b 44 | return base_fee * sigmoid_at_b * math.exp(c * ((x - b) / (b - a))) 45 | ``` 46 | 47 | The different parameters (`a`, `b`, `k`, `base_fee`) will be stored in `protocol_changes.json`. 48 | 49 | Here is what the price evolution looks like as a function of the number of transactions using this function (a sigmoid to an exponential). (Parameters are not final.) 50 | 51 | ![sigmoid.png](/img/sigmoid.png) 52 | 53 | # API Changes 54 | 55 | - New Routes 56 | - Get Estimated XCP Fees: `/v2/addresses/
/send/compose/estimatexcpfees` 57 | 58 | # Database Changes 59 | 60 | To facilitate the calculation of fees, a new table `transaction_count` will be added. For each valid transaction a counter stored in this table will be incremented. This table will contain the following fields: 61 | 62 | 1. **transaction_type** (for now `send_from_address_to_utxo` or `send_from_utxo_to_address`) 63 | 2. **difficulty_period** (transaction block index modulo 2016) 64 | 3. **count** -------------------------------------------------------------------------------- /docs/advanced/command-line-interface/sending-bulk.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: How to send Counterparty assets in bulk 3 | --- 4 | 5 | Below is a script for constructing, signing and broadcasting a large 6 | number of sends efficiently. It assumes that the source addresses are in 7 | a (temporarily) unlocked Bitcoin Core wallet, to which a running 8 | instance of counterpartyd is connected. 9 | 10 | This script takes a single command-line argument of the CSV file from 11 | which to pull the sources, destinations, quantities, assets and fees. 12 | 13 | **Warning**: This example is outdated as it used the previous addrindex bitcoin 14 | branch, however, same principles apply to current mainline repo. 15 | 16 | ## Script 17 | 18 | ``` 19 | import csv 20 | import sys 21 | 22 | from counterpartylib.lib import util 23 | from counterpartylib.lib import config 24 | from counterpartylib.lib.backend import addrindex 25 | 26 | config.BACKEND_URL = 'http://user:password@localhost:4000' 27 | config.BACKEND_SSL_NO_VERIFY = False 28 | config.TESTNET = False 29 | config.REQUESTS_TIMEOUT = 5 30 | 31 | def counterparty_api(method, params): 32 | return util.api(method, params) 33 | 34 | def bitcoin_api(method, params): 35 | return addrindex.rpc(method, params) 36 | 37 | def do_send(source, destination, asset, quantity, fee, encoding): 38 | validateaddress = bitcoin_api('validateaddress', [source]) 39 | assert validateaddress['ismine'] 40 | pubkey = validateaddress['pubkey'] 41 | unsigned_tx = counterparty_api('create_send', {'source': source, 'destination': destination, 'asset': asset, 'quantity': quantity, 'pubkey': pubkey, 'allow_unconfirmed_inputs': True}) 42 | signed_tx = bitcoin_api('signrawtransaction', [unsigned_tx])['hex'] 43 | tx_hash = bitcoin_api('sendrawtransaction', [signed_tx]) 44 | return tx_hash 45 | 46 | 47 | with open(sys.argv[1], 'r') as csvfile: 48 | reader = csv.reader(csvfile) 49 | print('{}|{}|{}'.format('linenum', 'input', 'result')) 50 | 51 | for row in reader: 52 | if reader.line_num == 1: 53 | continue 54 | 55 | source, destination, asset, quantity, fee = row 56 | fee, quantity = int(fee), int(quantity) 57 | 58 | try: 59 | tx_hash = do_send(source, destination, asset, quantity, fee, 'opreturn') 60 | except Exception as e: 61 | tx_hash = str(e) 62 | 63 | print('{}|{}|{}'.format(reader.line_num, ','.join(row), tx_hash)) 64 | ``` 65 | 66 | ## CSV File 67 | 68 | All quantities are specified in satoshis. The format of the CSV file is as follows: 69 | 70 | source,destination,asset,quantity,fee 71 | mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns,mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns,XCP,100000000,150 72 | mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns,mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns,XCP,200000000,100 73 | 74 | ## Instructions 75 | 76 | Use this script on a system with `counterparty-core` installed and in the `PYTHONPATH`. (If using a Federated Node, this is possible by issuing the command `fednode shell counterparty` or `fednode shell counterparty-testnet` as appropriate, and using the script in that shell.) 77 | 78 | If the CSV file with the data is called input.csv, and the script is 79 | called sendmany.py, then call this script with 80 | ``$ python3 sendmany.py input.csv``. 81 | -------------------------------------------------------------------------------- /docs/advanced/specifications/enable-dispense-tx.md: -------------------------------------------------------------------------------- 1 | # Make Dispenses Normal Counterparty Transactions 2 | 3 | ## Motivation 4 | 5 | It is a serious flaw in the protocol that dispenses are not normal Counterparty transactions with the `CNTRPRTY` prefix. Any BTC transaction sent to an address with an open dispenser will trigger that dispenser. This was not part of the original specification for the feature, and it causes major problems both in terms of the Counterparty user experience and in overall code-quality/performance. 6 | 7 | That vanilla BTC transactions can trigger dispenses is responsible for significant loss of funds due to accidental and invalid dispenses. Some users now consider this to be a feature instead of a bug, however without a Counterparty wallet users are unable to detect whether a dispenser is already closed, whether they are using a compatible address type, etc. and they regularly lose funds due to those missing checks. Of course, after receiving the dispensed asset, the user is unable to view or spend that asset without migrating to a Counterparty wallet. 8 | 9 | ## Design 10 | 11 | Currently, it's possible to use a `dispenser` with a vanilla BTC transaction. The `get_tx_info` function examines each output of every transaction to determine if the destination address contains a dispenser. If so, `get_tx_info` behaves as if the transaction contained the following data: 12 | 13 | ``` 14 | data = struct.pack(config.SHORT_TXTYPE_FORMAT, dispenser.DISPENSE_ID) 15 | data += b"\\x00" 16 | ``` 17 | 18 | Subsequently, in the second parsing step, the `parse_tx` function recognizes the `dispenser.DISPENSE_ID` and invokes the `dispenser.dispense` function. 19 | 20 | ## Implementation 21 | 22 | 1. Introduce two protocol changes in the `protocol_changes.json` file: 23 | 1. `enable_dispense_tx`: From this block onwards, transactions containing `dispenser.DISPENSE_ID` will trigger one or more dispenses, similar to current vanilla BTC transactions. 24 | 2. `disable_vanilla_btc_dispense`: From this block onwards, vanilla BTC transactions will no longer trigger dispenses. 25 | 2. Add a new `dispense.compose()` to construct a transaction with the same data as currently used (see above). This function will perform necessary sanity checks (e.g., empty dispenser, closed status). 26 | 3. Modify `send.compose()` to check if the destination is a dispenser. If so, call the `dispense.compose()` function. 27 | 4. Update `get_tx_info` so that from the `disable_vanilla_btc_dispense` block onwards, transactions without `data` will consistently raise a `BTCOnlyError`, and outputs will no longer be checked for dispensers. 28 | 5. For `/v2/addresses/
/compose/send?asset=BTC` check if the destination is not a dispenser and if so return the same as `/v2/addresses/
/compose/dispense`(after `enable_dispense_tx`) 29 | 30 | ## API Changes 31 | 32 | 1. New route: `/v2/addresses/
/compose/dispense` 33 | 34 | *NOTE: It will no longer be possible to trigger a dispense with a non-Counterparty wallet. Explorers should update their existing dispenser warnings accordingly.* 35 | 36 | ## Database Changes 37 | 38 | After this change has gone into effect, it will be possible to record in a separate file all historical vanilla BTC dispenses and parse this file during the initial catchup. (The same thing was done with the original BTC burns for XCP.) This will allow for a major simplification and optimization of the existing codebase. The file will be able to be validated simply using old versions of the Counterparty Core software. -------------------------------------------------------------------------------- /docs/advanced/how-to/atomic-swap.md: -------------------------------------------------------------------------------- 1 | # Atomic Swap with UTXO Support 2 | 3 | With the new `attach` and `detach` functionalities which allow you to attach and detach assets from a UTXO, it is now possible to do Atomic Swaps like Ordinals. 4 | 5 | This guide details the different steps from opening a sell order to executing the buy order using Bitcoin Core for examples. 6 | 7 | # Step 1: Generation of a PSBT by the seller 8 | 9 | After attaching assets to the UTXO `$UTXO_TXID:$UTXO_VOUT`, the seller `$SELLER_ADDRESS` can decide to sell them at the price `$PRICE_BTC`. To do this, he must first prepare a “sale order” in the form of a signed PSBT: 10 | 11 | Creation of the PSBT `$SELLER_PSBT` 12 | 13 | ```bash 14 | $ bitcoin-cli createpsbt '[{"txid":"$UTXO_TXID", "vout":"$UTXO_VOUT"}]' \ 15 | '[{"$SELLER_ADDRESS": "$PRICE_BTC"}]' 16 | ``` 17 | 18 | Signature of PSBT 19 | 20 | ```bash 21 | $ bitcoin-cli walletprocesspsbt $SELLER_PSBT 22 | ``` 23 | 24 | # Step 2: Dissemination of the PSBT 25 | 26 | The seller can then share the PSBT in the way that seems most appropriate to him. 27 | 28 | # Step 3: Generation of a PSBT by the buyer 29 | 30 | Once collected by a potential buyer, he creates a PSBT with the inputs of the sum necessary to pay for the assets and an output for the exchange. 31 | 32 | After having determined the list of UTXOs with the `listunspent` command, calculated the exchange `$CHANGE` and the fees, the buyer `$BUYER_ADDRESS`can create his PSBT `$BUYER_PSBT`: 33 | 34 | ```bash 35 | $ bitcoin-cli createpsbt '[{"txid":"$UTXO1_TXID", "vout":"$UTXO2_VOUT"}, …]' \ 36 | '[{"$BUYER_ADDRESS": "$CHANGE"}]' 37 | ``` 38 | 39 | # Step 4: Joining the PSBTs of the seller and the buyer 40 | 41 | We must now join the two PSBTs into a single PSBT `$PSBT_FINAL` with the `joinpsbts` function. 42 | 43 | **Attention**: the `joinpsbts` function mixes the inputs and outputs randomly, you must therefore repeat the operation until the first output belongs to the buyer. Indeed, it is always the first non-OP_RETURN output which is the destination of the atomic swap. 44 | 45 | ```bash 46 | $ bitcoin-cli joinpsbts '["$BUYER_PSBT", "$SELLER_PSBT"]' 47 | ``` 48 | 49 | # Step 5: Signature, finalization and broadcast of the transaction 50 | 51 | Signature of `$PSBT_FINAL` 52 | 53 | ```bash 54 | $ bitcoin-cli walletprocesspsbt $PSBT_FINAL 55 | ``` 56 | 57 | Then finalizing `$SIGNED_PSBT_FINAL` 58 | 59 | ```bash 60 | $ bitcoin-cli finalizepsbt $SIGNED_PSBT_FINAL 61 | ``` 62 | 63 | And finally broadcast of the transaction 64 | 65 | ```bash 66 | $ bitcoin-cli sendrawtransaction $RAWTRANSACTION 67 | ``` 68 | 69 | # Include a Counterparty transaction 70 | 71 | It is possible to include a Counterparty transaction inside the transaction used to finalize the atomic swap. For this it is enough: 72 | 73 | 1. use the composition API with the `return_data_only` argument 74 | 2. Add the `CNTRPTY` prefix 75 | 3. Encrypt with ARC4 using the `txid` of the first input of the transaction 76 | 4. Use the `$DATA` obtained in “Step 3: Generation of a PSBT by the buyer” 77 | 78 | ```bash 79 | $ bitcoin-cli createpsbt '[{"txid":"$UTXO1_TXID", "vout":"$UTXO2_VOUT"}, …]' \ 80 | '[{"$BUYER_ADDRESS": "$CHANGE"}, {"data": "$DATA"}]' 81 | ``` 82 | 83 | 5. In “Step 4: Joining the PSBTs of the seller and the buyer” ensure that: 84 | 1. The first input belongs to the buyer 85 | 2. The first output is the OP_RETURN 86 | 3. The second output is to the buyer 87 | 88 | **Attention**: this only works with an OP_RETURN, the size of `$DATA` must therefore not exceed 80 bytes. -------------------------------------------------------------------------------- /docs/advanced/exchange-integration.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Exchange Integration 3 | --- 4 | 5 | ## Handling Deposits using Separate Addresses 6 | 7 | - Create a XCP holding address (or several primary XCP holding addresses). The address will hold deposited XCP funds for all users using the exchange. 8 | 9 | - Create a regular Bitcoin address for each user wanting to deposit XCP using the API of the Bitcoin Core instance that `counterparty-server` is connecting to. 10 | 11 | - Poll for deposits using `get_sends`, filtering for `asset==XCP`, `destination==deposit_address` and `block_index<=current_block_index-number_of_desired_confirmations`. Record the quantity of the send transaction and the transaction's `txid`. 12 | 13 | - 'Prime' the deposit address by sending it 0.0005 BTC. 14 | 15 | - For deposit, send the quantity deposited to the holding address using the `do_send` with the flag `unconfirmed=True` (so you don't have to wait for the priming to confirm). Record the `txid` of this transaction. 16 | 17 | - When the second send is confirmed (poll `get_sends` again), credit the user’s account balance. 18 | 19 | 20 | ## Handling Deposits using Memo Transactions 21 | 22 | - Create a XCP deposit address. The address will hold deposited XCP funds for all users using the exchange. 23 | 24 | - 'Prime' the deposit address by sending it small amount of BTC. 25 | 26 | - Make the deposit address require a memo by broadcasting `OPTIONS 1` from that address. The value and fee_fraction can be 0. 27 | 28 | - When a user wishes to deposit to your exchange, generate a unique hexadecimal invoice ID for the deposit and convey that to the user. The user must send counterparty assets into the address along with the matching invoice ID in the memo field. If the user fails to include a memo, the send will be rejected by the network and the user's address will retain the assets they sent. 29 | 30 | - Poll for deposits using `get_sends`, filtering for `asset==XCP`, `destination==deposit_address` and `block_index<={current_block_index-number_of_desired_confirmations}` and `memo_hex=={invoice_id}`. Record the quantity of the send transaction and the transaction's `txid`. 31 | 32 | - When the send is confirmed with 2 confirmations (poll `get_sends` again), credit the user’s account balance. 33 | 34 | - Memo transactions are available as of block 489956 35 | 36 | ## Handling Withdrawals (Single Send) 37 | 38 | - Prime the holding address if its current balance is below 0.0005 BTC. 39 | 40 | - Send the funds to the user-provided address with `create_send` (Counterparty API). 41 | 42 | ## Batching Withdrawals (Multi-Peer-Multi-Asset Send) 43 | 44 | - Prime the holding address if its current balance is below 0.0005 BTC. 45 | 46 | - Generate first MPMA transaction by making a `create_send` (Counterparty API) call and specify as many assets and recipient addresses as you would like. 47 | 48 | - Sign and Broadcast first MPMA transaction and note `txid` 49 | 50 | - Generate second MPMA transaction by making identical `create_send` (Counterparty API) call as before, except also specify `p2sh_pretx_txid` param and give `txid` of first MPMA transaction 51 | 52 | - Sign and Broadcast second MPMA transaction 53 | 54 | ## Best practices 55 | 56 | - For deposits, wait for at least two confirmations on the send to the desposit address and one confirmation for the send to the holding address. 57 | 58 | - Keep the private key for the holding address secret and safe. 59 | 60 | - Keep the bulk of your exchange's funds in cold storage. 61 | 62 | - Set a maximum XCP and BTC withdrawal amount, both per day and per event. 63 | 64 | - Use a segwit address for memo deposits and MPMA/Batched withdrawals to keep transaction costs minimal. 65 | -------------------------------------------------------------------------------- /docs/basics/what-is-counterparty.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: What is Counterparty? 3 | --- 4 | 5 | ### What is Counterparty? 6 | 7 | The Counterparty Protocol is an extension to the Bitcoin protocol which implements a number of features that Bitcoin itself does not offer. These include token issuance, a fully decentralized and trustless asset exchange, contracts for difference, native oracles and trustless gaming. 8 | 9 | 10 | ### How does Counterparty work? 11 | 12 | Counterparty works by ‘writing in the margins’ of Bitcoin transactions, and all Counterparty transactions are Bitcoin transactions with additional data that the Counterparty software can read and interpret. To a regular Bitcoin client, these transactions look like normal Bitcoin transactions, with one party sending another party a very small amount of Bitcoin. A Counterparty node (which runs the Bitcoin client along with [Counterparty Core](https://github.com/CounterpartyXCP/counterparty-core)) will recognize and interpret the data in these Bitcoin transactions based on specific rules. From this, it constructs its own ledger of Counterparty transactions and Counterparty network state. 13 | 14 | 15 | ### What does a Counterparty transaction look like? 16 | 17 | [Here](https://counterpartychain.io/transaction/c717d2d205155c2067786c08b7c7e6e6f904a18626969daca0ecb6c3e8bb7b8f) is a record of a Counterparty transaction where one address is sending 48 SJCX tokens (a custom token used by [Storj](https://storj.io/)) to another address. 18 | 19 | [Here](https://blockchain.info/tx/c717d2d205155c2067786c08b7c7e6e6f904a18626969daca0ecb6c3e8bb7b8f) is what this transaction looks like to a blockchain.info, a popular Bitcoin block explorer. You can see that while it is indeed a Bitcoin transaction, the amount of Bitcoin moved is small. In reality, the BTC spent is just enough to compensate the Bitcoin miners to include the transaction in a block. Essentially, the user that sent the transaction is paying the Bitcoin network to record and secure this embedded Counterparty data. 20 | 21 | 22 | ### Does Counterparty have its own blockchain? 23 | 24 | Counterparty lives entirely on the Bitcoin blockchain. Such a protocol is sometimes called a **metaprotocol** or **metachain**. 25 | 26 | 27 | ### Is Counterparty "polluting" the Bitcoin blockchain, then? 28 | 29 | The vast majority of Counterparty transactions utilize a data-encoding method called `OP_RETURN`, which is fully "prunable". This means that the data may be safely discarded by Bitcoin nodes that don't wish to store it. Unprunable Counterparty transactions use alternative encoding methods. However, these outputs for these transactions do not stay in the memory of Bitcoin nodes for very long. Of course, every Counterparty transaction pays a fair fee to the network for being mined. 30 | 31 | 32 | ### How is the Counterparty network secured? 33 | 34 | Counterparty transactions are just as secure as regular Bitcoin transactions because Counterparty transactions *are* Bitcoin transactions, so Bitcoin miners validate the entire history of the Counterparty network. It is no easier to attack Counterparty than it is to attack Bitcoin itself. 35 | 36 | 37 | ### How do the Counterparty nodes stay in sync? What's to stop one node from disagreeing with another? 38 | 39 | As all Counterparty nodes run the same code, and all receive the same Bitcoin transaction data, the ledgers across each node match exactly. Counterparty nodes are not like Bitcoin nodes in that they don't communicate with each other directly: they simply connect to the Bitcoin software and download transactions from it, decoding each one as they go along. In this way, the immense security and computing power behind Bitcoin is leveraged as the "transport network" for Counterparty data. 40 | -------------------------------------------------------------------------------- /docusaurus.config.js: -------------------------------------------------------------------------------- 1 | /** @type {import('@docusaurus/types').DocusaurusConfig} */ 2 | import {themes as prismThemes} from 'prism-react-renderer'; 3 | 4 | module.exports = { 5 | title: 'Counterparty', 6 | url: 'https://counterpartyxcp.github.io', 7 | baseUrl: '/', 8 | trailingSlash: true, 9 | onBrokenLinks: 'throw', 10 | onBrokenMarkdownLinks: 'warn', 11 | favicon: 'img/favicon.ico', 12 | organizationName: 'CounterpartyXCP', // Usually your GitHub org/user name. 13 | projectName: 'Documentation', // Usually your repo name. 14 | themeConfig: { 15 | prism: { 16 | theme: prismThemes.dracula, 17 | }, 18 | navbar: { 19 | title: 'Counterparty', 20 | logo: { 21 | alt: 'Counterparty', 22 | src: 'img/xcp.png', 23 | }, 24 | items: [ 25 | { 26 | to: 'docs/basics/what-is-counterparty', 27 | activeBasePath: 'docs/basics', 28 | label: 'Basics', 29 | position: 'left', 30 | }, 31 | { 32 | to: 'docs/advanced/protocol', 33 | activeBasePath: 'docs/protocol', 34 | label: 'Advanced', 35 | position: 'left', 36 | }, 37 | { 38 | href: 'https://krellenstein.com/adam/get/counterparty-whitepaper_2024-04-25.pdf', 39 | label: 'Whitepaper', 40 | position: 'right', 41 | }, 42 | { 43 | href: 'https://counterpartycore.docs.apiary.io/', 44 | label: 'API Documentation', 45 | position: 'right', 46 | }, 47 | { 48 | href: 'https://github.com/CounterpartyXCP/Documentation', 49 | label: 'GitHub', 50 | position: 'right', 51 | }, 52 | ], 53 | }, 54 | footer: { 55 | style: 'dark', 56 | links: [ 57 | { 58 | title: 'Docs', 59 | items: [ 60 | { 61 | label: 'Getting Started', 62 | to: 'docs/basics/what-is-counterparty', 63 | }, 64 | ], 65 | }, 66 | { 67 | title: 'Community', 68 | items: [ 69 | { 70 | label: 'Telegram', 71 | href: 'https://t.me/Counterparty_XCP', 72 | }, 73 | { 74 | label: 'Forum', 75 | href: 'https://forums.counterparty.io/', 76 | }, 77 | { 78 | label: 'Reddit', 79 | href: 'https://www.reddit.com/r/counterparty_xcp/', 80 | }, 81 | { 82 | label: 'Twitter', 83 | href: 'https://twitter.com/CounterpartyXCP', 84 | } 85 | ], 86 | }, 87 | { 88 | title: 'More', 89 | items: [ 90 | { 91 | label: 'GitHub', 92 | href: 'https://github.com/CounterpartyXCP/Documentation', 93 | } 94 | ], 95 | }, 96 | ], 97 | }, 98 | }, 99 | presets: [ 100 | [ 101 | '@docusaurus/preset-classic', 102 | { 103 | docs: { 104 | sidebarCollapsible: false, 105 | sidebarPath: require.resolve('./sidebars.js'), 106 | editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/', 107 | }, 108 | blog: { 109 | showReadingTime: false, 110 | // Please change this to your repo. 111 | editUrl: 'https://github.com/facebook/docusaurus/edit/master/website/', 112 | }, 113 | theme: { 114 | customCss: require.resolve('./src/css/custom.css'), 115 | }, 116 | }, 117 | ], 118 | ], 119 | }; 120 | -------------------------------------------------------------------------------- /docs/advanced/api-v1/api-v1-changelog.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API v1 ChangeLog 3 | --- 4 | 5 | 6 | This section documents any changes to the v1 API, for version numbers where there were API-level modifications. 7 | 8 | There will be no incompatible API pushes that do not either have: 9 | 10 | * A well known set cut over date in the future 11 | * Or, a deprecation process where the old API is supported for an amount of time 12 | 13 | ### 9.58.0 14 | * Added `P2SH` support and `MPMA` support: 15 | * Explanation of the new array parameters for `create_send` 16 | * Explanation of the new `p2sh_pretx_txid` parameter 17 | * Example to sign the new kind of `P2SH transaction` 18 | 19 | ### 9.55.5 20 | * create_*: adds `extended_tx_info` parameter to create methods 21 | 22 | ### 9.55.4 23 | * No changes 24 | 25 | ### 9.55.3 26 | * create_send: Added `memo`, `memo_is_hex` and `use_enhanced_send` parameters 27 | * get_sends: Added support for `memo` and `memo_hex` filters 28 | * get_sends: Returns `memo` and `memo_hex` in the search results 29 | 30 | ### 9.55.2 31 | * create_issuance: subassets longname are supported in the `asset` parameter 32 | 33 | ### 9.53.0 34 | * Add min_message_index to get_blocks API call 35 | 36 | ### 9.52.0 37 | * Added getrawtransaction and getrawtransaction_batch methods to the API 38 | * Added optional custom_inputs parameter to API calls, which allows for controlling the exact UTXOs to use in transactions (contributed by Tokenly) 39 | 40 | ### 9.51.0 41 | * Deprecated `get_asset_info(assets)` API method. Use `get_issuances()` and `get_supply()` instead. 42 | * Deprecated `get_xcp_supply()` API method in favor of `get_supply(asset)`. 43 | * Changed `get_unspent_txouts` API method parameter and return values. 44 | * Added HTTP Rest API. 45 | * Authentication on JSON‐RPC API is off by default 46 | * `rpc_password` configuration parameter is no longer mandatory 47 | 48 | ### 9.49.4 49 | * The `do_*`, `sign_tx` and `broadcast_tx` methods have been completely deprecated. See the section [Wallet Integration](#Wallet-Integration). 50 | * Added REST API. 51 | 52 | ### 9.49.3 53 | 54 | * \*_issuance: ``callable``, ``call_date`` and ``call_price`` are no longer valid parameters 55 | * \*_callback: removed 56 | * Bitcoin addresses may everywhere be replaced by pubkeys. 57 | * The API will no longer search the local wallet for pubkeys, so they must be passed to the API manually if being used for the first time. Otherwise, you may get a "not published in blockchain" error. 58 | 59 | ### 9.43.0 60 | 61 | * create_issuance: ``callable`` is also accepted 62 | * create_*: ``null`` is used as default value for missing parameters 63 | 64 | ### 9.32.0 65 | 66 | **Summary:** API framework overhaul for performance and simplicity 67 | 68 | * "/api" with no trailing slash no longer supported as an API endpoint (use "/" or "/api/" instead) 69 | * We now consistently reject positional arguments with all API methods. Make sure your API calls do not use positional 70 | arguments (e.g. use `{"argument1": "value1", "argument2": "value2"}` instead of `["value1", "value2"]`) 71 | 72 | ### 9.25.0 73 | 74 | * new do_* methods: like create_*, but also sign and broadcast the transaction. Same parameters as create_*, plus optional privkey parameter. 75 | 76 | **backwards incompatible changes** 77 | 78 | * create_*: accept only dict as parameters 79 | * create_bet: ``bet_type`` must be a integer (instead string) 80 | * create_bet: ``wager`` and ``counterwager`` args are replaced by ``wager_quantity`` and ``counterwager_quantity`` 81 | * create_issuance: parameter ``lock`` (boolean) removed (use LOCK in description) 82 | * create_issuance: parameter ``transfer_destination`` replaced by ``destination`` 83 | * DatabaseError: now a DatabaseError is returned immediately if the database is behind the backend, instead of after fourteen seconds 84 | 85 | ### 9.24.1 86 | 87 | **Summary:** New API parsing engine added, as well as dynamic get method composition in ``api.py``: 88 | 89 | * Added ``sql`` API method 90 | * Filter params: Added ``LIKE``, ``NOT LIKE`` and ``IN`` 91 | -------------------------------------------------------------------------------- /docs/basics/assets/enhanced-asset.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Enhanced Asset Info 3 | --- 4 | 5 | When initially setting or changing your asset's (token's) description, you can enable enhanced functionality (such as an token image and a longer description) by providing a URL to a specially formatted .json file (e.g. http://www.mydomain.com/foo.json) as the description. This allows the token owner to provide enhanced information to the token's holders, and enhances the user experience for these holders for wallet implementations that support this spec. 6 | 7 | Token Info URL format 8 | --------------------------- 9 | 10 | The URL itself in the broadcast text field must conform to the following: 11 | * Must fully fit within the text field space allowed 12 | * May or may not start with "http://" or "https://". If the URL does not start with either, "http://" is assumed 13 | * Must end with ".json" 14 | * It is recommended that the server return the JSON data with the correct MIME type set (e.g. "application/json") 15 | * A HTTP 200 response code must be returned (redirects, e.g. 301, 302, etc. are not allowed) 16 | 17 | ## Token Info JSON format 18 | 19 | The JSON object/mapping the URL points to must contain the following data: 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 |
assetRequiredThe name of the token. Must match your token's name exactly. 24 characters max.
descriptionOptionalA longish description about this token. 2048 characters max.
imageOptionalA link a 48x48 PNG image to represent the token on the leaderboard and portfolio views. The text itself must be a valid URL that starts with "http://" or "https://" (100 characters max). The image the URL references must be in PNG format (the URL must end in .png). It must be 48x48, and it must use the RGB or RGBA color palette. If any of these are not correct, the system will reject it.
websiteOptionalA link to the website for the token. 100 characters max. Must be a valid URL that starts with "http://" or "https://"
pgpsigOptionalA link to a pgp signature text/file that will or can be used to sign messages by the issuer of this token. 100 characters max. Must be a valid URL that starts with "http://" or "https://"
28 | 29 | Examples 30 | -------- 31 | 32 | Here's an example for a token called MYTOKEN: 33 | 34 | ```json 35 | { 36 | "asset": "MYTOKEN", 37 | "description": "This is a description of MYTOKEN", 38 | "image": "http://www.mysite.com/mytoken.png", 39 | "website": "http://www.mysite.com", 40 | "pgpsig": "http://www.mysite.com/MYTOKEN.pgp" 41 | } 42 | ``` 43 | 44 | Other Topics 45 | ------------ 46 | 47 | ### Validity and refreshing 48 | 49 | Every 30-60 minutes, the Counterwallet system will query this URL provided to validate and fetch the necessary information. If the information you provided is reachable and valid (within a 1 second response time), your token's information will be enhanced based on this data. 50 | In order for this data file to be deemed as valid for a specific token/asset, there must have been either an initial issuance, or a description change transaction for that asset, and the text field of that description must have been set to the URL of this JSON file. If the information you provided is reachable and valid (within a 5 second response time), your token's information will be enhanced based on this data. If it is not, counterblockd will retry up to 2 additional times, over the next 30 or so minutes, and then give up until another transaction is made that changes the description field (it may be to the same URL, but another description change transaction is necessary to reinitialize the validity check by counterblockd). 51 | 52 | ### Validating your JSON data 53 | 54 | Your JSON data must respect and validate against [this][] JSON schema. 55 | If the validation fails on any level, counterblockd will not accept the 56 | data. 57 | 58 | To check your data against this schema, go [here][]. Paste the schema 59 | from the link above into the **Schema** field, and place your example 60 | output into the **Data** field. Then click the **Validate** button 61 | 62 | [this]: https://raw.githubusercontent.com/CounterpartyXCP/counterblock/master/counterblock/schemas/asset.schema.json 63 | [here]: http://json-schema-validator.herokuapp.com/ 64 | -------------------------------------------------------------------------------- /docs/basics/manual-installation.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Manual Installation 3 | --- 4 | 5 | Counterparty Core can be installed on most platforms but, for now, manual installation is being tested and is only officially supported on Ubuntu 22.04 and MacOS. 6 | 7 | Dependencies: 8 | 9 | - Bitcoin Core 10 | - AddrIndexRS 11 | - Python >= 3.10 12 | - Rust 13 | - Maturin 14 | - LevelDB 15 | 16 | ## Install dependencies 17 | 18 | ### Install Bitcoin Core 19 | 20 | Download the latest [Bitcoin Core](https://github.com/bitcoin/bitcoin/releases) and create 21 | a `bitcoin.conf` file (by default located in `~.bitcoin/`) with the following options: 22 | 23 | ``` 24 | rpcuser=rpc 25 | rpcpassword=rpc 26 | server=1 27 | addresstype=legacy 28 | txindex=1 29 | prune=0 30 | mempoolfullrbf=1 31 | rpcworkqueue=100 32 | [main] 33 | zmqpubrawtx=tcp://0.0.0.0:9332 34 | zmqpubhashtx=tcp://0.0.0.0:9332 35 | zmqpubsequence=tcp://0.0.0.0:9332 36 | zmqpubrawblock=tcp://0.0.0.0:9333 37 | [test] 38 | zmqpubrawtx=tcp://0.0.0.0:19332 39 | zmqpubhashtx=tcp://0.0.0.0:19332 40 | zmqpubsequence=tcp://0.0.0.0:19332 41 | zmqpubrawblock=tcp://0.0.0.0:19333 42 | [testnet4] 43 | zmqpubrawtx=tcp://0.0.0.0:49332 44 | zmqpubhashtx=tcp://0.0.0.0:49332 45 | zmqpubsequence=tcp://0.0.0.0:49332 46 | zmqpubrawblock=tcp://0.0.0.0:49333 47 | [regtest] 48 | zmqpubrawtx=tcp://0.0.0.0:29332 49 | zmqpubhashtx=tcp://0.0.0.0:29332 50 | zmqpubsequence=tcp://0.0.0.0:29332 51 | zmqpubrawblock=tcp://0.0.0.0:29333 52 | ``` 53 | 54 | Adding the following lines, and opening up port `8333` to incoming traffic, may improve your sync speed: 55 | 56 | ``` 57 | listen=1 58 | dbcache=4000 59 | ``` 60 | 61 | ### Install Rust 62 | 63 | The recommended way to install Rust is to use `rustup`: 64 | 65 | ```bash 66 | curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh 67 | source "$HOME/.cargo/env" 68 | ``` 69 | 70 | See https://www.rust-lang.org/tools/install for more information. 71 | 72 | 73 | ### Install Python >= 3.10 and Maturin 74 | 75 | On Ubuntu 22.04 and similar: 76 | 77 | ```bash 78 | apt-get install -y python3 python3-dev python3-pip 79 | pip3 install maturin 80 | ``` 81 | 82 | On MacOS: 83 | 84 | ```bash 85 | brew install python 86 | pip3 install maturin 87 | ``` 88 | 89 | See https://brew.sh/ to install Homewrew. 90 | 91 | 92 | ### Install LevelDB 93 | 94 | On Ubuntu 22.04 and similar: 95 | 96 | ```bash 97 | apt-get install -y libleveldb-dev 98 | ``` 99 | 100 | On MacOS: 101 | 102 | ```bash 103 | brew install leveldb 104 | ``` 105 | 106 | ## Install Counterparty Core 107 | 108 | Download the latest version `counterparty-core`: 109 | 110 | ```bash 111 | git clone https://github.com/CounterpartyXCP/counterparty-core.git 112 | ``` 113 | 114 | Install the `counterparty-rs` library: 115 | 116 | ```bash 117 | cd counterparty-core/counterparty-rs 118 | pip3 install . 119 | ``` 120 | 121 | Install the `counterparty-core` library: 122 | 123 | ```bash 124 | cd counterparty-core/counterparty-core 125 | pip3 install . 126 | ``` 127 | 128 | Install the `counterparty-wallet` library: 129 | 130 | ```bash 131 | cd counterparty-core/counterparty-wallet 132 | pip3 install . 133 | ``` 134 | 135 | On most platforms you need to update your $PATH variable so that `counterparty-server` and `counterparty-wallet` are accessible. For example: 136 | 137 | ``` 138 | export PATH=$PATH:/home/username/.local/bin/ 139 | ``` 140 | Look at the `counterparty-core` and `counterparty-wallet` installation logs to find out the path of the binaries on your system. 141 | 142 | *Note for MacOS users* 143 | 144 | Use this command if you get an error while installing one of the packages: 145 | 146 | ```bash 147 | CFLAGS="-I/opt/homebrew/include -L/opt/homebrew/lib" 148 | ``` 149 | 150 | ## Upgrade Counterparty Core 151 | 152 | To update, simply follow the same procedure as for installation. 153 | 154 | ### Notes 155 | 156 | #### Update from 10.0.0 to 10.1.0 or from 10.1.0 to 10.1.1 157 | 158 | given the change of names of certain packages you must start by uninstalling the previous version: 159 | 160 | ``` 161 | pip uninstall counterparty-lib counterparty-cli counterparty-core 162 | ``` 163 | 164 | 165 | ## Install Electrs 166 | 167 | It is optionally possible to install Electrs. It allows to compose transactions, without the `inputs_set` parameter, for addresses not in the Bitcoin Core wallet. 168 | 169 | ```bash 170 | git clone https://github.com/mempool/electrs 171 | cd electrs 172 | cargo install --path=. 173 | ``` 174 | 175 | Start `electrs` with: 176 | 177 | ```bash 178 | electrs --cookie=rpc:rpc -vvv 179 | ``` 180 | 181 | When working with a remote full node or low-memory system, you can tell `electrs` to use JSON-RPC to communicate with `bitcoind` using the flag `--jsonrpc-import`. 182 | You can also limit the resources available for `electrs` with: 183 | 184 | ```bash 185 | ulimit -n 8192 186 | ``` 187 | 188 | Use `electrs -h` for more options. 189 | 190 | To connect Electrs to the Counterparty Server use the flag `--electrs-url`: 191 | 192 | ```bash 193 | counterparty-server start --electrs-url=http://localhost:3000 194 | ``` -------------------------------------------------------------------------------- /docs/advanced/bounties.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Bug Bounties 3 | --- 4 | 5 | According to [Linus’ Law](http://en.wikipedia.org/wiki/Linus), “given enough eyeballs, all bugs are shallow”. That’s one of the reasons why Counterparty’s source code is publicly available; but merely making the source code available doesn't accomplish anything if people don’t read it! 6 | 7 | For this reason, Counterparty has a series of bug bounties. Counterparty bug bounties provide an opportunity for people who find bugs to be compensated. 8 | 9 | Depending on the type of bug and when it is reported, different bounties will be awarded. Bounties are paid out in a mix of XCP and BTC (the ratio is negotiable), at the 3-day average of each to a fixed US Dollar value. 10 | 11 | ## Things that do not qualify under the bug bounty 12 | 13 | - **counterpartytalk.org website** (unless the issue is a serious misconfiguration where user security details are being leaked in a way that they can be proven to be exploited) 14 | - **Counterwallet or counterblock** (unless the issue allows for theft of funds, in that case the $1,500 bounty defined below would apply) 15 | - **Please do not try XSS attacks in the Counterwallet chat box. It is annoying, and it has already been tested extensively** 16 | - Vulnerabilities which are too broad or not documented properly (i.e. do not include a specific example relevant to a Counterparty-controlled site) 17 | - Bugs or issues with a third-party site, software, or service that we use, such as support.counterparty.io (freshdesk.com), which is not due to an improper configuration issue specific to us. Please submit any potential issues **to the maintainers of that site or providers of that service** 18 | - Usability issues 19 | - Anything requiring social engineering 20 | - DOS/DDOS attacks 21 | - Missing HSTS (HttpOnly flags), Secure flag, Browser Cache vulnerabilities 22 | - CSRF that doesn’t affect the victim 23 | - Referrer leakage to pages an attacker cannot control 24 | - Lack of explicit rate-limiting for counterwallet.io passphrase entry 25 | - The presence of unnecessary files, e.g. for backups, when these files do not expose any sensitive information 26 | - Anything that is the result of an automated Nessus/PCI scans (too general) 27 | - DNS issues (e.g. lack of an SPF record) 28 | - SSL certificate issues (such as lack of Perfect Forward Secrecy on our SSL certificates) 29 | - Bugs that have received mainstream tech media attention before the date of your disclosure (e.g. Heartbleed, Poodlebleed, etc) 30 | 31 | ## Bounties for counterparty-core 32 | 33 | | Total USD amount (BTC/XCP mix) | Type of bug | 34 | | ----------------------------------------|------------------------------------| 35 | | $1,500 | A flaw in the protocol that allows for theft or loss of funds | 36 | | $1,000 | A bug in the reference client that leads to consensus issues | 37 | | $750 | A bug which causes data corruption or loss | 38 | | $200 | A bug which causes the application to crash | 39 | | $100 | Other non-harmless bugs | 40 | | $50 | Build breakage on a supported platform | 41 | | $20 | 'Harmless' bugs, e.g. cosmetic errors | 42 | 43 | Bounties will be paid out for bugs found in the `master` branch of the official GitHub repositories. 44 | 45 | ## How to report a bug 46 | 47 | ### For security-related issues 48 | 49 | Email [the developers](mailto:dev@counterparty.io) **privately with the details of the issue.** 50 | 51 | 52 | ### For code issues 53 | 54 | We would strongly prefer if you create a pull request on GitHub in the proper repository with the necessary fix (along with your Bitcoin address to claim the bounty). For more information, see [this link](https://help.github.com/categories/63/articles).  55 | 56 | ### For website issues 57 | 58 | Please contact [support](mailto:support@counterparty.io) with the error, along with your Bitcoin address. 59 | 60 | ## The fine print 61 | 62 | - A bounty will only be awarded to the first person who reports a bug, unless two or more people report the same bug at approximately the same time, in which case the bounty may be split between them. 63 | - If the same bug appears in multiple locations it will normally only receive a single bounty. 64 | - Reports of security-related bugs are not eligible for bounties if the bugs are publicly disclosed prior to being fixed. 65 | - The issue must be described in necessary detail to address it. 66 | - Only the discoverer of a bug is eligible for the associated bounty. 67 | - Bounties will be confirmed and awarded within 10 days of their 68 | reporting. Inquiries on bounty status may be sent to [bounties@counterparty.io](mailto:bounties@counterparty.io) 69 | - Bounties will not be awarded if it is illegal to do so. 70 | - The classification of bugs, values of bounties, and conditions under which bounties are paid are subject to change without notice. 71 | - The core Counterparty team has sole discretion to determine whether a bug report qualifies for a bounty and for which bounty it qualifies. 72 | 73 | ## CREDITS 74 | 75 | Credit to the general structure of this program as well as much of the wording goes to [Tarsnap](http://www.tarsnap.com/bugbounty.html). 76 | -------------------------------------------------------------------------------- /static/img/logo.svg: -------------------------------------------------------------------------------- 1 | -------------------------------------------------------------------------------- /docs/basics/faq.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: FAQ 3 | --- 4 | 5 | ### Can I secure my XCP and Counterparty tokens in cold storage? 6 | 7 | Yes. You can make a regular Bitcoin paper wallet and store them there. Later, you can sweep the funds into a Counterparty wallet. 8 | 9 | 10 | ### Is a 51% attack against Counterparty possible? 11 | 12 | As every Counterparty transaction is a Bitcoin transaction, to do a "51% attack" on Counterparty you would have to do a 51% attack on Bitcoin. 13 | 14 | 15 | ### So can the Counterparty Team rewrite the Counterparty ledger’s history, in an emergency or by decree? How does that compare to the same risks with Bitcoin Core devs? 16 | 17 | It’s identical to the case with Bitcoin. The Bitcoin core devs could publish a copy of Bitcoin Core that does anything, but no one would download it. 18 | 19 | Counterparty is 100% open source, with [a list of code changes](https://github.com/CounterpartyXCP/counterparty-core/releases) from one release to the next visible for all to see and inspect. 20 | 21 | 22 | ### What about support for other blockchains instead of Bitcoin? 23 | 24 | Counterparty is built on Bitcoin. That has always been the case and we do not see it changing, ever. For other blockchains, there are "forks" of the Counterparty software. Examples would be Dogeparty for Dogecoin, and Viacoin's ClearingHouse. 25 | 26 | 27 | ### What happens if and when `OP_RETURN` data is auto-pruned? 28 | 29 | Counterparty only needs some Bitcoin full nodes somewhere to have an unpruned copy of the blockchain. As every Counterparty full node is also a Bitcoin full node, this is easily done. 30 | 31 | 32 | ### How are blockchain reorganizations ("reorgs") handled by Counterparty? 33 | 34 | Blockchain reorganizations are essentially handled by Counterparty the same way they are handled by Bitcoin. The Counterparty database is log-structured. This means that Counterparty simply deletes all the database rows written after a certain block to execute a rollback, and then process new transactions on the now-longest chain. 35 | 36 | 37 | ### What Counterparty wallet should I use? 38 | 39 | The list of Counterparty wallets currently available may be found here on the [official project page](https://www.counterparty.io/#wallets). 40 | 41 | 42 | ### What is “Counterparty 2.0”? 43 | 44 | “Counterparty 2.0” is an affectionate term that the community has given to the revival of the Counterparty project this year, and specifically the development of a number of long-awaited, major new features such as UTXO Support, Atomic Swaps with Bitcoin, Fair Minting and (the forthcoming) AMMs/LPs. “Counterparty 2.0” doesn’t refer to any particular version of Counterparty. 45 | 46 | 47 | ### Did Counterparty recently fork? 48 | 49 | Protocol upgrades are a normal part of the evolution of the Counterparty protocol, and there have been [dozens](https://github.com/CounterpartyXCP/counterparty-core/blob/master/counterparty-core/counterpartycore/protocol_changes.json) throughout its history. The developer of Freewallet and Tokenscan has published versions of those applications which run on top of an old version of Counterparty (v9.61.3—the last version that he contributed to), rather than the latest version of Counterparty (currently [v10.6.1](https://github.com/CounterpartyXCP/counterparty-core/releases/tag/v10.6.1)). Every other node host has upgraded to the latest release of Counterparty and offers no support for out-of-date versions. A list of services that have upgraded is as follows: 50 | 51 | - Dex-Trade 52 | - Zaif 53 | - Horizon Wallet 54 | - RarepepeWallet 55 | - Pepe.wtf 56 | - OpenSea 57 | - Firemints.xyz 58 | - Horizon Explorer 59 | - Memepool 60 | - XCP.io 61 | - Pepe.wtf 62 | - XCPDex 63 | - XCPNinja 64 | - Emblem Vault 65 | - Spells of Genesis 66 | - Bitcoin Stamps 67 | 68 | 69 | ### Is it safe to use Counterparty? 70 | 71 | Yes, as long as you use tooling that supports the latest version of Counterparty, there’s no risk. 72 | 73 | 74 | ### What happened to Counterwallet? 75 | 76 | Counterwallet has unfortunately not been actively maintained in a number of years (see below). A bug was introduced into Counterparty last year (in [v9.61.1](https://github.com/CounterpartyXCP/counterparty-core/issues/1294)) which broke the Counterblock service that Counterwallet depends on. This bug was fixed in [Counterparty Core v10.0.0](https://github.com/CounterpartyXCP/counterparty-core/releases/tag/v10.0.0), however—as is often the case—when old software goes down, sometimes it doesn’t come back up. The community has since spent its energy on the creation of a new generation of wallets rather than attempt to revive Counterblock and Counterwallet. However, [the code is all open-source](https://github.com/CounterpartyXCP/counterwallet) and anyone is free to work on it. 77 | 78 | 79 | ### What is the “origin” functionality that was recently lost? 80 | 81 | Part of the protocol change that was implemented in [Counterparty Core v10.4.0](https://github.com/CounterpartyXCP/counterparty-core/releases/tag/v10.4.0) fixed two critical bugs in the design of dispensers. One of these fixes required the removal of *the ability for someone to open dispensers at an empty address that they don't own*. Per the [protocol spec published in August](https://docs.counterparty.io/docs/advanced/specifications/dispenser-must-be-created-by-source/), this change was necessary for two main reasons: 82 | 83 | 1. It resolves a critical security vulnerability whereby one user could force others to sell assets (e.g. illicit material) without their consent. 84 | 85 | 2. It allows for the elimination of the AddrIndexRs dependency for Counterparty Core. This piece of middleware is source of major stability, scalability and correctness issues in the node software. Removing AddrIndexRs makes Counterparty nodes dramatically faster and easier to deploy, and it shrinks the node storage requirements from around 250 GB to around 45 GB. 86 | 87 | Even with this protocol change, users can of course still open dispensers at empty addresses, it simply requires two transactions (send asset \+ BTC; open dispenser), which may be chained together. In effect, this doubles the Bitcoin transaction fee. The other new limitation is that it is no longer possible to open a dispenser at a cold wallet without actually *using* the cold wallet (with a second transaction). [Community consensus](https://github.com/CounterpartyXCP/counterparty-core/issues/1785) was that these trade-offs were perfectly reasonable given the severity of the problem. Moreover, the increase in transaction fees is temporary. There is already a [popular proposal for changing the Counterparty transaction format](https://github.com/CounterpartyXCP/counterparty-core/issues/2197) to allow for the bundling of multiple Counterparty transactions together in a single Bitcoin transaction. In addition, with [the adoption of modern data storage methods](https://github.com/CounterpartyXCP/counterparty-core/issues/1375), it will soon be able to dramatically reduce tx fees in the future (by around 75%). For any node host, the savings in storage costs from eliminating AddrIndexRs will easily outweigh the temporary increase in tx fees. 88 | -------------------------------------------------------------------------------- /docs/advanced/api-v2/v1-to-v2.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API v2 Migration Guide 3 | --- 4 | 5 | The main differences between the new v2 API and the deprecated v1 API are: 6 | 7 | - The new API is RESTful instead of RPC-based. 8 | - All requests use the `GET` method and so may be made easily from any browser. 9 | - The new API has fewer filters, but is optimized for the new log-structure database architecture. 10 | 11 | The v2 API also has HTTP Basic Authentication disabled by default. 12 | 13 | The following is a table of equivalent endpoints to help you easily migrate to the new version: 14 | 15 | ## Table of Equivalences between API v1 and v2 16 | 17 | ### Get Ledger State 18 | 19 | | API v1 | API v2 | 20 | | ------ | ------ | 21 | | `get_assets` | `/assets`
`/assets/`
`/events/ASSET_CREATION`
`/blocks//events/ASSET_CREATION` | 22 | | `get_balances` | `/assets//balances`
`/addresses/
/balances`
`/addresses/
/balances/`
`/assets//balances/
` | 23 | | `get_credits` | `/blocks//credits`
`/addresses/
/credits`
`/assets//credits`
`/events/CREDIT`
`/blocks//events/CREDIT` | 24 | | `get_debits` | `/blocks//debits`
`/addresses/
/debits`
`/assets//debits`
`/events/DEBIT`
`/blocks//events/DEBIT` | 25 | | `get_bets` | `/addresses//bets`
`/bets/`
`/events/OPEN_BET`
`/blocks//events/OPEN_BET` | 26 | | `get_bet_matches` | `/bets//matches`
`/events/BET_MATCH`
`/blocks//events/BET_MATCH` | 27 | | `get_broadcasts` | `/addresses//broadcasts`
`/events/BROADCAST`
`/blocks//events/BROADCAST` | 28 | | `get_btcpays` | `/orders//btcpays`
`/events/BTC_PAY`
`/blocks//events/BTC_PAY` | 29 | | `get_burns` | `/addresses/
/burns`
`/burns`
`/events/BURN`
`/blocks//events/BURN` | 30 | | `get_cancels` | `/blocks//cancels`
`/events/CANCEL_BET`
`/blocks//events/CANCEL_BET`
`/events/CANCEL_ORDER`
`/blocks//events/CANCEL_ORDER`
`/events/CANCEL_RPS`
`/blocks//events/CANCEL_RPS` | 31 | | `get_destructions` | `/blocks//destructions`
`/events/ASSET_DESTRUCTION`
`/blocks//events/ASSET_DESTRUCTION` | 32 | | `get_dividends` | `/assets//dividends`
`/events/ASSET_DIVIDEND`
`/blocks//events/ASSET_DIVIDEND` | 33 | | `get_issuances` | `/blocks//issuances`
`/assets//issuances`
`/events/ASSET_ISSUANCE`
`/blocks//events/ASSET_ISSUANCE` | 34 | | `get_orders` | `/assets//orders`
`/orders/`
`/events/OPEN_ORDER`
`/blocks//events/OPEN_ORDER` | 35 | | `get_order_matches` | `/orders//matches`
`/events/ORDER_MATCH`
`/blocks//events/ORDER_MATCH` | 36 | | `get_sends` | `/blocks//sends`
`/assets//sends`
`/addresses/
/sends`
`/addresses/
/receives`
`/addresses/
/sends/`
`/addresses/
/receives/`
`/events/SEND`
`/blocks//events/SEND`
`/events/MPMA_SEND`
`/blocks//events/MPMA_SEND`
`/events/ENHANCED_SEND`
`/blocks//events/ENHANCED_SEND` | 37 | | `get_bet_expirations` | `/blocks//expirations`
`/events/BET_EXPIRATION`
`/blocks//events/BET_EXPIRATION` | 38 | | `get_order_expirations` | `/blocks//expirations`
`/events/ORDER_EXPIRATION`
`/blocks//events/ORDER_EXPIRATION` | 39 | | `get_bet_match_expirations` | `/blocks//expirations`
`/events/BET_MATCH_EXPIRATION`
`/blocks//events/BET_MATCH_EXPIRATION` | 40 | | `get_order_match_expirations` | `/blocks//expirations`
`/events/ORDER_MATCH_EXPIRATION`
`/blocks//events/ORDER_MATCH_EXPIRATION` | 41 | | `get_bet_match_resolutions` | `/bets//resolutions`
`/events/BET_MATCH_RESOLUTON`
`/blocks//events/BET_MATCH_RESOLUTON` | 42 | | `get_rps` | `/events/OPEN_RPS`
`/blocks//events/OPEN_RPS` | 43 | | `get_rpsresolves` | `/events/RPS_RESOLVE`
`/blocks//events/RPS_RESOLVE` | 44 | | `get_rps_matches` | `/events/RPS_MATCH`
`/blocks//events/RPS_MATCH` | 45 | | `get_rps_expirations` | `/blocks//expirations`
`/events/RPS_EXPIRATION`
`/blocks//events/RPS_EXPIRATION` | 46 | | `get_rps_match_expirations` | `/blocks//expirations`
`/events/RPS_MATCH_EXPIRATION`
`/blocks//events/RPS_MATCH_EXPIRATION` | 47 | | `get_sweeps` | `/addresses/
/sweeps`
`/blocks//sweeps`
`/events/SWEEP`
`/blocks//events/SWEEP` | 48 | | `get_dispensers` | `/assets//dispensers`
`/asset//dispensers/
`
`/addresses/
/dispensers`
`/addresses/
/dispensers/`
`/dispensers/`
`/events/OPEN_DISPENSER`
`/blocks//events/OPEN_DISPENSER` | 49 | | `get_dispenses` | `/blocks//dispenses`
`/dispensers//dispenses`
`/events/DISPENSE`
`/blocks//events/DISPENSE` | 50 | | `get_transactions` | `/blocks//transactions`
`/transactions/`
`/events/NEW_TRANSACTION`
`/blocks//events/NEW_TRANSACTION` | 51 | | `get_messages` | `/blocks//events`
`/blocks//events/`
`/events/` | 52 | | `get_messages_by_index` | `/events/` | 53 | | `get_supply` | `/assets/` | 54 | | `get_xcp_supply` | `/assets/XCP` | 55 | | `get_asset_info` | `/assets/` | 56 | | `get_block_info` | `/blocks/`
`/blocks//events` | 57 | | `get_blocks`| `/blocks` | 58 | | `get_asset_names` | `/assets` | 59 | | `get_asset_longnames` | `/assets` | 60 | | `get_holder_count` | `/assets/` | 61 | | `get_holders` | `/assets//holders` | 62 | | `get_dispenser_info` | `/dispensers/` | 63 | | `get_mempool` | `/mempool/events`
`/mempool/events/` | 64 | | `get_element_counts` | `/blocks//events/counts`
`/events/counts` | 65 | | `sql` | NA | 66 | 67 | ### Compose and Parse Transactions 68 | 69 | | API v1 | API v2 | 70 | | ------ | ------ | 71 | | `create_bet` | `/addresses/
/compose/bet` | 72 | | `create_broadcast` | `/addresses/
/compose/broadcast` | 73 | | `create_btcpay` | `/addresses/
/compose/btcpay` | 74 | | `create_burn` | `/addresses/
/compose/burn` | 75 | | `create_cancel` | `/addresses/
/compose/cancel` | 76 | | `create_destroy` | `/addresses/
/compose/destroy` | 77 | | `create_dividend` | `/addresses/
/compose/dividend` | 78 | | `create_issuance` | `/addresses/
/compose/issuance` | 79 | | `create_order` | `/addresses/
/compose/order` | 80 | | `create_send` | `/addresses/
/compose/send` | 81 | | `create_rps` | N/A | 82 | | `create_rpsresolve` | N/A | 83 | | `create_sweep` | `/addresses/
/compose/sweep` | 84 | | `create_dispenser` | `/addresses/
/compose/dispenser` | 85 | | `get_tx_info` | `/transactions/info` | 86 | | `unpack` | `/transactions/unpack` | 87 | 88 | 89 | ### Get Server State 90 | 91 | | API v1 | API v2 | 92 | | ------ | ------ | 93 | | `get_running_info` | `/` | 94 | | `/healthz` | `/healthz` | 95 | 96 | 97 | ### Backend Proxy 98 | 99 | | API v1 | API v2 | 100 | | ------ | ------ | 101 | | `search_raw_transactions` | `/backend/addresses/
/transactions` | 102 | | `get_oldest_tx` | `/backend/addresses/
/transactions/oldest` | 103 | | `get_unspent_txouts` | `/backend/addresses/
/utxos` | 104 | | `getrawtransaction` | `/backend/transactions/` | 105 | | `getrawtransaction_batch` | `/backend/transactions` | 106 | | `search_pubkey` | `/backend/addresses/
/pubkey` | 107 | | `fee_per_kb` | `/backend/estimatesmartfee` | 108 | -------------------------------------------------------------------------------- /docs/basics/assets/counterparty-assets.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Understanding Assets on Counterparty 3 | --- 4 | 5 | 6 | With Counterparty, users can create their own assets (also known as "tokens", "coins" or "currencies") _inside_ the Bitcoin blockchain. These are seperate from Bitcoin the currency itself, but exist entirely inside ordinary Bitcoin transactions. Tokens can be received, stored, and sent from any Bitcoin address to any other. They can also be placed in cold storage. Unlike Colored Coins, Counterparty tokens are _not_ tied to the BTC balance of any given address. This means that sending/receiving bitcoins has no effect on the balance of tokens. 7 | 8 | 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. 9 | 10 | 11 | ## Creating assets 12 | 13 | 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. 14 | 15 | *You can create two different types of assets:* 16 | 17 | 1. **Named**: A unique string of 4 to 12 uppercase Latin characters (inclusive) not beginning with ‘A’. Alphabetic tokens carry a one‐time issuance fee of `0.5 XCP` to discourage spam and squatting. This fee is burned (permanently taken out of circulation). `BTC` and `XCP` are the only three‐character asset names. For more information, see the Assets section in the Counterparty specification. 18 | 19 | 2. **Numeric (Free)**: An integer between `26^12 + 1` and `256^8` (inclusive), prefixed with `A`. Numeric assets only require one Bitcoin transaction fee to be created. 20 | 21 | ### The different kinds of assets 22 | 23 | The most basic kind of asset must specify: 24 | 25 | - who is issuing it (`source`) 26 | - the name of the asset (`asset`) 27 | - how much of `asset` is being issued (`quantity`) 28 | - a description of asset (`description`) 29 | 30 | It is possible to issue more of `asset`, but, at any one time, there can only be one address which issues `asset`. With that said, the Counterparty protocol allows `source` to transfer issuance rights of `asset`. Moreover, an asset can also be locked, so that there can be no further issuances of it. (See the instructions on how to do this with `counterparty-wallet`). A description must always be included, even if `description` is just an empty string; the syntax of an asset *with no description* is `description=""`. 31 | Beyond creating the most basic asset, it is also possible to make assets either *divisible* or *callable*. If an asset is made divisible (or callable) upon its initial issuance, it must always be divisible (or 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. 32 | 33 | ## Sending assets (`send`) 34 | 35 | To send an asset in Counterparty, one must specify: 36 | 37 | - who is sending the asset (`source`) 38 | - what asset `source` is sending (`asset`) 39 | - how much of `asset` `source` is sending (`quantity`) 40 | - to whom `source` is sending `quantity` of asset (`destination`) 41 | 42 | ## Paying distributions on assets 43 | 44 | 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: Let `total` equal the total distribution paid out, and `quantity` be the total amount of asset, then: `quantity-per-unit = total/quantity` 45 | 46 | Distributions can be paid out to any assets that you ownership and control over. You can freely select the currency in which distributions are to be paid out: BTC, XCP, or any other user-created asset. 47 | 48 | ## Trading on the decentralized exchange 49 | 50 | Counterparty supports *peer-to-peer asset exchange*: users can trade assets with no middleman and no counterparty risk. The platform upon which trading is done is Counterparty’s *decentralized exchange* and the Bitcoin blockchain. In what follows trading on the decentralized exchange will be detailed and explained by means of examples. For the purposes of the following use-cases: 51 | 52 | - “ordern” denotes the *nth* order in time, `give_asset n` denotes 53 | the asset being given in the order, etc. 54 | - Sally’s creates order1 and Alice creates order2 55 | - `give_asset2 = get_asset1` 56 | 57 | ### Creating an order 58 | 59 | At its most basic level, a trade on Counterparty’s decentralized 60 | exchange consists of two *orders*, which are *matched* by the protocol. 61 | When Sally is constructing her order, she must specify: 62 | 63 | - her address (`source`1) 64 | - the asset she will give (`give_asset1`) 65 | - the quantity of `give_asset1` she will give (`give_quantity1`) 66 | - the asset she will get (`get_asset`) 67 | - the quantity of `get_asset1` she will get (`get_quantity`) 68 | - how long before her order expires (`expiration1`) 69 | 70 | ### Protocol-based trustless escrow 71 | 72 | **The Counterparty protocol acts as an escrow service, and thereby eliminates counterparty risk from the exchange of assets.** Once Sally publishes her order `give_quantity1` of `give_asset1` is debited from her address; her address is debited *before* her order is matched with Alice’s, and so she cannot spend those funds before `expiration1` passes, i.e. until her order expires. In the meantime, Sally’s funds are not lost or borrowed, they are held by the protocol itself. If another order is placed which satisfies Sally’s order, the protocol matches them, and sends each counterparty its respective funds. 73 | 74 | #### Automatic order matching on the Bitcoin blockchain 75 | 76 | `give_quantity1 / get_quantity1` is the "ratio" in which Sally will exchange `give_asset1` for `get_asset1`, and is denoted by `ratio1`. In order for two orders to be matched, `ratio1 must always be’‘greater than or equal’’ to the inverse of `ratio2`, Thus, if, for example `ratio2 (give_quantity1 + 1) / get_quantity1` would be high enough ratio to match Sally’s bet, but if `ratio2 =(quantity2 - 1) / quantity2` it would not. Having been matched, the exchange is always made at `ratio1`. Further, when when an order is matched, the exchange is always settled as much as it can be. 77 | 78 | #### A straightforward case 79 | 80 | Suppose that Alice places order2 before `expiration`1 which matches order1 perfectly: `give_quantity2 == get_quantity1` `get_quantity2 == give_quantity1`. Once Alice has made her order, the protocol debits `quantity2` of `asset2` from her address, and, since her order satisfies Sally’s, Alice’s order funds are sent to Alice, and Sally’s order funds are sent to Alice. This completes the trade between Alice and Sally. 81 | 82 | #### Matching an order: partially fulfilling an order 83 | 84 | For the following example, let `give_quantity1 = 10` and `get_quantity1 = 20`, and that neither `give_asset1` nor `get_asset1` is BTC. Suppose that Alice wants to match Sally’s order, does not want all 10 of `give_asset`; rather, she only wants 8. 85 | 86 | Since the `ratio1 == 10/20 == 1/2`, Alice must `ratio2 >= 2/1`, to match Sally’s order. In other words Alice must offer ‘’at least’‘16 of `asset_2` to get 8 of `asset_1` from Sally’s order. Let’s say Alice constructs order2 such that `give_quantity2 == 18` and hence `ratio2 = 18/8 > 2/1`. The order will be settled at `ratio1`: for every unit of `give_asset1` that Sally gives Alice, she will get two units of `get_asset1`. Moreover, since every trade is settled as much and `give_quantity2 == 18` Sally will receive’‘18’’ `get_asset1` in exchange for 9 `give_asset1`. 87 | 88 | #### Trading BTC on the Decentralized Exchange 89 | 90 | Suppose Sally makes an order to trade `asset` in exchange for BTC, and Alice makes an order to trade BTC in exchange for `asset`. Upon placing order1, Sally’s account is immediately debited, as usual, and, once Alice has placed `order2`, it is matched with `order1`. However, her BTC is not debited from her account, and the protocol will not send her Sally’s XCP until Alice sends her BTC using Counterparty’s `btcpay` function. If Alice sends the BTC using `btcpay` in ‘’fewer than 10 blocks’’, the protocol will send her the XCP and thereby complete the transaction, otherwise, the trade expires, and the protocol will re-credit Sally’s address with `give_asset`. 91 | -------------------------------------------------------------------------------- /docs/advanced/specifications/fairminter.md: -------------------------------------------------------------------------------- 1 | # Fair Minting 2 | 3 | # Motivation 4 | 5 | **Fair Minting** is a process whereby users are able to “mint” tokens in a decentralized manner. One user initiates a minter (either with or without a “premint”), and others are able to trigger it to mint tokens for themselves. Fair Minting was likely inspired by the original Counterparty **Proof-of-Burn** mechanism, by which users sent BTC to an unspendable address and XCP tokens were generated for them. 6 | 7 | More recently, **BRC-20** introduced a variant of the Fair Minting model that has recently been adopted by many fungible token protocols including SRC-20 on Bitcoin Stamps. In this system, users are able to mint "for free" paying only a miner fee: the term “fair mint” refers to the fact that the creator of the minting system is not enriched in the process and that the minting process is decentralized 8 | 9 | In 2023, Joe Looney introduced the [**”XCP-20”** Fair Mint model](https://xcp20.wtf/) by setting up a **dispenser on a burn address**; its name is a tongue-in-cheek reference to BRC-20. Buyers, largely unaware that Counterparty existed—and this was not new in any way—sent massive amounts of Bitcoin to the burn address and received tokens in return. In this way, tokens got distributed, but the deployer was not directly enriched. 10 | 11 | 12 | # Design 13 | 14 | The primary goal is to create a native mechanism for Fair Minting so that a burn address isn’t used. Additionally native support allows for multiple extensions of the core Fair Minting system. 15 | 16 | 1. Miner Fees Only, with a Max Mint per Transaction 17 | 2. XCP Fee with a Price per Unit Token (Distributed to Issuer) 18 | 3. XCP Fee with a Price per Unit (Burned) 19 | 4. A “soft cap” mechanism, establishing a minimum amount of the token to be issued, optionally by a particular block height. (Before `soft_cap_deadline_block` payment will be escrowed trustlessly.) 20 | 5. A commission in the new token sent to the creator of the mint for each mint operation (proportional to the quantity minted) 21 | 6. A “Start Block” and “End Block” 22 | 23 | 24 | The Fair Minting system allows users to issue assets through a fair and controlled minting process. It involves two primary entities: Fairminters and Fairmints. 25 | 26 | - **Fairminter**: Represents the rules and constraints under which an asset can be minted. 27 | - **Fairmint**: Represents an individual minting event tied to a specific fairminter. 28 | 29 | - Fair Minters can be added to existing assets as long as those assets do not have locked quantities. 30 | - The `premint` quantity will be credited to the issuer at the `start_block`. 31 | - If an asset can be reset it can also be Fair Minted, but fair minting itself would not first effect an asset reset. 32 | - Outside the fair minting period the `hard_cap` has no effect. To lock the quantity you have to use the parameter `lock_quantity=true` or use an issuance after the minting period. 33 | - For the duration of the mint period, the state of description lock and quantity lock cannot be changed. 34 | - In the Fair Minting system, creating a fairminter additionally triggers the creation of an issuance for the referenced asset. If the asset does not exist then it will be created. 35 | 36 | - `minted_asset_commision` must be between `0` and `1` 37 | - `price` and `max_mint_per_tx` *cannot both* be `0` 38 | - `end_block` must be greater than `start_block` 39 | - `soft_cap` must be less than `hard_cap` 40 | - `soft_cap` and `soft_cap_deadline_block` must be set together 41 | - `soft_cap_deadline_block` must be less than `end_block` and greater than `start_block` 42 | - If the asset exists 43 | - It must *not* currently have an `open` fairminter 44 | - It must *not* be locked 45 | - The asset `issuer` must match the fairminter's `source` 46 | - If the asset's description is locked then the fairminter's description must be `""` or match the existing description 47 | - The existing supply plus `premint_quantity` must not exceed the `hard_cap` 48 | - `divisible` must match the existing `divisible` 49 | - If the asset does not exist 50 | - If `asset_parent` is a provided argument then the asset it references must exist 51 | - If `asset` is not a numeric asset then the `source`s balance must be sufficient to pay a `0.5 XCP` fee 52 | - `asset` and `asset_parent` must respect the named asset format 53 | - If `asset` does not exist one will be created 54 | - `premint_quantity` of asset will be credited to the `source` if there is no soft cap and the status is open otherwise it will be held in escrow 55 | - If there is a fee the `source` will be debited that amount 56 | - An `open` fairminter must exist for `asset` 57 | - If `Fairminter.price` is `0` `quantity` must be supplied as `0` or omitted. `Fairminter.max_mint_per_tx` is used instead 58 | - `quantity` must be greater than `0` 59 | - `quantity` cannot exceed `Fairminter.max_mint_per_tx` if set 60 | - The existing supply plus `quantity` cannot exceed `Farminter.hard_cap` if set 61 | - `Fairmint.source` must have a sufficient balance to cover the cost 62 | - If the soft cap has *not* been reached both the XCP and asset amounts will be escrowed 63 | - If the hard cap is hit 64 | - quantity and description are locked 65 | - soft cap is implicitly hit and payouts are made if they have not been already 66 | - If `Fairminter.burn_payment` is `True` then the XCP used to mint the asset will be destroyed; otherwise it will be sent to `Fairminter.source` 67 | - The `Fairmint.source` will be credited with `quantity` of the asset. 68 | - When the `end_block` is reached, the fairminter closes. 69 | - If `lock_quantity=True`, the issuances table records the final issuance event with locked=True. 70 | 71 | 72 | # API 73 | 74 | - Get All Fair Minters: `/v2/fairminters` 75 | - Get Fair Minter By Tx Hash: `/v2/fairminters/` 76 | - Get Fair Minter By Asset: `/v2/assets//fairminter` 77 | - Get Fair Minters By Address: `/v2/addresses/
/fairminters` 78 | - Get Mints By Fair Minter: `/v2/fairminters//mints` 79 | - Get Mints By Asset: `/v2/assets//mints` 80 | - Get Mints By Address: `/v2/addresses/
/mints` 81 | 82 | ## Fairminter 83 | 84 | A fairminter defines the rules under which an asset is minted. This table stores configuration details such as price, supply limits, soft/hard caps, and minting constraints. 85 | 86 | `tx_hash`: *TEXT* - Hash of the transaction that created the fairminter. 87 | 88 | `tx_index`: *INTEGER* - Index of the transaction. 89 | 90 | `block_index`: *INTEGER* - Index of the block containing the transaction. 91 | 92 | `source`: *TEXT* - Address of the fairminter creator. 93 | 94 | `asset`: *TEXT* - The asset to be minted. 95 | 96 | `asset_parent`: *TEXT* - Parent asset of the asset. 97 | 98 | `asset_longname`: *TEXT* - Full name of the asset (parent + asset name). 99 | 100 | `description`: *TEXT* - Description of the asset. 101 | 102 | `price`: *INTEGER* - Price per unit of the asset, in XCP Satoshis. 103 | 104 | `quantity_by_price`: *INTEGER* - Units of the asset minted per price unit. 105 | 106 | `hard_cap`: *INTEGER* - Maximum supply that can be minted (asset limit). 107 | 108 | `burn_payment`: *BOOL* - If True, payment is burned instead of credited to the issuer. 109 | 110 | `max_mint_per_tx`: *INTEGER* - Maximum amount of assets that can be minted per transaction. 111 | 112 | `premint_quantity`: *INTEGER* - Quantity pre-minted when the Fairminter opens. 113 | 114 | `start_block`: *INTEGER* - Block index when the minting becomes open. 115 | 116 | `end_block`: *INTEGER* - Block index when the minting ends. 117 | 118 | `minted_asset_commission_int`: *INTEGER* - Commission percentage (in millionths) to the issuer for each mint. 119 | 120 | `soft_cap`: *INTEGER* - Minimum quantity that needs to be minted for the Fairminter to succeed. 121 | 122 | `soft_cap_deadline_block`: *INTEGER* - Block index when the soft cap must be reached. 123 | 124 | `lock_description`: *BOOL* - If True, locks the description of the asset. 125 | 126 | `lock_quantity`: *BOOL* - If True, locks the quantity minted after the Fairminter closes. 127 | 128 | `divisible`: *BOOL* - If True, the asset can be divided into fractions. 129 | 130 | `pre_minted`: *BOOL* - Indicates if the premint quantity has already been issued. 131 | 132 | `status`: *TEXT* - Current status of the fairminter (pending, open, or closed). 133 | 134 | 135 | ## Fairmint 136 | 137 | A fairmint records an individual minting event under a fairminter. This includes the amount minted, the payment made, and the commission, if any, awarded to the issuer. 138 | 139 | `tx_hash`: *TEXT* - Hash of the transaction that created the mint. 140 | 141 | `tx_index`: *INTEGER* - Transaction index. 142 | 143 | `block_index`: *INTEGER* - Index of the block containing the transaction. 144 | 145 | `source`: *TEXT* - Address of the user who performed the mint. 146 | 147 | `fairminter_tx_hash`: *TEXT* - Transaction hash of the associated fairminter. 148 | 149 | `asset`: *TEXT* - The asset being minted. 150 | 151 | `earn_quantity`: *INTEGER* - Quantity of the asset earned by the minter. 152 | 153 | `paid_quantity`: *INTEGER* - Amount of XCP paid by the minter. 154 | 155 | `commission`: *INTEGER* - Commission awarded to the issuer. 156 | 157 | `status`: *TEXT* - Status of the mint (valid or invalid). 158 | -------------------------------------------------------------------------------- /docs/basics/assets/enhanced-feed.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Enhanced Feed Info 3 | --- 4 | 5 | Feed providers can initialize a feed via a broadcast where the broadcast text field contains a URL to a specially formatted .json file (e.g. http://www.mydomain.com/foo.json). This allows the feed operator to provide enhanced information to their users. 6 | 7 | 8 | ## Feed URL format 9 | 10 | The URL itself in the broadcast text field must conform to the following: 11 | * Must fully fit within the text field space allowed 12 | * May or may not start with "http://" or "https://". If the URL does not start with either, "http://" is assumed 13 | * May or may not end with ".json" (i.e., no specific file name ending is required) 14 | * It is recommended that the server return the JSON data with the correct MIME type set (e.g. "application/json") 15 | * A HTTP 200 response code must be returned (redirects, e.g. 301, 302, etc. are not allowed) 16 | 17 | ## Feed JSON format 18 | 19 | The JSON object/mapping data the URL points to must contain the following data: 20 | 21 | 22 | 23 | 24 | 25 | 26 | 27 | 28 | 29 | 30 | 31 | 32 | 33 | 34 | 35 | 36 | 37 | 38 | 39 | 40 | 41 |
addressRequiredThe Bitcoin address used to broadcast the json url and that will broadcast the result.
titleRequiredThe title of the feed. 64 characters max.
broadcast_dateRequiredWhen the bet will be resolved. When type=binary broadcast_date must be a rfc3339 date. When type=cfd broadcast_date must be an iso8601 repeating interval.
deadline Required if type='cfd'.Must be an iso8601 repeating interval.
targets Required if type='binary'.A list/array of JSON objects. Each object contains details about a potential user choice for the bet. Normally, with binary bets, there is only one target object provided. However, it is possible to provide more than one, but in this case, the user would be able to bet yes or no for each option (meaning, if two targets were provided, there would be 4 separate user choices possible).
typeOptionalThe type of the bet. Must be one of: 'binary', 'cfd' or 'all'. If type is not specified, targets OR deadline MUST be provided.
categoryOptionalThe nature of the feed. Must be one of: 'sports', 'politics', 'entertainment', 'economics', or 'other'.
descriptionOptionalA longish description about this feed. 255 characters max.
imageOptionalA link a 48x48 PNG image to represent the feed in the graphical user interface listing. The text itself must be a valid URL that starts with "http://" or "https://". The image the URL references must be in PNG format (the URL must end in .png). It must be 48x48, and it must use the RGB or RGBA color palette. If any of these are not correct, the system will reject it.
urlOptionalA link to the website for the feed. 100 characters max. Must be a valid URL that starts with "http://" or "https://"
operatorOptionalObject that contains informations about the feed operator.
customsOptionalObject that contains additional custom informations about the feed. All values should be integer or string.
versionOptionalVersion of the schema used for the json (current 1.0).
labelsOptional Labels used for CFD bets.
labels.bullRequired Label for bet type equal BullCFD. 32 characters max.
labels.bearRequired Label for bet type equal BearCFD. 32 characters max.
oddsOptional Object that contains default odds for Bull bets (the inverse is used for Bear bets).
odds.initialRequired (or odds.suggested)Default odds used when there is not open bets.
odds.suggestedRequired (or odds.initial)Default odds used when there is open bets.
42 | 43 |
44 | 'targets' Object format: 45 | 46 | 47 | 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 |
textRequiredTopic of the target_value. 64 characters max.
valueRequiredThe value used for this target_value.
deadlineRequiredThe exact or approximate time that the feed will be resolved.
imageOptionalA link a 48x48 PNG image to represent the target_value in the graphical user interface listing.
labelsOptional Object that contains labels used for each bet type.
labels.equalRequired Label for Equal. 32 characters max.
labels.not_equalRequired Label for NotEqual. 32 characters max.
oddsOptional Object that contains default odds for Equal bets (the inverse is used for NotEqual bets).
odds.initialRequired (or odds.suggested)Default odds used when there is not open bets.
odds.suggestedRequired (or odds.initial)Default odds used when there is open bets.
57 | 58 |
59 | 'operator' fields: 60 | 61 | 62 | 63 | 64 | 65 |
nameRequiredThe operator name.
descriptionOptionalA longish description about the operator. 2048 characters max.
imageOptionalA link a 48x48 PNG image to represent the operator in the graphical user interface listing.
urlOptionalA link to the website for the operator. 100 characters max. Must be a valid URL that starts with "http://" or "https://"
66 | 67 | 68 | ## Examples 69 | 70 | Here's an example for a binary feed called Superbowl 2014: 71 | 72 | ```json 73 | { 74 | "version": "1.0", 75 | "address": "muYJYjRZDPmTEMfyEGe34BGN8tZ6rmRZCu", 76 | "type": "binary", 77 | "category": "sports", 78 | "title": "Superbowl 2014", 79 | "image": "https://www.jahpowerbit.org/feeds/image-1.png", 80 | "description": "The feed for the Super Bowl final", 81 | "url": "http://www.jahpowerbit.org/superbowl2014", 82 | "broadcast_date": "2014-11-01T05:06:07+00:00", 83 | "operator": { 84 | "name": "JahPowerBit", 85 | "image": "https://www.jahpowerbit.org/feeds/image-1.png", 86 | "description": "Development site", 87 | "url": "http://www.jahpowerbit.org" 88 | }, 89 | "targets": [{ 90 | "text": "The Bronco wins", 91 | "image": "https://www.jahpowerbit.org/feeds/image-1.png", 92 | "value": 1, 93 | "labels": { 94 | "equal": "yes", 95 | "not_equal": "no" 96 | }, 97 | "odds": { 98 | "initial": 2, 99 | "suggested": 3 100 | }, 101 | "deadline": "2014-07-01T05:06:07+00:00" 102 | }, { 103 | "text": "The Seahawks wins", 104 | "image": "https://www.jahpowerbit.org/feeds/image-1.png", 105 | "value": 2, 106 | "labels": { 107 | "equal": "yes", 108 | "not_equal": "no" 109 | }, 110 | "deadline": "2014-07-01T05:06:07+00:00" 111 | }, { 112 | "text": "They draw", 113 | "image": "https://www.jahpowerbit.org/feeds/image-1.png", 114 | "value": 3, 115 | "labels": { 116 | "equal": "yes", 117 | "not_equal": "no" 118 | }, 119 | "odds": { 120 | "initial": 3, 121 | "suggested": 4 122 | }, 123 | "deadline": "2014-09-01T05:06:07+00:00" 124 | }], 125 | "customs": { 126 | "key1": "value1", 127 | "key2": 2 128 | } 129 | } 130 | ``` 131 | 132 | ## Other Topics 133 | 134 | ### Validity and refreshing 135 | In order for this data file to be deemed as valid against the specified address, there must have been a broadcast at that address, and the text field of that broadcast must have been set to the URL of this JSON file and the value field set to -1 (negative 1). From this feed broadcast, Counterwallet system will pull the fee-fraction, to use as the fee for the given feed, and will query this URL provided to validate and fetch the necessary information. 136 | 137 | If the information you provided is reachable and valid (within a 5 second response time), the feed's information will be enhanced based on this data. If it is not, counterblockd will retry up to 2 additional times, over the next 30 or so minutes, and then give up until rebroadcast is made with a JSON URL and value=-1 (the URL may be the same). 138 | 139 | ### Validating your JSON data 140 | 141 | Your JSON data must respect and validate against [this](https://github.com/CounterpartyXCP/counterblock/blob/master/counterblock/schemas/feed.schema.json) JSON schema. If the validation fails on any level, counterblockd will not accept the data. 142 | 143 | To check your data against this schema, go [here](http://json-schema-validator.herokuapp.com/). Paste the schema from the link above into the '''Schema''' field, and place your example output into the '''Data''' field. Then click the '''Validate''' button. 144 | -------------------------------------------------------------------------------- /static/img/undraw_docusaurus_tree.svg: -------------------------------------------------------------------------------- 1 | docu_tree -------------------------------------------------------------------------------- /docs/advanced/command-line-interface/usage.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Command-line (CLI) Guide 3 | --- 4 | 5 | 6 | The following examples are abridged for parsimony (meaning: actions are 7 | normally preceded by `counterparty-client`, i.e. the `burn` command would be 8 | called with `counterparty-client --testnet burn`). 9 | 10 | `counterparty-server` should always be running in the background (or 11 | another console). All other commands will fail if the index of the last 12 | block in the database is less than that of the last block seen by 13 | Bitcoin Core. 14 | 15 | Burn 16 | ---- 17 | *Destroy BTC to earn XCP, during an initial period of time* 18 | 19 | The `burn` command is currently usable only on testnet because on mainnet 20 | the burn period finished in early 2014. 21 | 22 | * --source = the source address 23 | * --quantity = quantity of BTC to be burned 24 | * --fee = the exact BTC fee to be paid to miners 25 | 26 | 27 | 28 | burn --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --quantity=0.5 29 | 30 | 31 | Send 32 | ---------------------------------------- 33 | *Create and broadcast a `send` message* 34 | 35 | * --source = the source address 36 | * --destination = the destination address 37 | * --quantity = the quantity of ASSET to send 38 | * --asset = the ASSET of which you would like to send QUANTITY 39 | * --fee = the exact BTC fee to be paid to miners 40 | 41 | 42 | 43 | send --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --quantity=3 \ 44 | --asset=BBBC --destination=n3BrDB6zDiEPWEE6wLxywFb4Yp9ZY5fHM7 45 | 46 | 47 | Dispenser 48 | ---------------------------------------- 49 | *Create and broadcast a `dispenser` message* 50 | 51 | * --source = the source address 52 | * --give_quantity = the quantity of ASSET to send on each dispense 53 | * --escrow_quantity = the quantity of ASSET to escrow for the dispenser 54 | * --mainchainrate = the quantity of BTC to receive for each give_quantity sent 55 | * --asset = the ASSET of which you would like to dispense 56 | * --status = the status of the dispenser (0 open, 10 close) 57 | 58 | 59 | 60 | dispenser --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --give_quantity=3 \ 61 | --escrow_quantity=3000 --asset=BBBC --mainchainrate=0.01 --status=10 62 | 63 | Order 64 | ---------------------------------------- 65 | *Create and broadcast an `order` message* 66 | 67 | * --source = the source address 68 | * --get-quantity = the quantity of GET_ASSET that the source would like to receive 69 | * --get-asset = the asset that you would like to buy 70 | * --give-quantity = the quantity of GIVE_ASSET that the source is willing to give 71 | * --give-asset = the asset that the source would like to sell 72 | * --expiration = the number of blocks for which the order should be valid 73 | * --fee-fraction-required = the miners’ fee required for an order to match 74 | * --fee = the exact BTC fee to be paid to miners 75 | 76 | To make a trade that involves BTC, the `order` function requires an 77 | extra parameter, and a second step (`btcpay`) is needed. If [address_1] is trading 78 | [give_quantity_1] of BTC in exchange for [get_quantity_1] of [asset]. 79 | 80 | 81 | order --source=[address_1] --give-asset=BTC --give-quantity=[give_quantity_1] \ 82 | --get-asset=[asset] --get-quantity=[get_quantity_1] --fee-provided=[fee_provided] \ 83 | --expiration=[expiration_1] 84 | 85 | If [address_2] is trading [give_quantity_2] of [asset] for [get_quantity_2] of BTC: 86 | 87 | 88 | order --source=[address_2] --give-asset=[asset] --give-quantity=[give_quantity_2] \ 89 | --get-asset=BTC --get-quantity=[get_quantity_2] --fee-required=[fee_required] \ 90 | --expiration=[expiration_2] 91 | 92 | 93 | [asset] is debited immediately from [address_2] and is held in the Counterparty 94 | protocol's escrow. [address_1] then must complete the trade using `btcpay` before 10 95 | blocks have passed (or the lesser of the two `expiration` periods has passed, 96 | if the latter is less than 10 blocks from the time of match). After the payment 97 | transaction has received enough confirmations, the asset will be automatically 98 | released to the BTC seller by the Counterparty protocol. 99 | 100 | The command for a `btcpay` is: 101 | 102 | 103 | btcpay --source=[source_address] -–order-match-id=[txhash1]+[txhash2] 104 | 105 | 106 | order --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --get-quantity=10 \ 107 | --get-asset=BTC --give-quantity=20 --give-asset=XCP --expiration=10 \ 108 | --fee_required=0.0002 109 | 110 | 111 | order --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --get-quantity=10 \ 112 | --get-asset=BBBC --give-quantity=20 --give-asset=BTC --expiration=10 \ 113 | --fee_provided=0.0002 114 | 115 | For orders that do not involve BTC buy or sell, `BTCpay` is not required. 116 | For Sally to receive [get_quantity_1] of [get_asset_1] in exchange for 117 | [give_quantity_1] of [give_asset_1], the command is the following: 118 | 119 | 120 | order --source=[sallys_address] --give-asset=[give_asset_1] \ 121 | --give-quantity=[give_quantity_1] --get-asset=[get_asset_1] \ 122 | --get-quantity=[get_quantity_1] --expiration=expiration_1 123 | 124 | In order for Alice to receive [get_quantity_2] of Sally's [give_asset_1] 125 | in exchange for [give_quantity_2] of [get_asset_2], the command is: 126 | 127 | 128 | order --source=[alices_address] --give-asset=[give_asset_2] \ 129 | --give-quantity=[give_quantity_2] --get-asset=[get_asset_2] \ 130 | --get-quantity=[get_quantity_2] --expiration=expiration_2 131 | 132 | For example, Alice wants to sell 20 BBBC for 10 XCP within (expiration) 133 | 144 bitcoin blocks (approximately 144 * 10 min = 24 hours): 134 | 135 | 136 | order --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --get-quantity=10 \ 137 | --get-asset=XCP --give-quantity=20 --give-asset=BBBC --expiration=144 138 | 139 | Note that orders can be partially matched. 140 | 141 | BTCPay 142 | ---------------------------------------- 143 | *Create and broadcast a `BTCpay` message, to settle an Order Match for which you owe* 144 | 145 | BTC Pay has been disabled in Counterwallet, but remains available in the 146 | CLI (and API). 147 | 148 | * --source = the source address 149 | * --order-match-id = the underscore-separated concatenation of the hashes of the two transactions which compose the order match 150 | * --fee = the exact BTC fee to be paid to miners 151 | 152 | 153 | 154 | btcpay --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns \ 155 | --order-match-id=092f15d36786136c4d868c3335_6ec3c9b5a0c77de54ed0e96a8dbdd8af160c23 156 | 157 | Order Match ID can be obtained with the `pending` command. The source address of BTC sell 158 | has 20 blocks (or approximately 200 minutes) after his offer has been matched) to send 159 | BTC to fund his side of transaction, but should wait for the order-matching transaction to 160 | receive several confirmations because BTC cannot be escrowed by the Counterparty protocol. 161 | 162 | Use the `pending` command to display own DEx order matches that require BTCpay and 163 | make sure you use the correct `source` address to fund each pending BTCpay. 164 | 165 | Issuance 166 | ------------------------ 167 | *Issue a new asset, issue more of an existing asset or transfer the ownership of an asset.* 168 | 169 | * --source = the source address 170 | * --transfer-destination = for transfer of ownership of asset issuance rights. 171 | * --quantity = the quantity of ASSET to be issued 172 | * --asset = the name of the asset to be issued (if it’s available) 173 | * --divisible = the asset is divisible (must agree with previous issuances; omitted means indivisible) 174 | * --description = a description of the asset (set to ‘LOCK’ to lock against further issuances with non‐zero quantities). It can be up to 41 bytes with opreturn and up to 52 with pubkeyhash (see Optional Arguments further below). 175 | * --fee = the exact fee to be paid to miners 176 | 177 | Assets can be divisible or indivisible (the smallest unit is 1). Issuance and transfer 178 | cannot happen in the same transaction. 179 | 180 | 181 | issuance --source=[source] --quantity=[quantity] --asset=[asset] 182 | 183 | 184 | issuance --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --quantity=100 \ 185 | --asset='BBBQ' --divisible 186 | 187 | 188 | Destroy 189 | ------------ 190 | *Destroy a quantity of a Counterparty asset* 191 | 192 | * --source = the source address 193 | * --asset = the ASSET of which you would like to destroy QUANTITY 194 | * --quantity = the quantity of ASSET to destroy 195 | * --tag = tag 196 | * --fee = the exact BTC fee to be paid to miners 197 | 198 | This command is not yet implemented (enabled). 199 | 200 | 201 | Broadcast 202 | ---------------------------------------- 203 | 204 | *Broadcast textual and numerical information to the network.* 205 | 206 | * --source = the source address 207 | * --text = the textual part of the broadcast (set to ‘LOCK’ to lock feed) 208 | * --value = numerical value of the broadcast 209 | * --fee-fraction = the fraction of bets on this feed that go to its operator 210 | * --fee = the exact fee to be paid to miners 211 | 212 | 213 | 214 | broadcast --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --text="Bitcoin price feed" \ 215 | --value=825.22 216 | 217 | 218 | **Note:** for some users counterparty-wallet has trouble parsing spaces in the 219 | `--text` argument. One workaround is to add an additional set of quotes. 220 | For example, `--text='"Bitcoin price feed"'`. This may not work on 221 | Windows due to Python/Windows issues unrelated to Counterparty. Another 222 | situation where double quotes may be required on Windows is filtering 223 | (e.g. `--filter "source" "=" "mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns"`). 224 | 225 | 226 | Bet (Equal or Not Equal) 227 | ---------------------------------------- 228 | *Offer to make a bet on the value of a feed* 229 | 230 | * --source = the source address 231 | * --feed-address = the address which publishes the feed to bet on 232 | * --bet-type = choices: `{Equal,NotEqual}` 233 | * --deadline = the date and time at which the bet should be decided/settled 234 | * --wager = the quantity of XCP to wager 235 | * --counterwager = the minimum quantity of XCP to be wagered by the user to bet against you, if he were to accept the whole thing 236 | * --target-value = target value for Equal or NotEqual bet 237 | * --leverage = leverage, as a fraction of 5040 238 | * --expiration = the number of blocks for which the bet should be valid 239 | * --fee = the exact BTC fee to be paid to miners 240 | 241 | 242 | Bet on Super Bowl Feed. Denver vs. Seattle. Feed value of 1 243 | means Seattle Wins. Feed value of 2 means Denver Wins. This command 244 | places a 1 XCP bet on the Super Bowl Feed for Seattle to win, paying out 245 | 2 to 1. The bet will expire in 100 blocks and the settlement value of 246 | the bet is based on the first feed update after the deadline timestamp 247 | of February 3, 2014 1:39 PM US Eastern Standard Time (UTC-0500). 248 | 249 | bet --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns \ 250 | --feed-address=n3BrDB6zDiEPWEE6wLxywFb4Yp9ZY5fH --bet-type=Equal \ 251 | --deadline=2014-02-03T13:39:00-0500 --wager=1 --counterwager=2 \ 252 | --target-value=1 --expiration=100 253 | 254 | 255 | Cancel 256 | ---------------------------------------- 257 | *Cancel an open order or bet you created* 258 | 259 | * --source = the source address 260 | * --offer-hash = the transaction hash of the order or bet 261 | * --fee = the exact BTC fee to be paid to miners 262 | 263 | 264 | 265 | cancel --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns \ 266 | --offer-hash=092f15d36786136c4d868c33356ec3c9b5a0c77de54ed0e96a8dbdd8af160c23 267 | 268 | 269 | Dividend 270 | ---------------------------------------- 271 | *Pay dividends to the holders of an asset (in proportion to their stake in it)* 272 | 273 | * --source = the source address 274 | * --quantity-per-unit = the quantity of XCP to be paid per whole unit held of ASSET 275 | * --asset = the asset to which pay dividends 276 | * --dividend-asset = asset in which to pay the dividends 277 | * --fee = the exact BTC fee to be paid to miners 278 | 279 | To pay dividends in BTC, you should, for now, just use a regular Bitcoin 280 | client, coupled with the output from `counterparty-wallet asset ASSET`, which 281 | will list all of the shareholders (and their holdings) of ASSET. 282 | 283 | 284 | dividend --source=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns --quantity-per-share=1 \ 285 | --asset=MULTIPOOLSTOCK 286 | 287 | 288 | Asset 289 | ---------------------------------------- 290 | *The `asset` action displays the basic properties of a given asset.* 291 | 292 | asset=[asset] 293 | 294 | To lock an asset, the command is: 295 | 296 | 297 | issuance --source=[source] --asset=[asset] --description="LOCK" 298 | 299 | 300 | Balances 301 | ---------------- 302 | *The `balances` action displays the balances of an address.* 303 | 304 | 305 | balances --address=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns 306 | 307 | 308 | Wallet 309 | ----------- 310 | *The `wallet` action lists the addresses in your backend wallet along with their balances in all assets.* 311 | 312 | 313 | Pending 314 | ----------- 315 | *The `pending` action lists pending order matches awaiting payment from you.* 316 | 317 | 318 | Getrows 319 | --------- 320 | 321 | *The `getrows` action gets rows from a Counterparty table.* 322 | 323 | * --table = table name 324 | * --filter = filters to get specific rows 325 | * --filter-op = operator uses to combine filters 326 | * --order-by = field used to order results 327 | * --order-dir = direction used to order results 328 | * --start-block = return only rows with block_index greater than start-block 329 | * --end-block = return only rows with block_index lower than end-block 330 | * --status = return only rows with the specified status 331 | * --limit = number of rows to return 332 | * --offset = number of rows to skip 333 | 334 | 335 | 336 | getrows --table balances --filter 'address' '=' 'muQjaj46wghHprjSjpgU7D55JxKyK5dJtZ' 337 | 338 | getrows --table balances --filter 'address' '=' 'muQjaj46wghHprjSjpgU7D55JxKyK5dJtZ' \ 339 | --filter 'asset' '=' 'BBBQ' --filter-op OR 340 | 341 | Windows users may need to make changes to handle console quirks. On Windows 10, the double quotes work fine: 342 | ` --filter "address" "=" "muQjaj46wghHprjSjpgU7D55JxKyK5dJtZ"`. 343 | 344 | Note that balances (quantities) for divisible assets such as XCP are stored and retrieved in "satoshi"-like units. 345 | Hence, an address with 4 XCP and 4 INDIVISIBLE may show their respective balances as 400,000,000 and 4 (which would 346 | be the case if INDIVISIBLE wasn't a divisible asset). 347 | 348 | 349 | GetInfo 350 | --------- 351 | *The `getinfo` action gets the current state of the server.* 352 | 353 | 354 | Get_TX_Info 355 | --------- 356 | *Display information about an unsigned raw transaction* 357 | 358 | The `get_tx_info` command displays information about an unsigned raw transaction. Some destinations (e.g. P2SH addresses) are not supported by this command. 359 | 360 | 361 | 362 | get_tx_info=[tx_hex] 363 | 364 | 365 | Input and Output 366 | ---------------------------------------- 367 | 368 | - Quantities of divisible assets are written to eight decimal places. 369 | - Quantities of indivisible assets are written as integers. 370 | - All other quantities, i.e. prices, odds, leverages, feed values and 371 | target values, fee multipliers, are represented internally as 372 | fractions, but printed to four decimal places. 373 | - As note above, "direct" access to tables via the getrows action outputs 374 | "raw" values (amounts) using internal representation 375 | 376 | 377 | Optional arguments 378 | ---------------------------------------- 379 | This list contains some optional arguments for counterparty-client. A complete list for client and server is available in online help. 380 | 381 | * -h, --help = show help message and exit 382 | * -V, --version = show version 383 | * --config-file = the location of the configuration file 384 | * --testnet = use Bitcoin testnet 385 | * --json-output = display result in JSON format 386 | * --unconfirmed = allow the spending of unconfirmed transaction outputs 387 | * --unsigned = print out unsigned hex of transaction; do not sign or broadcast 388 | * --encoding = the default is auto, which lets counterparty-core determine the encoding (opreturn, pubkeyhash, or multisig); certain transactions may require this argument with a non-default value 389 | -------------------------------------------------------------------------------- /docs/advanced/protocol.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: Protocol Specification 3 | --- 4 | 5 | 6 | Summary 7 | ------- 8 | 9 | Counterparty is a suite of financial tools in a protocol built on top of 10 | the Bitcoin blockchain and using the blockchain as a service for the 11 | reliable publication and timestamping of its messages. 12 | 13 | The reference implementation is Counterparty Core, which is hosted at [GitHub](https://github.com/CounterpartyXCP/counterparty-core). 14 | 15 | This document describes exclusively the latest version of the Counterparty protocol. For historical protocol changes, see the Counterparty Core [Release Notes](https://github.com/CounterpartyXCP/counterparty-core/release-notes/). 16 | 17 | Transactions 18 | ------------ 19 | 20 | Counterparty messages have the following components: 21 | 22 | - Source addresses 23 | - Destination addresses (optional) 24 | - A quantity of bitcoins sent from the sources to the destinations, if it exists. 25 | - A fee, in bitcoins, paid to the Bitcoin miners who include the transaction in a block. 26 | - Some ‘data’, imbedded in specially constructed transaction outputs. 27 | 28 | Every Bitcoin transaction carrying a Counterparty transaction has the 29 | following possible outputs: 30 | 31 | - zero or more destination outputs, 32 | - zero or more data outputs, and optional change outputs. 33 | 34 | All data outputs follow all destination outputs. Change outputs (outputs after the last data 35 | output) have no significance. 36 | 37 | For identification purposes, every Counterparty transaction’s ‘data’ 38 | field is prefixed by the string ``CNTRPRTY``, encoded in UTF‐8. This 39 | string is long enough that transactions with outputs containing 40 | pseudo‐random data cannot be mistaken for valid Counterparty 41 | transactions. In testing (i.e. using the TESTCOIN Counterparty network 42 | on any blockchain), this string is ‘XX’. 43 | 44 | Counterparty data may be stored in three different types of outputs, or 45 | in some combinations of those formats. All of the data is obfuscated by 46 | ARC4 encryption using the transaction identifier (TXID) of the first 47 | unspent transaction output (UTXO) as the encryption key. 48 | 49 | Multi‐signature data outputs are one‐of‐three outputs where the first 50 | public key is that of the sender, so that the value of the output is 51 | redeemable, and the second two public keys encode the data, zero‐padded 52 | and prefixed with a length byte. 53 | 54 | The data may also be stored in ``OP_RETURN`` outputs or as fake 55 | pubkeyhashes. 56 | 57 | The existence of the destination outputs, and the significance of the 58 | size of the Bitcoin fee and the Bitcoins transacted, depend on the 59 | Counterparty message type, which is determined by the four bytes in the 60 | data field that immediately follow the identification prefix. The rest 61 | of the data have a formatting specific to the message type, described in 62 | the source code. 63 | 64 | The sources and destinations of a Counterparty transaction are Bitcoin 65 | addresses, and may be either ``OP_CHECKSIG`` and ``OP_CHECKMULTISIG`` 66 | Bitcoin ScriptPubkeys. 67 | 68 | All messages are parsed in order, one at a time, ignoring block 69 | boundaries. 70 | 71 | Orders, bets, order matches, bet matches and rock‐paper‐scissor matches 72 | are expired at the end of blocks. 73 | 74 | Non‐Counterparty transactions 75 | ----------------------------- 76 | 77 | Counterparty Core supports the construction of two kinds of transactions 78 | that are not themselves considered Counterparty transactions: 79 | 80 | - BTC sends 81 | - BTC dividends to Counterparty assets 82 | 83 | Neither of these two transactions is constructed with a data field. 84 | 85 | mempool transactions 86 | -------------------- 87 | 88 | Always have block index = 9999999 (``config.MEMPOOL_BLOCK_INDEX``). 89 | 90 | DB changes never persist across sessions. 91 | 92 | Assets 93 | ------ 94 | 95 | All assets except BTC and XCP have the following properties: 96 | 97 | - Asset name 98 | - Asset ID 99 | - Description 100 | - Divisiblity 101 | - Callability 102 | - Call date (if callable) 103 | - may be delayed with later issuances 104 | - Call price (if callable) (non‐negative) 105 | - may be increased with later issuances 106 | 107 | Newly registered asset names will be either (unique) strings of 4 to 12 108 | uppercase Latin characters (inclusive) not beginning with ‘A’, or 109 | integers between 26^12 + 1 and 256^8 (inclusive), prefixed with ‘A’. 110 | Alphabetic asset names will carry a one‐time issuance fee (by burn) of 111 | 0.5 XCP and numeric asset names will be freely available. ‘BTC’ and 112 | ‘XCP’ are the only three‐character asset names. Example asset names: 113 | BBBB, A100000000000000000. 114 | 115 | Assets may be either divisible or indivisible, and divisible assets are 116 | divisible to eight decimal places. Assets also come with descriptions, 117 | which may be up to 52 single-byte characters long and updated at any time. 118 | 119 | Subassets 120 | ------ 121 | 122 | 1. Subasset names must meet following requirements : 123 | * Begin with the parent asset name followed by a period (.) 124 | * Contain at least 1 character following the parent asset name and a period (.) (e.g. PIZZA.x) 125 | * Contain up to 250 characters in length including the parent asset name (e.g. PIZZA.REALLY-long-VALID-Subasset-NAME) 126 | * Contain only characters `a-zA-Z0-9.-_@!` 127 | * Cannot end with a period (.) 128 | * Cannot contain multiple consecutive periods (..) 129 | 130 | 2. A subasset may only be issued from the same address that owns the parent asset at the time of the issuance 131 | 3. A subasset may be transferred to a new owner address after initial issuance 132 | 4. A subasset has an anti-spam issuance cost of 0.25 XCP 133 | 134 | 146 | 147 | Memos 148 | ------ 149 | 150 | A Memo can be attached to a send transactions. When a shared public address is used for incoming transactions, a memo may be used to link an incoming payments with a specific user account identifier or invoice. Memos do not need to be unique. Multiple sends may have the same memo. 151 | 152 | The Memo is a numeric value expressed in hexadecimal or a UTF-8 encoded text string. Valid memos are no more than 34 bytes long. 153 | 154 | 155 | Transaction Statuses 156 | -------------------- 157 | 158 | *Offers* (i.e. orders and bets) are given a status ``filled`` when their 159 | ``give_remaining``, ``get_remaining``, ``wager_remaining``, 160 | ``counterwager_remaining``, ``fee_provided_remaining`` or 161 | ``fee_required_remaining`` are no longer positive quantities. 162 | 163 | Because order matches pending BTC payment may be expired, orders 164 | involving Bitcoin cannot be filled, but remain always with a status 165 | ``open``. 166 | 167 | Message Types 168 | ------------- 169 | 170 | - Send 171 | - Order 172 | - BTCPay 173 | - Issue 174 | - Broadcast 175 | - Bet 176 | - Dividend 177 | - Burn 178 | - Cancel 179 | - Destroy 180 | - Dispenser 181 | 182 | ### Send 183 | 184 | A **send** message sends a quantity of any Counterparty asset from the 185 | source address to the destination address. If the sender does not hold a 186 | sufficient quantity of that asset at the time that the send message is 187 | parsed (in the sequence of transactions), then the send is considered an 188 | oversend. 189 | 190 | Oversends are handled as follows: 191 | 192 | 1) Oversends using the legacy send transaction type are valid and filled 193 | as much as they can be 194 | 2) Oversends using the new default enhanced send transaction type after 195 | block 489956 are invalid and none of the asset is sent 196 | 197 | Counterparty Core supports sending bitcoins, for which no data output is 198 | used. 199 | 200 | ### Order 201 | 202 | An ‘order’ is an offer to *give* a particular quantity of a particular 203 | asset and *get* some quantity of some other asset in return. No 204 | distinction is drawn between a ‘buy order’ and a ‘sell order’. The 205 | assets being given are escrowed away immediately upon the order being 206 | parsed. That is, if someone wants to give 1 XCP for 2 BTC, then as soon 207 | as he publishes that order, his balance of XCP is reduced by one. 208 | 209 | When an order is seen in the blockchain, the protocol attempts to match 210 | it, deterministically, with another open order previously seen. Two 211 | matched orders are called a ‘order match’. If either of a order match’s 212 | constituent orders involve Bitcoin, then the order match is assigned the 213 | status ‘pending’ until the necessary BTCPay transaction is published. 214 | Otherwise, the trade is completed immediately, with the protocol itself 215 | assigning the participating addresses their new balances. 216 | 217 | All orders are *limit orders*: an asking price is specified in the ratio 218 | of how much of one would like to get and give; an order is matched to 219 | the open order with the best price below the limit, and the order match 220 | is made at *that* price. That is, if there is one open order to sell at 221 | .11 XCP/ASST, another at .12 XCP/ASST, and another at .145 XCP/BTC, then 222 | a new order to buy at .14 XCP/ASST will be matched to the first sell 223 | order first, and the XCP and BTC will be traded at a price of .11 224 | XCP/ASST, and then if any are left, they’ll be sold at .12 XCP/ASST. If 225 | two existing orders have the same price, then the one made earlier will 226 | match first. 227 | 228 | All orders allow for partial execution; there are no all‐or‐none orders. 229 | If, in the previous example, the party buying the bitcoins wanted to buy 230 | more than the first sell offer had available, then the rest of the buy 231 | order would be filled by the latter existing order. After all possible 232 | order matches are made, the current (buy) order is listed as an open 233 | order itself. If there exist multiple open orders at the same price, 234 | then order that was placed earlier is matched first. 235 | 236 | Open orders expire after they have been open for a user‐specified number 237 | of blocks. When an order expires, all escrowed funds are returned to the 238 | parties that originally had them. 239 | 240 | Order Matches waiting for Bitcoin payments expire after twenty blocks; the 241 | constituent orders are replenished. 242 | 243 | In general, there can be no such thing as a fake order, because the 244 | assets that each party is offering are stored in escrow. However, it is 245 | impossible to escrow bitcoins, so those attempting to buy bitcoins may 246 | ask that only orders which pay a fee in bitcoins to Bitcoin miners be 247 | matched to their own. On the other hand, when creating an order to sell 248 | bitcoins, a user may pay whatever fee he likes. Partial orders pay 249 | partial fees. These fees are designated in the code as ``fee_required`` 250 | and ``fee_provided``, and as orders involving BTC are matched (expired), 251 | these fees (required and provided) are debited (sometimes replenished), 252 | in proportion to the fraction of the order that is matched. That is, if 253 | an order to sell 1 BTC has a ``fee_provided`` of 0.01 BTC (a 1%), and 254 | that order matches for 0.5 BTC initially, then the 255 | ``fee_provided_remaining`` for that order will thenceforth be 0.005 BTC. 256 | *Provided* fees, however, are not replenished upon failure to make BTC 257 | payments, or their anti‐trolling effect would be voided. 258 | 259 | Payments of bitcoins to close order matches waiting for bitcoins are 260 | done with a **BTCpay** message, which stores in its data field only 261 | the string concatenation of the transaction hashes which compose the 262 | Order Match which it fulfils. 263 | 264 | ### Issue 265 | 266 | Assets are issued with the **issuance** message type: the user picks a 267 | name and a quantity, and the protocol credits his address accordingly. 268 | The asset name must either be unique or be one previously issued by the 269 | same address. When re‐issuing an asset, that is, issuing more of an 270 | already‐issued asset, the divisibilities and the issuing address must 271 | match. 272 | 273 | The rights to issue assets under a given name may be transferred to any 274 | other address. 275 | 276 | Assets may be locked irreversibly against the issuance of further 277 | quantities and guaranteeing its holders against its inflation. To lock 278 | an asset, set the description to ‘LOCK’ (case‐insensitive). 279 | 280 | Issuances of any non‐zero quantity, that is, issuances which do not 281 | merely change, e.g., the description of the asset, involve a debit (and 282 | destruction) of now 0.5 XCP. 283 | 284 | Asset descriptions in enhanced asset information schema may be of 285 | arbitrary length. 286 | 287 | ### Broadcast 288 | 289 | A **broadcast** message publishes textual and numerical information, 290 | along with a timestamp, as part of a series of broadcasts called a 291 | ‘feed’. One feed is associated with one address: any broadcast from a 292 | given address is part of that address’s feed. The timestamps of a feed 293 | must increase monotonically. 294 | 295 | Bets are made on the numerical values in a feed, which values may be the 296 | prices of a currency, or parts of a code for describing discrete 297 | possible outcomes of a future event, for example. One might describe 298 | such a code with a text like, ‘US QE on 2014-01-01: dec=1, const=2, 299 | inc=3’ and announce the results with ‘US QE on 2014-01-01: decrease!’ 300 | and a value of 1. 301 | 302 | The publishing of a single broadcast with a textual message equal to 303 | ‘LOCK’ (case‐insensitive) locks the feed, and prevents it both from 304 | being the source of any further broadcasts and from being the subject of 305 | any new bets. (If a feed is locked while there are open bets or 306 | unsettled bet matches that refer to it, then those bets and bet matches 307 | will expire harmlessly.) 308 | 309 | The text field may be of arbitrary length. 310 | 311 | A feed is identified by the address which publishes it. 312 | 313 | Broadcasts with a value of -2 cancel all open bets on the feed. 314 | Broadcasts with a value of -3 cancel all pending bet matches on the 315 | feed. (This is equivalent to waiting for two weeks after the deadline.) 316 | Broadcasts with any other negative value are ignored for the purpose of 317 | bet settlement, but they still update the last broadcast time. 318 | 319 | ### Bet 320 | 321 | A bet is a wager that the value of a particular feed will be equal (or not 322 | equal) to a certain value — the *target value* — at the *deadline*. Bets have 323 | their wagers put in escrow upon being matched, and they are settled when the 324 | feed that they rely on passes the deadline. 325 | 326 | Equal/NotEqual Bets cannot be leveraged. However, for two Bets to be matched, 327 | their leverage levels, deadlines and target values must be identical. 328 | Otherwise, they are matched the same way that orders are, except a Bet’s *odds* 329 | are the multiplicative inverse of an order’s price (odds = wager/counterwager): 330 | each Bet is matched, if possible, to the open Bet with the highest odds, as 331 | much as possible. 332 | 333 | Target values must be non‐negative, and Bet Matches (contracts) are not 334 | affected by broadcasts with a value of -1. 335 | 336 | Bets cannot have a deadline later than the timestamp of the last 337 | broadcast of the feed that they refer to. 338 | 339 | Bets expire the same way that orders do, i.e. after a particular number 340 | of blocks. Bet Matches expire 2016 blocks after a block is seen with a 341 | block timestamp after its deadline. 342 | 343 | Betting fees are proportional to the initial wagers, not the earnings. 344 | They are taken from, not added to, the quantities wagered. 345 | 346 | - Because of the block time, and the non‐deterministic way in which 347 | transactions are ordered in the blockchain, all contracts must not be 348 | incrementally settled, but the funds in question must be immediately 349 | put into escrow, and there must be a settlement date. Otherwise, one 350 | could see a price drop coming, and ‘fight’ to hide the funds that 351 | were going to be deducted. 352 | 353 | Feed fees are deducted from the final settlement amount. 354 | 355 | ### Dividend 356 | 357 | A dividend payment is a payment of some quantity of any Counterparty 358 | asset (including BTC) to every holder of a an asset (except BTC or XCP) 359 | in proportion to the size of their holdings. Dividend‐yielding assets 360 | may be either divisible or indivisible. A dividend payment to any asset 361 | may originate from any address. The asset for dividend payments and the 362 | assets whose holders receive the payments may be the same. Bitcoin 363 | dividend payments do not employ the Counterparty protocol and so are 364 | larger and more expensive (in fees) than all other dividend payments. 365 | 366 | - TODO: dividends on escrowed funds 367 | 368 | There is a small anti-spam fee of 0.0002 XCP per recipient with dividends. 369 | 370 | ### Burn 371 | 372 | Balances in Counterparty’s native currency, ‘XCP’, will be initialised 373 | by ‘burning’ bitcoins in miners’ fees during a particular period of time 374 | using the a **burn** message type. The number of XCP earned per bitcoin 375 | is calculated thus: 376 | 377 | XCP_EARNED = BTC_BURNED * (1000 * (1 + .5 * 378 | ((END_BLOCK - CURRENT_BLOCK) / (END_BLOCK - START_BLOCK)) 379 | )) 380 | 381 | 382 | ``END_BLOCK`` is the block after which the burn period is over (**block #283810**) and ``START_BLOCK`` is the block with which the burn period 383 | begins (**block #278310**). The earlier the burn, the better the price, 384 | which may be between 1000 and 1500 XCP/BTC. 385 | 386 | Burn messages have precisely the string ‘ProofOfBurn’ stored in the 387 | ``OP_RETURN`` output. 388 | 389 | 390 | - new data‐less burn 391 | - burn period is over 392 | 393 | ### Cancel 394 | 395 | Open offers may be cancelled, which cancellation is irrevocable. 396 | 397 | A *cancel* message contains only the hash of the Bitcoin transaction 398 | that contains the order or bet to be cancelled. Only the address which 399 | made an offer may cancel it. 400 | 401 | ### Destroy 402 | 403 | A **destroy** message sends a quantity of any Counterparty asset from the 404 | source address to the default burn address. If the sender does not hold a 405 | sufficient quantity of that asset at the time that the destroy message is 406 | parsed (in the sequence of transactions), then the destroy is considered 407 | invalid. 408 | 409 | ### Dispenser 410 | 411 | A dispenser message creates a special type of artifact on the counterparty db 412 | that watches an address for incoming main chain asset (BTC). When any BTC reaches 413 | a dispenser enabled address, the amount received gets divided by the dispenser 414 | mainchainrate (or satoshirate in the db). The quantity rounded down is the 415 | multiplier to *give_quantity* that is sent to the first address on the sending 416 | transaction. All dispensers that can match on an address are triggered by each 417 | BTC send that has a dispense multiplier of at least 1. 418 | 419 | A dispenser can be in either of two status: 0 (open) or 10 (closed). 420 | 421 | ## Note about the database. 422 | 423 | Counterparty Core is backed by a SQLite3 database. All data stored in SQLite3 is “log-structured”, meaning that `UPDATE` is ever used. 424 | 425 | Each time that a Counterparty “object” is created, for example when opening an order, updating a balance, closing a bet, etc. this marks an `event` with a corresponding `payload`. By monitoring these events using the API (for the moment `/get_messages`) it is possible to reconstruct a the complete Counterparty state database with all balances, orders etc. 426 | 427 | Events are systematically logged at the `INFO` log level. By default, events are displayed in prose, but it is possible to display them in JSON format using the `--json-logs` CLI flag. 428 | 429 | It is important to note that there is no guarantee of backwards-compatibility regarding the internal structure of the database. However, maximum effort will be made to guarantee backwards compatibility for the API, including the endpoint used to retrieve events. 430 | 431 | -------------------------------------------------------------------------------- /docs/advanced/api-v1/api-v1-overview.md: -------------------------------------------------------------------------------- 1 | --- 2 | title: API v1 Overview 3 | --- 4 | 5 | **NOTE: This API is now EOL and will soon be removed entirely. All node hosts are strongly encouraged to update to API v2 ASAP.** 6 | 7 | Counterparty Core provides a JSON RPC 2.0-based API based off of 8 | that of Bitcoin Core. It is the primary means by which other applications 9 | should interact with the Counterparty network. 10 | 11 | The API server is started with the command `counterparty-server`. It listens on port 12 | 4000 by default (14000 for ``testnet``) and requires HTTP Basic Authentication to connect. 13 | 14 | The API includes numerous information retrieval methods, most of which begin with `get_`, as well as several 15 | `create_` methods which create new Counterparty transactions. While the `get_` type methods simply return the 16 | requested information, the `create_` methods return unsigned raw transactions which must then be signed and 17 | broadcast on the Bitcoin network. This means that while `counterparty-server` requires Bitcoin Core and 18 | uses it for retieval and parsing of blockchain data, it and this API do not require Bitcoin Core's wallet functionality 19 | for private key storage and transaction signing. Transaction signing and broadcast can thus 20 | be accomplished using whatever means the developer sees fit (including using Bitcoin core's APIs if desired, or 21 | a library like Bitcore, or a service like blockchain.info, and so on). 22 | 23 | In addition to the JSON RPC API, ``counterparty-core`` provides a complementary RESTful API also based off of that 24 | of Bitcoin Core's design. This REST API is still under development and will include more functionality 25 | in the future, and listens on the same port as JSON RPC one. 26 | 27 | 28 | ## Getting Started 29 | 30 | By default, the server will listen on port ``4000`` (if on mainnet) or port ``14000`` (on testnet) for API 31 | requests. 32 | 33 | Note that the main API is built on JSON-RPC 2.0, not 1.1. JSON-RPC itself is pretty lightweight, and API requests 34 | are made via a HTTP POST request to ``/api/`` (note the trailing slash), with JSON-encoded data passed as the POST body. 35 | 36 | The requests to the secondary REST API are made via HTTP GET to ``/rest/``, with request action and parameters encoded in the URL. 37 | 38 | 39 | ### General Format 40 | 41 | #### JSON-RPC 42 | 43 | All requests must have POST data that is JSON encoded. Here's an example of the POST data for a valid API request: 44 | 45 | ``` 46 | { 47 | "method": "get_sends", 48 | "params": {"order_by": "tx_hash", 49 | "order_dir": "asc", 50 | "start_block": 280537, 51 | "end_block": 280539}, 52 | "jsonrpc": "2.0", 53 | "id": 0 54 | } 55 | ``` 56 | 57 | The ``jsonrpc`` and ``id`` properties are requirements under the JSON-RPC 2.0 spec. 58 | 59 | You should note that the data in ``params`` is a JSON object (e.g. mapping), not an array. In other words, 60 | **the API only supports named arguments, not positional arguments** (e.g. use 61 | `{"argument1": "value1", "argument2": "value2"}` instead of `["value1", "value2"]`). This is the case for safety and bug-minimization reasons. 62 | 63 | For more information on JSON RPC, please see the [JSON RPC 2.0 specification](http://www.jsonrpc.org/specification). 64 | 65 | #### REST 66 | 67 | For REST API all requests are made via GET where query-specific arguments are encoded as URL parameters. Moreover, the same requests can be passed via HTTP POST in order to encrypt the transaction parameters. There are only two methods supported: ``get`` and ``compose``. The URL formats are as follows, respectively: 68 | `/rest//get?&op=` 69 | `/rest//compose?` 70 | 71 | ### Authentication 72 | 73 | The API support HTTP basic authentication to use, which is enabled if and only 74 | if a password is set. **The default user is ``'rpc'``.** 75 | 76 | 77 | ## Example Implementations for JSON RPC API 78 | 79 | The following examples have authentication enabled and the `user` set to its 80 | default value of `'rpc'`. The password is not set (default: `'rpc'`). Ensure 81 | these values correspond to values in your counterparty-server's configuration 82 | file `'server.conf'`. 83 | 84 | Submissions of examples in additional languages are welcome! 85 | 86 | ### Python 87 | 88 | ``` 89 | import json 90 | import requests 91 | from requests.auth import HTTPBasicAuth 92 | 93 | url = "http://localhost:4000/api/" 94 | headers = {'content-type': 'application/json'} 95 | auth = HTTPBasicAuth('rpc', PASSWORD) 96 | 97 | payload = { 98 | "method": "get_running_info", 99 | "params": {}, 100 | "jsonrpc": "2.0", 101 | "id": 0 102 | } 103 | response = requests.post(url, data=json.dumps(payload), headers=headers, auth=auth) 104 | print("Response: ", response.text) 105 | ``` 106 | 107 | ### PHP 108 | 109 | With PHP, you use the [JsonRPC](https://github.com/fguillot/JsonRPC) 110 | library. 111 | 112 | ``` 113 | authentication('rpc', PASSWORD); 118 | 119 | $result = $client->execute('get_balances', array('filters' => array('field' => 'address', 'op' => '==', 'value' => '1NFeBp9s5aQ1iZ26uWyiK2AYUXHxs7bFmB'))); 120 | print("get_balances result:\n"); 121 | var_dump($result); 122 | 123 | $result2 = $client->execute('get_running_info'); 124 | print("get_running_info result:\n"); 125 | var_dump($result2); 126 | ?> 127 | ``` 128 | 129 | ### curl 130 | 131 | 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. 132 | 133 | #### Linux 134 | 135 | ``` 136 | curl -X POST http://127.0.0.1:4000/api/ --user rpc:$PASSWORD -H 'Content-Type: application/json; charset=UTF-8' -H 'Accept: application/json, text/javascript' --data-binary '{ "jsonrpc": "2.0", "id": 0, "method": "get_running_info" }' 137 | ``` 138 | 139 | #### Windows 140 | 141 | On Windows, depending on implementation the above curl command may need to be formatted differently due to problems that Windows has with escapes. For example this particular format was found to work with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10 (x64). 142 | 143 | ``` 144 | curl -X POST http://127.0.0.1:4000/api/ --user rpc:$PASSWORD -H "Content-Type: application/json; charset=UTF-8" -H "Accept: application/json, text/javascript" --data-binary "{ \"jsonrpc\": \"2.0\", \"id\": 0, \"method\": \"get_running_info\" }" 145 | ``` 146 | 147 | ### c# (RestSharp) 148 | 149 | Authorization string in the example below is based on the default username/password. 150 | 151 | ``` 152 | var client = new RestClient("http://127.0.0.1:4000/api/"); 153 | var request = new RestRequest(Method.POST); 154 | request.AddHeader("cache-control", "no-cache"); 155 | request.AddHeader("authorization", "Basic cnBjOjEyMzQ="); 156 | request.AddHeader("content-type", "application/json"); 157 | request.AddParameter("application/json", "{\r\n \"method\": \"get_running_info\",\r\n \"params\": {},\r\n \"jsonrpc\": \"2.0\",\r\n \"id\": 1\r\n}", ParameterType.RequestBody); 158 | IRestResponse response = client.Execute(request); 159 | ``` 160 | 161 | ### Go 162 | 163 | Authorization string in the example below is based on the default username/password. 164 | 165 | ``` 166 | package main 167 | 168 | import ( 169 | "fmt" 170 | "strings" 171 | "net/http" 172 | "io/ioutil" 173 | ) 174 | 175 | func main() { 176 | 177 | url := "http://127.0.0.1:4000/api/" 178 | 179 | payload := strings.NewReader("{\r\n \"method\": \"get_running_info\",\r\n \"params\": {},\r\n \"jsonrpc\": \"2.0\",\r\n \"id\": 1\r\n}") 180 | 181 | req, _ := http.NewRequest("POST", url, payload) 182 | 183 | req.Header.Add("content-type", "application/json") 184 | req.Header.Add("authorization", "Basic cnBjOjEyMzQ=") 185 | req.Header.Add("cache-control", "no-cache") 186 | 187 | res, _ := http.DefaultClient.Do(req) 188 | 189 | defer res.Body.Close() 190 | body, _ := ioutil.ReadAll(res.Body) 191 | 192 | fmt.Println(res) 193 | fmt.Println(string(body)) 194 | 195 | } 196 | ``` 197 | 198 | ### Ruby (Net::HTTP) 199 | 200 | Authorization string in the example below is based on the default username/password. 201 | 202 | ``` 203 | require 'uri' 204 | require 'net/http' 205 | 206 | url = URI("http://127.0.0.1:4000/api/") 207 | 208 | http = Net::HTTP.new(url.host, url.port) 209 | 210 | request = Net::HTTP::Post.new(url) 211 | request["content-type"] = 'application/json' 212 | request["authorization"] = 'Basic cnBjOjEyMzQ=' 213 | request["cache-control"] = 'no-cache' 214 | request.body = "{\r\n \"method\": \"get_running_info\",\r\n \"params\": {},\r\n \"jsonrpc\": \"2.0\",\r\n \"id\": 1\r\n}" 215 | 216 | response = http.request(request) 217 | puts response.read_body 218 | ``` 219 | 220 | 221 | ## Example Implementations for REST API 222 | 223 | The following examples don't use authentication as with default settings. 224 | 225 | ### Python 226 | 227 | ``` 228 | import requests 229 | 230 | url = "http://localhost:4000/rest/" 231 | headers = {'content-type': 'application/json'} 232 | 233 | query = 'sends/get?source=mn6q3dS2EnDUx3bmyWc6D4szJNVGtaR7zc&destination=mtQheFaSfWELRB2MyMBaiWjdDm6ux9Ezns&op=AND' 234 | 235 | response = requests.get(url + query, headers=headers) 236 | print("Response: ", response.text) 237 | ``` 238 | 239 | 240 | ### curl 241 | 242 | These examples use the default username/password combination in URL. 243 | 244 | #### Linux 245 | 246 | ``` 247 | 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" 248 | ``` 249 | 250 | #### Windows 251 | 252 | This example was created with curl 7.50.1 (x86_64-w64-mingw32) on Windows 10. For POST encryption add `'-X POST'`. 253 | 254 | ``` 255 | 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" 256 | ``` 257 | 258 | ## Example Parameters 259 | 260 | * Fetch all balances for all assets for both of two addresses, using keyword-based arguments 261 | 262 | ``` 263 | payload = { 264 | "method": "get_balances", 265 | "params": { 266 | "filters": [{"field": "address", "op": "==", "value": "14qqz8xpzzEtj6zLs3M1iASP7T4mj687yq"}, 267 | {"field": "address", "op": "==", "value": "1bLockjTFXuSENM8fGdfNUaWqiM4GPe7V"}], 268 | "filterop": "or" 269 | }, 270 | "jsonrpc": "2.0", 271 | "id": 0 272 | } 273 | ``` 274 | 275 | * Get all burns between blocks 280537 and 280539 where greater than .2 BTC was burned, sorting by `tx_hash` (ascending order) 276 | 277 | ``` 278 | payload = { 279 | "method": "get_burns", 280 | "params": { 281 | "filters": {"field": "burned", "op": ">", "value": 20000000}, 282 | "filterop": "AND", 283 | "order_by": "tx_hash", 284 | "order_dir": "asc", 285 | "start_block": 280537, 286 | "end_block": 280539 287 | }, 288 | "jsonrpc": "2.0", 289 | "id": 0 290 | } 291 | ``` 292 | 293 | * Fetch all debits for > 2 XCP between blocks 280537 and 280539, sorting the results by quantity (descending order) 294 | 295 | ``` 296 | payload = { 297 | "method": "get_debits", 298 | "params": { 299 | "filters": [{"field": "asset", "op": "==", "value": "XCP"}, 300 | {"field": "quantity", "op": ">", "value": 200000000}], 301 | "filterop": "AND", 302 | "order_by": "quantity", 303 | "order_dir": "desc" 304 | }, 305 | "jsonrpc": "2.0", 306 | "id": 0 307 | } 308 | ``` 309 | 310 | 311 | * Send 1 XCP (specified in satoshis) from one address to another. 312 | 313 | ``` 314 | payload = { 315 | "method": "create_send", 316 | "params": { 317 | "source": "1CUdFmgK9trTNZHALfqGvd8d6nUZqH2AAf", 318 | "destination": "17rRm52PYGkntcJxD2yQF9jQqRS4S2nZ7E", 319 | "asset": "XCP", 320 | "quantity": 100000000 321 | }, 322 | "jsonrpc": "2.0", 323 | "id": 0 324 | } 325 | ``` 326 | 327 | * Issuance (indivisible) 328 | 329 | ``` 330 | payload = { 331 | "method": "create_issuance", 332 | "params": { 333 | "source": "1CUdFmgK9trTNZHALfqGvd8d6nUZqH2AAf", 334 | "asset": "MYASSET", 335 | "quantity": 1000, 336 | "description": "my asset is cool", 337 | "divisible": false 338 | }, 339 | "jsonrpc": "2.0", 340 | "id": 0 341 | } 342 | ``` 343 | 344 | * Transfer asset ownership 345 | 346 | ``` 347 | payload = { 348 | "method": "create_issuance", 349 | "params": { 350 | "source": "1CUdFmgK9trTNZHALfqGvd8d6nUZqH2AAf", 351 | "transfer_destination": "17rRm52PYGkntcJxD2yQF9jQqRS4S2nZ7E", 352 | "asset": "MYASSET", 353 | "quantity": 0 354 | }, 355 | "jsonrpc": "2.0", 356 | "id": 0 357 | } 358 | ``` 359 | 360 | * Lock asset 361 | 362 | ``` 363 | payload = { 364 | "method": "create_issuance", 365 | "params": { 366 | "source": "1CUdFmgK9trTNZHALfqGvd8d6nUZqH2AAf", 367 | "asset": "MYASSET", 368 | "quantity": 0, 369 | "description": "LOCK" 370 | }, 371 | "jsonrpc": "2.0", 372 | "id": 0 373 | } 374 | ``` 375 | 376 | 377 | ## Signing Transactions Before Broadcasting 378 | 379 | **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. 380 | 381 | 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. 382 | 383 | 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. 384 | 385 | **Bitcoin Core with Python** 386 | 387 | ``` 388 | #! /usr/bin/env python3 389 | 390 | from counterpartylib.lib import util 391 | from counterpartylib.lib import config 392 | from counterpartylib.lib.backend import addrindex 393 | 394 | config.TESTNET = 395 | config.RPC = 396 | config.BACKEND_URL = 397 | config.BACKEND_SSL_NO_VERIFY = 398 | 399 | def counterparty_api(method, params): 400 | return util.api(method, params) 401 | 402 | def bitcoin_api(method, params): 403 | return addrindex.rpc(method, params) 404 | 405 | def do_send(source, destination, asset, quantity, fee, encoding): 406 | validateaddress = bitcoin_api('validateaddress', [source]) 407 | assert validateaddress['ismine'] 408 | pubkey = validateaddress['pubkey'] 409 | unsigned_tx = counterparty_api('create_send', {'source': source, 'destination': destination, 'asset': asset, 'quantity': quantity, 'pubkey': pubkey, 'allow_unconfirmed_inputs': True}) 410 | signed_tx = bitcoin_api('signrawtransaction', [unsigned_tx])['hex'] 411 | tx_hash = bitcoin_api('sendrawtransaction', [signed_tx]) 412 | return tx_hash 413 | ``` 414 | 415 | **Bitcoin Core with Javascript** 416 | (Utilizing the [Counterwallet Bitcore wrapper code](https://raw.githubusercontent.com/CounterpartyXCP/counterwallet/master/src/js/util.bitcore.js) for brevity.) 417 | 418 | ``` 419 | 420 | 421 | 422 | 423 | 450 | 451 | ``` 452 | 453 | **Bitcoinjs-lib on javascript, signing a P2SH redeeming transaction** 454 | 455 | ```javascript 456 | // Assumes NodeJS runtime. Several libraries exist to replace the Buffer class on web browsers 457 | const bitcoin = require('bitcoinjs-lib') 458 | 459 | async function signP2SHDataTX(wif, txHex) { 460 | const network = bitcoin.networks.testnet // Change appropiately to your used network 461 | const keyPair = bitcoin.ECPair.fromWIF(wif, network) 462 | const dataTx = bitcoin.Transaction.fromHex(txHex) // The unsigned second part of the 2 part P2SH transactions 463 | 464 | const sigType = bitcoin.Transaction.SIGHASH_ALL // This shouldn't be changed unless you REALLY know what you're doing 465 | 466 | for (let i=0; i < dataTx.ins.length; i++) { 467 | const sigHash = dataTx.hashForSignature(i, bitcoin.script.decompile(dataTx.ins[i].script)[0], sigType) 468 | const sig = keyPair.sign(sigHash) 469 | const encodedSig = bitcoin.script.signature.encode(sig, sigType) 470 | const compiled = bitcoin.script.compile([encodedSig]) 471 | 472 | dataTx.ins[i].script = Buffer.concat([compiled, dataTx.ins[i].script]) 473 | } 474 | 475 | dataTx.ins[0].script = Buffer.concat([compiled, dataTx.ins[0].script]) 476 | return dataTx.toHex() // The resulting signed transaction in raw hex, ready to be broadcasted 477 | } 478 | ``` 479 | 480 | ## Terms & Conventions 481 | 482 | ### assets 483 | 484 | Everywhere in the API an asset is referenced by its name, not its ID. See the [Counterparty protocol specification](../../../../docs/advanced/protocol/#assets) for what constitutes a valid asset name. 485 | Examples: 486 | 487 | - "BTC" 488 | - "XCP" 489 | - "FOOBAR" 490 | - "A7736697071037023001" 491 | 492 | ### subassets 493 | 494 | See the [Counterparty protocol specification](../../../../docs/advanced/protocol/#subassets) for what constitutes a valid subasset name. 495 | Examples: 496 | 497 | - "PIZZA.X" 498 | - "PIZZA.REALLY-long-VALID-Subasset-NAME" 499 | 500 | ### Quantities and balances 501 | 502 | Anywhere where an quantity is specified, it is specified in **satoshis** (if a divisible asset), or as whole numbers 503 | (if an indivisible asset). To convert satoshis to floating-point, simply cast to float and divide by 100,000,000. 504 | 505 | Examples: 506 | 507 | - 4381030000 = 43.8103 (if divisible asset) 508 | - 4381030000 = 4381030000 (if indivisible asset) 509 | 510 | **NOTE:** XCP and BTC themselves are divisible assets. 511 | 512 | ### floats 513 | 514 | Floats are ratios or floating point values with six decimal places of precision, used in bets and dividends. 515 | 516 | ### Memos 517 | 518 | See the [Counterparty protocol specification](../../../advanced/protocol/#memos) for what constitutes a valid memo. 519 | Examples: 520 | 521 | - "for pizza" 522 | - "1ca6" 523 | 524 | 525 | ## Miscellaneous 526 | 527 | ### Filtering Read API results 528 | 529 | The Counterparty API aims to be as simple and flexible as possible. To this end, it includes a straightforward 530 | way to filter the results of most [Read API](api-v1-spec.md#read-api-function-reference) to get the data you want, and only that. 531 | 532 | For each Read API function that supports it, a ``filters`` parameter exists. To apply a filter to a specific data field, 533 | specify an object (e.g. dict in Python) as this parameter, with the following members: 534 | 535 | - field: The field to filter on. Must be a valid field in the type of object being returned 536 | - op: The comparison operation to perform. One of: ``"=="``, ``"!="``, ``">"``, ``"<"``, ``">="``, ``"<="``, ``"IN"``, ``"LIKE"``, ``"NOT IN"``, ``"NOT LIKE"`` 537 | - value: The value that the field will be compared against. Must be the same data type as the field is 538 | (e.g. if the field is a string, the value must be a string too) 539 | 540 | If you want to filter by multiple fields, then you can specify a list of filter objects. To this end, API functions 541 | that take ``filters`` also take a ``filterop`` parameter, which determines how the filters are combined when multiple 542 | filters are specified. It defaults to ``"and"``, meaning that filters are ANDed togeher (and that any match 543 | must satisfy all of them). You can also specify ``"or"`` as an alternative setting, which would mean that 544 | filters are ORed together, and that any match must satisfy only one of them. 545 | 546 | To disable filtering, you can just not specify the filter argument (if using keyword-based arguments), or, 547 | if using positional arguments, just pass ``null`` or ``[]`` (empty list) for the parameter. 548 | 549 | For examples of filtering in-use, please see the [examples](#example-parameters). 550 | 551 | NOTE: Note that with strings being compared, operators like ``>=`` do a lexigraphic string comparison (which 552 | compares, letter to letter, based on the ASCII ordering for individual characters. For more information on 553 | the specific comparison logic used, please see [this page](http://www.sqlite.org/lang_expr.html). 554 | --------------------------------------------------------------------------------