Blocktrailメモ

Bitcoinアプリ作成を簡単にしてくれるWebサービス[Blocktrail](https://www.blocktrail.com/)。 以下にその特徴や使い方をメモしておきます。（このエントリは今後も更新される予定です） # 目次 (index) + [特徴](#feature) + [制限](#limitation) + [ドキュメント](#document-link) + [インストール](#install) + [HelloWorld的なExample](#helloworld) + [Testnet](#testnet) + [blocktrailで使われるキー](#keys) + [ちょっとだけ実践的なExamples](#example) + [SDKの初期化](#init-sdk) + [ウォレット作成](#example-create-new-wallet) + [ウォレットの初期化](#example-init-wallet) + [Bitcoinアドレスの取得](#example-get-address) + [ウォレットの残高照会](#example-get-balance) + [ウォレットWebhookのセットアップ](#example-setup-webhook) + [トランザクション送信](#example-pay) + [トランザクション履歴](#example-transactions) + [Webhookで特定のイベントを購読＆停止](#example-subscribe-address-transactions) + [アドレス指定でUnspentOutputsを取得](#example-address-unspent-outputs) + [ブロック情報を取得](#example-block) + [特定ブロックのトランザクションを取得](#example-block-transactions) + [全ブロック情報を取得](#example-all-blocks) + [最新ブロックを取得](#example-block-latest) + [クライアントのトランザクションを取得](#example-client-transaction) + [Webhookの取得](#example-all-webhooks) + [Webhookを更新](#example-update-webhook) + [Webhookを削除](#example-delete-webhook) + [参考](#refs) ## 特徴 (feature) - BitcoinクライアントWebサービス - APIキーは[ここで作成可能](https://www.blocktrail.com/dev/signup) - 巨大なブロックチェーンをダウンロードしなくても使える - 主要言語に対応したシンプルなAPI (対応言語: cURL, Python, PHP, jQuery, Node.js) - jQuery対応＝ブラウザアプリも作成可能 - ただし現時点 (2016/11/01)でAPIフル機能が使えるのは `PHP` と `Node.js` だけ。 - Webhook対応 [⤒](#index) ## 制限 (limitation) [APIの利用制限](https://www.blocktrail.com/api/docs/lang/nodejs#rate_limits)有り。 Freeデベロッパーアカウントで、 - 432,000 リクエスト/日 - 300 リクエスト/分 制限を超えた場合は、APIがステータスコード `429` エラーを返す。 利用制限回数のアップグレードは可能。（有料？） [⤒](#index) ## ドキュメント (document-link) [Getting Started](https://www.blocktrail.com/api/docs/lang/nodejs#getting_started) [⤒](#index) ## インストール (install) ``` $ npm install blocktrail-sdk --save ``` [⤒](#index) ## HelloWorld的なExample (helloworld) Node.js: ``` var blocktrail = require('blocktrail-sdk'); console.log("123456789 Satoshi to BTC: ", blocktrail.toBTC(123456789)); console.log("1.23456789 BTC to Satoshi: ", blocktrail.toSatoshi(1.23456789)); ``` [⤒](#index) ## Testnet (testnet) [ここ](http://tpfaucet.appspot.com/)でテスト用のコインがもらえる。 そしてもらったテスト用コインは[こちらのTestnet用ウォレット](http://testnetwallet.com/)で管理できる。 [⤒](#index) ## blocktrailで使われるキー (keys) blocktrailであなたのBitcoinにアクセスするには、以下の3つのうち *2つのキーが必要*: + Primary Key: - SDKでランダムに生成されるPrivateキーの一種 - パスフレーズと合わせることで実際のPrivateキーを得ることができる + Backup Key: - 万が一の時のためのキー - Offline管理推奨 - パスフレーズは不要 - **!重要!: このキーを取得できるチャンスはウォレットを作った時の一回だけ！** + BlockTrail Key: - あなたのトランザクションの共同署名に使われる - blocktrail.comが唯一アクセスできるキー - このキーだけではあなたのBitcoinにアクセスできない [⤒](#index) ## ちょっとだけ実践的なExamples (example) [⤒](#index) ### SDKの初期化: (init-sdk) ``` blocktrail = require('blocktrail-sdk'); client = blocktrail.BlocktrailSDK({apiKey: "MY_APIKEY", apiSecret: "MY_APISECRET", network: "BTC", testnet: true}); ``` [⤒](#index) ### ウォレット作成: (example-create-new-wallet) ``` client.createNewWallet("mywallet", "mypass", function(err, wallet, backupInfo) {}); ``` **!重要!: functionの引数の `backupInfo` は必ず保存すること！[Backupキー](#keys)を取得するチャンスはこの時だけ。** [⤒](#index) ### ウォレットの初期化: (example-init-wallet) ``` client.initWallet("mywallet", "mypass", function(err, wallet) {}); ``` functionの引数`wallet`には暗号化された**Primaryキー**が入っている。これはユーザ側で復号化できる。 [⤒](#index) ### Bitcoinアドレスの生成: (example-get-address) ``` wallet.getNewAddress(function(err, address) {}); ``` [⤒](#index) ### ウォレットの残高照会: (example-get-balance) ``` wallet.getBalance( function(err, confirmedBalance, unconfirmedBalance) { console.log('Balance: ', blocktrail.toBTC(confirmedBalance)); console.log('Unconfirmed Balance: ', blocktrail.toBTC(unconfirmedBalance)); } ); ``` [⤒](#index) ### ウォレットWebhookのセットアップ: (example-setup-webhook) ``` wallet.setupWebhook('https://user:pass@example.com/'); ``` Webhookデータには以下のような値が入っている: ``` { "network" : "BTC", "data" : { "hash": "8fa29a1db30aceed2ec5afb2bcdf6196207975780b4ca5f3f1d6313cab855fe7", "time": "2014-08-25T09:29:28+0000", "confirmations": 3948, "...etc..." : "...etc..." }, "wallet" : { "addresses" : [ "1qMBuZnrmGoAc2MWyTnSgoLuWReDHNYyF" ], "balance" : -347328 }, "addresses": { "1qMBuZnrmGoAc2MWyTnSgoLuWReDHNYyF": −347328, ... ``` [⤒](#index) ### トランザクション送信: (example-pay) ``` value = blocktrail.toSatoshi(1.1); wallet.pay({'1NcXPMRaanz43b1kokpPuYDdk6GGDvxT2T': value}, null, false, true, blocktrail.Wallet.FEE_STRATEGY_BASE_FEE, function(err, result) {}); wallet.pay({'1NcXPMRaanz43b1kokpPuYDdk6GGDvxT2T': value}, null, false, true, blocktrail.Wallet.FEE_STRATEGY_LOW_PRIORITY, function(err, result) {}); ``` [⤒](#index) ### トランザクション履歴: (example-transactions) #### ウォレットトランザクション: ``` wallet.transactions(function(err, result) {}); ``` #### アドレストランザクション: ``` client.addressTransactions('1NcXPMRaanz43b1kokpPuYDdk6GGDvxT2T', function(err, addressTxs) {}); ``` 引数: | Name | Type | Description | |:-----------|:------------|:------------| | address | (string) | A bitcoin address hash | | page | (integer) (optional) | The pagination page to retrieve | | limit | (integer) (optional) | the number of records to retrieve per page (max 200) | | sort_dir | (string) (optional) | the direction to sort the results ('asc' or 'desc') | [⤒](#index) ### Webhookで特定のイベントを購読＆停止: (example-subscribe-address-transactions) ``` // アドレスを指定してトランザクション購読(引数の `6` はconfirmationの数): client.subscribeAddressTransactions('my-webhook-id', '1dice8EMZmqKvrGE4Qc9bUFf9PX3xaYDp', 6, function(err, result) {/*...*/}); // ブロック購読: client.subscribeNewBlocks('my-webhook-id', function(err, result) {/*...*/}); // アドレス指定購読停止: client.unsubscribeAddressTransactions('my-webhook-id', '1dice8EMZmqKvrGE4Qc9bUFf9PX3xaYDp', function(err, result) {/*...*/}); // ブロック購読停止: client.unsubscribeNewBlocks('my-webhook-id', function(err, result) {/*...*/}); ``` こんな感じでデータが配信される: ``` { "network" : "BTC", "data" : { "hash": "8fa29a1db30aceed2ec5afb2bcdf6196207975780b4ca5f3f1d6313cab855fe7", "time": "2014-08-25T09:29:28+0000", "confirmations": 3948, "...etc..." : "...etc..." }, "addresses": { "1qMBuZnrmGoAc2MWyTnSgoLuWReDHNYyF": −2501000 } } ``` [⤒](#index) ### アドレス指定でUnspentOutputsを取得: (example-address-unspent-outputs) ``` client.addressUnspentOutputs('1NcXPMRaanz43b1kokpPuYDdk6GGDvxT2T', function(err, address_utxo) {}); ``` 返り値`address_utxo`の値はこんな感じ: ``` { "data": [ { "hash": "902912aeafe06a03ca95c70cad2e709c89e9b4f4a99aa6a0ae386408ae131b0f", "time": "2014-09-05T17:08:04+0000", "confirmations": 279, "is_coinbase": false, "value": 15000, "index": 0, "address": "1NcXPMRaanz43b1kokpPuYDdk6GGDvxT2T", "type": "pubkeyhash", "multisig": null, "script": "DUP HASH160 0x14 0xed12908714ffd43142bf9832692017e8ad54e9a8 EQUALVERIFY CHECKSIG", "script_hex": "76a914ed12908714ffd43142bf9832692017e8ad54e9a888ac" }, { /* ... */ } ], "current_page": 1, "per_page": 20, "total": 4 } ``` [⤒](#index) ### ブロック情報を取得: (example-block) ``` client.block(0, function(err, block) {}); client.block('0000000000000000fa0b2badd05db0178623ebf8dd081fe7eb874c26e27d0b3b', function(err, block) {}); ``` 引数には、ブロックheightかブロックhashを指定する。 返り値: ``` { "hash": "0000000000000000fa0b2badd05db0178623ebf8dd081fe7eb874c26e27d0b3b", "height": 290000, "block_time": "2014-03-11T08:27:57+0000", "difficulty": 3815723798, "merkleroot": "23ff0bafcf34ef9aa1c8117bd5cb4e410f9cd69be214325f7518457da99479b9", "is_orphan": false, "prev_block": "0000000000000000417e85b03b5c8e973ccf3c88359512b43d22c49501041eb6", "next_block": "00000000000000006fa3f3b92c95c83ddd9026af8e00227c2acd34b35a7bb290", "byte_size": 332014, "confirmations": 31130, "transactions": 355, "value": 591629880320, "miningpool_name": "Eligius", "miningpool_url": "http://eligius.st", "miningpool_slug": "eligius" } ``` [⤒](#index) ### 特定ブロックのトランザクションを取得: (example-block-transactions) ``` client.blockTransactions(0, function(err, blockTxs) {}); client.block_transactions('0000000000000000fa0b2badd05db0178623ebf8dd081fe7eb874c26e27d0b3b', function(err, blockTxs) {}); ``` 返り値: ``` { "current_page": 1, "per_page": 20, "total": 651, "data": [ { "hash": "6f61bb2cdbe5c604ffa3d1ec3f6ae66508c2d63317a13f40b07f8e8c9e0c54e7", "time": "2014-03-11T08:27:57+0000", "confirmations": 31130, "is_coinbase": true, "estimated_value": 2508678875, "total_input_value": 2500000000, "total_output_value": 2508678875, "total_fee": 8678875, "estimated_change": null, "estimated_change_address": null, "inputs": [ { "index": 0, "output_hash": null, "output_index": 0, "value": 2500000000, "address": null, "type": "coinbase", "multisig": null, "script_signature": null } ], "outputs": [ { "index": 0, "value": 2499999999, "address": "1ChANGeATMH8dFnj39wGTjfjudUtLspzXr", "type": "pubkeyhash", "multisig": null, "script": "DUP HASH160 0x14 0x8041d74e20e69ebe3ec37c57434cee842ba1bd16 EQUALVERIFY CHECKSIG", "script_hex": "76a9148041d74e20e69ebe3ec37c57434cee842ba1bd1688ac", "spent_hash": "f5ab086676bbd6e671097a4148a978ded7f67b3de3efac54ae39dda1e644fe69", "spent_index": 9 }, { "index": 1, "value": 8678876, "address": "18d3HV2bm94UyY4a9DrPfoZ17sXuiDQq2B", "type": "pubkeyhash", "multisig": null, "script": "DUP HASH160 0x14 0x5399c3093d31e4b0af4be1215d59b857b861ad5d EQUALVERIFY CHECKSIG", "script_hex": "76a9145399c3093d31e4b0af4be1215d59b857b861ad5d88ac", "spent_hash": "8bfc37bcd44acc2262f6ab714c0caf9faadb2b8eda79497040b59af04c3c6e7d", "spent_index": 32 } ] }, { /* ... */ } ] } ``` [⤒](#index) ### 全ブロック情報を取得: (example-all-blocks) ``` client.allBlocks(function(err, blocks) {}); ``` 返り値: ``` { "current_page": 1, "per_page": 20, "total": 321129, "data": [ { "hash": "000000000019d6689c085ae165831e934ff763ae46a2a6c172b3f1b60a8ce26f", "height": 0, "block_time": "2009-01-03T18:15:05+0000", "difficulty": 1, "merkleroot": "4a5e1e4baab89f3a32518a88c31bc87f618f76673e2cc77ab2127b7afdeda33b", "is_orphan": false, "byte_size": 285, "confirmations": 321130, "transactions": 1, "value": 5000000000, "miningpool_name": null, "miningpool_url": null, "miningpool_slug": null }, { /* ... */ } ] } ``` [⤒](#index) ### 最新ブロックを取得: (example-block-latest) ``` client.blockLatest(function(err, latestBlock) {}); ``` 返り値: ``` { "hash": "000000000000000005afebaa75ff40714a1ed96539adb1266bbf7be9aaf767ae", "height": "321129", "block_time": "2014-09-17T09:00:26+0000", "difficulty": "29829733124.00000000", "merkleroot": "aaadea1a8c2cb1777d822d47e6acd0360b2f2e4f3c7c1f79cb4284866457ade3", "prev_block": "000000000000000019bea784e37fe450d522b9a4f0a4e8dcad4bd7c9283e4203", "next_block": null, "byte_size": "670679", "confirmations": 1, "transactions": "727", "value": "277325560913", "miningpool_name": "Eligius", "miningpool_url": "http://eligius.st", "miningpool_slug": "eligius" } ``` [⤒](#index) ### クライアントのトランザクションを取得: (example-client-transaction) ``` client.transaction('c326105f7fbfa4e8fe971569ef8858f47ee7e4aa5e8e7c458be8002be3d86aad', function(err, tx) {}); ``` [⤒](#index) ### Webhookを取得: (example-all-webhooks) ``` // 全て: client.allWebhooks(page, limit, function(err, result) {/*...*/}); // ID指定: client.getWebhook('my-webhook-id', function(err, result) {/*...*/}); ``` [⤒](#index) ### Webhookを更新: (example-update-webhook) ``` var webhookData = { identifier:'new-webhook-id', url:'https://user:pass@example.com/new-url' }; client.updateWebhook('my-webhook-id', webhookData, function(err, result) {/*...*/}); ``` [⤒](#index) ### Webhookを削除: (example-delete-webhook) ``` client.deleteWebhook('my-webhook-id', function(err, result) {/*...*/}); ``` [⤒](#index) # 参考: (refs) [Document - BLOCKTRAIL](https://www.blocktrail.com/api/docs/lang/nodejs) [⤒](#index)