diff --git a/.travis.yml b/.travis.yml index 7d29fa0..241288d 100644 --- a/.travis.yml +++ b/.travis.yml @@ -1,9 +1,14 @@ language: node_js node_js: -- stable + - stable +before_install: + - rvm get stable + - rvm use ruby --install --default before_script: -- npm run clear-guides -- npm run convert-markdown -- --all + - npm run clear-guides + - npm run convert-markdown -- --all +script: + - sh ./build-api.sh deploy: provider: pages skip_cleanup: true diff --git a/api-docs-slate/Gemfile b/api-docs-slate/Gemfile new file mode 100644 index 0000000..dae5e50 --- /dev/null +++ b/api-docs-slate/Gemfile @@ -0,0 +1,11 @@ +ruby '>=2.3.1' +source 'https://rubygems.org' + +# Middleman +gem 'middleman', '~>4.2.1' +gem 'middleman-syntax', '~> 3.0.0' +gem 'middleman-autoprefixer', '~> 2.7.0' +gem "middleman-sprockets", "~> 4.1.0" +gem 'rouge', '~> 2.0.5' +gem 'redcarpet', '~> 3.4.0' +gem 'nokogiri', '~> 1.6.8' diff --git a/api-docs-slate/Gemfile.lock b/api-docs-slate/Gemfile.lock new file mode 100644 index 0000000..1fc04a9 --- /dev/null +++ b/api-docs-slate/Gemfile.lock @@ -0,0 +1,129 @@ +GEM + remote: https://rubygems.org/ + specs: + activesupport (5.0.1) + concurrent-ruby (~> 1.0, >= 1.0.2) + i18n (~> 0.7) + minitest (~> 5.1) + tzinfo (~> 1.1) + addressable (2.5.0) + public_suffix (~> 2.0, >= 2.0.2) + autoprefixer-rails (6.6.1) + execjs + backports (3.6.8) + coffee-script (2.4.1) + coffee-script-source + execjs + coffee-script-source (1.12.2) + compass-import-once (1.0.5) + sass (>= 3.2, < 3.5) + concurrent-ruby (1.0.4) + contracts (0.13.0) + dotenv (2.2.0) + erubis (2.7.0) + execjs (2.7.0) + fast_blank (1.0.0) + fastimage (2.0.1) + addressable (~> 2) + ffi (1.9.17) + haml (4.0.7) + tilt + hamster (3.0.0) + concurrent-ruby (~> 1.0) + hashie (3.5.1) + i18n (0.7.0) + kramdown (1.13.2) + listen (3.0.8) + rb-fsevent (~> 0.9, >= 0.9.4) + rb-inotify (~> 0.9, >= 0.9.7) + memoist (0.15.0) + middleman (4.2.1) + coffee-script (~> 2.2) + compass-import-once (= 1.0.5) + haml (>= 4.0.5) + kramdown (~> 1.2) + middleman-cli (= 4.2.1) + middleman-core (= 4.2.1) + sass (>= 3.4.0, < 4.0) + middleman-autoprefixer (2.7.1) + autoprefixer-rails (>= 6.5.2, < 7.0.0) + middleman-core (>= 3.3.3) + middleman-cli (4.2.1) + thor (>= 0.17.0, < 2.0) + middleman-core (4.2.1) + activesupport (>= 4.2, < 5.1) + addressable (~> 2.3) + backports (~> 3.6) + bundler (~> 1.1) + contracts (~> 0.13.0) + dotenv + erubis + execjs (~> 2.0) + fast_blank + fastimage (~> 2.0) + hamster (~> 3.0) + hashie (~> 3.4) + i18n (~> 0.7.0) + listen (~> 3.0.0) + memoist (~> 0.14) + padrino-helpers (~> 0.13.0) + parallel + rack (>= 1.4.5, < 3) + sass (>= 3.4) + servolux + tilt (~> 2.0) + uglifier (~> 3.0) + middleman-sprockets (4.1.0) + middleman-core (~> 4.0) + sprockets (>= 3.0) + middleman-syntax (3.0.0) + middleman-core (>= 3.2) + rouge (~> 2.0) + mini_portile2 (2.1.0) + minitest (5.10.1) + nokogiri (1.6.8.1) + mini_portile2 (~> 2.1.0) + padrino-helpers (0.13.3.3) + i18n (~> 0.6, >= 0.6.7) + padrino-support (= 0.13.3.3) + tilt (>= 1.4.1, < 3) + padrino-support (0.13.3.3) + activesupport (>= 3.1) + parallel (1.10.0) + public_suffix (2.0.5) + rack (2.0.1) + rb-fsevent (0.9.8) + rb-inotify (0.9.8) + ffi (>= 0.5.0) + redcarpet (3.4.0) + rouge (2.0.7) + sass (3.4.23) + servolux (0.12.0) + sprockets (3.7.1) + concurrent-ruby (~> 1.0) + rack (> 1, < 3) + thor (0.19.4) + thread_safe (0.3.5) + tilt (2.0.6) + tzinfo (1.2.2) + thread_safe (~> 0.1) + uglifier (3.0.4) + execjs (>= 0.3.0, < 3) + +PLATFORMS + ruby + +DEPENDENCIES + middleman (~> 4.2.1) + middleman-autoprefixer (~> 2.7.0) + middleman-sprockets (~> 4.1.0) + middleman-syntax (~> 3.0.0) + nokogiri (~> 1.6.8) + redcarpet (~> 3.4.0) + rouge (~> 2.0.5) + +RUBY VERSION + ruby 2.3.3p222 + +BUNDLED WITH + 1.14.5 diff --git a/api-docs-slate/LICENSE b/api-docs-slate/LICENSE new file mode 100644 index 0000000..5ceddf5 --- /dev/null +++ b/api-docs-slate/LICENSE @@ -0,0 +1,13 @@ +Copyright 2008-2013 Concur Technologies, Inc. + +Licensed under the Apache License, Version 2.0 (the "License"); you may +not use this file except in compliance with the License. You may obtain +a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +License for the specific language governing permissions and limitations +under the License. \ No newline at end of file diff --git a/api-docs-slate/README.md b/api-docs-slate/README.md new file mode 100644 index 0000000..565828d --- /dev/null +++ b/api-docs-slate/README.md @@ -0,0 +1,114 @@ +

+ Slate: API Documentation Generator +
+ Build Status +

+ +

Slate helps you create beautiful, intelligent, responsive API documentation.

+ +

Screenshot of Example Documentation created with Slate

+ +

The example above was created with Slate. Check it out at lord.github.io/slate.

+ +Features +------------ + +* **Clean, intuitive design** — With Slate, the description of your API is on the left side of your documentation, and all the code examples are on the right side. Inspired by [Stripe's](https://stripe.com/docs/api) and [Paypal's](https://developer.paypal.com/webapps/developer/docs/api/) API docs. Slate is responsive, so it looks great on tablets, phones, and even in print. + +* **Everything on a single page** — Gone are the days when your users had to search through a million pages to find what they wanted. Slate puts the entire documentation on a single page. We haven't sacrificed linkability, though. As you scroll, your browser's hash will update to the nearest header, so linking to a particular point in the documentation is still natural and easy. + +* **Slate is just Markdown** — When you write docs with Slate, you're just writing Markdown, which makes it simple to edit and understand. Everything is written in Markdown — even the code samples are just Markdown code blocks. + +* **Write code samples in multiple languages** — If your API has bindings in multiple programming languages, you can easily put in tabs to switch between them. In your document, you'll distinguish different languages by specifying the language name at the top of each code block, just like with Github Flavored Markdown. + +* **Out-of-the-box syntax highlighting** for [over 100 languages](https://github.com/jneen/rouge/wiki/List-of-supported-languages-and-lexers), no configuration required. + +* **Automatic, smoothly scrolling table of contents** on the far left of the page. As you scroll, it displays your current position in the document. It's fast, too. We're using Slate at TripIt to build documentation for our new API, where our table of contents has over 180 entries. We've made sure that the performance remains excellent, even for larger documents. + +* **Let your users update your documentation for you** — By default, your Slate-generated documentation is hosted in a public Github repository. Not only does this mean you get free hosting for your docs with Github Pages, but it also makes it simple for other developers to make pull requests to your docs if they find typos or other problems. Of course, if you don't want to use GitHub, you're also welcome to host your docs elsewhere. + +Getting started with Slate is super easy! Simply fork this repository and follow the instructions below. Or, if you'd like to check out what Slate is capable of, take a look at the [sample docs](http://lord.github.io/slate). + +Getting Started with Slate +------------------------------ + +### Prerequisites + +You're going to need: + + - **Linux or OS X** — Windows may work, but is unsupported. + - **Ruby, version 2.3.1 or newer** + - **Bundler** — If Ruby is already installed, but the `bundle` command doesn't work, just run `gem install bundler` in a terminal. + +### Getting Set Up + +1. Fork this repository on Github. +2. Clone *your forked repository* (not our original one) to your hard drive with `git clone https://github.com/YOURUSERNAME/slate.git` +3. `cd slate` +4. Initialize and start Slate. You can either do this locally, or with Vagrant: + +```shell +# either run this to run locally +bundle install +bundle exec middleman server + +# OR run this to run with vagrant +vagrant up +``` + +You can now see the docs at http://localhost:4567. Whoa! That was fast! + +Now that Slate is all set up on your machine, you'll probably want to learn more about [editing Slate markdown](https://github.com/lord/slate/wiki/Markdown-Syntax), or [how to publish your docs](https://github.com/lord/slate/wiki/Deploying-Slate). + +If you'd prefer to use Docker, instructions are available [in the wiki](https://github.com/lord/slate/wiki/Docker). + +### Note on JavaScript Runtime + +For those who don't have JavaScript runtime or are experiencing JavaScript runtime issues with ExecJS, it is recommended to add the [rubyracer gem](https://github.com/cowboyd/therubyracer) to your gemfile and run `bundle` again. + +Companies Using Slate +--------------------------------- + +* [NASA](https://api.nasa.gov) +* [IBM](https://docs.cloudant.com/api.html) +* [Sony](http://developers.cimediacloud.com) +* [Best Buy](https://bestbuyapis.github.io/api-documentation/) +* [Travis-CI](https://docs.travis-ci.com/api/) +* [Greenhouse](https://developers.greenhouse.io/harvest.html) +* [Woocommerce](http://woocommerce.github.io/woocommerce-rest-api-docs/) +* [Appium](http://appium.io/slate/en/master) +* [Dwolla](https://docs.dwolla.com/) +* [Clearbit](https://clearbit.com/docs) +* [Coinbase](https://developers.coinbase.com/api) +* [Parrot Drones](http://developer.parrot.com/docs/bebop/) +* [Fidor Bank](http://docs.fidor.de/) +* [Scale](https://docs.scaleapi.com/) + +You can view more in [the list on the wiki](https://github.com/lord/slate/wiki/Slate-in-the-Wild). + +Need Help? Found a bug? +-------------------- + +[Submit an issue](https://github.com/lord/slate/issues) to the Slate Github if you need any help. And, of course, feel free to submit pull requests with bug fixes or changes. + +Contributors +-------------------- + +Slate was built by [Robert Lord](https://lord.io) while interning at [TripIt](https://www.tripit.com/). + +Thanks to the following people who have submitted major pull requests: + +- [@chrissrogers](https://github.com/chrissrogers) +- [@bootstraponline](https://github.com/bootstraponline) +- [@realityking](https://github.com/realityking) +- [@cvkef](https://github.com/cvkef) + +Also, thanks to [Sauce Labs](http://saucelabs.com) for sponsoring the development of the responsive styles. + +Special Thanks +-------------------- +- [Middleman](https://github.com/middleman/middleman) +- [jquery.tocify.js](https://github.com/gfranko/jquery.tocify.js) +- [middleman-syntax](https://github.com/middleman/middleman-syntax) +- [middleman-gh-pages](https://github.com/edgecase/middleman-gh-pages) +- [Font Awesome](http://fortawesome.github.io/Font-Awesome/) diff --git a/api-docs-slate/config.rb b/api-docs-slate/config.rb new file mode 100644 index 0000000..e0f2479 --- /dev/null +++ b/api-docs-slate/config.rb @@ -0,0 +1,57 @@ +# Unique header generation +require './lib/unique_head.rb' + +# Markdown +set :markdown_engine, :redcarpet +set :markdown, + fenced_code_blocks: true, + smartypants: true, + disable_indented_code_blocks: true, + prettify: true, + tables: true, + with_toc_data: true, + no_intra_emphasis: true, + renderer: UniqueHeadCounter + +# Assets +set :css_dir, 'stylesheets' +set :js_dir, 'javascripts' +set :images_dir, 'images' +set :fonts_dir, 'fonts' + +# Activate the syntax highlighter +activate :syntax +ready do + require './lib/multilang.rb' +end + +activate :sprockets + +activate :autoprefixer do |config| + config.browsers = ['last 2 version', 'Firefox ESR'] + config.cascade = false + config.inline = true +end + +# Github pages require relative links +activate :relative_assets +set :relative_links, true + +# Build Configuration +configure :build do + # If you're having trouble with Middleman hanging, commenting + # out the following two lines has been known to help + activate :minify_css + activate :minify_javascript + # activate :relative_assets + # activate :asset_hash + # activate :gzip +end + +# Deploy Configuration +# If you want Middleman to listen on a different port, you can set that below +set :port, 4567 + +helpers do + require './lib/toc_data.rb' +end diff --git a/api-docs-slate/font-selection.json b/api-docs-slate/font-selection.json new file mode 100755 index 0000000..5e78f5d --- /dev/null +++ b/api-docs-slate/font-selection.json @@ -0,0 +1,148 @@ +{ + "IcoMoonType": "selection", + "icons": [ + { + "icon": { + "paths": [ + "M438.857 73.143q119.429 0 220.286 58.857t159.714 159.714 58.857 220.286-58.857 220.286-159.714 159.714-220.286 58.857-220.286-58.857-159.714-159.714-58.857-220.286 58.857-220.286 159.714-159.714 220.286-58.857zM512 785.714v-108.571q0-8-5.143-13.429t-12.571-5.429h-109.714q-7.429 0-13.143 5.714t-5.714 13.143v108.571q0 7.429 5.714 13.143t13.143 5.714h109.714q7.429 0 12.571-5.429t5.143-13.429zM510.857 589.143l10.286-354.857q0-6.857-5.714-10.286-5.714-4.571-13.714-4.571h-125.714q-8 0-13.714 4.571-5.714 3.429-5.714 10.286l9.714 354.857q0 5.714 5.714 10t13.714 4.286h105.714q8 0 13.429-4.286t6-10z" + ], + "attrs": [], + "isMulticolor": false, + "tags": [ + "exclamation-circle" + ], + "defaultCode": 61546, + "grid": 14 + }, + "attrs": [], + "properties": { + "id": 100, + "order": 4, + "prevSize": 28, + "code": 58880, + "name": "exclamation-sign", + "ligatures": "" + }, + "setIdx": 0, + "iconIdx": 0 + }, + { + "icon": { + "paths": [ + "M585.143 786.286v-91.429q0-8-5.143-13.143t-13.143-5.143h-54.857v-292.571q0-8-5.143-13.143t-13.143-5.143h-182.857q-8 0-13.143 5.143t-5.143 13.143v91.429q0 8 5.143 13.143t13.143 5.143h54.857v182.857h-54.857q-8 0-13.143 5.143t-5.143 13.143v91.429q0 8 5.143 13.143t13.143 5.143h256q8 0 13.143-5.143t5.143-13.143zM512 274.286v-91.429q0-8-5.143-13.143t-13.143-5.143h-109.714q-8 0-13.143 5.143t-5.143 13.143v91.429q0 8 5.143 13.143t13.143 5.143h109.714q8 0 13.143-5.143t5.143-13.143zM877.714 512q0 119.429-58.857 220.286t-159.714 159.714-220.286 58.857-220.286-58.857-159.714-159.714-58.857-220.286 58.857-220.286 159.714-159.714 220.286-58.857 220.286 58.857 159.714 159.714 58.857 220.286z" + ], + "attrs": [], + "isMulticolor": false, + "tags": [ + "info-circle" + ], + "defaultCode": 61530, + "grid": 14 + }, + "attrs": [], + "properties": { + "id": 85, + "order": 3, + "name": "info-sign", + "prevSize": 28, + "code": 58882 + }, + "setIdx": 0, + "iconIdx": 2 + }, + { + "icon": { + "paths": [ + "M733.714 419.429q0-16-10.286-26.286l-52-51.429q-10.857-10.857-25.714-10.857t-25.714 10.857l-233.143 232.571-129.143-129.143q-10.857-10.857-25.714-10.857t-25.714 10.857l-52 51.429q-10.286 10.286-10.286 26.286 0 15.429 10.286 25.714l206.857 206.857q10.857 10.857 25.714 10.857 15.429 0 26.286-10.857l310.286-310.286q10.286-10.286 10.286-25.714zM877.714 512q0 119.429-58.857 220.286t-159.714 159.714-220.286 58.857-220.286-58.857-159.714-159.714-58.857-220.286 58.857-220.286 159.714-159.714 220.286-58.857 220.286 58.857 159.714 159.714 58.857 220.286z" + ], + "attrs": [], + "isMulticolor": false, + "tags": [ + "check-circle" + ], + "defaultCode": 61528, + "grid": 14 + }, + "attrs": [], + "properties": { + "id": 83, + "order": 9, + "prevSize": 28, + "code": 58886, + "name": "ok-sign" + }, + "setIdx": 0, + "iconIdx": 6 + }, + { + "icon": { + "paths": [ + "M658.286 475.429q0-105.714-75.143-180.857t-180.857-75.143-180.857 75.143-75.143 180.857 75.143 180.857 180.857 75.143 180.857-75.143 75.143-180.857zM950.857 950.857q0 29.714-21.714 51.429t-51.429 21.714q-30.857 0-51.429-21.714l-196-195.429q-102.286 70.857-228 70.857-81.714 0-156.286-31.714t-128.571-85.714-85.714-128.571-31.714-156.286 31.714-156.286 85.714-128.571 128.571-85.714 156.286-31.714 156.286 31.714 128.571 85.714 85.714 128.571 31.714 156.286q0 125.714-70.857 228l196 196q21.143 21.143 21.143 51.429z" + ], + "width": 951, + "attrs": [], + "isMulticolor": false, + "tags": [ + "search" + ], + "defaultCode": 61442, + "grid": 14 + }, + "attrs": [], + "properties": { + "id": 2, + "order": 1, + "prevSize": 28, + "code": 58887, + "name": "icon-search" + }, + "setIdx": 0, + "iconIdx": 7 + } + ], + "height": 1024, + "metadata": { + "name": "slate", + "license": "SIL OFL 1.1" + }, + "preferences": { + "showGlyphs": true, + "showQuickUse": true, + "showQuickUse2": true, + "showSVGs": true, + "fontPref": { + "prefix": "icon-", + "metadata": { + "fontFamily": "slate", + "majorVersion": 1, + "minorVersion": 0, + "description": "Based on FontAwesome", + "license": "SIL OFL 1.1" + }, + "metrics": { + "emSize": 1024, + "baseline": 6.25, + "whitespace": 50 + }, + "resetPoint": 58880, + "showSelector": false, + "selector": "class", + "classSelector": ".icon", + "showMetrics": false, + "showMetadata": true, + "showVersion": true, + "ie7": false + }, + "imagePref": { + "prefix": "icon-", + "png": true, + "useClassSelector": true, + "color": 4473924, + "bgColor": 16777215 + }, + "historySize": 100, + "showCodes": true, + "gridSize": 16, + "showLiga": false + } +} diff --git a/api-docs-slate/lib/multilang.rb b/api-docs-slate/lib/multilang.rb new file mode 100644 index 0000000..36fbe5b --- /dev/null +++ b/api-docs-slate/lib/multilang.rb @@ -0,0 +1,16 @@ +module Multilang + def block_code(code, full_lang_name) + if full_lang_name + parts = full_lang_name.split('--') + rouge_lang_name = (parts) ? parts[0] : "" # just parts[0] here causes null ref exception when no language specified + super(code, rouge_lang_name).sub("highlight #{rouge_lang_name}") do |match| + match + " tab-" + full_lang_name + end + else + super(code, full_lang_name) + end + end +end + +require 'middleman-core/renderers/redcarpet' +Middleman::Renderers::MiddlemanRedcarpetHTML.send :include, Multilang diff --git a/api-docs-slate/lib/toc_data.rb b/api-docs-slate/lib/toc_data.rb new file mode 100644 index 0000000..f4663cd --- /dev/null +++ b/api-docs-slate/lib/toc_data.rb @@ -0,0 +1,30 @@ +require 'nokogiri' + +def toc_data(page_content) + html_doc = Nokogiri::HTML::DocumentFragment.parse(page_content) + + # get a flat list of headers + headers = [] + html_doc.css('h1, h2, h3').each do |header| + headers.push({ + id: header.attribute('id').to_s, + content: header.children, + level: header.name[1].to_i, + children: [] + }) + end + + [3,2].each do |header_level| + header_to_nest = nil + headers = headers.reject do |header| + if header[:level] == header_level + header_to_nest[:children].push header if header_to_nest + true + else + header_to_nest = header if header[:level] < header_level + false + end + end + end + headers +end \ No newline at end of file diff --git a/api-docs-slate/lib/unique_head.rb b/api-docs-slate/lib/unique_head.rb new file mode 100644 index 0000000..c5dc279 --- /dev/null +++ b/api-docs-slate/lib/unique_head.rb @@ -0,0 +1,17 @@ +# Unique header generation +require 'middleman-core/renderers/redcarpet' +class UniqueHeadCounter < Middleman::Renderers::MiddlemanRedcarpetHTML + def initialize + super + @head_count = {} + end + def header(text, header_level) + friendly_text = text.parameterize + @head_count[friendly_text] ||= 0 + @head_count[friendly_text] += 1 + if @head_count[friendly_text] > 1 + friendly_text += "-#{@head_count[friendly_text]}" + end + return "#{text}" + end +end diff --git a/api-docs-slate/source/fonts/slate.eot b/api-docs-slate/source/fonts/slate.eot new file mode 100755 index 0000000..13c4839 Binary files /dev/null and b/api-docs-slate/source/fonts/slate.eot differ diff --git a/api-docs-slate/source/fonts/slate.svg b/api-docs-slate/source/fonts/slate.svg new file mode 100755 index 0000000..5f34982 --- /dev/null +++ b/api-docs-slate/source/fonts/slate.svg @@ -0,0 +1,14 @@ + + + +Generated by IcoMoon + + + + + + + + + + diff --git a/api-docs-slate/source/fonts/slate.ttf b/api-docs-slate/source/fonts/slate.ttf new file mode 100755 index 0000000..ace9a46 Binary files /dev/null and b/api-docs-slate/source/fonts/slate.ttf differ diff --git a/api-docs-slate/source/fonts/slate.woff b/api-docs-slate/source/fonts/slate.woff new file mode 100755 index 0000000..1e72e0e Binary files /dev/null and b/api-docs-slate/source/fonts/slate.woff differ diff --git a/api-docs-slate/source/fonts/slate.woff2 b/api-docs-slate/source/fonts/slate.woff2 new file mode 100755 index 0000000..7c585a7 Binary files /dev/null and b/api-docs-slate/source/fonts/slate.woff2 differ diff --git a/api-docs-slate/source/images/logo.png b/api-docs-slate/source/images/logo.png new file mode 100644 index 0000000..9290d12 Binary files /dev/null and b/api-docs-slate/source/images/logo.png differ diff --git a/api-docs-slate/source/images/navbar.png b/api-docs-slate/source/images/navbar.png new file mode 100644 index 0000000..df38e90 Binary files /dev/null and b/api-docs-slate/source/images/navbar.png differ diff --git a/api-docs-slate/source/includes/_clients.md b/api-docs-slate/source/includes/_clients.md new file mode 100644 index 0000000..f6e4d95 --- /dev/null +++ b/api-docs-slate/source/includes/_clients.md @@ -0,0 +1,106 @@ +# Configuring Clients + +## Default Listeners +```shell--visible +# With curl you just send HTTP Requests based on further docs +# Only thing to have in mind is Authentication, which is described in Auth section. + +curl http://127.0.0.1:18332/ # will get info from testnet +``` + +By default API listens on these addresses: + +Network | API Port +--------- | ----------- +main | 8332 +testnet | 18332 +regtest | 48332 +simnet | 18556 + +You can interact with bcoin with REST Api as well as RPC, +there are couple of ways you can use API. + +- `bcoin cli` - has almost all methods described to be used. +- `javascript` - Clients used by `bcoin cli` can be used directly from javascript +- `curl` - or you can use direct HTTP calls for invoking REST/RPC API calls. + +## Configuring BCOIN CLI + +```shell--visible +# You can use config file +bcoin cli --config /full/path/to/bcoin.conf + +# Or with prefix (which will later load bcoin.conf file from the directory) +bcoin cli --prefix /full/path/to/bcoin/dir + +# You can configure it by passing arguments: +bcoin cli --network=regtest info +bcoin cli info --network=regtest + +# Or use ENV variables (Starting with BCOIN_) +export BCOIN_NETWORK=regtest +export BCOIN_API_KEY=yoursecret +bcoin cli info +``` + +`bcoin cli` can be configured with many params: + +### General configurations are: + +Config | Options | Description +--------- | ----------- | ----------- +prefix | dir path | This accepts directory where DBs and `bcoin.conf` are located. +network | `main`, `testnet`, `regtest` | This will configure which network to load, also where to look for config file +uri, url | Base HTTP URI | This can be used for custom port +api-key | secret | Secret used by RPC for auth. + +### Wallet Specific + +Config | Options | Description +--------- | ----------- | ----------- +id | primary, custom | specify which account to use by default +token | token str | Token specific wallet + + + +## Using Javascript Client + +```javascript--visible +const bcoin = require('bcoin'); +const Client = bcoin.http.Client; +const Wallet = bcoin.http.Wallet; + +const client = new Client({ + network: 'testnet', + uri: 'http://localhost:18332' +}); + +const wallet = new Wallet({ + network: 'testnet', + uri: 'http://localhost:18332', + id: 'primary' +}); +``` + +You can also use api with Javascript Library (used by `bcoin cli`). +There are two objects: `bcoin.http.Client` for general API and `bcoin.http.Wallet` for wallet API. + +`bcoin.http.Client` options: + +Config | Type | Description +--------- | ----------- | ----------- +network | `main`, `testnet`, `regtest` | Network to use (doesn't lookup configs by itself) +uri | String | URI of the service +apiKey | String | api secret + +`bcoin.http.Wallet` options: + +Config | Type | Description +--------- | ----------- | ----------- +network | `main`, `testnet`, `regtest` | Network to use (doesn't lookup configs by itself) +uri | String | URI of the service +apiKey | String | api secret +id | primary, custom | specify which account to use by default +token | token str | Token specific wallet diff --git a/api-docs-slate/source/includes/_coin.md b/api-docs-slate/source/includes/_coin.md new file mode 100644 index 0000000..2db8de2 --- /dev/null +++ b/api-docs-slate/source/includes/_coin.md @@ -0,0 +1,218 @@ +# Coin +Getting coin information via APi. + +*Coin stands for UTXO* + + + + +## Get coin by Outpoint + +```javascript +let hash, index; +``` + +```shell--vars +hash='c13039f53247f9ca14206da079bcf738d91bc60e251ac9ebaba9ea9a862d9092'; +index=0; +``` + +```shell--curl +curl $url/coin/$hash/$index +``` + +```shell--cli +bcoin cli coin $hash $index +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + + const coin = await client.getCoin(hash, index); + + console.log(coin); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +{ + "version": 1, + "height": 100019, + "value": 144709200, + "script": "76a9148fc80aadf127f6f92b6ed33404b110f851c8eca188ac", + "address": "mtdCZdNYny2U7met3umk47SoA7HMZGfsa2", + "coinbase": false, + "hash": "c13039f53247f9ca14206da079bcf738d91bc60e251ac9ebaba9ea9a862d9092", + "index": 0 +} +``` + +Get coin by outpoint (hash and index). Returns coin in bcoin coin json format. + +### HTTP Request +`GET /coin/:hash/:index` + +### URL Parameters +Parameter | Description +--------- | ----------- +:hash | Hash of tx +:index | Output's index in tx + + + +## Get coins by address + +```javascript +let address; +``` + +```shell--vars +address='n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr'; +``` + +```shell--curl +curl $url/coin/address/$address +``` + +```shell--cli +bcoin cli coin $address +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + + const coins = await client.getCoinsByAddress(address); + + console.log(coins); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +[ + { + "version": 1, + "height": 502, + "value": 275391, + "script": "76a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac", + "address": "n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr", + "coinbase": false, + "hash": "86150a141ebe5903a5d31e701698a01d598b81f099ea7577dad73033eab02ef9", + "index": 1 + } +] +``` + +Get coin objects array by address. + +### HTTP Request +`GET /coin/address/:address` + +### URL Parameters +Parameter | Description +--------- | ----------- +:address | bitcoin address + + + +## Get coins by addresses + +```javascript +let address0, address1; +``` + +```shell--vars +address0='n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr'; +address1='mwLHWwWPDwtCBZA7Ltg9QSzKK5icdCU5rb'; +``` + +```shell--curl +curl $url/coin/address \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "addresses":[ "'$address0'", "'$address1'" ]}' +``` + +```shell--cli +No CLI Option. +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + + const coins = await client.getCoinsByAddresses([address0, address1]); + + console.log(coins); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +[ + { + "version": 1, + "height": 502, + "value": 275391, + "script": "76a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac", + "address": "n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr", + "coinbase": false, + "hash": "86150a141ebe5903a5d31e701698a01d598b81f099ea7577dad73033eab02ef9", + "index": 1 + }, + { + "version": 1, + "height": 500, + "value": 1095497, + "script": "76a914ad7d7b9ac5260ad13fa55e06143283f5b36495f788ac", + "address": "mwLHWwWPDwtCBZA7Ltg9QSzKK5icdCU5rb", + "coinbase": false, + "hash": "4692772a73ea834c836915089acf97f2c790380a2b8fd32f82729da72545d8c5", + "index": 0 + } +] +``` + +Get coins by addresses, +returns array of coin objects. + +### HTTP Request +`POST /coin/address` + +### POST Parameters (JSON) +Parameter | Description +--------- | ----------- +addresses | List of bitcoin addresses diff --git a/api-docs-slate/source/includes/_errors.md b/api-docs-slate/source/includes/_errors.md new file mode 100644 index 0000000..779d423 --- /dev/null +++ b/api-docs-slate/source/includes/_errors.md @@ -0,0 +1,4 @@ +# Errors +Any errors will be returned with an http status code other than 200, containing a JSON object in the form: + +`{"error": { message: "message" } }` \ No newline at end of file diff --git a/api-docs-slate/source/includes/_node.md b/api-docs-slate/source/includes/_node.md new file mode 100644 index 0000000..5a70c5a --- /dev/null +++ b/api-docs-slate/source/includes/_node.md @@ -0,0 +1,294 @@ +# Node + +## JSON-RPC Requests + +Route for JSON-RPC requests, most of which mimic the bitcoind RPC calls completely. + +```shell--curl +curl $url \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "method": "getblockchaininfo", "params": [] }' +``` + +### HTTP Request +`POST /` + +More about RPC Requests in RPC Docs. + +## Get server info + +```shell--curl +curl $url/ +``` + +```shell--cli +bcoin cli info +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + const info = await client.getInfo(); + + console.log(info); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +{ + "version": "v1.0.0-beta.14", + "network": "testnet", + "chain": { + "height": 1157058, + "tip": "00000000000002ac70408966be53a1e01e7e014a3d4f1f275201c751de7d6e77", + "progress": 1 + }, + "pool": { + "host": "203.0.113.114", + "port": 18333, + "agent": "/bcoin:v1.0.0-beta.14/", + "services": "1001", + "outbound": 8, + "inbound": 0 + }, + "mempool": { + "tx": 39, + "size": 121512 + }, + "time": { + "uptime": 7403, + "system": 1502381034, + "adjusted": 1502381035, + "offset": 1 + }, + "memory": { + "total": 87, + "jsHeap": 23, + "jsHeapTotal": 30, + "nativeHeap": 56, + "external": 8 + } +} +``` + +Get server Info. + +### HTTP Request +

Get server info. No params.

+ +`GET /` + + No Params. + + +## Get mempool snapshot + +```shell--curl +curl $url/mempool +``` + +```shell--cli +bcoin cli mempool +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + const mempoolTxs = await client.getMempool(); + + console.log(mempoolTxs); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +[ + "9fee8350a3cc2f5bfa9d90f008af0bbc22d84aa5b1242da2f3479935f597c9ed", + "d3bd772f3b369e2e04b9b928e40dddded5ee1448b9d1ee0b6a13e6c2ae283f6a", + ... +] +``` + +Get mempool snapshot (array of json txs). + +### HTTP Request +`GET /mempool` + +No Params. + + +## Get block by hash or height + +```javascript +let blockHash, blockHeight; +``` + +```shell--vars +blockHash='00000000cabd2d0245add40f335bab18d3e837eccf868b64aabbbbac74fb21e0'; +blockHeight='1500'; +``` + +```shell--curl +curl $url/block/$blockHash # by hash +curl $url/block/$blockHeight # by height +``` + +```shell--cli +bcoin cli block $blockHash # by hash +bcoin cli block $blockHeight # by height +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + const blockByHash = await client.getBlock(blockHash); + const blockByHeight = await client.getBlock(blockHeight); + + console.log(blockByHash, blockByHeight); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +{ + "hash": "00000000cabd2d0245add40f335bab18d3e837eccf868b64aabbbbac74fb21e0", + "height": 1500, + "version": 1, + "prevBlock": "00000000f651e7fe6d9a4845dcf40f5642216e59054453a4368a73a7295f9f3d", + "merkleRoot": "e3e4590784a828967e6d9319eca2915c1860a63167449f9605e649a0aafe6d0a", + "time": 1337966228, + "bits": 486604799, + "nonce": 2671491584, + "txs": [ + { + "hash": "e3e4590784a828967e6d9319eca2915c1860a63167449f9605e649a0aafe6d0a", + "witnessHash": "e3e4590784a828967e6d9319eca2915c1860a63167449f9605e649a0aafe6d0a", + "fee": 0, + "rate": 0, + "mtime": 1502382669, + "index": 0, + "version": 1, + "flag": 1, + "inputs": [ + { + "prevout": { + "hash": "0000000000000000000000000000000000000000000000000000000000000000", + "index": 4294967295 + }, + "script": "0494bebf4f0108172f503253482f49636549726f6e2d51432d6d696e65722f", + "witness": "00", + "sequence": 4294967295, + "address": null + } + ], + "outputs": [ + { + "value": 5000000000, + "script": "21032fd2666c8d5ffae0147acc0b9628160652679663397e911170ebaf1e26358abfac", + "address": "mtohBeScUtM2ndcmmpSV8o2jcvmknp1Mpy" + } + ], + "locktime": 0 + } + ] +} +``` + +Returns block info by block hash or height. + +### HTTP Request +`GET /block/:blockhashOrHeight` + + +### URL Parameters + +Parameter | Description +--------- | ----------- +:blockhashOrHeight | Hash or Height of block + + + +## Broadcast transaction +```javascript +let tx; +``` + +```shell--vars +tx='0100000001ff2a3afc3a8133a3bfeedd391bc3cff39d47fe4e3caee492a93f92edff76b9d4000000006a47304402204cc6a35cb3d3d976cb10e3c98df66aba29b5efc7b5ecdbc0f4ed949aa64235f20220512fce2d63739012094f12c3a9402919b32149c32d4d71a3448d4695ae8e3dc601210325c9abd8916d6e5ba0b3c501a70c0186f3bf6e4567922b9d83ae205d1d9e9affffffffff0244cff505000000001976a91423f5580d600bcfe5b99d9fe737530fd8b32492a088ac00111024010000001976a91473f3ecd665da93701358bd957393b8085c1aa2d988ac00000000'; +``` + +```shell--curl +curl $url/broadcast \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "tx": "'$tx'" }' +``` + +```shell--cli +bcoin cli broadcast $txhex +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet', +}); + +(async () => { + await client.open(); + + const result = await client.broadcast(tx); + + console.log(result); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +{ + "success": true +} +``` + +Broadcast a transaction by adding it to the node's mempool. If mempool verification fails, the node will still forcefully advertise and relay the transaction for the next 60 seconds. + +### HTTP Request +`POST /broadcast` + +### POST Parameters (JSON) +Parameter | Description +--------- | ----------- +tx | transaction hash diff --git a/api-docs-slate/source/includes/_node_rpc.md b/api-docs-slate/source/includes/_node_rpc.md new file mode 100644 index 0000000..401c5cc --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc.md @@ -0,0 +1,52 @@ +# RPC Calls - Node + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "method": "methodname", "params": [...] "id": "some-id" }' +``` + +```shell--cli +bcoin cli rpc params... +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('MethodName', [ ...params ]); + + // RES will return "result" part of the object, not the id or error + // error will be thrown. +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +> Further examples will only include "result" part. + +```json +{"result": resultObject ,"error": errorObject, "id": passedID} +``` + + +Bcoin rpc calls mimic Bitcoin Core's RPC. +This is documentation how to use it with `bcoin`. + +RPC Calls are accepted at: +`POST /` + +*Note: bcoin cli rpc and javascript will return error OR result.* + + +### POST Parameters RPC +Parameter | Description +--------- | ----------- +method | Name of the RPC call +params | Parameters accepted by method +id | Will be returned with the response (Shouldn't be object) diff --git a/api-docs-slate/source/includes/_node_rpc_block.md b/api-docs-slate/source/includes/_node_rpc_block.md new file mode 100644 index 0000000..cfce301 --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc_block.md @@ -0,0 +1,581 @@ +# RPC Calls - Block + +## getblockchaininfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "method": "getblockchaininfo" }' +``` + +```shell--cli +bcoin cli rpc getblockchaininfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getblockchaininfo'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "chain": "test", + "blocks": 1178402, + "headers": 1178402, + "bestblockhash": "0000000000000dd897f549915ba7099b6d4f86f4512801d617a7c0c655827d08", + "difficulty": 1048576, + "mediantime": 1502814951, + "verificationprogress": 1, + "chainwork": "00000000000000000000000000000000000000000000002976ca78529498e335", + "pruned": false, + "softforks": [ + { + "id": "bip34", + "version": 2, + "reject": { + "status": true + } + }, + { + "id": "bip66", + "version": 3, + "reject": { + "status": true + } + }, + { + "id": "bip65", + "version": 4, + "reject": { + "status": true + } + } + ], + "bip9_softforks": { + "csv": { + "status": "active", + "bit": 0, + "startTime": 1456790400, + "timeout": 1493596800 + }, + "segwit": { + "status": "active", + "bit": 1, + "startTime": 1462060800, + "timeout": 1493596800 + }, + "segsignal": { + "status": "defined", + "bit": 4, + "startTime": 4294967295, + "timeout": 4294967295 + }, + "testdummy": { + "status": "failed", + "bit": 28, + "startTime": 1199145601, + "timeout": 1230767999 + } + }, + "pruneheight": null +} +``` + +Returns blockchain information. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getbestblockhash + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "method": "getbestblockhash" }' +``` + +```shell--cli +bcoin cli rpc getbestblockhash +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getbestblockhash'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +"0000000000000225f8332239fe00b74c65f916ff71dde5dee33b72ddd3b0e237" +``` + +Returns Block Hash of the tip. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getblockcount + + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "method": "getblockcount" }' +``` + +```shell--cli +bcoin cli rpc getbestblockhash +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getblockcount'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +1178418 +``` + +Returns block count. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. |||| + + + +## getblock + +```javascript +let blockhash, details, verbose; +``` + +```shell--vars +blockhash='00000000e0290b7c66227c7499692aac5437860ee912424bf8eea3a3883a4e37'; +verbose=1; +details=0; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getblock", + "params": [ "'$blockhash'", "'$verbose'", "'$details'" ] + }' +``` + +```shell--cli +bcoin cli rpc getblock $blockhash $verbose $details +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getblock', [ blockhash, verbose, details ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "hash": "00000000e0290b7c66227c7499692aac5437860ee912424bf8eea3a3883a4e37", + "confirmations": 1177921, + "strippedsize": 2499, + "size": 2499, + "weight": 9996, + "height": 502, + "version": 1, + "versionHex": "00000001", + "merkleroot": "4f7a9087973b891fc86cc59fd9c2cb696f7a813360d3553626dc6c38909f9571", + "coinbase": "3337346bde777ade327922b5deef5fb7f88e98cecb22", + "tx": [ + "2a69b021fc6cbd61260767302781c85fb0873acf18980ea6187fc868e4a3e3f9", + "c61f2ef26bb08dcf1e16db4fece56ac92a3acac24e4dac90315e5c0ad6af67e6", + "ed8c8213cc2d214ad2f293caae99e26e2c59d158f3eda5d9c1292e0961e20e76", + "21da008d1fddc1a067d2d6cd9bb6e78acb5bdc9560252c17cfd59c331dd5c2cf", + "90cc439e0a03109c33c966d92ccd18b0509ef678458d85a097397ee9bfbd54c0", + "1d67f7466fd711f8106fb437cb6a59b7ccd14cd6069edc132627a9fb01d4f09c", + "402450f5b4cd794d4198f940977bf4291ce25a7ff8b157adf71c07ed065db380", + "0173a5d24d393127d5e6fc043ff1a00dafc6a2777143cb98a803a0b6e8cd02c7", + "86150a141ebe5903a5d31e701698a01d598b81f099ea7577dad73033eab02ef9" + ], + "time": 1296746959, + "mediantime": 1296746728, + "bits": 486604799, + "difficulty": 1, + "chainwork": "000000000000000000000000000000000000000000000000000001f701f701f7", + "previousblockhash": "00000000c7f50b6dfac8b8a59e11b7e62f07fdef20597089b9c5d64ebfe6d682", + "nextblockhash": "00000000f797111d0f67d7f08346757948e7c469f14cddbd1c3d0217306bf003" +} +``` + +Returns information about block. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockhash | Required | Hash of the block +2 | verbose | true | If set to false, it will return hex of the block +3 | details | false | If set to true, it will return transaction details too. + + + +## getblockbyheight + +```javascript +let blockhash, details, verbose; +``` + +```shell--vars +blockheight=502; +verbose=1; +details=0; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getblockbyheight", + "params": [ "'$blockheight'", "'$verbose'", "'$details'" ] + }' +``` + +```shell--cli +bcoin cli rpc getblockbyheight $blockheight $verbose $details +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getblockbyheight', [ blockheight, verbose, details ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "hash": "00000000e0290b7c66227c7499692aac5437860ee912424bf8eea3a3883a4e37", + "confirmations": 1177921, + "strippedsize": 2499, + "size": 2499, + "weight": 9996, + "height": 502, + "version": 1, + "versionHex": "00000001", + "merkleroot": "4f7a9087973b891fc86cc59fd9c2cb696f7a813360d3553626dc6c38909f9571", + "coinbase": "3337346bde777ade327922b5deef5fb7f88e98cecb22", + "tx": [ + "2a69b021fc6cbd61260767302781c85fb0873acf18980ea6187fc868e4a3e3f9", + "c61f2ef26bb08dcf1e16db4fece56ac92a3acac24e4dac90315e5c0ad6af67e6", + "ed8c8213cc2d214ad2f293caae99e26e2c59d158f3eda5d9c1292e0961e20e76", + "21da008d1fddc1a067d2d6cd9bb6e78acb5bdc9560252c17cfd59c331dd5c2cf", + "90cc439e0a03109c33c966d92ccd18b0509ef678458d85a097397ee9bfbd54c0", + "1d67f7466fd711f8106fb437cb6a59b7ccd14cd6069edc132627a9fb01d4f09c", + "402450f5b4cd794d4198f940977bf4291ce25a7ff8b157adf71c07ed065db380", + "0173a5d24d393127d5e6fc043ff1a00dafc6a2777143cb98a803a0b6e8cd02c7", + "86150a141ebe5903a5d31e701698a01d598b81f099ea7577dad73033eab02ef9" + ], + "time": 1296746959, + "mediantime": 1296746728, + "bits": 486604799, + "difficulty": 1, + "chainwork": "000000000000000000000000000000000000000000000000000001f701f701f7", + "previousblockhash": "00000000c7f50b6dfac8b8a59e11b7e62f07fdef20597089b9c5d64ebfe6d682", + "nextblockhash": "00000000f797111d0f67d7f08346757948e7c469f14cddbd1c3d0217306bf003" +} +``` + +Returns information about block by height. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockheight | Required | height of the block in the blockchain. +2 | verbose | true | If set to false, it will return hex of the block. +3 | details | false | If set to true, it will return transaction details too. + + + +## getblockhash + +```javascript +let blockheight; +``` + +```shell--vars +blockheight=502; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getblockhash", + "params": [ "'$blockheight'" ] + }' +``` + +```shell--cli +bcoin cli rpc getblockhash $blockheight +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getblockhash', [ blockheight ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +"00000000e0290b7c66227c7499692aac5437860ee912424bf8eea3a3883a4e37" +``` + +Returns block's hash by height. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockheight | Required | height of the block in the blockchain. + + + +## getblockheader + +```javascript +let blockhash, verbose; +``` + +```shell--vars +blockhash='00000000e0290b7c66227c7499692aac5437860ee912424bf8eea3a3883a4e37'; +verbose=1; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getblockheader", + "params": [ "'$blockhash'", "'$details'" ] + }' +``` + +```shell--cli +bcoin cli rpc getblockheader $blockhash $verbose +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getblockheader', [ blockheight, verbose ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "hash": "00000000e0290b7c66227c7499692aac5437860ee912424bf8eea3a3883a4e37", + "confirmations": 1177934, + "height": 502, + "version": 1, + "versionHex": "00000001", + "merkleroot": "4f7a9087973b891fc86cc59fd9c2cb696f7a813360d3553626dc6c38909f9571", + "time": 1296746959, + "mediantime": 1296746728, + "bits": 486604799, + "difficulty": 1, + "chainwork": "000000000000000000000000000000000000000000000000000001f701f701f7", + "previousblockhash": "00000000c7f50b6dfac8b8a59e11b7e62f07fdef20597089b9c5d64ebfe6d682", + "nextblockhash": "00000000f797111d0f67d7f08346757948e7c469f14cddbd1c3d0217306bf003" +} +``` + +Returns block's header by hash. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockheight | Required | height of the block in the blockchain. +2 | verbose | true | If set to false, it will return hex of the block. + + + +## getchaintips + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getchaintips" + }' +``` + +```shell--cli +bcoin cli rpc getchaintips +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getchaintips'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +Returns chaintips. + +> The above command returns JSON "result" like this: + +```json +[ + { + "height": 1159071, + "hash": "0000000000043bc8896351bf4fbb9fadfa596566e6d88078a2364252346e0d2a", + "branchlen": 1, + "status": "valid-headers" + }, + { + "height": 1158313, + "hash": "0000000000011e8328cf0382888e07f207e178e967f896794d600e39c962362e", + "branchlen": 1, + "status": "valid-headers" + }, + ... +] +``` + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getdifficulty + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getdifficulty" + }' +``` + +```shell--cli +bcoin cli rpc getdifficulty +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getdifficulty'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +1048576 +``` + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + diff --git a/api-docs-slate/source/includes/_node_rpc_chain.md b/api-docs-slate/source/includes/_node_rpc_chain.md new file mode 100644 index 0000000..43a797b --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc_chain.md @@ -0,0 +1,144 @@ +# RPC Calls - Chain + +## pruneblockchain + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "pruneblockchain", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc pruneblockchain +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('pruneblockchain'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +Prunes the blockchain, it will keep blocks specified in Network Configurations. + +### Default Prune Options +Network | keepBlocks | pruneAfter +------- | ------- | ------- +main | 288 | 1000 +testnet | 10000 | 1000 +regtest | 10000 | 1000 + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## invalidateblock + +```javascript +let blockhash; +``` + +```shell--vars +blockhash='0000000000000dca8da883af9515dd90443d59139adbda3f9eeac1d18397fec3'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "invalidateblock", + "params": [ "'$blockhash'" ] + }' +``` + +```shell--cli +bcoin cli rpc invalidateblock $blockhash +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('invalidateblock', [ blockhash ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + + +Invalidates the block in the chain. +It will rewind network to blockhash and invalidate it. + +It won't accept that block as valid +*Invalidation will work while running, restarting node will remove invalid block from list.* + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockhash | Required | Block's hash + + + +## reconsiderblock + +```javascript +let blockhash; +``` + +```shell--vars +blockhash='0000000000000dca8da883af9515dd90443d59139adbda3f9eeac1d18397fec3'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "reconsiderblock", + "params": [ "'$blockhash'" ] + }' +``` + +```shell--cli +bcoin cli rpc reconsiderblock $blockhash +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('reconsiderblock', [ blockhash ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +This rpc command will remove block from invalid block set. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockhash | Required | Block's hash diff --git a/api-docs-slate/source/includes/_node_rpc_general.md b/api-docs-slate/source/includes/_node_rpc_general.md new file mode 100644 index 0000000..e045334 --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc_general.md @@ -0,0 +1,541 @@ +## stop + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "method": "stop" }' +``` + +```shell--cli +bcoin cli rpc stop +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('stop'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +"Stopping." +``` + +Stops the running node. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getinfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getinfo", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getinfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getinfo'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "version": "v1.0.0-beta.14", + "protocolversion": 70015, + "walletversion": 0, + "balance": 0, + "blocks": 1178980, + "timeoffset": 0, + "connections": 8, + "proxy": "", + "difficulty": 1048576, + "testnet": true, + "keypoololdest": 0, + "keypoolsize": 0, + "unlocked_until": 0, + "paytxfee": 0.0002, + "relayfee": 0.00001, + "errors": "" +} +``` + +Returns general info + + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getmemoryinfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getmemoryinfo", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getmemoryinfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getmemoryinfo'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "total": 99, + "jsHeap": 19, + "jsHeapTotal": 29, + "nativeHeap": 69, + "external": 10 +} +``` + +Returns Memory usage info. + + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## setloglevel + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "setloglevel", + "params": [ "none" ] + }' +``` + +```shell--cli +bcoin cli rpc setloglevel none +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('setloglevel', [ 'none' ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +null +``` + +Change Log level of the running node. + +Levels are: `NONE`, `ERROR`, `WARNING`, `INFO`, `DEBUG`, `SPAM` + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | level | Required | Level for the logger + + +## validateaddress + +```javascript +let address; +``` + +```shell--vars +address='n34pHHSqsXJQwq9FXUsrfhmTghrVtN74yo'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "validateaddress", + "params": [ "'$address'" ] + }' +``` + +```shell--cli +bcoin cli rpc validateaddress $address +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('validateaddress', [ address ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "isvalid": true, + "address": "n34pHHSqsXJQwq9FXUsrfhmTghrVtN74yo", + "scriptPubKey": "76a914ec61435a3c8f0efee2ffafb8ddb4e1440d2db8d988ac", + "ismine": false, + "iswatchonly": false +} +``` + +Validates address. + + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | address | Required | Address to validate + + + +## createmultisig + +```javascript +let nrequired, pubkey0, pubkey1, pubkey2; +``` + +```shell--vars +nrequired=2; +pubkey0='02b3280e779a7c849f9d6460e926097fe4b0f6280fa6fd038ce8e1236a4688c358'; +pubkey1='021f1dbc575db95a44e016fe6ecf00231109e7799d9b1e007dbe8814017cf0d65c'; +pubkey2='0315613667e3ebe065c0b8d86ae0443d97de56545bdf38c99a6ee584f300206d9a'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "createmultisig", + "params": [ "'$nrequired'", [ "'$pubkey0'", "'$pubkey1'", "'$pubkey2'" ] ] + }' +``` + +```shell--cli +bcoin cli rpc createmultisig $nrequired '[ "'$pubkey0'", "'$pubkey1'", "'$pubkey2'" ]' +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('createmultisig', [ nrequired, [ pubkey0, pubkey1, pubkey2 ] ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "address": "2MzY9R5P1Wfy9aNdqyoH63K1EQZF7APuZ4S", + "redeemScript": "5221021f1dbc575db95a44e016fe6ecf00231109e7799d9b1e007dbe8814017cf0d65c2102b3280e779a7c849f9d6460e926097fe4b0f6280fa6fd038ce8e1236a4688c358210315613667e3ebe065c0b8d86ae0443d97de56545bdf38c99a6ee584f300206d9a53ae" +} + +``` + +create multisig address + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | nrequired | Required | Required number of approvals for spending +2 | keyArray | Required | Array of public keys + + + +## createwitnessaddress + +```javascript +let script; +``` + +```shell--vars +script='5221021f1dbc575db95a44e016fe6ecf00231109e7799d9b1e007dbe8814017cf0d65c2102b3280e779a7c849f9d6460e926097fe4b0f6280fa6fd038ce8e1236a4688c358210315613667e3ebe065c0b8d86ae0443d97de56545bdf38c99a6ee584f300206d9a53ae'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "createwitnessaddress", + "params": [ "'$script'" ] + }' +``` + +```shell--cli +bcoin cli rpc createwitnessaddress $script +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('createwitnessaddress', [ script ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "address": "tb1qlfgqame3n0dt2ldjl2m9qjg6n2vut26jw3ezm25hqx9ez4m9wp5q567kg2", + "witnessScript": "0020fa500eef319bdab57db2fab650491a9a99c5ab5274722daa97018b9157657068" +} +``` + +Creates witness address. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | script | Required | Bitcoin script. + + + +## signmessagewithprivkey + +```javascript +let privkey, message; +``` + +```shell--vars +privkey='EL4QU6ViZvT4RuCTCivw2uBnvBPSamP5jMtH31gGQLbEEcmNCHVz'; +message='hello'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "signmessagewithprivkey", + "params": [ "'$privkey'", "'$message'"] + }' +``` + +```shell--cli +bcoin cli rpc signmessagewithprivkey $privkey $message +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('signmessagewithprivkey', [ privkey, message ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +"MEQCIAwF9NPMo5KBRsCWTBJ2r69/h7CfDl+RQfxxwAbNp1WJAiAiubiK5rg9MugiU7EHpwbJLc3b356LAedob0ePI40Wmg==" +``` + + +Signs message with private key. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | privkey | Required | Private key +1 | message | Required | Message you want to sign. + + +## verifymessage + +```javascript +let address, signature, message; +``` + +```shell--vars +address='R9LTC6Sp6Zwk71qUrm81sEdsppFNiDM6mF'; +signature='MEQCIAwF9NPMo5KBRsCWTBJ2r69/h7CfDl+RQfxxwAbNp1WJAiAiubiK5rg9MugiU7EHpwbJLc3b356LAedob0ePI40Wmg=='; +message='hello'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "verifymessage", + "params": [ "'$address'", "'$signature'", "'$message'" ] + }' +``` + +```shell--cli +bcoin cli rpc verifymessage $address $signature $message +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('verifymessage', [ address, signature, message ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +true +``` + +Verify sign + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | address | Required | Address of the signer +2 | signature | Required | Signature of signed message +3 | message | Required | Message that was signed + +## setmocktime + +```javascript +let timestamp; +``` + +```shell--vars +timestamp=1503058155; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "setmocktime", + "params": [ '$timestamp' ] + }' +``` + +```shell--cli +bcoin cli rpc setmocktime $timestamp +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('setmocktime', [ timestamp ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +null +``` + + +Changes network time (This is consensus-critical) + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | timestamp | Required | timestamp to change to diff --git a/api-docs-slate/source/includes/_node_rpc_mempool.md b/api-docs-slate/source/includes/_node_rpc_mempool.md new file mode 100644 index 0000000..518fa00 --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc_mempool.md @@ -0,0 +1,651 @@ +# RPC Calls - Mempool + +## getmempoolinfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getmempoolinfo" + }' +``` + +```shell--cli +bcoin cli rpc getmempoolinfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getmempoolinfo'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "size": 20, + "bytes": 68064, + "usage": 68064, + "maxmempool": 100000000, + "mempoolminfee": 0.00001 +} +``` + +Returns informations about mempool. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getmempoolancestors + +```javascript +let txhash, verbose; +``` + +```shell--vars +txhash='939a3b8485b53a718d89e7e4412473b3762fa1d9bbd555fc8b01e73be0ab1881'; +verbose=1; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getmempoolancestors", + "params": [ "'$txhash'", "'$verbose'" ] + }' +``` + +```shell--cli +bcoin cli rpc getmempoolancestors $txhash $verbose +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getmempoolancestors', [ txhash, verbose ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +// verbose=1 +[ + { + "size": 225, + "fee": 0.0000454, + "modifiedfee": 0, + "time": 1502891340, + "height": 201, + "startingpriority": 0, + "currentpriority": 0, + "descendantcount": 1, + "descendantsize": 451, + "descendantfees": 9080, + "ancestorcount": 0, + "ancestorsize": 0, + "ancestorfees": 0, + "depends": [] + } +] +``` + +```json +// verbose=0 +[ + "56ab7663c80cb6ffc9f8a4b493d77b2e6f52ae8ff64eefa8899c2065922665c8" +] +``` + +returns all in-mempool ancestors for a transaction in the mempool. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | txhash | Required | Transaction Hash +2 | verbose | false | False returns only tx hashs, true - returns dependency tx info + + + +## getmempooldescendants + +```javascript +let txhash, verbose; +``` + +```shell--vars +txhash='56ab7663c80cb6ffc9f8a4b493d77b2e6f52ae8ff64eefa8899c2065922665c8'; +verbose=1; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getmempooldescendants", + "params": [ "'$txhash'", "'$verbose'" ] + }' +``` + +```shell--cli +bcoin cli rpc getmempooldescendants $txhash $verbose +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getmempooldescendants', [ txhash, verbose ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +// verbose=1 +[ + { + "size": 226, + "fee": 0.0000454, + "modifiedfee": 0, + "time": 1502891378, + "height": 201, + "startingpriority": 0, + "currentpriority": 0, + "descendantcount": 0, + "descendantsize": 226, + "descendantfees": 4540, + "ancestorcount": 1, + "ancestorsize": 0, + "ancestorfees": 0, + "depends": [ + "56ab7663c80cb6ffc9f8a4b493d77b2e6f52ae8ff64eefa8899c2065922665c8" + ] + } +] +``` + +```json +// verbose=0 +[ + "939a3b8485b53a718d89e7e4412473b3762fa1d9bbd555fc8b01e73be0ab1881" +] +``` + +returns all in-mempool descendants for a transaction in the mempool. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | txhash | Required | Transaction hash +2 | verbose | false | False returns only tx hashs, true - returns dependency tx info + + + +## getmempoolentry + +```javascript +let txhash; +``` + +```shell--vars +txhash='939a3b8485b53a718d89e7e4412473b3762fa1d9bbd555fc8b01e73be0ab1881'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getmempoolentry", + "params": [ "'$txhash'" ] + }' +``` + +```shell--cli +bcoin cli rpc getmempoolentry $txhash +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getmempoolentry', [ txhash ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "size": 226, + "fee": 0.0000454, + "modifiedfee": 0, + "time": 1502891378, + "height": 201, + "startingpriority": 0, + "currentpriority": 0, + "descendantcount": 0, + "descendantsize": 226, + "descendantfees": 4540, + "ancestorcount": 1, + "ancestorsize": 0, + "ancestorfees": 0, + "depends": [ + "56ab7663c80cb6ffc9f8a4b493d77b2e6f52ae8ff64eefa8899c2065922665c8" + ] +} +``` + +returns mempool transaction info by its hash. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | txhash | Required | Transaction Hash + + + +## getrawmempool + +```javascript +let verbose; +``` + +```shell--vars +verbose=1; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getrawmempool", + "params": [ "'$verbose'" ] + }' +``` + +```shell--cli +bcoin cli rpc getrawmempool $verbose +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getrawmempool', [ verbose ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "56ab7663c80cb6ffc9f8a4b493d77b2e6f52ae8ff64eefa8899c2065922665c8": { + "size": 225, + "fee": 0.0000454, + "modifiedfee": 0, + "time": 1502891340, + "height": 201, + "startingpriority": 0, + "currentpriority": 0, + "descendantcount": 1, + "descendantsize": 451, + "descendantfees": 9080, + "ancestorcount": 0, + "ancestorsize": 0, + "ancestorfees": 0, + "depends": [] + }, + "939a3b8485b53a718d89e7e4412473b3762fa1d9bbd555fc8b01e73be0ab1881": { + "size": 226, + "fee": 0.0000454, + "modifiedfee": 0, + "time": 1502891378, + "height": 201, + "startingpriority": 0, + "currentpriority": 0, + "descendantcount": 0, + "descendantsize": 226, + "descendantfees": 4540, + "ancestorcount": 1, + "ancestorsize": 0, + "ancestorfees": 0, + "depends": [ + "56ab7663c80cb6ffc9f8a4b493d77b2e6f52ae8ff64eefa8899c2065922665c8" + ] + } +} +``` + +Returns mempool detailed information (on verbose). +Or mempool tx list. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | verbose | false | False returns only tx hashs, true - returns full tx info + + + +## prioritisetransaction + +```javascript +let txhash, priorityDelta, feeDelta; +``` + +```shell--vars +txhash=''; +priorityDelta=1000; +feeDelta=1000; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "prioritisetransaction", + "params": [ "'$txhash'", "'$priorityDelta'", "'$feeDelta'" ] + }' +``` + +```shell--cli +bcoin cli rpc prioritisetransaction $txhash $priorityDelta $feeDelta +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('prioritisetransaction', [ txhash, priorityDelta, feeDelta ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +true +``` + +Prioritises the transaction. + +*Note: changing fee or priority will only trick local miner (using this mempool) +into accepting Transaction(s) into the block. (even if Priority/Fee doen't qualify)* + + +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | txid | Required | Transaction hash +2 | priority delta | Required | Virtual priority to add/subtract to the entry +3 | fee delta | Required | Virtual fee to add/subtract to the entry + + + +## estimatefee + +```javascript +let nblocks; +``` + +```shell--vars +nblocks=10; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "estimatefee", + "params": [ "'$nblocks'" ] + }' +``` + +```shell--cli +bcoin cli rpc estimatefee $nblocks +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('estimatefee', [ nblocks ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +0.001 +``` + +Estimates fee to be paid for transaction. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | nblocks | 1 | Number of blocks to check for estimation. + + + +## estimatepriority + +```javascript +let nblocks; +``` + +```shell--vars +nblocks=10; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "estimatepriority", + "params": [ "'$nblocks'" ] + }' +``` + +```shell--cli +bcoin cli rpc estimatepriority $nblocks +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('estimatepriority', [ nblocks ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +718158904.3501 +``` + +estimates the priority (coin age) that a transaction needs in order to be included within a certain number of blocks as a free high-priority transaction. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | nblocks | 1 | Number of blocks to check for estimation. + + + +## estimatesmartfee + +```javascript +let nblocks; +``` + +```shell--vars +nblocks=10; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "estimatesmartfee", + "params": [ "'$nblocks'" ] + }' +``` + +```shell--cli +bcoin cli rpc estimatesmartfee $nblocks +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('estimatesmartfee', [ nblocks ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "fee": 0.001, + "blocks": 10 +} +``` + +Estimates smart fee to be paid for transaction. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | nblocks | 1 | Number of blocks to check for estimation. + + + +## estimatesmartpriority + +```javascript +let nblocks; +``` + +```shell--vars +nblocks=10; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "estimatesmartpriority", + "params": [ "'$nblocks'" ] + }' +``` + +```shell--cli +bcoin cli rpc estimatesmartpriority $nblocks +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('estimatesmartpriority', [ nblocks ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "priority": 718158904.3501, + "blocks": 10 +} +``` + +estimates smart priority (coin age) that a transaction needs in order to be included within a certain number of blocks as a free high-priority transaction. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | nblocks | 1 | Number of blocks to check for estimation. + + + diff --git a/api-docs-slate/source/includes/_node_rpc_mining.md b/api-docs-slate/source/includes/_node_rpc_mining.md new file mode 100644 index 0000000..ccb6103 --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc_mining.md @@ -0,0 +1,638 @@ +# RPC Calls - Mining + +## getnetworkhashps + +```javascript +let blocks, height; +``` + +```shell--vars +blocks=120; +height=1000000; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getnetworkhashps", + "params": [ "'$blocks'", "'$height'" ] + }' +``` + +```shell--cli +bcoin cli rpc getnetworkhashps $blocks $height +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getnetworkhashps', [ blocks, height ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +453742051556.55084 +``` + +Returns the estimated current or historical network hashes per second, based on last `blocks`. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blocks | 120 | Number of blocks to lookup. +2 | height | 1 | Starting height for calculations. + + + +## getmininginfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getmininginfo", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getmininginfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getmininginfo', []); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "blocks": 1178789, + "currentblocksize": 11895, + "currentblockweight": 47580, + "currentblocktx": 35, + "difficulty": 1048576, + "errors": "", + "genproclimit": 0, + "networkhashps": 10880012194348.812, + "pooledtx": 34, + "testnet": true, + "chain": "test", + "generate": false +} + +``` + +Returns mining info. + +*Note: currentblocksize, currentblockweight, currentblocktx, difficulty are returned when there's active work.* +*generate - is true when `bcoin` itself is mining.* + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getwork + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getwork", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getwork +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getwork'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "data": "2000000082c18ff1d76f61dccbf37d5eca24d252c009af5f622ce08700000580000000009f447a03a1df9ae8f1ee24f0cf5ab69f1b321071f0e57344f2c61b922c12b8335994bdb51a0ffff000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000080020000", + "target": "0000000000000000000000000000000000000000000000f0ff0f000000000000", + "height": 1178782 +} +``` + +Returns hashing work to be solved by miner. +Or submits solved block. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | data | | Data to be submitted to the network. + +## getworklp + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getworklp", + "params": [] + }' +``` + +```shell--cli +# Because there is a request timeout set on CLI http requests +# without manually adjusting the timeout, this call will timeout before the request is complete +bcoin cli rpc getworklp +``` + +```javascript +// Because there is a request timeout set on CLI http requests +// without manually adjusting the timeout, this call will timeout before the request is complete +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getworklp'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "data": "2000000082c18ff1d76f61dccbf37d5eca24d252c009af5f622ce08700000580000000009f447a03a1df9ae8f1ee24f0cf5ab69f1b321071f0e57344f2c61b922c12b8335994bdb51a0ffff000000000000000800000000000000000000000000000000000000000000000000000000000000000000000000000000080020000", + "target": "0000000000000000000000000000000000000000000000f0ff0f000000000000", + "height": 1178782 +} +``` + +Long polling for new work. + +Returns new work, whenever new TX is received in the mempool or +new block has been discovered. So miner can restart mining on new data. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getblocktemplate + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getblocktemplate", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getblocktemplate +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getblocktemplate'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "capabilities": [ + "proposal" + ], + "mutable": [ + "time", + "transactions", + "prevblock" + ], + "version": 536870912, + "rules": [ + "csv", + "!segwit" + ], + "vbavailable": {}, + "vbrequired": 0, + "height": 1178933, + "previousblockhash": "0000000000000e19ff0c98e7d99987071a791c47338f71389342f7457eeb8695", + "target": "0000000000000ffff00000000000000000000000000000000000000000000000", + "bits": "1a0ffff0", + "noncerange": "00000000ffffffff", + "curtime": 1502974969, + "mintime": 1502974260, + "maxtime": 1502982169, + "expires": 1502982169, + "sigoplimit": 80000, + "sizelimit": 4000000, + "weightlimit": 4000000, + "longpollid": "0000000000000e19ff0c98e7d99987071a791c47338f71389342f7457eeb86950000000018", + "submitold": false, + "coinbaseaux": { + "flags": "62636f696e206d6163626f6f6b" + }, + "coinbasevalue": 156465644, + "default_witness_commitment": "6a24aa21a9edc9f8a77e851392ce58c6b5c64fafbebd76e92c03a198d1e2c942d71fe05c7bc4", + "transactions": [ + { + "data": "010000000194a1dd786bc486412dd4125c90eeac0550131b7ffee190d3c8bce92007dfe682000000006b483045022100e2ee65fcdb3c005e430c279e759764937e70993c3a97c21b8580b16146766cdc022044cbb4a09ce4ed4f9c6be14befb6fbccd7819814073f33220e076ced7b103fca01210396e891cf6f1e71e1a266abd3c1e990331da6dc2d3b41e53c6e991f66262f2f32ffffffff022aee0500000000001976a914a21138d3322b67910f66f676396ea432faee34cb88aca0860100000000001976a91494178f0b288078717873b4228e2aad27b91a492188ac00000000", + "txid": "809c3d8fb6524acc4ffcaeb2a97ccb1c4c1124ccc5034745ba6ac43f8d4d63c9", + "hash": "809c3d8fb6524acc4ffcaeb2a97ccb1c4c1124ccc5034745ba6ac43f8d4d63c9", + "depends": [], + "fee": 11350, + "sigops": 8, + "weight": 904 + }, + ... + ] +} +``` + +returns block template or proposal for use with mining. +Also validates proposal if `mode` is specified as `proposal`. + +*Note: This is described in +[BIP22 - Fundamentals](https://github.com/bitcoin/bips/blob/master/bip-0022.mediawiki), +[BIP23 - Pooled Mining](https://github.com/bitcoin/bips/blob/master/bip-0023.mediawiki), +[BIP145 - Updates for Segregated Witness](https://github.com/bitcoin/bips/blob/master/bip-0145.mediawiki)* + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | jsonrequestobject | {} | JSONRequestObject. + + + +## submitblock + +```javascript +let blockdata; +``` + +```shell--vars +blockdata='0100000082d6e6bf4ed6c5b989705920effd072fe6b7119ea5b8c8fa6d0bf5c70000000071959f90386cdc263655d36033817a6f69cbc2d99fc56cc81f893b9787907a4fcfc94a4dffff001d000f90930901000000010000000000000000000000000000000000000000000000000000000000000000ffffffff163337346bde777ade327922b5deef5fb7f88e98cecb22ffffffff01800c0c2a0100000023210207a8b8758b4886d85b7f94fbd9cacb3452c5e643dc3188a1dbea8d1a1dd4bbc3ac0000000001000000017c9665a50c9bcc8c359c58ffd511d8cfe122b440cdb6ad864a43f1644eb31fe6000000006b48304502201569b4872c3639811ab467ec559416c1006d257a5d6fea103a41a408dd8a5682022100c1a3c90cbd148a4ca69189c88d059e2af8268807982d89b76725d38f65494f5201210394afa526e43a0e03f5aaa2a55312f6c25a9b5fedd66e7f4e4847af79d517c5f5ffffffff02bc80b01f010000001976a91451513561deaa318f4a3ad2bfccc889225499194388ac359a0300000000001976a914bc0f9f5fc9dc55323d52a9e354b5fb67cecd389788ac0000000001000000035f836b328d40944483c39c90cb4dfd3d9b83f96d71586b3230118629fb7893f7000000006a473044022076232b5d3b8372da7e0a5b58614676b6ad77debf0ed75a5996f9b91642326059022037e2ee19b56916465e9c76e7e1d558a64738e7444649144bf7e19143423aee1401210281392a2cd37ac1108b8bc0f647784f66017fd837379e6fc2109f1793f5dccfdbffffffff58bd81fd34d42c015ac22537440c49450453e8284b717667c418ed7dc3693579000000006b48304502200352ee3028c8c4ff14574e71837a2e68b1c285dd57b993e19d9b24728161409f022100d7cd062e64e57200bf1ffa0fbd41726a67cfe547849b0fcfe72556fb42596d630121039bd575a5913e93d227afa8e65c5c37954688e53e069980e4790aba8652d9d557ffffffff8a64fa7fb31eff45e2145ba1d09a4ac627e259d14a3b9154c510d44c9954f3c1000000006a473044022044e97e0e287472385c60c68f4e16a73e3e6d7fcb1bc3700fa7c36c4fb653e1cb022034c624487aedb8bc3c86b02d0338b10922fa1c6c8fd8c39eaf64564d62289fe101210370410acad1e5601c9e8e8968ccf648daab3902744091c19b29a17c8e2cf92132ffffffff0268911d00000000001976a91480cac4151b3a9ceffaee95018f0ca3d202a71b2c88ac334f1000000000001976a914cd4529e867a0b96d43e358998387b06fc3e06e8c88ac0000000001000000015f836b328d40944483c39c90cb4dfd3d9b83f96d71586b3230118629fb7893f701000000fd3301347b3d4a6f10829e9c617770a52f2334a434677a08ac775c968b3097b1353d1e1a10b53099a2003c7cb03a5152690e687e191a990048304502201613b0ce320ccc1d206a03f67fecf6d1b31fdd23e51923a821fda745c23cd4db022100854bdd81256edfac75ac7dc9d0b073118b5879f50b26021eeffa4d126f39cf7301493046022100bce73cabbb1d4bca0ee33b241bc526cbb6c17f219057a58993738d614c898e0f022100b9aa31160b3bc6e2bf2e33240ea8543a9f54551b78c7cb268e72a3cee45cc5a3014c69522102ca2a810ab17249b6033a038de563983881b4069270183f3c0aba945653e442162103f480f1b648d0d5167804ad4d586e0e757cc33fde0e133fd036e45d60d2db59e12103c18131d8de99d45fb72a774cab0ccc258cd2abd9605610da20b9a232c88a3cb653aeffffffff025e310100000000001976a91445c502d496058c41721e06c6ebd5a8580dd66d8488ac78940100000000001976a914bc0f9f5fc9dc55323d52a9e354b5fb67cecd389788ac000000000100000001e667afd60a5c5e3190ac4d4ec2ca3a2ac96ae5ec4fdb161ecf8db06bf22e1fc6000000006b483045022100a0cc8f57d5a171aa4a5d3c963640039e11c5dac38820eb90c284eb360326041d02202917e30b20178f9c4464d44f956aa8105b83b24f4a0f011ca380b35f31c6bcf20121029e6f1aaf22a7114a000627eba8b2990c86136e7fab46dffccf1a33a505d039f6ffffffff024c79a81f010000001976a914a196eec6c686089ffcc8a9d4077643ede546535088ac204407000000000017a914184cd0a38ac3b1357d07179553788375a9e8a3b887000000000100000001c054bdbfe97e3997a0858d4578f69e50b018cd2cd966c9339c10030a9e43cc90000000006a47304402201feccc650991032dc98ed330aaa68840feac3e0ae568d674ebc480d8f810eedf02205b06d5dce842cb5f684fb6816d61425d5533cc73b05cbdf2a1552699da98f97d01210391af1358729c7ea974cf76e43a125158687550610108791a1563be587e48bf9affffffff02a194a41f010000001976a914bdfa420798058a37dd0c37ba1d38f103a793649c88ac5b210300000000001976a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac0000000001000000019cf0d401fba9272613dc9e06d64cd1ccb7596acb37b46f10f811d76f46f7671d000000006b48304502202599390550a38555ae661be940716ac669c7493e34216a71ca86d069636d6e3a022100ae406057ec3f60f9e3410360facf1bd1f59b1e4cc27a2b4ba67e325658319b390121032165eff60895ce9b519aa327adc44e4867b3aa5998d8bdb0e277da3fa67873a3ffffffff024e55991f010000001976a9149c5c9a7c09d843b451eaa0c7cbf866623405babf88ac037c0a000000000017a914a4b7adff15fec83376d5e4468afeed627abe1ed88700000000010000000180b35d06ed071cf7ad57b1f87f5ae21c29f47b9740f998414d79cdb4f5502440000000006c4930460221009014b9cb28077036096492e8c0a46bd8aa6d43758fc211817d22e0401db5a0300221008c23434e440108b2d0dce98a0647bab603e8e876467ecb339201473054ff80650121023cf5ef93ca567172647fad0e3b1cb0456cbfad88e4f65e286471ed93fba66a10ffffffff024a2e8c1f010000001976a914bc7aad9746a0bc03ed9715f13c94e554df90b84688acb4630c00000000001976a914bc0f9f5fc9dc55323d52a9e354b5fb67cecd389788ac000000000100000001c702cde8b6a003a898cb437177a2c6af0da0f13f04fce6d52731394dd2a57301000000006c493046022100be75ae6dbf9eab7656562136511501c83918ca28c5f96565ca1960b3dbb581b6022100d15692af456e8721fddeeb0d6df5d8a147afd8a3b2a39bbceae9b1bdfd53ade20121038e297cf2cf71c16592c36ca48f5b2a5bbb73e776e772079f4c695b12eec1a509ffffffff023b37871f010000001976a914682215dfa6912d88f55a1853414d516122fcc66988acbf330400000000001976a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac00000000'; +``` + +```shell--curl +# Block data is old, so it should return error +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "submitblock", + "params": [ "'$blockdata'" ] + }' +``` + +```shell--cli +# Block data is old, so it should return error +bcoin cli rpc submitblock $blockdata +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + // Block data is old, so it should return error + const res = await rpc.execute('submitblock', [ blockdata ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +Adds block to chain. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockdata | Required. | Mined block data (hex) + +## verifyblock + +```javascript +let blockdata; +``` + +```shell--vars +blockdata='0100000082d6e6bf4ed6c5b989705920effd072fe6b7119ea5b8c8fa6d0bf5c70000000071959f90386cdc263655d36033817a6f69cbc2d99fc56cc81f893b9787907a4fcfc94a4dffff001d000f90930901000000010000000000000000000000000000000000000000000000000000000000000000ffffffff163337346bde777ade327922b5deef5fb7f88e98cecb22ffffffff01800c0c2a0100000023210207a8b8758b4886d85b7f94fbd9cacb3452c5e643dc3188a1dbea8d1a1dd4bbc3ac0000000001000000017c9665a50c9bcc8c359c58ffd511d8cfe122b440cdb6ad864a43f1644eb31fe6000000006b48304502201569b4872c3639811ab467ec559416c1006d257a5d6fea103a41a408dd8a5682022100c1a3c90cbd148a4ca69189c88d059e2af8268807982d89b76725d38f65494f5201210394afa526e43a0e03f5aaa2a55312f6c25a9b5fedd66e7f4e4847af79d517c5f5ffffffff02bc80b01f010000001976a91451513561deaa318f4a3ad2bfccc889225499194388ac359a0300000000001976a914bc0f9f5fc9dc55323d52a9e354b5fb67cecd389788ac0000000001000000035f836b328d40944483c39c90cb4dfd3d9b83f96d71586b3230118629fb7893f7000000006a473044022076232b5d3b8372da7e0a5b58614676b6ad77debf0ed75a5996f9b91642326059022037e2ee19b56916465e9c76e7e1d558a64738e7444649144bf7e19143423aee1401210281392a2cd37ac1108b8bc0f647784f66017fd837379e6fc2109f1793f5dccfdbffffffff58bd81fd34d42c015ac22537440c49450453e8284b717667c418ed7dc3693579000000006b48304502200352ee3028c8c4ff14574e71837a2e68b1c285dd57b993e19d9b24728161409f022100d7cd062e64e57200bf1ffa0fbd41726a67cfe547849b0fcfe72556fb42596d630121039bd575a5913e93d227afa8e65c5c37954688e53e069980e4790aba8652d9d557ffffffff8a64fa7fb31eff45e2145ba1d09a4ac627e259d14a3b9154c510d44c9954f3c1000000006a473044022044e97e0e287472385c60c68f4e16a73e3e6d7fcb1bc3700fa7c36c4fb653e1cb022034c624487aedb8bc3c86b02d0338b10922fa1c6c8fd8c39eaf64564d62289fe101210370410acad1e5601c9e8e8968ccf648daab3902744091c19b29a17c8e2cf92132ffffffff0268911d00000000001976a91480cac4151b3a9ceffaee95018f0ca3d202a71b2c88ac334f1000000000001976a914cd4529e867a0b96d43e358998387b06fc3e06e8c88ac0000000001000000015f836b328d40944483c39c90cb4dfd3d9b83f96d71586b3230118629fb7893f701000000fd3301347b3d4a6f10829e9c617770a52f2334a434677a08ac775c968b3097b1353d1e1a10b53099a2003c7cb03a5152690e687e191a990048304502201613b0ce320ccc1d206a03f67fecf6d1b31fdd23e51923a821fda745c23cd4db022100854bdd81256edfac75ac7dc9d0b073118b5879f50b26021eeffa4d126f39cf7301493046022100bce73cabbb1d4bca0ee33b241bc526cbb6c17f219057a58993738d614c898e0f022100b9aa31160b3bc6e2bf2e33240ea8543a9f54551b78c7cb268e72a3cee45cc5a3014c69522102ca2a810ab17249b6033a038de563983881b4069270183f3c0aba945653e442162103f480f1b648d0d5167804ad4d586e0e757cc33fde0e133fd036e45d60d2db59e12103c18131d8de99d45fb72a774cab0ccc258cd2abd9605610da20b9a232c88a3cb653aeffffffff025e310100000000001976a91445c502d496058c41721e06c6ebd5a8580dd66d8488ac78940100000000001976a914bc0f9f5fc9dc55323d52a9e354b5fb67cecd389788ac000000000100000001e667afd60a5c5e3190ac4d4ec2ca3a2ac96ae5ec4fdb161ecf8db06bf22e1fc6000000006b483045022100a0cc8f57d5a171aa4a5d3c963640039e11c5dac38820eb90c284eb360326041d02202917e30b20178f9c4464d44f956aa8105b83b24f4a0f011ca380b35f31c6bcf20121029e6f1aaf22a7114a000627eba8b2990c86136e7fab46dffccf1a33a505d039f6ffffffff024c79a81f010000001976a914a196eec6c686089ffcc8a9d4077643ede546535088ac204407000000000017a914184cd0a38ac3b1357d07179553788375a9e8a3b887000000000100000001c054bdbfe97e3997a0858d4578f69e50b018cd2cd966c9339c10030a9e43cc90000000006a47304402201feccc650991032dc98ed330aaa68840feac3e0ae568d674ebc480d8f810eedf02205b06d5dce842cb5f684fb6816d61425d5533cc73b05cbdf2a1552699da98f97d01210391af1358729c7ea974cf76e43a125158687550610108791a1563be587e48bf9affffffff02a194a41f010000001976a914bdfa420798058a37dd0c37ba1d38f103a793649c88ac5b210300000000001976a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac0000000001000000019cf0d401fba9272613dc9e06d64cd1ccb7596acb37b46f10f811d76f46f7671d000000006b48304502202599390550a38555ae661be940716ac669c7493e34216a71ca86d069636d6e3a022100ae406057ec3f60f9e3410360facf1bd1f59b1e4cc27a2b4ba67e325658319b390121032165eff60895ce9b519aa327adc44e4867b3aa5998d8bdb0e277da3fa67873a3ffffffff024e55991f010000001976a9149c5c9a7c09d843b451eaa0c7cbf866623405babf88ac037c0a000000000017a914a4b7adff15fec83376d5e4468afeed627abe1ed88700000000010000000180b35d06ed071cf7ad57b1f87f5ae21c29f47b9740f998414d79cdb4f5502440000000006c4930460221009014b9cb28077036096492e8c0a46bd8aa6d43758fc211817d22e0401db5a0300221008c23434e440108b2d0dce98a0647bab603e8e876467ecb339201473054ff80650121023cf5ef93ca567172647fad0e3b1cb0456cbfad88e4f65e286471ed93fba66a10ffffffff024a2e8c1f010000001976a914bc7aad9746a0bc03ed9715f13c94e554df90b84688acb4630c00000000001976a914bc0f9f5fc9dc55323d52a9e354b5fb67cecd389788ac000000000100000001c702cde8b6a003a898cb437177a2c6af0da0f13f04fce6d52731394dd2a57301000000006c493046022100be75ae6dbf9eab7656562136511501c83918ca28c5f96565ca1960b3dbb581b6022100d15692af456e8721fddeeb0d6df5d8a147afd8a3b2a39bbceae9b1bdfd53ade20121038e297cf2cf71c16592c36ca48f5b2a5bbb73e776e772079f4c695b12eec1a509ffffffff023b37871f010000001976a914682215dfa6912d88f55a1853414d516122fcc66988acbf330400000000001976a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac00000000'; +``` + +```shell--curl +# Block data is old, so it should return error +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "verifyblock", + "params": [ "'$blockdata'" ] + }' +``` + +```shell--cli +# Block data is old, so it should return error +bcoin cli rpc verifyblock $blockdata +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + // Block data is old, so it should return error + const res = await rpc.execute('verifyblock', [ blockdata ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +Verifies the block data. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | blockdata | Required. | Mined block data (hex) + + + + + +## setgenerate + +```javascript +let mining, proclimit; +``` + +```shell--vars +mining=1; +proclimit=1; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "setgenerate", + "params": [ "'$mining'", "'$proclimit'" ] + }' +``` + +```shell--cli +bcoin cli rpc setgenerate $mining $proclimit +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('setgenerate', [ mining, proclimit ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +true +``` + +Will start the mining on CPU. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | mining | 0 | `true` will start mining, `false` will stop. +2 | proclimit | 0 | + + + +## getgenerate + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getgenerate", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getgenerate +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getgenerate'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +true +``` + +Returns status of mining on Node. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. + + + +## generate + +```javascript +let numblocks; +``` + +```shell--vars +numblocks=2; +``` + +```shell--curl +# Will return once all blocks are mined. +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "generate", + "params": [ "'$numblocks'" ] + }' +``` + +```shell--cli +# Timeout error +bcoin cli rpc generate $numblocks +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + // Timeout error + const res = await rpc.execute('generate', [ numblocks ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +[ + "0aac2269ce67d5bda3743b1a179a7824f17b3b6df011befd7bd224cb958bd4ec", + "0871f1a42279397b7508c75e142b903a945a19af08c6de6970e266255d10f08f" +] +``` + +Mines `numblocks` number of blocks. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | numblocks | 1 | Number of blocks to mine. +2 | maxtries | + + + +## generatetoaddress + +```javascript +let numblocks, address; +``` + +```shell--vars +numblocks=2; +address='RTZJdYScA7uGb5pbQPEczpDmq9HiYLv2fJ'; +``` + +```shell--curl +# Will return once all blocks are mined. +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "generatetoaddress", + "params": [ "'$numblocks'", "'$address'" ] + }' +``` + +```shell--cli +# Timeout error +bcoin cli rpc generatetoaddress $numblocks $address +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + // Timeout error + const res = await rpc.execute('generatetoaddress', [ numblocks, address ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +[ + "0aac2269ce67d5bda3743b1a179a7824f17b3b6df011befd7bd224cb958bd4ec", + "0871f1a42279397b7508c75e142b903a945a19af08c6de6970e266255d10f08f" +] +``` +Mines `blocknumber` blocks, with `address` as coinbase. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | numblocks | 1 | Number of blocks to mine. +2 | address | | Coinbase address for new blocks. diff --git a/api-docs-slate/source/includes/_node_rpc_network.md b/api-docs-slate/source/includes/_node_rpc_network.md new file mode 100644 index 0000000..b91679f --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc_network.md @@ -0,0 +1,614 @@ +# RPC Calls - Network + +## getconnectioncount + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getconnectioncount", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getconnectioncount +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getconnectioncount'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +8 +``` + +Returns connection count. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + +## ping + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "ping", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc ping +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('ping'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +null +``` + +Will send ping request to every connected peer. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getpeerinfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getpeerinfo", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getpeerinfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getpeerinfo'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +[ + { + "id": 1, + "addr": "198.51.100.82:18333", + "addrlocal": "203.0.113.114:60760", + "services": "0000000d", + "relaytxes": true, + "lastsend": 1503257171, + "lastrecv": 1503257171, + "bytessent": 1962, + "bytesrecv": 32499, + "conntime": 121, + "timeoffset": -1, + "pingtime": 0.143, + "minping": 0.143, + "version": 70015, + "subver": "/Satoshi:0.14.1/", + "inbound": false, + "startingheight": 1179570, + "besthash": null, + "bestheight": -1, + "banscore": 0, + "inflight": [], + "whitelisted": false + }, + ... +] +``` + +Returns information about all connected peers. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + + +## addnode + +```javascript +let nodeAddr, cmd; +``` + +```shell--vars +nodeAddr='198.51.100.82:18333'; +cmd='add' +``` + + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "addnode", + "params": [ "'$nodeAddr'", "'$cmd'" ] + }' +``` + +```shell--cli +bcoin cli rpc addnode $nodeAddr $cmd +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('addnode', [ nodeAddr, cmd ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +null +``` + +Adds or removes peers in Host List. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | addr | Required | IP Address of the Node. +2 | cmd | Required | Command + +### Commands +Command | Description +---- | ---- +add | Adds node to Host List and connects to it +onetry | Tries to connect to the given node +remove | Removes node from host list + + + +## disconnectnode + +```javascript +let nodeAddr; +``` + +```shell--vars +nodeAddr='198.51.100.82:18333'; +``` + + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "disconnectnode", + "params": [ "'$nodeAddr'" ] + }' +``` + +```shell--cli +bcoin cli rpc disconnectnode $nodeAddr +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('disconnectnode', [ nodeAddr ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +null +``` + +Disconnects node. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | addr | Required | IP Address of the Node. + + + +## getaddednodeinfo + +```javascript +let nodeAddr; +``` + +```shell--vars +nodeAddr='198.51.100.82:18333'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getaddednodeinfo", + "params": [ "'$nodeAddr'" ] + }' +``` + +```shell--cli +bcoin cli rpc getaddednodeinfo $nodeAddr +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getaddednodeinfo', [ nodeAddr ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +[ + { + "addednode": "198.51.100.82:18333", + "connected": true, + "addresses": [ + { + "address": "198.51.100.82:18333", + "connected": "outbound" + } + ] + } +] +``` + +Returns node information from host list. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | addr | Required | IP Address of the Node. + + + +## getnettotals + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getnettotals", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getnettotals +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getnettotals'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "totalbytesrecv": 370598, + "totalbytessent": 110058, + "timemillis": 1503262547279 +} +``` + +Returns information about used network resources. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getnetworkinfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getnetworkinfo", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc getnetworkinfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getnetworkinfo'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + + +> The above command returns JSON "result" like this: + +```json +{ + "version": "v1.0.0-beta.14", + "subversion": "/bcoin:v1.0.0-beta.14/", + "protocolversion": 70015, + "localservices": "00000009", + "localrelay": true, + "timeoffset": -1, + "networkactive": true, + "connections": 8, + "networks": [], + "relayfee": 0.00001, + "incrementalfee": 0, + "localaddresses": [ + { + "address": "203.0.113.114", + "port": 18333, + "score": 3 + } + ], + "warnings": "" +} +``` + +Returns local node's network information + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## setban + +```javascript +let nodeAddr, cmd; +``` + +```shell--vars +nodeAddr='198.51.100.82:18333'; +cmd='add' +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "setban", + "params": [ "'$nodeAddr'", "'$cmd'" ] + }' +``` + +```shell--cli +bcoin cli rpc setban $nodeAddr $cmd +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('setban', [ nodeAddr, cmd ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +null +``` + +Adds or removes nodes from banlist. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | addr | Required | IP Address of the Node. +2 | cmd | Required | Command + +### Commands +Command | Description +---- | ---- +add | Adds node to ban list, removes from host list, disconnects. +remove | Removes node from ban list + + + +## listbanned + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "listbanned", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc listbanned +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('listbanned'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +[ + { + "address": "198.51.100.82:18333", + "banned_until": 1503349501, + "ban_created": 1503263101, + "ban_reason": "" + }, + ... +] +``` + +Lists all banned peers. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## clearbanned + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "clearbanned", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc clearbanned +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('clearbanned'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +null +``` + +Removes all banned peers. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | diff --git a/api-docs-slate/source/includes/_node_rpc_tx.md b/api-docs-slate/source/includes/_node_rpc_tx.md new file mode 100644 index 0000000..c2c36a9 --- /dev/null +++ b/api-docs-slate/source/includes/_node_rpc_tx.md @@ -0,0 +1,680 @@ +# RPC Calls - Transactions + +## gettxout + +```javascript +let txhash, index, includemempool; +``` + +```shell--vars +txhash='28d65fdaf5334ffd29066d7076f056bb112baa4bb0842f6eaa06171c277b4e8c'; +index=0; +includemempool=1; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "gettxout", + "params": [ "'$txhash'", "'$index'", "'$includemempool'" ] + }' +``` + +```shell--cli +bcoin cli rpc gettxout $txhash $index $includemempool +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('gettxout', [ txhash, index, includemempool ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "bestblock": "00000000000004f0fbf1b2290e8255bbd468640d747fd9d44a16e77d9e129a55", + "confirmations": 1, + "value": 1.01, + "scriptPubKey": { + "asm": "OP_HASH160 6a58967510cfd7e04987b245f73dbf62e8d3fdf8 OP_EQUAL", + "hex": "a9146a58967510cfd7e04987b245f73dbf62e8d3fdf887", + "type": "SCRIPTHASH", + "reqSigs": 1, + "addresses": [ + "2N2wXjoQbEQTKQuqYdkpHMp7rPpnpumYYqe" + ] + }, + "version": 1, + "coinbase": false +} +``` + +Get outpoint of the transaction. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | txid | Required | Transaction hash +2 | index | Required | Index of the Outpoint tx. +3 | includemempool | true | Whether to include mempool transactions. + + + +## gettxoutsetinfo + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "gettxoutsetinfo", + "params": [] + }' +``` + +```shell--cli +bcoin cli rpc gettxoutsetinfo +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('gettxoutsetinfo'); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "height": 1178729, + "bestblock": "00000000000004f0fbf1b2290e8255bbd468640d747fd9d44a16e77d9e129a55", + "transactions": 14827318, + "txouts": 17644185, + "bytes_serialized": 0, + "hash_serialized": 0, + "total_amount": 20544080.67292757 +} +``` + +Returns information about UTXO's from Chain. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +None. | + + + +## getrawtransaction + +```javascript +let txhash, verbose=0; +``` + +```shell--vars +txhash='28d65fdaf5334ffd29066d7076f056bb112baa4bb0842f6eaa06171c277b4e8c'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "getrawtransaction", + "params": [ "'$txhash'", "'$verbose'" ] + }' +``` + +```shell--cli +bcoin cli rpc getrawtransaction $txhash $verbose +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('getrawtransaction', [ txhash, verbose ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +"0100000002500310ff36beb6c3608230534ef995f7751b6f948aeea8d21d5cc9dd5023a2c4010000006b483045022100e7c71d397b687f9f30e6003ceedc4c50436fdb2329b7a8a36c9c6759077969d30220059f24e917260d3e601c77079d03c9e73d04fd85f625eaebfd14a1ff695a72230121020bc134c91f4ff068f3a970616fad577f949406c18849321a2f6d4df96fc56c77feffffffeffed95ded4f227fc6717f224e85e50348ce0198303a5418f157ade42828a1e3000000006b483045022100f0bde463404db0983e0f221bfa1b13edf1063a78e869295c9457864b122a622b02207d9d5df76ecac6289784201e9a918acb34510c2d65144bf8e4753a3413024e320121022565ed0ff8f79ecf11e8f33b9fbba5606dbc0618813acd74603f9466e88fb8a8feffffff02402305060000000017a9146a58967510cfd7e04987b245f73dbf62e8d3fdf8871e194f00000000001976a914132b05f47f2b1b56f26a78d3962e3acd0735f12d88ac00000000" +``` + +Returns raw transaction + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | txhash | Required | Transaction hash +2 | verbose | false | Returns json formatted if true + + + +## decoderawtransaction + +```javascript +let rawtx; +``` + +```shell--vars +rawtx='0100000002500310ff36beb6c3608230534ef995f7751b6f948aeea8d21d5cc9dd5023a2c4010000006b483045022100e7c71d397b687f9f30e6003ceedc4c50436fdb2329b7a8a36c9c6759077969d30220059f24e917260d3e601c77079d03c9e73d04fd85f625eaebfd14a1ff695a72230121020bc134c91f4ff068f3a970616fad577f949406c18849321a2f6d4df96fc56c77feffffffeffed95ded4f227fc6717f224e85e50348ce0198303a5418f157ade42828a1e3000000006b483045022100f0bde463404db0983e0f221bfa1b13edf1063a78e869295c9457864b122a622b02207d9d5df76ecac6289784201e9a918acb34510c2d65144bf8e4753a3413024e320121022565ed0ff8f79ecf11e8f33b9fbba5606dbc0618813acd74603f9466e88fb8a8feffffff02402305060000000017a9146a58967510cfd7e04987b245f73dbf62e8d3fdf8871e194f00000000001976a914132b05f47f2b1b56f26a78d3962e3acd0735f12d88ac00000000'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "decoderawtransaction", + "params": [ "'$rawtx'" ] + }' +``` + +```shell--cli +bcoin cli rpc decoderawtransaction $rawtx +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('decoderawtransaction', [ rawtx ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "txid": "28d65fdaf5334ffd29066d7076f056bb112baa4bb0842f6eaa06171c277b4e8c", + "hash": "28d65fdaf5334ffd29066d7076f056bb112baa4bb0842f6eaa06171c277b4e8c", + "size": 372, + "vsize": 372, + "version": 1, + "locktime": 0, + "vin": [ + { + "txid": "c4a22350ddc95c1dd2a8ee8a946f1b75f795f94e53308260c3b6be36ff100350", + "scriptSig": { + "asm": "3045022100e7c71d397b687f9f30e6003ceedc4c50436fdb2329b7a8a36c9c6759077969d30220059f24e917260d3e601c77079d03c9e73d04fd85f625eaebfd14a1ff695a722301 020bc134c91f4ff068f3a970616fad577f949406c18849321a2f6d4df96fc56c77", + "hex": "483045022100e7c71d397b687f9f30e6003ceedc4c50436fdb2329b7a8a36c9c6759077969d30220059f24e917260d3e601c77079d03c9e73d04fd85f625eaebfd14a1ff695a72230121020bc134c91f4ff068f3a970616fad577f949406c18849321a2f6d4df96fc56c77" + }, + "sequence": 4294967294, + "vout": 1 + }, + { + "txid": "e3a12828e4ad57f118543a309801ce4803e5854e227f71c67f224fed5dd9feef", + "scriptSig": { + "asm": "3045022100f0bde463404db0983e0f221bfa1b13edf1063a78e869295c9457864b122a622b02207d9d5df76ecac6289784201e9a918acb34510c2d65144bf8e4753a3413024e3201 022565ed0ff8f79ecf11e8f33b9fbba5606dbc0618813acd74603f9466e88fb8a8", + "hex": "483045022100f0bde463404db0983e0f221bfa1b13edf1063a78e869295c9457864b122a622b02207d9d5df76ecac6289784201e9a918acb34510c2d65144bf8e4753a3413024e320121022565ed0ff8f79ecf11e8f33b9fbba5606dbc0618813acd74603f9466e88fb8a8" + }, + "sequence": 4294967294, + "vout": 0 + } + ], + "vout": [ + { + "value": 1.01, + "n": 0, + "scriptPubKey": { + "asm": "OP_HASH160 6a58967510cfd7e04987b245f73dbf62e8d3fdf8 OP_EQUAL", + "hex": "a9146a58967510cfd7e04987b245f73dbf62e8d3fdf887", + "type": "SCRIPTHASH", + "reqSigs": 1, + "addresses": [ + "2N2wXjoQbEQTKQuqYdkpHMp7rPpnpumYYqe" + ] + } + }, + { + "value": 0.05183774, + "n": 1, + "scriptPubKey": { + "asm": "OP_DUP OP_HASH160 132b05f47f2b1b56f26a78d3962e3acd0735f12d OP_EQUALVERIFY OP_CHECKSIG", + "hex": "76a914132b05f47f2b1b56f26a78d3962e3acd0735f12d88ac", + "type": "PUBKEYHASH", + "reqSigs": 1, + "addresses": [ + "mhGJg1PJg8hVPX9A6zg4q389YFisSzQW6d" + ] + } + } + ], + "blockhash": null, + "confirmations": 0, + "time": 0, + "blocktime": 0 +} +``` + +Decodes raw tx and provide chain info. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | rawtx | Required | Raw transaction hex + + + +## decodescript + +```javascript +let script; +``` + +```shell--vars +script='483045022100f0bde463404db0983e0f221bfa1b13edf1063a78e869295c9457864b122a622b02207d9d5df76ecac6289784201e9a918acb34510c2d65144bf8e4753a3413024e320121022565ed0ff8f79ecf11e8f33b9fbba5606dbc0618813acd74603f9466e88fb8a8'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "decodescript", + "params": [ "'$script'" ] + }' +``` + +```shell--cli +bcoin cli rpc decodescript $script +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('decodescript', [ script ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "asm": "3045022100f0bde463404db0983e0f221bfa1b13edf1063a78e869295c9457864b122a622b02207d9d5df76ecac6289784201e9a918acb34510c2d65144bf8e4753a3413024e3201 022565ed0ff8f79ecf11e8f33b9fbba5606dbc0618813acd74603f9466e88fb8a8", + "type": "NONSTANDARD", + "reqSigs": 1, + "addresses": [], + "p2sh": "2MyVRHsEpec67MkPLGr4NR2bT1ZFuzFGUoB" +} +``` + +Decodes script + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | script | Required | Script hex + + +## sendrawtransaction + +```javascript +let rawtx; +``` + +```shell--vars +rawtx='0100000002500310ff36beb6c3608230534ef995f7751b6f948aeea8d21d5cc9dd5023a2c4010000006b483045022100e7c71d397b687f9f30e6003ceedc4c50436fdb2329b7a8a36c9c6759077969d30220059f24e917260d3e601c77079d03c9e73d04fd85f625eaebfd14a1ff695a72230121020bc134c91f4ff068f3a970616fad577f949406c18849321a2f6d4df96fc56c77feffffffeffed95ded4f227fc6717f224e85e50348ce0198303a5418f157ade42828a1e3000000006b483045022100f0bde463404db0983e0f221bfa1b13edf1063a78e869295c9457864b122a622b02207d9d5df76ecac6289784201e9a918acb34510c2d65144bf8e4753a3413024e320121022565ed0ff8f79ecf11e8f33b9fbba5606dbc0618813acd74603f9466e88fb8a8feffffff02402305060000000017a9146a58967510cfd7e04987b245f73dbf62e8d3fdf8871e194f00000000001976a914132b05f47f2b1b56f26a78d3962e3acd0735f12d88ac00000000'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "sendrawtransaction", + "params": [ "'$rawtx'" ] + }' +``` + +```shell--cli +bcoin cli rpc sendrawtransaction $rawtx +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('sendrawtransaction', [ rawtx ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> + +```json +"28d65fdaf5334ffd29066d7076f056bb112baa4bb0842f6eaa06171c277b4e8c" +``` + +Sends raw transaction without verification + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | rawtx | Required | Raw transaction hex + + + +## createrawtransaction + +```javascript +let txhash, txindex, amount, address, data; +``` + +```shell--vars +txhash='d1e1b6a8ff8c4d2ade2113a5dd250637e5f99667d36dcae9b70139516cb7052f'; +txindex=1; +amount=1; + +address='RStiqGLWA3aSMrWDyJvur4287GQ81AtLh1'; +data=''; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "createrawtransaction", + "params": [ + [{ "txid": "'$txhash'", "vout": "'$txindex'" }], + { "'$address'": "'$amount'", "data": "'$data'" } + ] + }' +``` + +```shell--cli +bcoin cli rpc createrawtransaction \ + '[{ "txid": "'$txhash'", "vout": "'$txindex'" }]' \ + '{ "'$address'": "'$amount'", "data": "'$data'" }' + +``` + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'regtest' +}); + +(async () => { + const sendTo = { + data: data + }; + + sendTo[address] = amount; + + const res = await rpc.execute('createrawtransaction', [ [{ txid: txhash, vout: txindex }], sendTo]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +"01000000012f05b76c513901b7e9ca6dd36796f9e5370625dda51321de2a4d8cffa8b6e1d10100000000ffffffff0200e1f505000000001976a914c1325e8fb60bd71d23532c39b4c9e743a2cc764988ac0000000000000000026a0000000000" +``` + + + +Creates raw, unsigned transaction without any formal verification. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | outpoints | Required | Outpoint list +1.1 | txid | | Transaction Hash +1.2 | vout | | Transaction Outpoint Index +1.3 | sequence | | Sequence number for input +2 | sendto | Required | List of addresses with amounts that we are sending to. +2.1 | address | 0 | `address: amount` key pairs +2.2 | data | nullData | Data output +3 | locktime | | earliest time a transaction can be added + + +## signrawtransaction + +```javascript +let rawtx, txhash, txindex, scriptPubKey, amount, privkey; +``` + +```shell--vars +rawtx='01000000012f05b76c513901b7e9ca6dd36796f9e5370625dda51321de2a4d8cffa8b6e1d10100000000ffffffff020000000000000000026a0000e1f505000000001976a914c1325e8fb60bd71d23532c39b4c9e743a2cc764988ac00000000'; +txhash='d1e1b6a8ff8c4d2ade2113a5dd250637e5f99667d36dcae9b70139516cb7052f'; +txindex=1; +scriptPubKey='76a9146efd5e2fda72ae2e37f8fb8cde83fbc8025fc96e88ac'; +amount=1; + +privkey='ET4VkeCoHmtKtoWJKco5PBSaVkqsVwqSbsqhneqN4Uo5yaTMxRmV'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "signrawtransaction", + "params": [ + "'$rawtx'", + [{ + "txid": "'$txhash'", + "vout": "'$txindex'", + "scriptPubKey": "'$scriptPubKey'", + "amount": "'$amount'" + }], + [ "'$privkey'" ] + ] + }' +``` + +```shell--cli +bcoin cli rpc signrawtransaction $rawtx \ + '[{ "txid": "'$txhash'", "vout": "'$txindex'", "scriptPubKey": "'$scriptPubKey'", "amount": "'$amount'" }]' \ + '[ "'$privkey'" ]' +``` + + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'regtest' +}); + +(async () => { + const res = await rpc.execute('signrawtransaction', [ rawtx, + [{ + txid: txhash, + vout: txindex, + scriptPubKey: scriptPubKey, + amount: amount + }], + [ privkey ] + ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +{ + "hex": "01000000012f05b76c513901b7e9ca6dd36796f9e5370625dda51321de2a4d8cffa8b6e1d1010000006b48304502210094252b4db106def63264668717c5ad66e2804c5e1b390c6240e82515fb0c12690220708430b14ceb0a15308e665de21cb3eb9e6cd9e4571e110fbfddf65ef702cd990121035ef2bf6d09a343c4c0be6fb5b489b217c00f477a9878b60ca3ceca4c2b052c3cffffffff020000000000000000026a0000e1f505000000001976a914c1325e8fb60bd71d23532c39b4c9e743a2cc764988ac00000000", + "complete": true +} +``` + +Signs raw transaction + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | rawtx | Required | raw tx +2 | inputs | Required | Coins you're going to spend +2.1 | txid | | Transaction Hash +2.2 | vout | | Transaction Outpoint Index +2.3 | scriptPubKey | | script with pubkey you are going to sign +2.4 | redeemScript | | redeemScript if tx is P2SH +3 | privkeylist | | List of private keys +4 | sighashtype | | Type of signature hash + + + +## gettxoutproof + +```javascript +let txhash; +``` + +```shell--vars +txhash='c75f8c12c6d0d1a16d7361b724898968c71de0335993ee589f82fda8ac482bfc'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "gettxoutproof", + "params": [ "'$txhash'" ] + }' +``` + +```shell--cli +bcoin cli rpc gettxoutproof $txhash +``` + + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('gettxoutproof', [ txhash ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +"000000208c13da491196839dd019c4ae0564f351502a4951e11b4302454b020000000000f1788fd057d657150b12e5638c7348fb55fdcda4ff4ddb1d1503de3576de6a4cbe22db58f0ec091b918981c50200000001f1788fd057d657150b12e5638c7348fb55fdcda4ff4ddb1d1503de3576de6a4c0100" +``` + +Checks if transactions are within block. +Returns raw block. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | txidlist | Required | array of transaction hashes +2 | blockhash | Based on TX | Block hash + + +## verifytxoutproof + +```javascript +let proof; +``` + +```shell--vars +proof='000000208c13da491196839dd019c4ae0564f351502a4951e11b4302454b020000000000f1788fd057d657150b12e5638c7348fb55fdcda4ff4ddb1d1503de3576de6a4cbe22db58f0ec091b918981c50200000001f1788fd057d657150b12e5638c7348fb55fdcda4ff4ddb1d1503de3576de6a4c0100'; +``` + +```shell--curl +curl $url/ \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ + "method": "verifytxoutproof", + "params": [ "'$proof'" ] + }' +``` + +```shell--cli +bcoin cli rpc verifytxoutproof $proof +``` + + +```javascript +const rpc = new bcoin.http.RPCClient({ + network: 'testnet' +}); + +(async () => { + const res = await rpc.execute('verifytxoutproof', [ proof ]); + + console.log(res); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON "result" like this: + +```json +[] +``` + +Checks the proof for transaction inclusion. + +### Params +N. | Name | Default | Description +--------- | --------- | --------- | ----------- +1 | proof | Required | Proof of transaction inclusion. diff --git a/api-docs-slate/source/includes/_transaction.md b/api-docs-slate/source/includes/_transaction.md new file mode 100644 index 0000000..18e5d1c --- /dev/null +++ b/api-docs-slate/source/includes/_transaction.md @@ -0,0 +1,336 @@ +# Transaction +Getting transaction information via APi. + + + +## Get tx by txhash + +```javascript +let txhash; +``` + +```shell--vars +txhash='86150a141ebe5903a5d31e701698a01d598b81f099ea7577dad73033eab02ef9'; +``` + +```shell--curl +curl $url/tx/$txhash +``` + +```shell--cli +bcoin cli tx $txhash +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + + const tx = await client.getTX(txhash); + + console.log(tx); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +{ + "hash": "86150a141ebe5903a5d31e701698a01d598b81f099ea7577dad73033eab02ef9", + "witnessHash": "86150a141ebe5903a5d31e701698a01d598b81f099ea7577dad73033eab02ef9", + "fee": 50000, + "rate": 220264, + "mtime": 1501093478, + "height": 502, + "block": "00000000e0290b7c66227c7499692aac5437860ee912424bf8eea3a3883a4e37", + "time": 1296746959, + "index": 8, + "version": 1, + "flag": 1, + "inputs": [ + { + "prevout": { + "hash": "0173a5d24d393127d5e6fc043ff1a00dafc6a2777143cb98a803a0b6e8cd02c7", + "index": 0 + }, + "script": "493046022100be75ae6dbf9eab7656562136511501c83918ca28c5f96565ca1960b3dbb581b6022100d15692af456e8721fddeeb0d6df5d8a147afd8a3b2a39bbceae9b1bdfd53ade20121038e297cf2cf71c16592c36ca48f5b2a5bbb73e776e772079f4c695b12eec1a509", + "witness": "00", + "sequence": 4294967295, + "coin": { + "version": 1, + "height": 502, + "value": 4824247882, + "script": "76a914bc7aad9746a0bc03ed9715f13c94e554df90b84688ac", + "address": "mxhYHwYZdYh1AkLsUbEmU9ZGdvLfoNRdD6", + "coinbase": false + } + } + ], + "outputs": [ + { + "value": 4823922491, + "script": "76a914682215dfa6912d88f55a1853414d516122fcc66988ac", + "address": "mq1ZQJW1qPeNPNL83mpAWfNFPW9qwGDR2K" + }, + { + "value": 275391, + "script": "76a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac", + "address": "n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr" + } + ], + "locktime": 0 +} +``` + +### HTTP Request +`GET /tx/:txhash` + +### URL Parameters +Parameter | Description +--------- | ----------- +:txhash | Hash of tx. + + +## Get tx by address +```javascript +let address; +``` + +```shell--vars +address='n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr'; +``` + +```shell--curl +curl $url/tx/address/$address +``` + +```shell--cli +bcoin cli tx $address +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + + const txs = await client.getTXByAddress(address); + + console.log(txs); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +[ + ... + { + "hash": "8351d991c5dfb49d534fcd28f56bb2d5b0d5f31f5c9e2e0711b5f86312a5abfe", + "witnessHash": "8351d991c5dfb49d534fcd28f56bb2d5b0d5f31f5c9e2e0711b5f86312a5abfe", + "fee": 50000, + "rate": 129198, + "mtime": 1501093478, + "height": 467, + "block": "00000000057c13f1fa6b30c6ec32284875781e31474a532e96739523d926a9e2", + "time": 1296743253, + "index": 20, + "version": 1, + "flag": 1, + "inputs": [ + { + "prevout": { + "hash": "d4d30e49228051bffe1317a013c06ae53f5325302a03cdcacb3312d0998f512a", + "index": 1 + }, + "script": "47304402201c29f13e8d817f2c2d1ea8b89d1d603677b86d0b4658f5d836bb16c56dc5dc3e02203e815b7ef739ba95c7bbbfdd63f38baa0806ad235f73c7df2492271e0b14ea43012103d50917ce22f377797a28c5e17e33000ea7d7d149d98b942d83f25ef2a223a8aa", + "witness": "00", + "sequence": 4294967295, + "coin": { + "version": 1, + "height": 464, + "value": 457110, + "script": "76a914583d5f973c850ec26f8efa39dabf8fbe0fcbb59c88ac", + "address": "moZXHEWiTwWyy1HSwvNANn9CKoCocPzDwm", + "coinbase": false + } + }, + { + "prevout": { + "hash": "3d708378adc61ad2b6d623bfbb89df92e3c88f6c85f6e132796d5abefae8c587", + "index": 1 + }, + "script": "0d17a6a8512d174b6b679c375091483045022100a3d133ccd4353c6dbcd9dc035c059b9b45f3c044644613e2311b8290bd02a3fb022026ae0af0adaea2fad2bc76d40d77fde3628031ee73c8e0e36343d5585e9d93f50121029f15918cd48f9e5cecfc1fccf1efc0c518110a6d6258cf14d0ee49a0fd88a535", + "witness": "00", + "sequence": 4294967295, + "coin": { + "version": 1, + "height": 466, + "value": 966270, + "script": "76a914edb1dfaf6e0b39449da811275386edf2eb54baba88ac", + "address": "n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr", + "coinbase": false + } + } + ], + "outputs": [ + { + "value": 1021229, + "script": "76a91419eb536dc042d76454bea8dbec5ddc384e783e5a88ac", + "address": "mht16aZhnsHivv3cDGuzgHGvoLFy8rNkg8" + }, + { + "value": 352151, + "script": "76a914342e5d1f2eb9c6e99fda90c85ca05aa36616644c88ac", + "address": "mkGrySSnxcqRbtPCisApj3zXCQVmUUWbf1" + } + ], + "locktime": 0 + } +] +``` + +Returns transaction objects array by address + +### HTTP Request +`GET /tx/address/:address` + +### URL Parameters +Parameter | Description +--------- | ----------- +:address | Bitcoin address. + +## Get tx by addresses +```javascript +let address0, address1; +``` + +```shell--vars +address0='n3BmXQPa1dKi3zEyCdCGNHTuE5GLdmw1Tr'; +address1='mwLHWwWPDwtCBZA7Ltg9QSzKK5icdCU5rb'; +``` + +```shell--curl + curl $url/tx/address \ + -H 'Content-Type: application/json' \ + -X POST \ + --data '{ "addresses":[ "'$address0'", "'$address1'" ]}' +``` + +```shell--cli +No CLI Option. +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet' +}); + +(async () => { + await client.open(); + + const txs = await client.getTXByAddress([address0, address1]); + + console.log(txs); + + await client.close(); +})().catch((err) => { + console.error(err.stack); +}); +``` + +> The above command returns JSON structured like this: + +```json +[ + ... + { + "hash": "4692772a73ea834c836915089acf97f2c790380a2b8fd32f82729da72545d8c5", + "witnessHash": "4692772a73ea834c836915089acf97f2c790380a2b8fd32f82729da72545d8c5", + "fee": 50000, + "rate": 134048, + "mtime": 1501093478, + "height": 500, + "block": "00000000a2424460c992803ed44cfe0c0333e91af04fde9a6a97b468bf1b5f70", + "time": 1296746771, + "index": 3, + "version": 1, + "flag": 1, + "inputs": [ + { + "prevout": { + "hash": "cff00582fa957178139b0db60228fc9b252adc01ec6b11c3e16f708802c12d3f", + "index": 0 + }, + "script": "48304502203ef5c34af08cd2865820757844ac079e081e7b41bf427ac896f41ab12a9f9857022100bd0914548145648ec538c088640228baaa983a7c78fbf49526c5c30358fe0f54012103420f2cb862c7a77d7b2376660573eb6976f01f59222892dd16326ee7ef37fc5b", + "witness": "00", + "sequence": 4294967295, + "coin": { + "version": 1, + "height": 499, + "value": 346342, + "script": "76a914f93f789537ba00a23e7e84dcf145dae36f50ea8088ac", + "address": "n4Eras4wT4kRjX34zP96nCiHqietgeKnTn", + "coinbase": false + } + }, + { + "prevout": { + "hash": "39661409f6bc4d9e08e413e01f867fe276e12e83dae89ee351df17757ca64b3f", + "index": 0 + }, + "script": "47304402201468bcfff3b1d8bdd0ba5fd94692c4dc7766411bdafe8d65b6e7a5be8f7efa8602207cdcbe3a107db271f24d7d8ac83a887ef4a1b72c910cc9ea5627b4cf37e87bcf0121025f9a9951e2d2a3037c1af09d9789b84a5776c504cd5b59bccd469124eb59835f", + "witness": "00", + "sequence": 4294967295, + "coin": { + "version": 1, + "height": 499, + "value": 1024528, + "script": "76a914c4a22b009b02fe8488c5543f0873e062712b7f6888ac", + "address": "mySf1HGynwyAuNyYrapRnwM83k3svzWTgD", + "coinbase": false + } + } + ], + "outputs": [ + { + "value": 1095497, + "script": "76a914ad7d7b9ac5260ad13fa55e06143283f5b36495f788ac", + "address": "mwLHWwWPDwtCBZA7Ltg9QSzKK5icdCU5rb" + }, + { + "value": 225373, + "script": "76a914bc0f9f5fc9dc55323d52a9e354b5fb67cecd389788ac", + "address": "mxfL3bJohxaoBkKNtUF8xSU1DVKzbiChnZ" + } + ], + "locktime": 0 + } +] +``` + +Returns transaction objects array by addresses + +### HTTP Request +`POST /tx/address` + +### POST Parameters (JSON) +Parameter | Description +--------- | ----------- +addresses | array of bitcoin addresses diff --git a/api-docs-slate/source/includes/_wallet.md b/api-docs-slate/source/includes/_wallet.md new file mode 100644 index 0000000..f5f7bbb --- /dev/null +++ b/api-docs-slate/source/includes/_wallet.md @@ -0,0 +1,1888 @@ +# Wallet +## The WalletDB and Object +```javascript +let id, url; +``` + +```shell--vars +id="primary" +url="http://localhost:18332" +``` + +```shell--curl +curl $url/wallet/$id/ +``` + +```shell--cli +bcoin cli wallet get --id=$id +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const wallet = await httpWallet.getInfo(); + console.log(wallet); +})(); +``` + + +> The wallet object will look something like this: + +```json +{ + "network": "testnet", + "wid": 1, + "id": "primary", + "initialized": true, + "watchOnly": false, + "accountDepth": 1, + "token": "977fbb8d212a1e78c7ce9dfda4ff3d7cc8bcd20c4ccf85d2c9c84bbef6c88b3c", + "tokenDepth": 0, + "state": { + "tx": 0, + "coin": 0, + "unconfirmed": 0, + "confirmed": 0 + }, + "master": { + "encrypted": false + }, + "account": { + "name": "default", + "initialized": true, + "witness": false, + "watchOnly": false, + "type": "pubkeyhash", + "m": 1, + "n": 1, + "accountIndex": 0, + "receiveDepth": 1, + "changeDepth": 1, + "nestedDepth": 0, + "lookahead": 10, + "receiveAddress": "mwfDKs919Br8tNFamk6RhRpfaa6cYQ5fMN", + "nestedAddress": null, + "changeAddress": "msG6V75J6XNt5mCqBhjgC4MjDH8ivEEMs9", + "accountKey": "tpubDDRH1rj7ut9ZjcGakR9VGgXU8zYSZypLtMr7Aq6CZaBVBrCaMEHPzye6ZZbUpS8YmroLfVp2pPmCdaKtRdCuTCK2HXzwqWX3bMRj3viPMZo", + "keys": [] + } +} +``` + +Bcoin maintains a wallet database which contains every wallet. Wallets are not usable without also using a wallet database. For testing, the wallet database can be in-memory, but it must be there. Wallets are uniquely identified by an id and the walletdb is created with a default id of `primary`. (See [Create a Wallet](#create-a-wallet) below for more details.) + +Wallets in bcoin use bip44. They also originally supported bip45 for multisig, but support was removed to reduce code complexity, and also because bip45 doesn't seem to add any benefit in practice. + +The wallet database can contain many different wallets, with many different accounts, with many different addresses for each account. Bcoin should theoretically be able to scale to hundreds of thousands of wallets/accounts/addresses. + +Each account can be of a different type. You could have a pubkeyhash account, as well as a multisig account, a witness pubkeyhash account, etc. + +Note that accounts should not be accessed directly from the public API. They do not have locks which can lead to race conditions during writes. + +## Wallet Options +> Wallet options object will look something like this + +```json +{ + "id": "walletId", + "witness": true, + "watchOnly": false, + "accountKey": key, + "accountIndex": 1, + "type": "pubkeyhash" + "m": 1, + "n": 1, + "keys": [], + "mnemonic": 'differ trigger sight sun undo fine sheriff mountain prison remove fantasy arm' +} +``` +Options are used for wallet creation. None are required. + +### Options Object +Name | Type | Default | Description +---------- | ----------- | -------------- | ------------- +id | String | | Wallet ID (used for storage) +master | HDPrivateKey/HDPublicKey | | | Master HD key. If not present, it will be generated +witness | Boolean | `false` | Whether to use witness programs +accountIndex | Number | `0` | The BIP44 [account index](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki#Account) +receiveDepth | Number | | The index of the _next_ receiveing address +changeDepth | Number | | The index of the _next_ change address +type | String | `'pubkeyhash'` |Type of wallet (pubkeyhash, multisig) +compressed | Boolean | `true` | Whether to use compressed public keys +m | Number | `1` | m value for multisig (`m-of-n`) +n | Number | `1` | n value for multisig (`m-of-n`) +mnemonic | String | | A mnemonic phrase to use to instantiate an hd private key. One will be generated if none provided + + +## Wallet Auth +> The following samples return a wallet object + +```javascript +let token, id; +``` + +```shell--vars +token='977fbb8d212a1e78c7ce9dfda4ff3d7cc8bcd20c4ccf85d2c9c84bbef6c88b3c' +id='foo' +``` + +```shell--curl +curl $url/wallet/$id \ + -H 'Content-Type: application/json' \ + -d '{ "token": "$token" ... }' +``` + +```shell--cli +bcoin cli wallet get --network=testnet --token=$token +``` + +```javascript +`use strict` + +const httpWallet = new bcoin.http.Wallet({ + id: id, + token: token, + network: 'testnet', +}); + +(async () => { + const wallet = await httpWallet.getInfo(); + console.log(wallet); +})(); +``` + +Individual wallets have their own api keys, referred to internally as "tokens" (a 32 byte hash - calculated as `HASH256(m/44'->ec-private-key|tokenDepth)`). + +A wallet is always created with a corresponding token. When using api endpoints +for a specific wallet, the token must be sent back in the query string or json +body. + +e.g. To get information from a wallet that requires a token + +`GET /wallet/primary/tx/:hash?token=977fbb8d212a1e78c7ce9dfda4ff3d7cc8bcd20c4ccf85d2c9c84bbef6c88b3c` + +## Reset Authentication Token +```javascript +let id, passphrase; +``` + +```shell--vars +id='foo' +passphrase="bar" +``` + +```shell--cli +bcoin cli wallet retoken --id=$id --passphrase=$passphrase +``` + +```shell--curl +curl $url/wallet/$id/retoken \ + -X POST + --data '{"passphrase":'$passphrase'}" +``` + +```javascript +const wallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const token = await wallet.retoken(passphrase); + console.log(token); +})(); +``` + +> Sample response: + +```json +{ + "token": "2d04e217877f15ba920d02c24c6c18f4d39df92f3ae851bec37f0ade063244b2" +} +``` + +Derive a new wallet token, required for access of this particular wallet. + + + + +### HTTP Request + +`POST /wallet/:id/retoken` + +## Get Wallet Info +```javascript +let id; +``` + +```shell--vars +id='foo' +``` + +```shell--curl +curl $url/wallet/$id/ + +``` + +```shell--cli +# ID defaults to `primary` if none is passed +bcoin cli wallet get --id=$id +``` + +```javascript +`use strict` + +const httpWallet = new bcoin.http.Wallet({ id: id }); +const id = 'foo'; + +(async () => { + const wallet = await httpWallet.getInfo(); + console.log(wallet); +})(); +``` + +> Sample output + +```json +{ + "network": "testnet", + "wid": 1, + "id": "foo", + "initialized": true, + "watchOnly": false, + "accountDepth": 1, + "token": "2d04e217877f15ba920d02c24c6c18f4d39df92f3ae851bec37f0ade063244b2", + "tokenDepth": 0, + "state": { + "tx": 177, + "coin": 177, + "unconfirmed": "8150.0", + "confirmed": "8150.0" + }, + "master": { + "encrypted": false + }, + "account": { + "name": "default", + "initialized": true, + "witness": false, + "watchOnly": false, + "type": "pubkeyhash", + "m": 1, + "n": 1, + "accountIndex": 0, + "receiveDepth": 8, + "changeDepth": 1, + "nestedDepth": 0, + "lookahead": 10, + "receiveAddress": "mu5Puppq4Es3mibRskMwoGjoZujHCFRwGS", + "nestedAddress": null, + "changeAddress": "n3nFYgQR2mrLwC3X66xHNsx4UqhS3rkSnY", + "accountKey": "tpubDC5u44zLNUVo2gPVdqCbtX644PKccH5VZB3nqUgeCiwKoi6BQZGtr5d6hhougcD6PqjszsbR3xHrQ5k8yTbUt64aSthWuNdGi7zSwfGVuxc", + "keys": [] + } +} +``` + +Get wallet info by ID. If no id is passed in the CLI it assumes an id of `primary`. + +### HTTP Request +`GET /wallet/:id` + +Parameters | Description +---------- | ----------- +id
_string_ | named id of the wallet whose info you would like to retrieve + +## Get Master HD Key +```javascript +let id, network; +``` +```shell--vars +id='foo' +network='testnet' +``` + +```shell--curl +curl $url/wallet/$id/master +``` + +```shell--cli +bcoin cli wallet master --id=$id --network=$network +``` + +```javascript +const wallet = new bcoin.http.Wallet({ id: id, network: network}); + +(async () => { + const master = await wallet.getMaster(); + console.log(master); +})(); +``` + +> Sample response: + +```json +{ + "encrypted": false, + "key": { + "xprivkey": "tprv8ZgxMBicQKsPe7977psQCjBBjWtLDoJVPiiKog42RCoShJLJATYeSkNTzdwfgpkcqwrPYAmRCeudd6kkVWrs2kH5fnTaxrHhi1TfvgxJsZD", + "mnemonic": { + "bits": 128, + "language": "english", + "entropy": "a560ac7eb5c2ed412a4ba0790f73449d", + "phrase": "pistol air cabbage high conduct party powder inject jungle knee spell derive", + "passphrase": "" + } + } +} +``` + +Get wallet master HD key. This is normally censored in the wallet info route. The provided api key must have admin access. + +### HTTP Request + +`GET /wallet/:id/master` + +Parameters | Description +---------- | ----------- +id
_string_ | named id of the wallet whose info you would like to retrieve + +## Create A Wallet + +```javascript +let id, passphrase, witness, accountKey; +``` + +```shell--vars +id = 'foo' +passphrase = 'bar' +witness = false +accountKey='tpubDDh2XgSds1vBbeVgye88gsGQeCityoywRndtyrXcmvWqCgsFUyUKwzeDv8HiJhu9fC8jRAFMqxr4jj8eRTNTycmMao5wmsAScVf4jSMdPYZ' +``` + +```shell--curl +curl $url/wallet/$id \ + -X PUT \ + --data '{"witness":'$witness', "passphrase":"'$passphrase'", watchOnly: "true", "accountKey":"'$accountKey'"}' +``` + +```shell--cli +bcoin cli wallet create $id --witness=$witness --passphrase=$passphrase --watch=$accountKey +``` + +```javascript +const client = new bcoin.http.Client(); +const options = { + id: id, + passphrase: passphrase, + witness: witness, + watchOnly: true, + accountKey: accountKey +}; + +(async() => { + const newWallet = await client.createWallet(options) +})(); +``` + +> Sample response: + +```json +{ + "network": "testnet", + "wid": 2, + "id": "foo", + "initialized": true, + "watchOnly": false, + "accountDepth": 1, + "token": "d9de1ddc83bf058d14520a203df6ade0dc92a684aebfac57b667705b4cac3916", + "tokenDepth": 0, + "state": { + "tx": 0, + "coin": 0, + "unconfirmed": "0.0", + "confirmed": "0.0" + }, + "master": { + "encrypted": false + }, + "account": { + "name": "default", + "initialized": true, + "witness": false, + "watchOnly": false, + "type": "pubkeyhash", + "m": 1, + "n": 1, + "accountIndex": 0, + "receiveDepth": 1, + "changeDepth": 1, + "nestedDepth": 0, + "lookahead": 10, + "receiveAddress": "muYkrSDbD8UhyWBMXxXf99EKWn22YqmwyF", + "nestedAddress": null, + "changeAddress": "mwveV7A6svE5EGGSduZmMKTwcbE775NVFt", + "accountKey": "tpubDDh2XgSds1vBbeVgye88gsGQeCityoywRndtyrXcmvWqCgsFUyUKwzeDv8HiJhu9fC8jRAFMqxr4jj8eRTNTycmMao5wmsAScVf4jSMdPYZ", + "keys": [] + } +} +``` + +Create a new wallet with a specified ID. + +### HTTP Request + +`PUT /wallet/:id` + +Parameters | Description +---------- | ----------- +id
_string_ | id of wallet you would like to create + + + + +## Change Passphrase +```javascript +let id, oldPass, newPass; +``` + +```shell--vars +id='foo' +oldPass = 'oldpass123' +newPass='newpass123' +``` + +```shell--cli +> No cli command available +``` + +```shell-curl +curl $url/wallet/$id/passphrase \ + -X POST + --data '{"old":'$oldPass', "new":'$newPass'}' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.setPassphrase(oldPass, newPass); + console.log(response); +}); +``` + +> Sample Response: + +```json +{"success": true} +``` + +Change wallet passphrase. Encrypt if unencrypted. + +### HTTP Request + +`POST /wallet/:id/passphrase` + +### Body Parameters +Paramters | Description +--------- | --------------------- +old
_string_ | Old passphrase. Pass in empty string if none +new
_string | New passphrase + + + +## Send a transaction + +```javascript +let id, passphrase, rate, value, address; +``` + +```shell--vars +id="foo" +passphrase="bar" +rate=100 +value=3000 +address="moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA" +``` + +```shell--cli +bcoin cli wallet send --id=$id --value=$value --address=$address ---passphrase=$passphrase +``` + +```shell--curl +curl $url/wallet/$id/send \ + -X POST \ + --data '{ + "passphrase":"'$passphrase'", + "rate":'$rate', + "outputs":[ + {"address":"'$address'", "value":'$value'} + ] + }' +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); +const options = { + rate: rate, + outputs: [{ value: value, address; address }] +}; + +(async () => { + const tx = await httpWallet.send(options); + console.log(tx); +})(); +``` + +> Sample response: + +```json +{ + "wid": 13, + "id": "foo", + "hash": "c2da22cafcd076ea3db74bb2e3cf50f030e5240aa5daf4f778fb4954a866b41c", + "height": -1, + "block": null, + "time": 0, + "mtime": 1503364758, + "date": "2017-08-22T01:19:18Z", + "size": 225, + "virtualSize": 225, + "fee": 22, + "rate": 100, + "confirmations": 0, + "inputs": [ + { + "value": 59991393, + "address": "mgChJ3wXDqRns7Y6UhjXCyxeuZZJoQNj7c", + "path": { + "name": "default", + "account": 0, + "change": true, + "derivation": "m/0'/1/5" + } + } + ], + "outputs": [ + { + "value": 10000000, + "script": "76a9143f4f69730dcb175c830b94226ae13f89bef969c488ac", + "address": "mmHhzmwiUzorZLYhFH9fhrfFTAHGhx1biN" + }, + { + "value": 30000000, + "script": "76a9143f4f69730dcb175c830b94226ae13f89bef969c488ac", + "address": "mmHhzmwiUzorZLYhFH9fhrfFTAHGhx1biN" + } + + ], + "tx": "01000000015a9b8fa3fb300a29e9cde6464f49882228862b8e333792fea35ad15536383417010000006a47304402202df28a6fe24dc26b016acee539e137b9502009f57ae6988d468d203e770339f202203b6ab4cc020493061db2d405b2799af2b872d3395f5798616fc51e59f304d5cd0121028986f0724eb55b66bba72985212b95a2c5487631e411dc9cc5348a4531928129ffffffff02e8030000000000001976a9144462dc0989942e38474616dc104e46486c5744ee88ac63619303000000001976a9149affd314659d5ce9fa815fde4e82c879d1ea41d188ac00000000" +} + +``` + +Create, sign, and send a transaction. + +### HTTP Request + +`POST /wallet/:id/send` + +### Post Paramaters +Parameter | Description +--------- | ------------------ +rate
_int_ | the rate for transaction fees. Denominated in satoshis per kb +outputs
_array_ | An array of outputs to send for the transaction +smart
_bool_ | whether or not to estimate a smart fee based on current mempool +account
_string_ | account to use for transaction +passphrase
_string_ | passphrase to unlock the account + + +### Output object +Property | Description +--------- | ----------- +value
_int_ | Value to send in satoshis +address
_string_ | destination address for transaction + +## Create a Transaction +```javascript +let id, rate, value, address, passphrase; +``` + +```shell--vars +id="foo" +passphrase="bar" +rate=100 +value=.3 +address="moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA" +``` + +```shell--cli +bcoin cli wallet mktx --id=$id --rate=$rate --value=$value --address=$address --passphrase=$passphrase +``` + +```shell--curl +curl $url/wallet/$id/create \ + -X POST \ + --data '{ + "rate":"'$rate'", + "passphrase": "'$passphrase'" + "outputs":[ + {"address":"'$address'", "value":'$value'} + ] + }' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); +const outputs = [{ value: value, address: address }] +const options = { + passphrase: passphrase, + outputs: outputs, + rate: rate, +}; + +(async () => { + const tx = await httpWallet.createTX(options); + console.log(tx); +})(); +``` + +> Sample response: + +```json +{ + "hash": "0799a1d3ebfd108d2578a60e1b685350d42e1ef4d5cd326f99b8bf794c81ed17", + "witnessHash": "0799a1d3ebfd108d2578a60e1b685350d42e1ef4d5cd326f99b8bf794c81ed17", + "fee": "0.0000454", + "rate": "0.00020088", + "mtime": 1486686322, + "version": 1, + "flag": 1, + "inputs": [ + { + "prevout": { + "hash": "6dd8dfa9b425a4126061a1032bc6ff6e208b75ee09d0aac089d105dcf972465a", + "index": 0 + }, + "script": "483045022100e7f1d57e47cd8a28b7c27e015b291f3fd43a6eb0c051a4b65d8697b5133c29f5022020cada0f62a32aecd473f606780b2aef3fd9cbd44cfd5e9e3d9fe6eee32912df012102272dae7ff2302597cb785fd95529da6c07e32946e65ead419291258aa7b17871", + "witness": "00", + "sequence": 4294967295, + "coin": { + "version": 1, + "height": 2, + "value": "50.0", + "script": "76a9149621fb4fc6e2e48538f56928f79bef968bf17ac888ac", + "address": "muCnMvAoUFZXzuao4oy3vQJFcUntax53wE", + "coinbase": true + } + } + ], + "outputs": [ + { + "value": 10000000, + "script": "76a9143f4f69730dcb175c830b94226ae13f89bef969c488ac", + "address": "mmHhzmwiUzorZLYhFH9fhrfFTAHGhx1biN" + }, + { + "value": 30000000, + "script": "76a9143f4f69730dcb175c830b94226ae13f89bef969c488ac", + "address": "moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA" + } + ], + "locktime": 0 +} +``` + +Create and template a transaction (useful for multisig). +Do not broadcast or add to wallet. + +### HTTP Request + +`POST /wallet/:id/create` + +### Post Paramters +Paramter | Description +--------- | ---------------- +rate
_int_ | the rate for transaction fees. Denominated in satoshis per kb +outputs
_array_ | An array of outputs to send for the transaction +smart
_bool_ | whether or not to estimate a smart fee based on current mempool +passphrase
_string_ | passphrase to unlock the account + + +### Output object +Property | Description +--------- | ----------- +value
_int_ | Value to send in bitcoin (as of beta-1.14) +address
_string_ | destination address for transaction + + + +## Sign Transaction +```javascript +let id, tx, passphrase; +``` + +```shell--vars +id="foo" +passphrase="bar" +tx="01000000010d72c6b2582c2b2e625d29dd5ad89209de7e2600ab12a1a8e05813c28b703d2c000000006b483045022100af93a8761ad22af858c5bc4e68b5991eac017dcddd933cf125553ec0b83eb8f30220373a4d8ee331ac4c3975718e2a789f873af0520ddbd2db18957cdf488ccd4ee301210215a9110e2a9b293c332c28d69f88081aa2a949fde67e35a13fbe19410994ffd9ffffffff0280969800000000001976a9143f4f69730dcb175c830b94226ae13f89bef969c488ac80c3c901000000001976a9143f4f69730dcb175c830b94226ae13f89bef969c488ac00000000" +``` + +```shell--cli +bcoin cli wallet sign --id=$id --passphrase=$passphrase --tx=$tx +``` + +```shell--curl +curl $url/wallet/$id/sign \ + -X POST \ + --data '{"tx": "'$tx'", "passphrase":"'$passphrase'"}' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); +const options = { passphrase: passphrase }; +(async () => { + const signedTx = await httpWallet.sign(tx, options); + console.log(signedTx); +})(); +``` + +> Sample Output + +```json +{ + "hash": "2a22606ee555d2c26ec979f0c45cd2dc18c7177056189cb345989749fd587868", + "witnessHash": "2a22606ee555d2c26ec979f0c45cd2dc18c7177056189cb345989749fd587868", + "fee": 10000000, + "rate": 44247787, + "mtime": 1503683721, + "version": 1, + "inputs": [ + { + "prevout": { + "hash": "2c3d708bc21358e0a8a112ab00267ede0992d85add295d622e2b2c58b2c6720d", + "index": 0 + }, + "script": "483045022100af93a8761ad22af858c5bc4e68b5991eac017dcddd933cf125553ec0b83eb8f30220373a4d8ee331ac4c3975718e2a789f873af0520ddbd2db18957cdf488ccd4ee301210215a9110e2a9b293c332c28d69f88081aa2a949fde67e35a13fbe19410994ffd9", + "witness": "00", + "sequence": 4294967295, + "coin": { + "version": 1, + "height": 1179720, + "value": 50000000, + "script": "76a9145730f139d833e3af30ccfb7c4e253ff4bab5de9888ac", + "address": "moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA", + "coinbase": false + } + } + ], + "outputs": [ + { + "value": 10000000, + "script": "76a9143f4f69730dcb175c830b94226ae13f89bef969c488ac", + "address": "mmHhzmwiUzorZLYhFH9fhrfFTAHGhx1biN" + }, + { + "value": 30000000, + "script": "76a9143f4f69730dcb175c830b94226ae13f89bef969c488ac", + "address": "mmHhzmwiUzorZLYhFH9fhrfFTAHGhx1biN" + } + ], + "locktime": 0, + "hex": "01000000010d72c6b2582c2b2e625d29dd5ad89209de7e2600ab12a1a8e05813c28b703d2c000000006b483045022100af93a8761ad22af858c5bc4e68b5991eac017dcddd933cf125553ec0b83eb8f30220373a4d8ee331ac4c3975718e2a789f873af0520ddbd2db18957cdf488ccd4ee301210215a9110e2a9b293c332c28d69f88081aa2a949fde67e35a13fbe19410994ffd9ffffffff0280969800000000001976a9143f4f69730dcb175c830b94226ae13f89bef969c488ac80c3c901000000001976a9143f4f69730dcb175c830b94226ae13f89bef969c488ac00000000" +} +``` + +Sign a templated transaction (useful for multisig). + +### HTTP Request + +`POST /wallet/:id/sign` + +### Post Paramters +Parameter | Description +----------| ----------------- +tx
_string_ | the hex of the transaction you would like to sign +passphrase
_string_ | passphrase to unlock the wallet + +## Zap Transactions + +```javascript +let id, age, account; +``` + +```shell--vars +id="foo" +account="baz" +age=259200 # 72 hours +``` + +```shell--cli +bcoin cli wallet zap --id=$id account=$account age=$age +``` + +```shell--curl +curl $url/wallet/$id/zap \ + -X POST \ + --data '{ + "account": "'$account'", + "age": "'$age'" + }' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const response = httpWallet.zap(account, age); + console.log(response); +})(); +``` + +> Sample Response + + +```json +{ + "success": true +} +``` + +Remove all pending transactions older than a specified age. + +### HTTP Request + +`POST /wallet/:id/zap?age=3600` + +### Post Parameters +Paramaters | Description +----------- | ------------- +account
_string_ or _number_ | account to zap from +age
_number_ | age threshold to zap up to (unix time) + +## Unlock Wallet + +```javascript +let id, pass, timeout +``` + +```shell--vars +id='foo' +pass='bar', +timeout=60 +``` + +```shell--cli +bcoin cli wallet unlock --id=$id $pass $timeout +``` + +```shell--curl +curl $url/wallet/$id/unlock \ + -X POST + --data '{"passphrase":'$pass', "timeout": '$timeout'}' +``` + +```javascript +const client = new bcoin.http.Client(); +(async () => { + const response = await client.unlock(id, pass, timeout); + console.log(response); +})(); +``` +> Sample Response + +```json +{"success": true} +``` + +Derive the AES key from passphrase and hold it in memory for a specified number of seconds. Note: During this time, account creation and signing of transactions will not require a passphrase. + +### HTTP Request + +`POST /wallet/:id/unlock` + +### Body Parameters +Parameter | Description +--------- | ----------------------- +passphrase
_string_ | Password used to encrypt the wallet being unlocked +timeout
_number_ | time to re-lock the wallet in seconds. (default=60) + +## Lock Wallet + +```javascript +let id; +``` + +```shell--vars +id='foo' +``` + +```shell--cli +bcoin cli wallet lock --id=$id +``` + +```shell--curl +curl $url/wallet/$id/lock \ + -X POST +``` + +```javascript +const client = new bcoin.http.Client(); +(async () => { + const response = await client.lock(id); + console.log(response); +})(); +``` +> Sample Response + +```json +{"success": true} +``` + +If unlock was called, zero the derived AES key and revert to normal behavior. + +### HTTP Request + +`POST /wallet/:id/lock` + +## Import Public/Private Key + +```javascript +let id, account, key; +``` + +```shell--vars +id='foo' +account='test-account' +key='0215a9110e2a9b293c332c28d69f88081aa2a949fde67e35a13fbe19410994ffd9' +``` + +```shell--cli +bcoin cli wallet import --id=$id $key +``` + +```shell--curl +curl $url/wallet/$id/import \ + -X POST \ + --data '{"account":"'$account'", "privateKey":"'$key'"}' +``` + + +```javascript +const wallet = new bcoin.http.Wallet({ id: id }); +(async () => { + const response = await wallet.importPrivate(account, key); + console.log(response); +})(); +``` +> Sample Response + +```json +{ + "success": true +} +``` + +Import a standard WIF key. + +An import can be either a private key or a public key for watch-only. (Watch Only wallets will throw an error if trying to import a private key) + +A rescan will be required to see any transaction history associated with the +key. + + + +### HTTP Request + +`POST /wallet/:id/import` + +### Body Paramters +Paramter | Description +-------- | ------------------------- +id
_string_ | id of target wallet to import key into +privateKey
_string_ | Base58Check encoded private key +publicKey
_string_ | Hex encoded public key + +> Will return following error if incorrectly formatted: +`Bad key for import` + +## Import Address +```javascript +let id, account, address; +``` + +```shell--vars +id='foo' +account='bar' +address='moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA' +``` + +```shell--cli +bcoin cli wallet watch --id=$id --account=$account $address +``` + +```shell--curl +curl $url/wallet/$id/import \ + -X POST \ + --data '{"account":"'$account'", "address":"'$address'"}' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.importAddress(account, address) +})(); +``` + +> Sample Response + +```json +{ + "success": true +} +``` + +Import a Base58Check encoded address. Addresses (like public keys) can only be imported into watch-only wallets + +The HTTP endpoint is the same as for key imports. + +### HTTP Request + +`POST /wallet/:id/import` + +### Body Paramters +Paramter | Description +-------- | ------------------------- +id
_string_ | id of target wallet to import key into +address
_string_ | Base58Check encoded address + +## Get Blocks with Wallet Txs +```javascript +let id; +``` + +```shell--vars +id="foo" +``` + +```shell--curl +curl $url/wallet/$id/block +``` + +```shell--cli +bcoin cli wallet blocks --id=$id +``` + +```javascript +const httpWallet = new bcoin.http.wallet({ id: id }); + +(async () => { + const blocks = await httpWallet.getBlocks(); + console.log(blocks); +}()) +``` +> Sample Response + +```json +[ 1179720, 1179721, 1180146, 1180147, 1180148, 1180149 ] +``` + +List all block heights which contain any wallet transactions. Returns an array of block heights + +### HTTP Request + +`GET /wallet/:id/block` + +Parameters | Description +-----------| ------------ +id
_string_ | id of wallet to query blocks with its transactions in it + +## Get Wallet Block by Height +```javascript +let id, height; +``` + +```shell--vars +id="foo" +height=1179720 +``` + +```shell--cli +bcoin cli wallet --id=$id block $height +``` + +```shell--curl +curl $url/wallet/block/$height +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const blockInfo = await httpWallet.getBlock(height); + console.log(blockInfo); +}) +``` + +> Sample response: + +```json +{ + "hash": "0000000000013cc12ea4b3ff403a3c05d96da695638e468cf26409eca87beb6a", + "height": 1179720, + "time": 1503359756, + "hashes": [ + "2c3d708bc21358e0a8a112ab00267ede0992d85add295d622e2b2c58b2c6720d" + ] +} +``` + +Get block info by height. + +### HTTP Request + +`GET /wallet/:id/block/:height` + +Paramaters | Description +-----------| ------------- +id
_string_ | id of wallet which has tx in the block being queried +height
_int_ | height of block being queried + + +## Add xpubkey (Multisig) +```javascript +let id, key, account; +``` + +```shell--vars +id="multi-foo" +key="tpubDCUQshhR98hjDDPtefuQdg4Dmpk5mes3TRyUp1Qa4BjxCVytfqmqNWmJ3tUZfqu4qLfEypQhNcpMF3yhZJ8h8hcahnxCzrqWmV5qVHHTqGM" +``` + +```shell--cli +bcoin cli wallet --id=$id shared add $key +``` + +```shell--curl +curl $url/wallet/$id/shared-key \ + -X PUT + --data '{"accountKey": $key}' +``` + +```javascript +const httpWallet = new bcoin.http.wallet({ id: id }); +account = 'default'; + +(async () => { + const response = await httpWallet.addSharedKey(account, key); + console.log(response); +})(); +``` + +> Sample Response + +```json +{ + "success": true +} +``` + +Add a shared xpubkey to wallet. Must be a multisig wallet. + + + +### HTTP Request + +`PUT /wallet/:id/shared-key` + +### Body Parameters +Paramter | Description +---------| -------------- +accountKey
_string_ | xpubkey to add to the multisig wallet +account
_string_ | multisig account to add the xpubkey to (default='default') + +## Remove xpubkey (Multisig) + +```javascript +let id, key; +``` + +```shell--vars +id="multi-foo" +key="tpubDCUQshhR98hjDDPtefuQdg4Dmpk5mes3TRyUp1Qa4BjxCVytfqmqNWmJ3tUZfqu4qLfEypQhNcpMF3yhZJ8h8hcahnxCzrqWmV5qVHHTqGM" +``` + +```shell--cli +bcoin cli wallet --id=$id shared remove $key +``` + +```shell--curl +curl $url/wallet/$id/shared-key \ + -X DELETE + --data '{"accountKey": "'$key'"}' +``` + +```javascript +const httpWallet = new bcoin.http.wallet({ id: id }); +const account = 'default'; + +(async () => { + const response = await httpWallet.removeSharedKey(account, key); + console.log(response); +})(); +``` + +> Sample Response + +```json +{ + "success": true +} +``` + +Remove shared xpubkey from wallet if present. + +### HTTP Request + +`DEL /wallet/:id/shared-key` + +### Body Parameters +Paramter | Description +---------| -------------- +accountKey
_string_ | xpubkey to add to the multisig wallet +account
_string_ | multisig account to remove the key from (default='default') + + +## Get Public Key By Address +```javascript +let id, address; +``` + +```shell--vars +id="foo" +address="n1EDbjFaKFwz2XwWPueDUac4XZsQg8d1p2" +``` + +```shell--cli +bcoin cli wallet --id=$id key $address +``` + +```shell--curl +curl $url/wallet/$id/key/$address +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.getKey(address); + console.log(response); +})(); +``` + +> Sample Response + +```json +{ + "network": "testnet", + "wid": 8, + "id": "foo", + "name": "default", + "account": 0, + "branch": 0, + "index": 7, + "witness": false, + "nested": false, + "publicKey": "032b110a0f83d45c1010cf03adea64b440d83a1a3726f7c2d5e94db1d6509b3ac6", + "script": null, + "program": null, + "type": "pubkeyhash", + "address": "n1EDbjFaKFwz2XwWPueDUac4XZsQg8d1p2" +} +``` + +Get wallet key by address. Returns wallet information with address and public key + +### HTTP Request + +`GET /wallet/:id/key/:address` + +Parameters | Description +-----------| -------------- +id
_string_ | id of wallet that holds the address being queried +address
_string> | Base58 encoded address to get corresponding public key for + +## Get Private Key By Address +```javascript +let id, address; +``` + +```shell--vars +id="foo" +address="n1EDbjFaKFwz2XwWPueDUac4XZsQg8d1p2" +``` + +```shell--cli +bcoin cli wallet --id=$id dump $address +``` + +```shell--curl +curl $url/wallet/$id/wif/$address +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.getWIF(address); + console.log(response); +})(); +``` + +> Sample Response + +```json +{ + "privateKey": "cTMUJ7WeFsoQ6dLGR9xdLZeNQafcU88bbibR9TV3W2HheRntYa53" +} + +``` + +Get wallet private key (WIF format) by address. Returns just the private key + +### HTTP Request + +`GET /wallet/:id/wif/:address` + +Parameters | Description +-----------| -------------- +id
_string_ | id of wallet that holds the address being queried +address
_string> | Base58 encoded address to get corresponding public key for + + +## Generate Receiving Address +```javascript +let id, account; +``` + +```shell--vars +id="foo" +account="default" +``` + +```shell--cli +bcoin cli wallet --id=$id address +``` + +```shell--curl +curl $url/wallet/$id/address -X POST --data '{"account":"'$account'"}' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); +(async () => { + const receiveAddress = await httpWallet.createAddress(account); + console.log(receiveAddress); +})(); +``` + +> Sample response: + +```json +{ + "network": "testnet", + "wid": 1, + "id": "foo", + "name": "default", + "account": 0, + "branch": 0, + "index": 9, + "witness": false, + "nested": false, + "publicKey": "02801d9457837ed50e9538ee1806b6598e12a3c259fdc9258bbd32934f22cb1f80", + "script": null, + "program": null, + "type": "pubkeyhash", + "address": "mwX8J1CDGUqeQcJPnjNBG4s97vhQsJG7Eq" +} +``` + +Derive new receiving address for account. + + + +### HTTP Request + +`POST /wallet/:id/address` + +### Post Paramters +Parameter | Description +--------- | ------------- +account
_string_ | BIP44 account to generate address from + +## Generate Change Address +```javascript +let id, account; +``` + +```shell--vars +id="foo" +account="default" +``` + +```shell--cli +bcoin cli wallet --id=$id change +``` + +```shell--curl +curl $url/wallet/$id/change -X POST --data '{"account":"'$account'"}' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); +(async () => { + const receiveAddress = await httpWallet.createChange(account); + console.log(receiveAddress); +})(); +``` + +> Sample response: + +```json +{ + "network": "testnet", + "wid": 8, + "id": "foo", + "name": "default", + "account": 0, + "branch": 1, + "index": 7, + "witness": false, + "nested": false, + "publicKey": "022f5afafcc8c35dbbbe52842d58dc18d739f2dea85021ea1e9183031032f9fa1c", + "script": null, + "program": null, + "type": "pubkeyhash", + "address": "mgdArtHtCsxvcjzxRTMfk5ZyBcnsTgNKTT" +} +``` +Derive new change address for account. + + + +### HTTP Request + +`POST /wallet/:id/change` + +### Post Paramters +Parameter | Description +--------- | ------------- +account
_string_ | BIP44 account to generate address from + +## Derive Nested Address + +```javascript +let id, account; +``` + +```shell--vars +id="foo" +account="baz" +``` + +```shell--cli +bcoin cli wallet --id=$id nested --account=$account +``` + +```shell--curl +curl $url/wallet/$id/nested -X POST --data '{"account": "'$account'"}' +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.createNested(account); + console.log(response); +})(); +``` + +> Sample response + +```json +{ + "network": "testnet", + "wid": 31, + "id": "foo", + "name": "baz", + "account": 0, + "branch": 2, + "index": 2, + "witness": true, + "nested": true, + "publicKey": "02a7a12fa67a7f0dc0bb2ae2c45d80c9b6248c004ef8b3f8da3f6feaf623f60939", + "script": null, + "program": "0014be20ad0c7ad43d1bb9f922f15cd7ba63b7fee290", + "type": "scripthash", + "address": "2NBzYG49AiNJjUr7NA1r4eee8jUpacb3Eo2" +} +``` + +Derive new nested p2sh receiving address for account. Note that this can't be done on a non-witness account otherwise you will receive the following error: + +`[error] (node) Cannot derive nested on non-witness account.` + +### HTTP Request + +`POST /wallet/:id/nested` + +### Post Paramters +Paramter | Description +--------- | -------------- +account
_string_ | account to derive the nested address for (default='default') + +## Get Balance +```javascript +let id, account; +``` + +```shell--vars +id='foo' +account='bar' +``` + +```shell--cli +bcoin cli wallet --id=$id balance --account=$account +``` + +```shell--curl +curl $url/wallet/$id/balance?account=$account +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = httpWallet.getBalance(account); + console.log(response); +})(); +``` + +> Sample response: + +```json +{ + "wid": 1, + "id": "foo", + "account": 1, + "unconfirmed": "8149.9999546", + "confirmed": "8150.0" +} +``` + +Get wallet or account balance. If no account option is passed, the call defaults to wallet balance (with account index of `-1`) + +### HTTP Request + +`GET /wallet/:id/balance?account=:account` + +### Request Paramters + +Paramters | Description +--------- | ------------- +id
_string_ | wallet id to get balance of +account
_string_ | account name (optional, defaults to entire wallet balance) + +## List all Coins + +```javascript +let id; +``` + +```shell--vars +id="foo" +``` + +```shell--curl +curl $url/wallet/$id/coin +``` + +```shell--cli +bcoin cli wallet --id=$id coins +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = httpWallet.getCoins(); + console.log(response); +})(); +``` + +> Sample Response + +```json +[ + { + "version": 1, + "height": 1180963, + "value": 1000, + "script": "76a9145730f139d833e3af30ccfb7c4e253ff4bab5de9888ac", + "address": "moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA", + "coinbase": false, + "hash": "bf49aaf50dfa229b99e83d29cae2515487b05cccb88cd111fb2ac738dac1058a", + "index": 0 + }, + { + "version": 1, + "height": 1180963, + "value": 1000, + "script": "76a9145730f139d833e3af30ccfb7c4e253ff4bab5de9888ac", + "address": "moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA", + "coinbase": false, + "hash": "efbaa2681576e0c2a9ee8e0bdaddd889e95e9631b94467b57552e5bc7048c2ae", + "index": 0 + } +] +``` +List all wallet coins available. + +### HTTP Request + +`GET /wallet/:id/coin` + +## Lock Coin/Outpoints + +```javascript +let id, passphrase, hash, index; +``` + +```shell--vars +id="foo" +passphrase="bar" +hash="dd1a110edcdcbb3110a1cbe0a545e4b0a7813ffa5e77df691478205191dad66f" +index="0" +``` + +```shell--cli +# Not Supported in CLI +``` + +```shell--curl +curl $url/wallet/$id/locked$hash/$index -X PUT --data '{"passphrase": "'$pasphrase'"}' +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.lockCoin(hash, index); + console.log(response); +})(); +``` + +> Sample response: + +```json +{ + "success": true +} +``` + +Lock outpoints. + +### HTTP Request + +`PUT /wallet/:id/locked/:hash/:index` + +### Request Parameters +Paramters | Description +---------- | -------------- +id
_string_ | id of wallet that contains the outpoint +hash
_string_ | hash of transaction that created the outpoint +index
_string_ or _int_ | index of the output in the transaction being referenced + +### Body Paramters +Parameter | Description +--------- | ------------ +passphrase
_string_ | passphrase of wallet being referenced + +## Unlock Outpoint + +```javascript +let id, passphrase, hash, index; +``` + +```shell--vars +id="foo" +passphrase="bar" +hash="dd1a110edcdcbb3110a1cbe0a545e4b0a7813ffa5e77df691478205191dad66f" +index="0" +``` + +```shell--cli +# Not Supported in CLI +``` + +```shell--curl +curl $url/wallet/$id/locked/$hash/$index -X DELETE --data '{"passphrase": "'$pasphrase'"}' +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.unlockCoin(hash, index); + console.log(response); +})(); +``` + +> Sample response: + +```json +{ + "success": true +} +``` + +Unlock outpoints. + +### HTTP Request + +`DEL /wallet/:id/locked/:hash/:index` + +### Request Parameters +Paramters | Description +---------- | -------------- +id
_string_ | id of wallet that contains the outpoint +hash
_string_ | hash of transaction that created the outpoint +index
_string_ or _int_ | index of the output in the transaction being referenced + +### Body Paramters +Parameter | Description +--------- | ------------ +passphrase
_string_ | passphrase of wallet being referenced + + +## Get Locked Outpoints + +```javascript +let id; +``` + +```shell--vars +id="foo" +``` + +```shell--cli +# Not supported in CLI +``` + +```shell--curl +curl $url/wallet/$id/locked +``` + +```javascript +const httpWallet = bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.getLocked(); + console.log(response); +})(); +``` + +> Sample response: + +```json +[ + { + "hash":"dd1a110edcdcbb3110a1cbe0a545e4b0a7813ffa5e77df691478205191dad66f", + "index":0 + } +] +``` + +Get all locked outpoints. + +### HTTP Request + +`GET /wallet/:id/locked` + +### Request Parameters +Paramters | Description +---------- | -------------- +id
_string_ | id of wallet to check for outpoints + + +## Get Wallet Coin + +```javascript +let id, hash, index; +``` + +```shell--vars +id="foo" +hash="efbaa2681576e0c2a9ee8e0bdaddd889e95e9631b94467b57552e5bc7048c2ae" +index=0 +``` + +```shell--cli +# command is wallet agnostic, same as in vanilla coin command + +bcoin cli coin $hash $index +``` + +```shell--curl +curl $url/wallet/$id/coin/$hash/$index +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.getCoin(hash, index); + console.log(response); +})(); +``` + +> Sample response: + +```json +{ + "version": 1, + "height": 1180963, + "value": 1000, + "script": "76a9145730f139d833e3af30ccfb7c4e253ff4bab5de9888ac", + "address": "moTyiK7aExe2v3hFJ9BCsYooTziX15PGuA", + "coinbase": false, + "hash": "efbaa2681576e0c2a9ee8e0bdaddd889e95e9631b94467b57552e5bc7048c2ae", + "index": 0 +} +``` + +Get wallet coin +### HTTP Request + +`GET /wallet/:id/coin/:hash/:index` + +### Request Parameters +Paramters | Description +---------- | -------------- +id
_string_ | id of wallet that contains the outpoint +hash
_string_ | hash of transaction that created the outpoint +index
_string_ or _int_ | index of the output in the transaction being referenced \ No newline at end of file diff --git a/api-docs-slate/source/includes/_wallet_accounts.md b/api-docs-slate/source/includes/_wallet_accounts.md new file mode 100644 index 0000000..3f6ff3c --- /dev/null +++ b/api-docs-slate/source/includes/_wallet_accounts.md @@ -0,0 +1,231 @@ +# Wallet Accounts +## Account Object +> An account object looks like this: + +```json + { + "wid": 1, + "id": "test", + "name": "default", + "initialized": true, + "witness": false, + "watchOnly": false, + "type": "pubkeyhash", + "m": 1, + "n": 1, + "accountIndex": 0, + "receiveDepth": 8, + "changeDepth": 1, + "nestedDepth": 0, + "lookahead": 10, + "receiveAddress": "mu5Puppq4Es3mibRskMwoGjoZujHCFRwGS", + "nestedAddress": null, + "changeAddress": "n3nFYgQR2mrLwC3X66xHNsx4UqhS3rkSnY", + "accountKey": "tpubDC5u44zLNUVo2gPVdqCbtX644PKccH5VZB3nqUgeCiwKoi6BQZGtr5d6hhougcD6PqjszsbR3xHrQ5k8yTbUt64aSthWuNdGi7zSwfGVuxc", + "keys": [] + } + +``` +Represents a BIP44 Account belonging to a Wallet. +Note that this object does not enforce locks. Any method that does a write is internal API only and will lead to race conditions if used elsewhere. + +From the [BIP44 Specification](https://github.com/bitcoin/bips/blob/master/bip-0044.mediawiki): + +

+ + This level splits the key space into independent user identities, so the wallet never mixes the coins across different accounts. + +

+

+ + Users can use these accounts to organize the funds in the same fashion as bank accounts; for donation purposes (where all addresses are considered public), for saving purposes, for common expenses etc. + +

+

+ + Accounts are numbered from index 0 in sequentially increasing manner. This number is used as child index in BIP32 derivation. + +

+

+ + Hardened derivation is used at this level. + +

+ +## Get Wallet Account List + +```shell--vars +id='test' +``` + +```shell--cli +bcoin cli wallet account list --id=$id +``` + +```javascript +const client = new bcoin.http.Client(); +(async () => { + const accountInfo = await client.getAccounts(id); + console.log(accountInfo); +})(); +``` + +> Sample response: + +```json +[ + "default" +] +``` + +List all account names (array indices map directly to bip44 account indices) associated with a specific wallet id. + +### HTTP Request + +`GET /wallet/:id/account` + + +Parameters | Description +---------- | ----------- +id
_string_ | id of wallet you would like to retrieve the account list for + + + +## Get Account Information +```javascript +let id, account; +``` + +```shell--vars +id='test' +account='default' +``` + +```shell--curl +curl $url/wallet/$id/account/$account +``` + +```shell--cli +bcoin cli wallet --id=$id account get $account +``` + +```javascript +const client = new bcoin.http.Client(); +(async () => { + const accountInfo = await client.getAccount(id, account); + console.log(accountInfo); +})(); +``` + +> Sample response: + +```json +{ + "wid": 1, + "id": "test", + "name": "default", + "initialized": true, + "witness": false, + "watchOnly": false, + "type": "pubkeyhash", + "m": 1, + "n": 1, + "accountIndex": 0, + "receiveDepth": 8, + "changeDepth": 1, + "nestedDepth": 0, + "lookahead": 10, + "receiveAddress": "mu5Puppq4Es3mibRskMwoGjoZujHCFRwGS", + "nestedAddress": null, + "changeAddress": "n3nFYgQR2mrLwC3X66xHNsx4UqhS3rkSnY", + "accountKey": "tpubDC5u44zLNUVo2gPVdqCbtX644PKccH5VZB3nqUgeCiwKoi6BQZGtr5d6hhougcD6PqjszsbR3xHrQ5k8yTbUt64aSthWuNdGi7zSwfGVuxc", + "keys": [] +} +``` + +Get account info. + +### HTTP Request + +`GET /wallet/:id/account/:account` + +Parameters | Description +---------- | ----------- +id
_string_ | id of wallet you would like to query +account
_string_ | id of account you would to retrieve information for + +## Create new wallet account + +```javascript +let id, name, type; +``` + +```shell--vars +id='test' +name='menace' +type='multisig' +``` + +```shell--cli +bcoin cli wallet --id=$id account create $name --type=$type +``` + +```shell--curl +curl $url/wallet/$id/account/$name \ + -X PUT + --data '{"type": "'$type"}' +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); +const options = {type: type} + +(async () => { + const account = await httpWallet.createAccount(name, options); + console.log(account); +})(); +``` + +> Sample response: + +```json +{ + "wid": 1, + "id": "test", + "name": "menace", + "initialized": true, + "witness": false, + "watchOnly": false, + "type": "multisig", + "m": 1, + "n": 1, + "accountIndex": 1, + "receiveDepth": 1, + "changeDepth": 1, + "nestedDepth": 0, + "lookahead": 10, + "receiveAddress": "mg7b3H3ZCHx3fwvUf8gaRHwcgsL7WdJQXv", + "nestedAddress": null, + "changeAddress": "mkYtQFpxDcqutMJtyzKNFPnn97zhft56wH", + "accountKey": "tpubDC5u44zLNUVo55dtQsJRsbQgeNfrp8ctxVEdDqDQtR7ES9XG5h1SGhkv2HCuKA2RZysaFzkuy5bgxF9egvG5BJgapWwbYMU4BJ1SeSj916G", + "keys": [] +} +``` + +Create account with specified account name. + +### HTTP Request + +`PUT /wallet/:id/account/:name` + +### Options object +Parameter | Description +--------- | ----------------- +name
_string_ | name to give the account. Option can be `account` or `name` +witness
_bool_ | whether or not to act as segregated witness wallet account +watchOnly
_bool_ | whether or not to make watch only account. Watch only accounts can't accept private keys for import (or sign transactions) +type
_string_ | what type of wallet to make it ('multisig', 'pubkeyhash') +m
_int_ | for multisig accounts, what to make `m` in m-of-n +n
_int_ | for multisig accounts, what to make the `n` in m-of-n diff --git a/api-docs-slate/source/includes/_wallet_admin.md b/api-docs-slate/source/includes/_wallet_admin.md new file mode 100644 index 0000000..3ec7b2f --- /dev/null +++ b/api-docs-slate/source/includes/_wallet_admin.md @@ -0,0 +1,162 @@ +# Wallet Admin +The _admin namespace exists to differentiate administrative level tasks on the wallet API that you probably don't want to expose to individual wallets. + +`/wallet/_admin/[TARGET_ACTION]` + + + +## Wallet Rescan +```javascript +let height; +``` + +```shell--vars +height = 50000 +``` + +```shell--curl +curl $url/wallet/_admin/rescan \ + -X POST \ + --data '{"height": '$height'}' +``` + +```shell--cli +bcoin cli rescan $height +``` + +```javascript +const height = 50000; +const client = new bcoin.http.Client({ + network: 'testnet', +}); + +(async () => { + await client.rescan(height); +})(); + +``` + +> Response Body: + +```json +{"success": true} +``` + +Initiates a blockchain rescan for the walletdb. Wallets will be rolled back to the specified height (transactions above this height will be unconfirmed). + +### Example HTTP Request +`POST /wallet/_admin/rescan?height=50000` + + +## Wallet Resend +```shell--curl +curl $url/wallet/_admin/resend \ +-X POST +``` + +```shell--cli +bcoin cli resend +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet', +}); + +(async () => { + await client.resend(); +})(); + +``` + +> Response Body: + +```json + {"success": true} +``` + +Rebroadcast all pending transactions in all wallets. + +### HTTP Request + +`POST /wallet/_admin/resend` + +##Wallet Backup +```javascript +let path; +``` + +```shell--vars +path='/path/to/new/backup' +``` + +```shell--curl +curl $url/wallet/_admin/backup?path=/home/user/walletdb-backup.ldb \ + -X POST \ +``` + +```shell--cli +bcoin cli backup $path +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet', +}); + +(async () => { + await client.backup(path); +})(); + +``` + +> Response Body: + +```json +{"success": true} +``` + +Safely backup the wallet database to specified path (creates a clone of the database). + +### HTTP Request + +`POST /wallet/_admin/backup?path=/home/user/walletdb-backup.ldb` + +## List all Wallets + +```shell--curl +curl $url/wallet/_admin/wallets +``` + +```shell--cli +bcoin cli wallets +``` + +```javascript +const client = new bcoin.http.Client({ + network: 'testnet', +}); + +(async () => { + const wallets = await client.getWallets(); + console.log(wallets) +})(); + +``` + +> Sample Response Body: + +```json +[ + "primary", + "test" +] +``` + +List all wallet IDs. Returns an array of strings. + +### HTTP Request + +`GET /wallet/_admin/wallets` \ No newline at end of file diff --git a/api-docs-slate/source/includes/_wallet_tx.md b/api-docs-slate/source/includes/_wallet_tx.md new file mode 100644 index 0000000..728e3dd --- /dev/null +++ b/api-docs-slate/source/includes/_wallet_tx.md @@ -0,0 +1,309 @@ +# Wallet Transactions + +## Get Wallet TX Details + +```javascript +let id, hash +``` + +```shell--vars +id="foo" +hash="18d2cf5683d7befe06941f59b7fb4ca0e915dcb9c6aece4ce8966a29e7c576fe" +``` + +```shell--cli +bcoin cli wallet --id=$id tx $hash +``` + +```shell--curl +curl $url/wallet/$id/tx/$hash +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.getTX(hash); + console.log(response); +})(); +``` +> Sample Response + +```json +{ + "wid": 1, + "id": "foo", + "hash": "18d2cf5683d7befe06941f59b7fb4ca0e915dcb9c6aece4ce8966a29e7c576fe", + "height": -1, + "block": null, + "time": 0, + "mtime": 1507077109, + "date": "2017-10-04T00:31:49Z", + "size": 225, + "virtualSize": 225, + "fee": 4540, + "rate": 20177, + "confirmations": 0, + "inputs": + [ { value: 5000009080, + address: "SdCEuxkbdMygcKtL36x2CT8p1vhz56SsbG", + path: [Object] } ], + "outputs": + [ { value: 100000000, + address: "SP7K3cSLH66zDisioqPrTC3QSRwP9GPENB", + path: null }, + { value: 4900004540, + address: "SSzzdLbBeWBwNTUpbGdD9gBk6Wzk34sT7J", + path: [Object] } ], + "tx": "010000000148ae6682231f381845f98049c871e9b6bf0a9a7f5c5270354f71079262577977000000006a47304402203359117c409d292700fbacc03e4b540066a6b8ca763f1dd578e8262fe5e74c1b02206c91f816755469cd4a6b110941b51f29e251b86afe246456cf17823ef4fc7f5301210299c1a1049d546a720dd614034ce2802a3f64d64c37b729ae184825f71d0a037affffffff0200e1f505000000001976a91413eab6745a3fcbcf8b4448c130ff8bc37db6e91b88acbc221024010000001976a9143e9958577401fe8d75ed6f162cc6832fcb26094188ac00000000" +} +``` +Get wallet transaction details. + +### HTTP Request + +`GET /wallet/:id/tx/:hash` + +### Request Parameters +Parameter | Description +--------- | -------------- +id
_string_ | id of wallet that handled the transaction +hash
_string_ | hash of the transaction you're trying to retrieve + +## Delete Transaction +```javascript +let id, hash, passphrase; +``` + +```shell--vars +id="foo" +hash="2a22606ee555d2c26ec979f0c45cd2dc18c7177056189cb345989749fd58786" +passphrase="bar" +``` + +```shell--cli +# Not available in CLI +``` + +```shell--curl +curl $url/wallet/$id/tx/$hash \ + -X DELETE \ + --data '{"passphrase": "'$passphrase'"}' +``` + +```javascript + // Not available in javascript wallet client. +``` + +Abandon single pending transaction. Confirmed transactions will throw an error. +`"TX not eligible"` + +### HTTP Request + +`DEL /wallet/:id/tx/:hash` + +Paramters | Description +----------| -------------------- +id
_string_ | id of wallet where the transaction is that you want to remove +hash
_string_ | hash of transaction you would like to remove. + +## Get Wallet TX History + +```javascript +let id; +``` + +```shell--vars +id='foo' +``` + +```shell--cli +bcoin cli wallet --id=$id history +``` + +```shell--curl +curl $url/wallet/$id/tx/history +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); +const account = 'default'; + +(async () => { + const response = await httpWallet.getHistory(account); + console.log(response); +})(); +``` +> Sample Response + +```json +[ + { + "wid": 1, + "id": "primary", + "hash": "f5968051ce275d89b7a6b797eb6e6b081243ecf027872fc6949fae443e21b858", + "height": -1, + "block": null, + "time": 0, + "mtime": 1503690544, + "date": "2017-08-25T19:49:04Z", + "size": 226, + "virtualSize": 226, + "fee": 0, + "rate": 0, + "confirmations": 0, + "inputs": [ + { + "value": 0, + "address": "mp2w1u4oqZnHDd1zDeAvCTX9B3SaFsUFQx", + "path": null + } + ], + "outputs": [ + { + "value": 100000, + "address": "myCkrhQbJwqM8wKi9YuhyTjN3pukNuWxZ9", + "path": { + "name": "default", + "account": 0, + "change": false, + "derivation": "m/0'/0/3" + } + }, + { + "value": 29790920, + "address": "mqNm1rSYVqD23Aj6fkupApuSok9DNZAeBk", + "path": null + } + ], + "tx": "0100000001ef8a38cc946c57634c2db05fc298bf94f5c88829c5a6e2b0610fcc7b38a9264f010000006b483045022100e98db5ddb92686fe77bb44f86ce8bf6ff693c1a1fb2fb434c6eeed7cf5e7bed4022053dca3980a902ece82fb8e9e5204c26946893388e4663dbb71e78946f49dd0f90121024c4abc2a3683891b35c04e6d40a07ee78e7d86ad9d7a14265fe214fe84513676ffffffff02a0860100000000001976a914c2013ac1a5f6a9ae91f66e71bbfae4cc762c2ca988acc892c601000000001976a9146c2483bf52052e1125fc75dd77dad06d65b70a8288ac00000000" + }, + ... +] +``` + +Get wallet TX history. Returns array of tx details. + +### HTTP Request +`GET /wallet/:id/tx/history` + +### Request Parameters +Paramter | Description +-------- | ------------------------- +id
_string_ | id of wallet to get history of + +## Get Pending Transactions + +```javascript +let id; +``` + +```shell--vars +id='foo' +``` + +```shell--cli +bcoin cli wallet --id=$id pending +``` + +```shell--curl +curl $url/wallet/$id/tx/unconfirmed +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.getPending(account); + console.log(response); +})(); +``` + +Get pending wallet transactions. Returns array of tx details. + +### HTTP Request + +`GET /wallet/:id/tx/unconfirmed` + +### Request Parameters +Paramter | Description +-------- | ------------------------- +id
_string_ | id of wallet to get pending/unconfirmed txs + + +## Get Range of Transactions +```javascript +let id, account, start, end; +``` + +```shell--vars +id="foo" +account="foo" +start="1506909119" +end="1506909154" +``` + +```shell--cli +# range not available in CLI +``` + +```shell--curl +curl $url/wallet/$id/tx/range?start=$start +``` + +```javascript +const httpWallet = new bcoin.http.Wallet({ id: id }); + +(async () => { + const response = await httpWallet.getRange(account, {start: start, end: end}); + console.log(response); +})(); +``` +> Sample Response + +```json +[ + { "wid": 1, + "id": "primary", + "hash": "80ac63671e7b8635d10d372c4c3bed5615624d9fa28dfd747abf440417d70983", + "height": -1, + "block": null, + "time": 0, + "mtime": 1506909119, + "date": "2017-10-02T01:51:59Z", + "size": 200, + "virtualSize": 173, + "fee": 0, + "rate": 0, + "confirmations": 0, + "inputs": [ [Object] ], + "outputs": [ [Object], [Object] ], + "tx": "010000000001010000000000000000000000000000000000000000000000000000000000000000ffffffff20028d010e6d696e65642062792062636f696e045460ad97080000000000000000ffffffff02bc03062a010000001976a914d7ee508e06ece23679ba9ee0a770561ae2ed595688ac0000000000000000266a24aa21a9ed5772988727e8641cf3c7d2bf5a7fee9a5d0e827de0b6bed5658eee8f0821b5200120000000000000000000000000000000000000000000000000000000000000000000000000" + }, + ... +] +``` +Get range of wallet transactions by timestamp. Returns array of tx details. + + + +### HTTP Request + +`GET /wallet/:id/tx/range` + +### Body Parameters +Paramter | Description +-------- | ------------------------- +account
_string_ | account to get the tx history from +start
_int_ | start time to get range from +end
_int_ | end time to get range from + + diff --git a/api-docs-slate/source/index.html.md b/api-docs-slate/source/index.html.md new file mode 100644 index 0000000..a02f88b --- /dev/null +++ b/api-docs-slate/source/index.html.md @@ -0,0 +1,80 @@ +--- +title: Bcoin API Reference + +home_link: http://bcoin.io + +language_tabs: # must be one of https://git.io/vQNgJ + - shell--curl: cURL + - shell--cli: CLI + - javascript + +toc_footers: + - Join us on Slack + - See the code on GitHub + - Browse the guides + - Full API Documentation + - Documentation Powered by Slate + +includes: + - clients + - node + - node_rpc + - node_rpc_general + - node_rpc_chain + - node_rpc_block + - node_rpc_mempool + - node_rpc_tx + - node_rpc_mining + - node_rpc_network + - coin + - transaction + - wallet_admin + - wallet + - wallet_tx + - wallet_accounts + - errors + +search: true +--- + +# Introduction + +Welcome to the Bcoin API! + +The default bcoin HTTP server listens on the standard RPC port (`8332` for main, `18332` for testnet, `48332` for regtest, and `18556` default for simnet). It exposes a REST json api, as well as a JSON-RPC api. + +# Authentication +## Auth + +```shell--curl +curl http://x:[api-key]@127.0.0.1:8332/ +``` + +```shell--cli +export BCOIN_API_KEY=[api-key] +bcoin cli info +``` + +```javascript +const client = new bcoin.http.Client({ + apiKey: [api-key], + //... +}); +// Or wallet +const wallet = new bcoin.http.Wallet({ + apiKey: [api-key], + //... +}); +``` + +> Make sure to replace `[api-key]` with your own key. + +Auth is accomplished via HTTP Basic Auth, using your node's API key (passed via --api-key). + + + + diff --git a/api-docs-slate/source/javascripts/all.js b/api-docs-slate/source/javascripts/all.js new file mode 100644 index 0000000..5f5d406 --- /dev/null +++ b/api-docs-slate/source/javascripts/all.js @@ -0,0 +1,2 @@ +//= require ./all_nosearch +//= require ./app/_search diff --git a/api-docs-slate/source/javascripts/all_nosearch.js b/api-docs-slate/source/javascripts/all_nosearch.js new file mode 100644 index 0000000..b18c1d8 --- /dev/null +++ b/api-docs-slate/source/javascripts/all_nosearch.js @@ -0,0 +1,16 @@ +//= require ./lib/_energize +//= require ./app/_toc +//= require ./app/_lang + +$(function() { + loadToc($('#toc'), '.toc-link', '.toc-list-h2', 10); + setupLanguages($('body').data('languages')); + $('.content').imagesLoaded( function() { + window.recacheHeights(); + window.refreshToc(); + }); +}); + +window.onpopstate = function() { + activateLanguage(getLanguageFromQueryString()); +}; diff --git a/api-docs-slate/source/javascripts/app/_lang.js b/api-docs-slate/source/javascripts/app/_lang.js new file mode 100644 index 0000000..208f4e0 --- /dev/null +++ b/api-docs-slate/source/javascripts/app/_lang.js @@ -0,0 +1,164 @@ +//= require ../lib/_jquery + +/* +Copyright 2008-2013 Concur Technologies, Inc. + +Licensed under the Apache License, Version 2.0 (the "License"); you may +not use this file except in compliance with the License. You may obtain +a copy of the License at + + http://www.apache.org/licenses/LICENSE-2.0 + +Unless required by applicable law or agreed to in writing, software +distributed under the License is distributed on an "AS IS" BASIS, WITHOUT +WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the +License for the specific language governing permissions and limitations +under the License. +*/ +;(function () { + 'use strict'; + + var languages = []; + + window.setupLanguages = setupLanguages; + window.activateLanguage = activateLanguage; + window.getLanguageFromQueryString = getLanguageFromQueryString; + + function activateLanguage(language) { + if (!language) return; + if (language === "") return; + + $(".lang-selector a").removeClass('active'); + $(".lang-selector a[data-language-name='" + language + "']").addClass('active'); + for (var i=0; i < languages.length; i++) { + $(".highlight.tab-" + languages[i]).hide(); + $(".lang-specific." + languages[i]).hide(); + } + $(".highlight.tab-" + language).show(); + $(".lang-specific." + language).show(); + + window.recacheHeights(); + + // scroll to the new location of the position + if ($(window.location.hash).get(0)) { + $(window.location.hash).get(0).scrollIntoView(true); + } + } + + // parseURL and stringifyURL are from https://github.com/sindresorhus/query-string + // MIT licensed + // https://github.com/sindresorhus/query-string/blob/7bee64c16f2da1a326579e96977b9227bf6da9e6/license + function parseURL(str) { + if (typeof str !== 'string') { + return {}; + } + + str = str.trim().replace(/^(\?|#|&)/, ''); + + if (!str) { + return {}; + } + + return str.split('&').reduce(function (ret, param) { + var parts = param.replace(/\+/g, ' ').split('='); + var key = parts[0]; + var val = parts[1]; + + key = decodeURIComponent(key); + // missing `=` should be `null`: + // http://w3.org/TR/2012/WD-url-20120524/#collect-url-parameters + val = val === undefined ? null : decodeURIComponent(val); + + if (!ret.hasOwnProperty(key)) { + ret[key] = val; + } else if (Array.isArray(ret[key])) { + ret[key].push(val); + } else { + ret[key] = [ret[key], val]; + } + + return ret; + }, {}); + }; + + function stringifyURL(obj) { + return obj ? Object.keys(obj).sort().map(function (key) { + var val = obj[key]; + + if (Array.isArray(val)) { + return val.sort().map(function (val2) { + return encodeURIComponent(key) + '=' + encodeURIComponent(val2); + }).join('&'); + } + + return encodeURIComponent(key) + '=' + encodeURIComponent(val); + }).join('&') : ''; + }; + + // gets the language set in the query string + function getLanguageFromQueryString() { + if (location.search.length >= 1) { + var language = parseURL(location.search).language + if (language) { + return language; + } else if (jQuery.inArray(location.search.substr(1), languages) != -1) { + return location.search.substr(1); + } + } + + return false; + } + + // returns a new query string with the new language in it + function generateNewQueryString(language) { + var url = parseURL(location.search); + if (url.language) { + url.language = language; + return stringifyURL(url); + } + return language; + } + + // if a button is clicked, add the state to the history + function pushURL(language) { + if (!history) { return; } + var hash = window.location.hash; + if (hash) { + hash = hash.replace(/^#+/, ''); + } + history.pushState({}, '', '?' + generateNewQueryString(language) + '#' + hash); + + // save language as next default + localStorage.setItem("language", language); + } + + function setupLanguages(l) { + var defaultLanguage = localStorage.getItem("language"); + + languages = l; + + var presetLanguage = getLanguageFromQueryString(); + if (presetLanguage) { + // the language is in the URL, so use that language! + activateLanguage(presetLanguage); + + localStorage.setItem("language", presetLanguage); + } else if ((defaultLanguage !== null) && (jQuery.inArray(defaultLanguage, languages) != -1)) { + // the language was the last selected one saved in localstorage, so use that language! + activateLanguage(defaultLanguage); + } else { + // no language selected, so use the default + activateLanguage(languages[0]); + } + } + + // if we click on a language tab, activate that language + $(function() { + $(".lang-selector a").on("click", function() { + var language = $(this).data("language-name"); + pushURL(language); + activateLanguage(language); + return false; + }); + }); +})(); diff --git a/api-docs-slate/source/javascripts/app/_search.js b/api-docs-slate/source/javascripts/app/_search.js new file mode 100644 index 0000000..9ff4233 --- /dev/null +++ b/api-docs-slate/source/javascripts/app/_search.js @@ -0,0 +1,98 @@ +//= require ../lib/_lunr +//= require ../lib/_jquery +//= require ../lib/_jquery.highlight +;(function () { + 'use strict'; + + var content, searchResults; + var highlightOpts = { element: 'span', className: 'search-highlight' }; + var searchDelay = 0; + var timeoutHandle = 0; + + var index = new lunr.Index(); + + index.ref('id'); + index.field('title', { boost: 10 }); + index.field('body'); + index.pipeline.add(lunr.trimmer, lunr.stopWordFilter); + + $(populate); + $(bind); + + function populate() { + $('h1, h2').each(function() { + var title = $(this); + var body = title.nextUntil('h1, h2'); + index.add({ + id: title.prop('id'), + title: title.text(), + body: body.text() + }); + }); + + determineSearchDelay(); + } + function determineSearchDelay() { + if(index.tokenStore.length>5000) { + searchDelay = 300; + } + } + + function bind() { + content = $('.content'); + searchResults = $('.search-results'); + + $('#input-search').on('keyup',function(e) { + var wait = function() { + return function(executingFunction, waitTime){ + clearTimeout(timeoutHandle); + timeoutHandle = setTimeout(executingFunction, waitTime); + }; + }(); + wait(function(){ + search(e); + }, searchDelay ); + }); + } + + function search(event) { + + var searchInput = $('#input-search')[0]; + + unhighlight(); + searchResults.addClass('visible'); + + // ESC clears the field + if (event.keyCode === 27) searchInput.value = ''; + + if (searchInput.value) { + var results = index.search(searchInput.value).filter(function(r) { + return r.score > 0.0001; + }); + + if (results.length) { + searchResults.empty(); + $.each(results, function (index, result) { + var elem = document.getElementById(result.ref); + searchResults.append("
  • " + $(elem).text() + "
    • "); + }); + highlight.call(searchInput); + } else { + searchResults.html('
  • '); + $('.search-results li').text('No Results Found for "' + searchInput.value + '"'); + } + } else { + unhighlight(); + searchResults.removeClass('visible'); + } + } + + function highlight() { + if (this.value) content.highlight(this.value, highlightOpts); + } + + function unhighlight() { + content.unhighlight(highlightOpts); + } +})(); + diff --git a/api-docs-slate/source/javascripts/app/_toc.js b/api-docs-slate/source/javascripts/app/_toc.js new file mode 100644 index 0000000..bb651b0 --- /dev/null +++ b/api-docs-slate/source/javascripts/app/_toc.js @@ -0,0 +1,117 @@ +//= require ../lib/_jquery +//= require ../lib/_imagesloaded.min +;(function () { + 'use strict'; + + var loaded = false; + + var debounce = function(func, waitTime) { + var timeout = false; + return function() { + if (timeout === false) { + setTimeout(function() { + func(); + timeout = false; + }, waitTime); + timeout = true; + } + }; + }; + + var closeToc = function() { + $(".toc-wrapper").removeClass('open'); + $("#nav-button").removeClass('open'); + }; + + function loadToc($toc, tocLinkSelector, tocListSelector, scrollOffset) { + var headerHeights = {}; + var pageHeight = 0; + var windowHeight = 0; + var originalTitle = document.title; + + var recacheHeights = function() { + headerHeights = {}; + pageHeight = $(document).height(); + windowHeight = $(window).height(); + + $toc.find(tocLinkSelector).each(function() { + var targetId = $(this).attr('href'); + if (targetId[0] === "#") { + headerHeights[targetId] = $(targetId).offset().top; + } + }); + }; + + var refreshToc = function() { + var currentTop = $(document).scrollTop() + scrollOffset; + + if (currentTop + windowHeight >= pageHeight) { + // at bottom of page, so just select last header by making currentTop very large + // this fixes the problem where the last header won't ever show as active if its content + // is shorter than the window height + currentTop = pageHeight + 1000; + } + + var best = null; + for (var name in headerHeights) { + if ((headerHeights[name] < currentTop && headerHeights[name] > headerHeights[best]) || best === null) { + best = name; + } + } + + // Catch the initial load case + if (currentTop == scrollOffset && !loaded) { + best = window.location.hash; + loaded = true; + } + + var $best = $toc.find("[href='" + best + "']").first(); + if (!$best.hasClass("active")) { + // .active is applied to the ToC link we're currently on, and its parent