mirror of
https://github.com/bitcoin-s/bitcoin-s.git
synced 2025-02-20 13:44:59 +01:00
Update website to 1.8 and bump various versions on README and node agent version (#3762)
This commit is contained in:
Chris Stewart
GitHub
parent
4f40d9522a
commit
be07786171
27 changed files with 3444 additions and 26 deletions
48
README.md
48
README.md
|
|
@ -1,5 +1,5 @@
|
|||
|
||||
[](https://github.com/bitcoin-s/bitcoin-s/actions) [](https://coveralls.io/github/bitcoin-s/bitcoin-s?branch=master) [](https://mvnrepository.com/artifact/org.bitcoin-s) [](https://gitter.im/bitcoin-s-core)
|
||||
[](https://github.com/bitcoin-s/bitcoin-s/actions) [](https://coveralls.io/github/bitcoin-s/bitcoin-s?branch=master) [](https://mvnrepository.com/artifact/org.bitcoin-s) [](https://gitter.im/bitcoin-s-core)
|
||||
|
||||
Feature-rich toolkit for making Bitcoin and Lightning applications on the JVM.
|
||||
|
||||
|
|
@ -55,52 +55,52 @@ This link is intended for setting up development of bitcoin-s. If you want to ju
|
|||
|
||||
### Adding bitcoin-s to your library
|
||||
|
||||
The latest release of bitcoin-s is `1.7.0`, here is how you can use the dependencies in your projects:
|
||||
The latest release of bitcoin-s is `1.8.0`, here is how you can use the dependencies in your projects:
|
||||
|
||||
```
|
||||
libraryDependencies += "org.bitcoin-s" % "bitcoin-s-secp256k1jni" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" % "bitcoin-s-secp256k1jni" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-core" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-core" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-crypto" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-crypto" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-chain" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-chain" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-dlc-oracle" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-dlc-oracle" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-oracle-explorer-client" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-oracle-explorer-client" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-app-commons" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-app-commons" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-db-commons" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-db-commons" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-fee-provider" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-fee-provider" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-bitcoind-rpc" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-bitcoind-rpc" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-eclair-rpc" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-eclair-rpc" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-lnd-rpc" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-lnd-rpc" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-key-manager" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-key-manager" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-node" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-node" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-dlc-node" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-dlc-node" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-wallet" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-wallet" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-dlc-wallet" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-dlc-wallet" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-testkit-core" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-testkit-core" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-testkit" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-testkit" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-zmq" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-zmq" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-tor" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-tor" % "1.8.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-cli" % "1.7.0"
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-cli" % "1.8.0"
|
||||
|
||||
```
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,5 @@
|
|||
package org.bitcoins.node.constant
|
||||
|
||||
case object NodeConstants {
|
||||
val userAgent = "/Bitcoin-S:1.7.0/"
|
||||
val userAgent = "/Bitcoin-S:1.8.0/"
|
||||
}
|
||||
|
|
|
|||
|
|
@ -23,7 +23,7 @@ import scala.util.Properties
|
|||
|
||||
object CommonSettings {
|
||||
|
||||
val previousStableVersion: String = "1.7.0"
|
||||
val previousStableVersion: String = "1.8.0"
|
||||
|
||||
private def isCI = {
|
||||
Properties
|
||||
|
|
|
|||
270
website/versioned_docs/version-1.8.0/applications/server.md
Normal file
270
website/versioned_docs/version-1.8.0/applications/server.md
Normal file
|
|
@ -0,0 +1,270 @@
|
|||
---
|
||||
id: version-1.8.0-server
|
||||
title: Application Server
|
||||
original_id: server
|
||||
---
|
||||
|
||||
|
||||
## App server
|
||||
|
||||
The server project is the aggregation of these three sub projects
|
||||
|
||||
1. [Wallet](../wallet/wallet.md)
|
||||
2. [Chain](../chain/chain.md)
|
||||
3. [Node](../node/node.md)
|
||||
|
||||
The server project provides a away to access information from these three projects via a JSON RPC.
|
||||
|
||||
## Building the server
|
||||
|
||||
### Java binary
|
||||
You can build the server with the [sbt native packager](https://github.com/sbt/sbt-native-packager).
|
||||
The native packager offers [numerous ways to package the project](https://github.com/sbt/sbt-native-packager#examples).
|
||||
|
||||
In this example we are going to use `stage` which will produce bash scripts we can easily execute. You can stage the server with the following command.
|
||||
|
||||
```bash
|
||||
sbt appServer/universal:stage
|
||||
```
|
||||
|
||||
This will produce a script to execute bitcoin-s which you can start with
|
||||
|
||||
```bash
|
||||
./app/server/target/universal/stage/bin/bitcoin-s-server
|
||||
```
|
||||
|
||||
### Docker
|
||||
|
||||
The oracle server also has docker support. You can build a docker image with the following commands
|
||||
|
||||
#### Using an existing docker image
|
||||
|
||||
We publish docker images on every PR that is merged to bitcoin-s.
|
||||
|
||||
You can find the docker repo for the app server [here](https://hub.docker.com/r/bitcoinscala/bitcoin-s-server/tags?page=1&ordering=last_updated)
|
||||
|
||||
#### Building a docker image
|
||||
```
|
||||
sbt "appServer/docker:stage"
|
||||
```
|
||||
|
||||
This will build a `Dockerfile` that is located in `app/server/target/docker/stage`
|
||||
|
||||
You can now build the docker image with
|
||||
|
||||
```
|
||||
docker build app/server/target/docker/stage/ -t bitcoin-s-server:latest
|
||||
```
|
||||
|
||||
Finally, let's run the image! It's important that you correctly configure port forwarding with the docker container so
|
||||
you can interact with the running container with `bitcoin-s-cli` or `curl`. By default, our oracle
|
||||
server listens for requests on port `9999`.
|
||||
|
||||
This means we need to forward requests on the host machine to the docker container correctly.
|
||||
|
||||
This can be done with the following command
|
||||
```
|
||||
docker run -d -p 9999:9999 bitcoin-s-server:latest
|
||||
```
|
||||
|
||||
Now you can send requests with `bitcoin-s-cli` or `curl`.
|
||||
Here is an example with `bitcoin-s-cli`
|
||||
```
|
||||
./bitcoin-s-cli getblockcount
|
||||
10000
|
||||
```
|
||||
|
||||
For more information on build configuration options with `sbt` please see the [sbt native packager docs](https://sbt-native-packager.readthedocs.io/en/latest/formats/docker.html#tasks)
|
||||
|
||||
## Configuration
|
||||
|
||||
### Java binary configuration
|
||||
If you would like to pass in a custom datadir for your server, you can do
|
||||
|
||||
```bash
|
||||
./app/server/target/universal/stage/bin/bitcoin-s-server --datadir /path/to/datadir/
|
||||
```
|
||||
|
||||
To use a config file that is not the `bitcoin-s.conf` file in your datadir, you can do
|
||||
|
||||
```bash
|
||||
./app/server/target/universal/stage/bin/bitcoin-s-server --conf /path/to/file.conf
|
||||
```
|
||||
|
||||
You can also pass in a custom `rpcport` to bind to
|
||||
|
||||
```bash
|
||||
./app/server/target/universal/stage/bin/bitcoin-s-server --rpcport 12345
|
||||
```
|
||||
|
||||
For more information on configuring the server please see our [configuration](../config/configuration.md) document
|
||||
|
||||
For more information on how to use our built in `cli` to interact with the server please see [cli.md](cli.md)
|
||||
|
||||
### Docker configuration
|
||||
|
||||
In this example, we are using the latest docker image published to our [docker hub](https://hub.docker.com/repository/docker/bitcoinscala/bitcoin-s-oracle-server/tags?page=1&ordering=last_updated)
|
||||
which is referenced by `bitcoinscala/bitcoin-s-server:latest`
|
||||
|
||||
You can use bitcoin-s with docker volumes. You can also pass in a custom configuration at container runtime.
|
||||
|
||||
#### Using a docker volume
|
||||
|
||||
```basrc
|
||||
docker volume create bitcoin-s
|
||||
docker run -p 9999:9999 \
|
||||
--mount source=bitcoin-s,target=/home/bitcoin-s/ bitcoinscala/bitcoin-s-server:latest
|
||||
```
|
||||
|
||||
Now you can re-use this volume across container runs. It will keep the same oracle database
|
||||
and seeds directory located at `/home/bitcoin-s/.bitcoin-s/seeds` in the volume.
|
||||
|
||||
#### Using a custom bitcoin-s configuration with docker
|
||||
|
||||
You can also specify a custom bitcoin-s configuration at container runtime.
|
||||
You can mount the configuration file on the docker container and that
|
||||
configuration will be used in the docker container runtime rather than
|
||||
the default one we provide [here](https://github.com/bitcoin-s/bitcoin-s/blob/master/app/oracle-server/src/universal/docker-application.conf)
|
||||
|
||||
You can do this with the following command
|
||||
|
||||
```bashrc
|
||||
docker run -p 9999:9999 \
|
||||
--mount type=bind,source=/my/new/config/,target=/home/bitcoin-s/.bitcoin-s/ \
|
||||
bitcoinscala/bitcoin-s-server:latest --conf /home/bitcoin-s/.bitcoin-s/bitcoin-s.conf
|
||||
```
|
||||
|
||||
Note: If you adjust the `bitcoin-s.server.rpcport` setting you will need to adjust
|
||||
the `-p 9999:9999` port mapping on the docker container to adjust for this.
|
||||
|
||||
## Server Endpoints
|
||||
|
||||
### Blockchain
|
||||
|
||||
- `getblockcount` - Get the current block height
|
||||
- `getfiltercount` - Get the number of filters
|
||||
- `getfilterheadercount` - Get the number of filter headers
|
||||
- `getbestblockhash` - Get the best block hash
|
||||
- `getblockheader` - Returns information about block header <hash>
|
||||
- `hash` - The block hash
|
||||
- `decoderawtransaction` `tx` - `Decode the given raw hex transaction`
|
||||
- `tx` - Transaction encoded in hex to decode
|
||||
|
||||
### Wallet
|
||||
- `rescan` `[options]` - Rescan for wallet UTXOs
|
||||
- `--force` - Clears existing wallet records. Warning! Use with caution!
|
||||
- `--batch-size <value>` - Number of filters that can be matched in one batch
|
||||
- `--start <value>` - Start height
|
||||
- `--end <value>` - End height
|
||||
- `--ignorecreationtime` - Ignores the wallet creation date and will instead do a full rescan
|
||||
- `isempty` - Checks if the wallet contains any data
|
||||
- `walletinfo` - Returns data about the current wallet being used
|
||||
- `getbalance` `[options]` - Get the wallet balance
|
||||
- `--sats ` - Display balance in satoshis
|
||||
- `getconfirmedbalance` `[options]` - Get the wallet balance of confirmed utxos
|
||||
- `--sats ` - Display balance in satoshis
|
||||
- `getunconfirmedbalance` `[options]` - Get the wallet balance of unconfirmed utxos
|
||||
- `--sats ` - Display balance in satoshis
|
||||
- `getbalances` `[options]` - Get the wallet balance by utxo state
|
||||
- `--sats ` - Display balance in satoshis
|
||||
- `getutxos` - Returns list of all wallet utxos
|
||||
- `getaddresses` - Returns list of all wallet addresses currently being watched
|
||||
- `getspentaddresses` - Returns list of all wallet addresses that have received funds and been spent
|
||||
- `getfundedaddresses` - Returns list of all wallet addresses that are holding funds
|
||||
- `getunusedaddresses` - Returns list of all wallet addresses that have not been used
|
||||
- `getaccounts` - Returns list of all wallet accounts
|
||||
- `walletinfo` - Returns meta information about the wallet
|
||||
- `createnewaccount` - Creates a new wallet account
|
||||
- `getaddressinfo` `address` - Returns list of all wallet accounts
|
||||
- `address` - Address to get information about
|
||||
- `getnewaddress` - Get a new address
|
||||
- `listreservedutxos` - lists all utxos that are reserved in the wallet
|
||||
- `sendtoaddress` `address` `amount` `[options]` - Send money to the given address
|
||||
- `address` - Address to send to
|
||||
- `amount` - Amount to send in BTC
|
||||
- `--feerate <value>` - Fee rate in sats per virtual byte
|
||||
- `sendfromoutpoints` `outpoints` `address` `amount` `[options]` - Send money to the given address
|
||||
- `outpoints` - Out Points to send from
|
||||
- `address` - Address to send to
|
||||
- `amount` - Amount to send in BTC
|
||||
- `--feerate <value>` - Fee rate in sats per virtual byte
|
||||
- `sweepwallet` `address` `[options]` - Sends the entire wallet balance to the given address
|
||||
- `address` - Address to send to
|
||||
- `--feerate <value>` - Fee rate in sats per virtual byte
|
||||
- `sendwithalgo` `address` `amount` `algo` `[options]` - Send money to the given address using a specific coin selection algo
|
||||
- `address` - Address to send to
|
||||
- `amount` - Amount to send in BTC
|
||||
- `algo` - Coin selection algo
|
||||
- `--feerate <value>` - Fee rate in sats per virtual byte
|
||||
- `signpsbt` `psbt` - Signs the PSBT's inputs with keys that are associated with the wallet
|
||||
- `psbt` - PSBT to sign
|
||||
- `opreturncommit` `message` `[options]` - Creates OP_RETURN commitment transaction
|
||||
- `message` - message to put into OP_RETURN commitment
|
||||
- `--hashMessage` - should the message be hashed before commitment
|
||||
- `--feerate <value>` - Fee rate in sats per virtual byte
|
||||
- `bumpfeecpfp` `txid` `feerate` - Bump the fee of the given transaction id with a child tx using the given fee rate
|
||||
- `txid` - Id of transaction to bump fee
|
||||
- `feerate` - Fee rate in sats per virtual byte of the child transaction
|
||||
- `bumpfeerbf` `txid` `feerate` - Replace given transaction with one with the new fee rate
|
||||
- `txid` - Id of transaction to bump fee
|
||||
- `feerate` - New fee rate in sats per virtual byte
|
||||
- `gettransaction` `txid` - Get detailed information about in-wallet transaction <txid>
|
||||
- `txid` - The transaction id
|
||||
- `lockunspent` `unlock` `transactions` - Temporarily lock (unlock=false) or unlock (unlock=true) specified transaction outputs.
|
||||
- `unlock` - Whether to unlock (true) or lock (false) the specified transactions
|
||||
- `transactions` - The transaction outpoints to unlock/lock, empty to apply to all utxos
|
||||
- `importseed` `walletname` `words` `passphrase` - Imports a mnemonic seed as a new seed file
|
||||
- `walletname` - Name to associate with this seed
|
||||
- `words` - Mnemonic seed words, space separated
|
||||
- `passphrase` - Passphrase to encrypt this seed with
|
||||
- `importxprv` `walletname` `xprv` `passphrase` - Imports a mnemonic seed as a new seed file
|
||||
- `walletname` - Name to associate with this seed
|
||||
- `xprv` - base58 encoded extended private key
|
||||
- `passphrase` - Passphrase to encrypt this seed with
|
||||
- `keymanagerpassphrasechange` `oldpassphrase` `newpassphrase` - Changes the wallet passphrase
|
||||
- `oldpassphrase` - The current passphrase
|
||||
- `newpassphrase` - The new passphrase
|
||||
- `keymanagerpassphraseset` `passphrase` - Encrypts the wallet with the given passphrase
|
||||
- `passphrase` - The passphrase to encrypt the wallet with
|
||||
|
||||
### Network
|
||||
- `getpeers` - List the connected peers
|
||||
- `stop` - Request a graceful shutdown of Bitcoin-S
|
||||
- `sendrawtransaction` `tx` `Broadcasts the raw transaction`
|
||||
- `tx` - Transaction serialized in hex
|
||||
|
||||
### PSBT
|
||||
- `decodepsbt` `psbt` - Return a JSON object representing the serialized, base64-encoded partially signed Bitcoin transaction.
|
||||
- `psbt` - PSBT serialized in hex or base64 format
|
||||
- `combinepsbts` `psbts` - Combines all the given PSBTs
|
||||
- `psbts` - PSBTs serialized in hex or base64 format
|
||||
- `joinpsbts` `psbts` - Combines all the given PSBTs
|
||||
- `psbts` - PSBTs serialized in hex or base64 format
|
||||
- `finalizepsbt` `psbt` - Finalizes the given PSBT if it can
|
||||
- `psbt` - PSBT serialized in hex or base64 format
|
||||
- `extractfrompsbt` `psbt` - Extracts a transaction from the given PSBT if it can
|
||||
- `psbt` - PSBT serialized in hex or base64 format
|
||||
- `converttopsbt` `unsignedTx` - Creates an empty psbt from the given transaction
|
||||
- `unsignedTx` - serialized unsigned transaction in hex
|
||||
|
||||
### Util
|
||||
- `createmultisig` `nrequired` `keys` `[address_type]` - Creates a multi-signature address with n signature of m keys required.
|
||||
- `nrequired` - The number of required signatures out of the n keys.
|
||||
- `keys` - The hex-encoded public keys.
|
||||
- `address_type` -The address type to use. Options are "legacy", "p2sh-segwit", and "bech32"
|
||||
- `estimatefee` - Returns the recommended fee rate using the fee provider
|
||||
|
||||
## Sign PSBT with Wallet Example
|
||||
|
||||
Bitcoin-S CLI:
|
||||
|
||||
```bash
|
||||
$ bitcoin-s-cli signpsbt cHNidP8BAP0FAQIAAAABWUWxYiPKgdGfXcIxJ6MRDxEpUecw59Gk4NpROI5oukoBAAAAAAAAAAAEPttkvdwAAAAXqRSOVAp6Qe/u2hq74e/ThB8foBKn7IfZYMgGCAAAAADbmaQ2nwAAAEdRIQLpfVqyaL9Jb/IkveatNyVeONE8Q/6TzXAWosxLo9e21SECc5G3XiK7xKLlkBG7prMx7p0fMeQwMH5e9H10mBon39JSrtgtgjjLAQAAUGMhAn2YaZnv25I6d6vbb1kw6Xp5IToDrEzl/0VBIW21gHrTZwXg5jGdALJ1IQKyNpDNiOiN6lWpYethib04+XC9bpFXrdpec+xO3U5IM2is9ckf5AABAD0CAAAAAALuiOL0rRcAABYAFPnpLByQq1Gg3vwiP6qR8FmOOjwxvVllM08DAAALBfXJH+QAsXUAAK4AAAAAAQcBAAAAAAAA
|
||||
cHNidP8BAP0FAQIAAAABWUWxYiPKgdGfXcIxJ6MRDxEpUecw59Gk4NpROI5oukoBAAAAAAAAAAAEPttkvdwAAAAXqRSOVAp6Qe/u2hq74e/ThB8foBKn7IfZYMgGCAAAAADbmaQ2nwAAAEdRIQLpfVqyaL9Jb/IkveatNyVeONE8Q/6TzXAWosxLo9e21SECc5G3XiK7xKLlkBG7prMx7p0fMeQwMH5e9H10mBon39JSrtgtgjjLAQAAUGMhAn2YaZnv25I6d6vbb1kw6Xp5IToDrEzl/0VBIW21gHrTZwXg5jGdALJ1IQKyNpDNiOiN6lWpYethib04+XC9bpFXrdpec+xO3U5IM2is9ckf5AABAD0CAAAAAALuiOL0rRcAABYAFPnpLByQq1Gg3vwiP6qR8FmOOjwxvVllM08DAAALBfXJH+QAsXUAAK4AAAAAAQcBAAAAAAAA
|
||||
```
|
||||
|
||||
CURL:
|
||||
```bash
|
||||
$ curl --data-binary '{"jsonrpc": "1.0", "id": "curltest", "method": "signpsbt", "params": ["cHNidP8BAP0FAQIAAAABWUWxYiPKgdGfXcIxJ6MRDxEpUecw59Gk4NpROI5oukoBAAAAAAAAAAAEPttkvdwAAAAXqRSOVAp6Qe/u2hq74e/ThB8foBKn7IfZYMgGCAAAAADbmaQ2nwAAAEdRIQLpfVqyaL9Jb/IkveatNyVeONE8Q/6TzXAWosxLo9e21SECc5G3XiK7xKLlkBG7prMx7p0fMeQwMH5e9H10mBon39JSrtgtgjjLAQAAUGMhAn2YaZnv25I6d6vbb1kw6Xp5IToDrEzl/0VBIW21gHrTZwXg5jGdALJ1IQKyNpDNiOiN6lWpYethib04+XC9bpFXrdpec+xO3U5IM2is9ckf5AABAD0CAAAAAALuiOL0rRcAABYAFPnpLByQq1Gg3vwiP6qR8FmOOjwxvVllM08DAAALBfXJH+QAsXUAAK4AAAAAAQcBAAAAAAAA"]}' -H "Content-Type: application/json" http://127.0.0.1:9999/
|
||||
{"result":"cHNidP8BAP0FAQIAAAABWUWxYiPKgdGfXcIxJ6MRDxEpUecw59Gk4NpROI5oukoBAAAAAAAAAAAEPttkvdwAAAAXqRSOVAp6Qe/u2hq74e/ThB8foBKn7IfZYMgGCAAAAADbmaQ2nwAAAEdRIQLpfVqyaL9Jb/IkveatNyVeONE8Q/6TzXAWosxLo9e21SECc5G3XiK7xKLlkBG7prMx7p0fMeQwMH5e9H10mBon39JSrtgtgjjLAQAAUGMhAn2YaZnv25I6d6vbb1kw6Xp5IToDrEzl/0VBIW21gHrTZwXg5jGdALJ1IQKyNpDNiOiN6lWpYethib04+XC9bpFXrdpec+xO3U5IM2is9ckf5AABAD0CAAAAAALuiOL0rRcAABYAFPnpLByQq1Gg3vwiP6qR8FmOOjwxvVllM08DAAALBfXJH+QAsXUAAK4AAAAAAQcBAAAAAAAA","error":null}
|
||||
```
|
||||
115
website/versioned_docs/version-1.8.0/chain/filter-sync.md
Normal file
115
website/versioned_docs/version-1.8.0/chain/filter-sync.md
Normal file
|
|
@ -0,0 +1,115 @@
|
|||
---
|
||||
title: Syncing Blockfilters
|
||||
id: version-1.8.0-filter-sync
|
||||
original_id: filter-sync
|
||||
---
|
||||
|
||||
The `chain` module has the ability to store [BIP157](https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki) block filters locally. Generally these filters are useful
|
||||
for doing wallet rescans. The idea is you can generate a list of script pubkeys you are interested in and see if
|
||||
the block filter matches the scriptPubKey.
|
||||
|
||||
As we demonstrated in [the chain docs](chain.md) with block headers, you can sync block filters from an external data source
|
||||
as well. We are going to use bitcoind as an example of an external data source to sync filters against. It is important
|
||||
that the bitcoind version you are using is >= `v19` as the [`getblockfilter`](https://github.com/bitcoin/bitcoin/blob/master/doc/release-notes/release-notes-0.19.0.1.md#new-rpcs)
|
||||
rpc is implemented there. You need to make sure bitcoind is started with the `-blockfilterindex` flag. This makes it
|
||||
so we can query filters.
|
||||
|
||||
> It is important to remember that you need fully synced block headers before you can sync filter headers and filters. Please see [the chain docs](chain.md) for syncing block headers.
|
||||
|
||||
#### Abstract idea of syncing filters.
|
||||
|
||||
Our internal infrastructure depends on one function to be implemented to be able to sync filters.
|
||||
|
||||
|
||||
```scala
|
||||
val getFilterFunc: BlockHeader => Future[FilterWithHeaderHash] = ???
|
||||
```
|
||||
|
||||
With `getFilterFunc` given a `BlockHeader` we can find it's associated `GolombFilter` -- which is our internal repesentation
|
||||
of a BIP157 block filter.
|
||||
|
||||
The basic idea for `FilterSync.syncFilters()` is to look at our current best block header inside of our `ChainApi.getBestBlockHeader()`
|
||||
and then check what our best block filter's block hash is with `ChainApi.getBestFilterHeader()`. If the blockfilter returned from our internal
|
||||
data store is NOT associated with our best block header, we attempt to sync our filter headers to catch up to our best block header.
|
||||
|
||||
### Syncing block filters against bitcoind
|
||||
|
||||
We are going to implement `getFilterFunc` with bitcoind and then sync a few filter headers.
|
||||
|
||||
```scala
|
||||
implicit val system = ActorSystem(s"filter-sync-example")
|
||||
implicit val ec = system.dispatcher
|
||||
implicit val chainAppConfig = BitcoinSTestAppConfig.getNeutrinoTestConfig(Vector.empty).chainConf
|
||||
|
||||
//let's use a helper method to get a v19 bitcoind
|
||||
//instance and a chainApi
|
||||
val bitcoindWithChainApiF: Future[BitcoindV19ChainHandler] = {
|
||||
ChainUnitTest.createBitcoindV19ChainHandler()
|
||||
}
|
||||
val bitcoindF = bitcoindWithChainApiF.map(_.bitcoindRpc)
|
||||
val chainApiF = bitcoindWithChainApiF.map(_.chainHandler)
|
||||
|
||||
val filterType = FilterType.Basic
|
||||
val addressF = bitcoindF.flatMap(_.getNewAddress)
|
||||
|
||||
//this is the function that we are going to use to sync
|
||||
//our internal filters against. We use this function to query
|
||||
//for each block filter associated with a blockheader
|
||||
val getFilterFunc: BlockHeader => Future[FilterWithHeaderHash] = { blockHeader =>
|
||||
val prevFilterResultF =
|
||||
bitcoindF.flatMap(_.getBlockFilter(blockHeader.hashBE, filterType))
|
||||
prevFilterResultF.map { filterResult =>
|
||||
FilterWithHeaderHash(filterResult.filter, filterResult.header)
|
||||
}
|
||||
}
|
||||
|
||||
//ok enough setup, let's generate a block that we need to sync the filter for in bitcoind
|
||||
val block1F = for {
|
||||
bitcoind <- bitcoindF
|
||||
address <- addressF
|
||||
hashes <- bitcoind.generateToAddress(1,address)
|
||||
} yield hashes
|
||||
|
||||
//to be able to sync filters, we need to make sure our block headers are synced first
|
||||
//so let's sync our block headers to our internal chainstate
|
||||
val chainApiSyncedHeadersF = for {
|
||||
bitcoind <- bitcoindF
|
||||
handler <- chainApiF
|
||||
getBestBlockHash = SyncUtil.getBestBlockHashFunc(bitcoind)
|
||||
getBlockHeader = SyncUtil.getBlockHeaderFunc(bitcoind)
|
||||
syncedChainApiHeaders <- ChainSync.sync(handler, getBlockHeader, getBestBlockHash)
|
||||
} yield syncedChainApiHeaders
|
||||
|
||||
//now that we have synced our 1 block header, we can now sync the 1 block filter
|
||||
//associated with that header.
|
||||
val chainApiSyncedFiltersF = for {
|
||||
syncedHeadersChainApi <- chainApiSyncedHeadersF
|
||||
syncedFilters <- FilterSync.syncFilters(syncedHeadersChainApi,getFilterFunc)
|
||||
} yield syncedFilters
|
||||
|
||||
//now we should have synced our one filter, let's make sure we have it
|
||||
val resultF = for {
|
||||
chainApi <- chainApiSyncedFiltersF
|
||||
filterHeaderCount <- chainApi.getFilterHeaderCount()
|
||||
filterCount <- chainApi.getFilterCount()
|
||||
} yield {
|
||||
println(s"filterHeaderCount=$filterHeaderCount filterCount=$filterCount")
|
||||
}
|
||||
|
||||
//cleanup
|
||||
resultF.onComplete { _ =>
|
||||
for {
|
||||
c <- bitcoindWithChainApiF
|
||||
_ <- ChainUnitTest.destroyBitcoindV19ChainApi(c)
|
||||
_ <- system.terminate()
|
||||
} yield ()
|
||||
}
|
||||
```
|
||||
|
||||
Yay! Now we have synced block filters from an external data source. If you want to repeatedly sync you can just call
|
||||
|
||||
`FilterSync.syncFilters(syncedFiltersChainApi,getFilterFunc)` every time you would like to sync.
|
||||
|
||||
Again, you need to ensure
|
||||
your headers are synced before you can sync filters, so make sure that you are calling `ChainSync.sync()` before syncing
|
||||
filters.
|
||||
454
website/versioned_docs/version-1.8.0/config/configuration.md
Normal file
454
website/versioned_docs/version-1.8.0/config/configuration.md
Normal file
|
|
@ -0,0 +1,454 @@
|
|||
---
|
||||
title: Application Configuration
|
||||
id: version-1.8.0-configuration
|
||||
original_id: configuration
|
||||
---
|
||||
|
||||
Bitcoin-S uses [HOCON](https://github.com/lightbend/config/blob/master/HOCON.md)
|
||||
to configure various parts of the application the library offers. HOCON is a superset of JSON, that is, all valid JSON
|
||||
is valid HOCON.
|
||||
|
||||
All configuration for Bitcoin-S is under the `bitcoin-s` key.
|
||||
|
||||
If you have a file `application.conf` anywhere on your classpath when using bitcoin-s, the values there take precedence
|
||||
over the ones found in our
|
||||
`reference.conf`. We also look for the file `bitcoin-s.conf` in the current Bitcoin-S data directory.
|
||||
|
||||
The resolved configuration gets parsed by
|
||||
[`AppConfig`](/api/org/bitcoins/db/AppConfig).
|
||||
`AppConfig` is an abstract class that's implemented by corresponding case classes in the `wallet`, `chain` and `node`
|
||||
projects. Here's some examples of how to construct a wallet configuration:
|
||||
|
||||
```scala
|
||||
import org.bitcoins.wallet.config.WalletAppConfig
|
||||
import com.typesafe.config.ConfigFactory
|
||||
import java.nio.file.Paths
|
||||
import scala.util.Properties
|
||||
import scala.concurrent.ExecutionContext.Implicits.global
|
||||
|
||||
// reads $HOME/.bitcoin-s/
|
||||
val defaultConfig = WalletAppConfig.fromDefaultDatadir()
|
||||
|
||||
|
||||
// reads a custom data directory
|
||||
val customDirectory = Paths.get(Properties.userHome, "custom-bitcoin-s-directory")
|
||||
val configFromCustomDatadir = WalletAppConfig(customDirectory)
|
||||
|
||||
// reads a custom data directory and overrides the network to be testnet3
|
||||
val customOverride = ConfigFactory.parseString("bitcoin-s.network = testnet3")
|
||||
val configFromCustomDirAndOverride = WalletAppConfig(customDirectory, customOverride)
|
||||
```
|
||||
|
||||
You can pass as many `com.typesafe.config.Config`s as you'd like. If any keys appear multiple times the last one
|
||||
encountered takes precedence.
|
||||
|
||||
## Command Line Options
|
||||
|
||||
There are a few command line options available that take precedence over configuration file.
|
||||
|
||||
- `--datadir <directory>`
|
||||
|
||||
`datadir` sets the data directory instead of using the default `$HOME/.bitcoin-s`
|
||||
|
||||
- `--rpcbind <ip>`
|
||||
|
||||
`rpcbind` sets the interface the rpc server binds to instead of using the default `127.0.0.1`
|
||||
|
||||
- `--rpcport <port>`
|
||||
|
||||
`rpcport` sets the port the rpc server binds to instead of using the default `9999`
|
||||
|
||||
- `--force-recalc-chainwork`
|
||||
|
||||
`force-recalc-chainwork` will force a recalculation of the entire chain's chain work, this can be useful if there is
|
||||
an incompatible migration or if it got out of sync.
|
||||
|
||||
- `-Dlogback.configurationFile=/path/to/config.xml`
|
||||
|
||||
You can set a custom logback configuration. If you need help creating a custom logback file you can
|
||||
read [the logback configuration documentation](http://logback.qos.ch/manual/configuration.html).
|
||||
|
||||
## Internal configuration
|
||||
|
||||
Database connections are also configured by using HOCON. This is done
|
||||
in [`reference.conf`](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/resources/reference.conf)
|
||||
inside the `db-commons` module. The options exposed here are **not** intended to be used by users of Bitcoin-S, and are
|
||||
internal only.
|
||||
|
||||
## Database Migrations
|
||||
|
||||
All of our modules that require databases now have database migrations. The tool we use for these migrations is
|
||||
called [flyway](https://flywaydb.org/). To find your projects migraitons, you need to look inside of the
|
||||
`[project-name]/src/main/resources/[database-name]/migration/`. For example, the chain projects migrations live under
|
||||
the path `chain/src/main/resources/chaindb/migration/V1__chain_db_baseline.sql`.
|
||||
|
||||
Migrations can be executed by calling
|
||||
the [`DbManagement.migrate()`](https://github.com/bitcoin-s/bitcoin-s/blob/e387d075b0ff2e0a0fec15788fcb48e4ddc4d9d5/db-commons/src/main/scala/org/bitcoins/db/DbManagement.scala#L92)
|
||||
method. Migrations are applied by default on server startup, via
|
||||
the [`AppConfig.start()`](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/scala/org/bitcoins/db/AppConfig.scala#L49)
|
||||
method.
|
||||
|
||||
These migrations are setup so that project's databases and migrations are independent of each other. Therefore if you
|
||||
want to use the `bitcoin-s-chain` project, but not the `bitcoin-s-wallet` project, wallet migrations are not applied. It
|
||||
should be noted if you are using a module as a library, you are responsible for configuring the database via
|
||||
[slick's configuration](https://scala-slick.org/doc/3.3.1/database.html#using-typesafe-config) and calling
|
||||
[`AppConfig.start()`](https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/scala/org/bitcoins/db/AppConfig.scala#L49)
|
||||
to ensure the entire module is initialized correctly.
|
||||
|
||||
## Example Configuration File
|
||||
|
||||
```$xslt
|
||||
bitcoin-s {
|
||||
datadir = ${HOME}/.bitcoin-s
|
||||
network = regtest # regtest, testnet3, mainnet, signet
|
||||
dbDefault = {
|
||||
dataSourceClass = slick.jdbc.DatabaseUrlDataSource
|
||||
profile = "slick.jdbc.SQLiteProfile$"
|
||||
|
||||
db {
|
||||
# for information on parameters available here see
|
||||
# https://scala-slick.org/doc/3.3.1/api/index.html#slick.jdbc.JdbcBackend$DatabaseFactoryDef@forConfig(String,Config,Driver,ClassLoader):Database
|
||||
path = ${bitcoin-s.datadir}/${bitcoin-s.network}/
|
||||
driver = org.sqlite.JDBC
|
||||
user = ""
|
||||
password = ""
|
||||
host = localhost
|
||||
port = 5432
|
||||
|
||||
# this needs to be set to 1 for SQLITE as it does not support concurrent database operations
|
||||
# see: https://github.com/bitcoin-s/bitcoin-s/pull/1840
|
||||
numThreads = 1
|
||||
queueSize=5000
|
||||
connectionPool = "HikariCP"
|
||||
registerMbeans = true
|
||||
}
|
||||
hikari-logging = false
|
||||
hikari-logging-interval = 10 minute
|
||||
}
|
||||
|
||||
bitcoind-rpc {
|
||||
# bitcoind rpc username
|
||||
rpcuser = user
|
||||
# bitcoind rpc password
|
||||
# If your password contains the characters '$','{', '}', '[', ']', ':', '=', ',', '+', '#', '`', '^', '?', '!', '@', '*', '&', whitespace
|
||||
# or the string "//", enclose it in double quotes
|
||||
# rpcpassword = "password=" if the original password is password=, rpcpassword = "passwo//rd" if the original password is passwo//rd etc.
|
||||
# If it contains '\' or '"', escape it with '\'
|
||||
# rpcpassword = "pass\\word" if the original password is pass\word, rpcpassword = "pass\"word" if the original password is pass"word
|
||||
rpcpassword = password
|
||||
|
||||
# Binary location of bitcoind
|
||||
binary = ${HOME}/.bitcoin-s/binaries/bitcoind/bitcoin-0.20.1/bin/bitcoind
|
||||
# bitcoind datadir
|
||||
datadir = ${HOME}/.bitcoin
|
||||
# bitcoind network binding
|
||||
bind = localhost
|
||||
# bitcoind p2p port
|
||||
port = 8333
|
||||
# bitcoind rpc binding
|
||||
rpcbind = localhost
|
||||
# bitcoind rpc port
|
||||
rpcport = 8332
|
||||
# bitcoind zmq raw tx
|
||||
zmqpubrawtx = "tcp://127.0.0.1:28332"
|
||||
# bitcoind zmq raw block
|
||||
zmqpubrawblock = "tcp://127.0.0.1:28333"
|
||||
# bitcoind zmq hash tx
|
||||
zmqpubhashtx = "tcp://127.0.0.1:28330"
|
||||
# bitcoind zmq raw block
|
||||
zmqpubhashblock = "tcp://127.0.0.1:28331"
|
||||
|
||||
#If you have a bitcoind instance that is running remotely on another machine, you should set it to true
|
||||
isRemote = false
|
||||
}
|
||||
|
||||
node {
|
||||
mode = neutrino # neutrino, spv, bitcoind
|
||||
|
||||
peers = [] # a list of peer addresses in form "hostname:portnumber"
|
||||
# (e.g. "neutrino.testnet3.suredbits.com:18333")
|
||||
# Port number is optional, the default value is 8333 for mainnet,
|
||||
# 18333 for testnet and 18444 for regtest.
|
||||
|
||||
hikari-logging = true
|
||||
hikari-logging-interval = 10 minute
|
||||
|
||||
# whether to have p2p peers relay us unconfirmed txs
|
||||
relay = false
|
||||
}
|
||||
|
||||
proxy {
|
||||
# You can configure SOCKS5 proxy to use Tor for outgoing connections
|
||||
enabled = false
|
||||
socks5 = "127.0.0.1:9050"
|
||||
}
|
||||
|
||||
tor {
|
||||
# You can enable Tor for incoming connections
|
||||
enabled = false
|
||||
control = "127.0.0.1:9051"
|
||||
|
||||
# Tor daemon can be provided by the node operator.
|
||||
# If this parameter set to true, bitcoin-s will connect the provided Tor daemon.
|
||||
# Otherwise bitcoin-s will start its own pre-packaged daemon.
|
||||
provided = false
|
||||
|
||||
# This parameter allows to use random port numbers for pre-packaged Tor daemon,
|
||||
# which is useful if another Tor daemon instance already bound SOCKS5 and control ports.
|
||||
# In this case bitcoin-s.tor.control and bitcoin-s.proxy.socks5
|
||||
# addresses will be automatically changed to "localhost:<random port>"
|
||||
use-random-ports = true
|
||||
|
||||
# The password used to arrive at the HashedControlPassword for the control port.
|
||||
# If provided, the HASHEDPASSWORD authentication method will be used instead of
|
||||
# the SAFECOOKIE one.
|
||||
# password = securePassword
|
||||
|
||||
# The path to the private key of the onion service being created
|
||||
# privateKeyPath = /path/to/priv/key
|
||||
}
|
||||
|
||||
chain {
|
||||
force-recalc-chainwork = false
|
||||
neutrino {
|
||||
filter-header-batch-size.default = 2000
|
||||
filter-header-batch-size.regtest = 10
|
||||
# You can set a network specific filter-header-batch-size
|
||||
# by adding a trailing `.networkId` (main, test, regtest)
|
||||
# It is recommended to keep the main and test batch size high
|
||||
# to keep the sync time fast, however, for regtest it should be small
|
||||
# so it does not exceed the chain size.
|
||||
|
||||
filter-batch-size = 1000
|
||||
}
|
||||
|
||||
hikari-logging = true
|
||||
hikari-logging-interval = 10 minute
|
||||
}
|
||||
|
||||
# settings for wallet module
|
||||
wallet {
|
||||
# You can have multiple wallets by setting a different
|
||||
# wallet name for each of them. They will each have
|
||||
# their own unique seed and database or schema,
|
||||
# depending on the database driver.
|
||||
# The wallet name can contain letters, numbers, and underscores '_'.
|
||||
# walletName = MyWallet0
|
||||
|
||||
defaultAccountType = segwit # legacy, segwit, nested-segwit
|
||||
|
||||
bloomFalsePositiveRate = 0.0001 # percentage
|
||||
|
||||
addressGapLimit = 20
|
||||
|
||||
discoveryBatchSize = 100
|
||||
|
||||
requiredConfirmations = 6
|
||||
|
||||
# How big the address queue size is before we throw an exception
|
||||
# because of an overflow
|
||||
addressQueueSize = 10
|
||||
|
||||
# How long we attempt to generate an address for
|
||||
# before we timeout
|
||||
addressQueueTimeout = 5 seconds
|
||||
|
||||
# How often the wallet will rebroadcast unconfirmed transactions
|
||||
rebroadcastFrequency = 4 hours
|
||||
|
||||
hikari-logging = true
|
||||
hikari-logging-interval = 10 minute
|
||||
}
|
||||
|
||||
keymanager {
|
||||
# You can optionally set a BIP 39 password
|
||||
# bip39password = "changeMe"
|
||||
|
||||
# Password that your seed is encrypted with
|
||||
aesPassword = changeMe
|
||||
}
|
||||
|
||||
# Bitcoin-S provides manny different fee providers
|
||||
# You can configure your server to use any of them
|
||||
# Below is some examples of different options
|
||||
fee-provider {
|
||||
# name = mempoolspace # Uses mempool.space's api
|
||||
# The target is optional for mempool.space
|
||||
# It refers to the expected number of blocks until confirmation
|
||||
# target = 6
|
||||
|
||||
# name = bitcoinerlive # Uses bitcoiner.live's api
|
||||
# The target is optional for Bitcoiner Live
|
||||
# It refers to the expected number of blocks until confirmation
|
||||
# target = 6
|
||||
|
||||
# name = bitgo # Uses BitGo's api
|
||||
# The target is optional for BitGo
|
||||
# It refers to the expected number of blocks until confirmation
|
||||
# target = 6
|
||||
|
||||
# name = constant # A constant fee rate in sats/vbyte
|
||||
# target = 1 # Will always use 1 sat/vbyte
|
||||
}
|
||||
|
||||
dlcnode {
|
||||
# The address we are listening on for incoming connections for DLCs
|
||||
# Binding to 0.0.0.0 makes us listen to all incoming connections
|
||||
listen = "0.0.0.0:2862"
|
||||
}
|
||||
|
||||
server {
|
||||
# The port we bind our rpc server on
|
||||
rpcport = 9999
|
||||
|
||||
# The ip address we bind our server too
|
||||
rpcbind = "127.0.0.1"
|
||||
}
|
||||
|
||||
oracle {
|
||||
# The port we bind our rpc server on
|
||||
rpcport = 9998
|
||||
|
||||
# The ip address we bind our server too
|
||||
rpcbind = "127.0.0.1"
|
||||
|
||||
hikari-logging = true
|
||||
hikari-logging-interval = 10 minute
|
||||
|
||||
db {
|
||||
path = ${bitcoin-s.datadir}/oracle/
|
||||
}
|
||||
}
|
||||
|
||||
testkit {
|
||||
pg {
|
||||
#enabled postgres backend database for all test cases
|
||||
enabled = false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
akka {
|
||||
loglevel = "OFF"
|
||||
stdout-loglevel = "OFF"
|
||||
http {
|
||||
client {
|
||||
# The time after which an idle connection will be automatically closed.
|
||||
# Set to `infinite` to completely disable idle connection timeouts.
|
||||
|
||||
# some requests potentially take a long time, like generate and prune
|
||||
idle-timeout = 5 minutes
|
||||
}
|
||||
|
||||
server {
|
||||
# The amount of time until a request times out on the server
|
||||
# If you have a large payload this may need to be bumped
|
||||
# https://doc.akka.io/docs/akka-http/current/common/timeouts.html#request-timeout
|
||||
request-timeout = 10s
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
actor {
|
||||
debug {
|
||||
# enable DEBUG logging of all AutoReceiveMessages (Kill, PoisonPill etc.)
|
||||
autoreceive= off
|
||||
# enable function of LoggingReceive, which is to log any received message at
|
||||
# DEBUG level
|
||||
receive = on
|
||||
# enable DEBUG logging of unhandled messages
|
||||
unhandled = off
|
||||
|
||||
# enable DEBUG logging of actor lifecycle changes
|
||||
lifecycle = off
|
||||
|
||||
event-stream=off
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Database configuration
|
||||
|
||||
By default, bitcoin-s uses Sqlite to store its data. It creates three Sqlite databases
|
||||
in `~/.bitcoin-s/${network}`: `chain.sqlite` for `chain` project,
|
||||
`node.sqlite` for `node` project and `wallet.sqlite` the wallet. This is the default configuration, it doesn't require
|
||||
additional changes in the config file.
|
||||
|
||||
`bitcoin-s` also supports PostgreSQL as a database backend. In order to use a PostgreSQL database for all project you
|
||||
need to add following into your config file:
|
||||
|
||||
```$xslt
|
||||
bitcoin-s {
|
||||
common {
|
||||
profile = "slick.jdbc.PostgresProfile$"
|
||||
db {
|
||||
driver = org.postgresql.Driver
|
||||
|
||||
# these 3 options will result into a jdbc url of
|
||||
# "jdbc:postgresql://localhost:5432/database"
|
||||
name = database
|
||||
host = localhost
|
||||
port = 5432
|
||||
|
||||
user = "user"
|
||||
password = "topsecret"
|
||||
numThreads = 5
|
||||
|
||||
# http://scala-slick.org/doc/3.3.3/database.html
|
||||
connectionPool = "HikariCP"
|
||||
registerMbeans = true
|
||||
}
|
||||
}
|
||||
|
||||
chain.profile = ${bitcoin-s.common.profile}
|
||||
chain.db = ${bitcoin-s.common.db}
|
||||
chain.db.poolName = "chain-connection-pool"
|
||||
|
||||
node.profile = ${bitcoin-s.common.profile}
|
||||
node.db = ${bitcoin-s.common.db}
|
||||
node.db.poolName = "node-connection-pool"
|
||||
|
||||
wallet.profile = ${bitcoin-s.common.profile}
|
||||
wallet.db = ${bitcoin-s.common.db}
|
||||
wallet.db.poolName = "wallet-connection-pool"
|
||||
|
||||
oracle.profile = ${bitcoin-s.common.profile}
|
||||
oracle.db = ${bitcoin-s.common.db}
|
||||
oracle.db.poolName = "oracle-connection-pool"
|
||||
}
|
||||
```
|
||||
|
||||
The database driver will create a separate SQL namespace for each sub-project: `chain`, `node` and `wallet`.
|
||||
|
||||
Also you can use mix databases and drivers in one configuration. For example, This configuration file enables Sqlite
|
||||
for `node` project (it's default, so its configuration is omitted), and `walletdb` and `chaindb` PostgreSQL databases
|
||||
for `wallet` and `chain` projects:
|
||||
|
||||
```$xslt
|
||||
bitcoin-s {
|
||||
chain {
|
||||
profile = "slick.jdbc.PostgresProfile$"
|
||||
db {
|
||||
driver = org.postgresql.Driver
|
||||
name = chaindb
|
||||
host = localhost
|
||||
port = 5432
|
||||
user = "user"
|
||||
password = "topsecret"
|
||||
}
|
||||
}
|
||||
wallet {
|
||||
profile = "slick.jdbc.PostgresProfile$"
|
||||
db {
|
||||
driver = org.postgresql.Driver
|
||||
name = walletdb
|
||||
host = localhost
|
||||
port = 5432
|
||||
user = "user"
|
||||
password = "topsecret"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
59
website/versioned_docs/version-1.8.0/core/addresses.md
Normal file
59
website/versioned_docs/version-1.8.0/core/addresses.md
Normal file
|
|
@ -0,0 +1,59 @@
|
|||
---
|
||||
id: version-1.8.0-addresses
|
||||
title: Generating Addresses
|
||||
original_id: addresses
|
||||
---
|
||||
|
||||
Almost all Bitcoin applications need to generate addresses
|
||||
for their users somehow. There's a lot going on in getting
|
||||
a correct bitcoin address, but our APIs make it possible to
|
||||
to get started with all types of addresses in a matter of
|
||||
minutes.
|
||||
|
||||
## Generating SegWit (bech32) addresses
|
||||
|
||||
Generating native SegWit addresses in the bech32 format
|
||||
is something that all Bitcoin applications should enable,
|
||||
as it makes the transaction fees less expensive, and also
|
||||
makes the addresses more readable by humans. However, it
|
||||
has seen slower than necessary adoption. With Bitcoin-S
|
||||
you can generate bech32 addresses in four(!) lines of code
|
||||
(not counting comments and imports), so now there's no
|
||||
reason to keep using legacy transaction formats.
|
||||
|
||||
|
||||
```scala
|
||||
// this generates a random private key
|
||||
val privkey = ECPrivateKey()
|
||||
// privkey: ECPrivateKey = Masked(ECPrivateKey)
|
||||
val pubkey = privkey.publicKey
|
||||
// pubkey: org.bitcoins.crypto.ECPublicKey = ECPublicKey(020da93f0234a254ea1a03c6b06e63c8f80ccc2b479822e60d0edfce39415332e5)
|
||||
|
||||
val segwitAddress = {
|
||||
// see https://bitcoin.org/en/glossary/pubkey-script
|
||||
// for reading resources on the details of scriptPubKeys
|
||||
// pay-to-witness-pubkey-hash scriptPubKey V0
|
||||
val scriptPubKey = P2WPKHWitnessSPKV0(pubkey)
|
||||
Bech32Address(scriptPubKey, TestNet3)
|
||||
}
|
||||
// segwitAddress: Bech32Address = tb1q5zftsyt25tfjhz3ydv5upas4jl7v2pyrt7ja4t
|
||||
|
||||
println(segwitAddress.toString)
|
||||
// tb1q5zftsyt25tfjhz3ydv5upas4jl7v2pyrt7ja4t
|
||||
```
|
||||
|
||||
## Generating legacy (base58) addresses
|
||||
|
||||
If you need to generate legacy addresses for backwards
|
||||
compatability reasons, that's also a walk in the park.
|
||||
Take a look:
|
||||
|
||||
```scala
|
||||
// we're reusing the same private/public key pair
|
||||
// from before. don't do this in an actual application!
|
||||
val legacyAddress = P2PKHAddress(pubkey, TestNet3)
|
||||
// legacyAddress: P2PKHAddress = mv9zAxoBHvG1Loa79XnwvNEmBxVkb4E1Cr
|
||||
|
||||
println(legacyAddress.toString)
|
||||
// mv9zAxoBHvG1Loa79XnwvNEmBxVkb4E1Cr
|
||||
```
|
||||
224
website/versioned_docs/version-1.8.0/core/dlc.md
Normal file
224
website/versioned_docs/version-1.8.0/core/dlc.md
Normal file
File diff suppressed because one or more lines are too long
145
website/versioned_docs/version-1.8.0/core/hd-keys.md
Normal file
145
website/versioned_docs/version-1.8.0/core/hd-keys.md
Normal file
|
|
@ -0,0 +1,145 @@
|
|||
---
|
||||
id: version-1.8.0-hd-keys
|
||||
title: HD Key Generation
|
||||
original_id: hd-keys
|
||||
---
|
||||
|
||||
In modern Bitcoin wallets, users only need to write down
|
||||
a sequence of words, and that sequence is a complete backup
|
||||
of their wallet. This is thanks to what's called Hierarchical
|
||||
Deterministic key generation. In short, every wallet using HD
|
||||
key generation has a root seed for each wallet, and this
|
||||
seed can be used to generate an arbitrary amount of later
|
||||
private and public keys. This is done in a standardized manner,
|
||||
so different wallets can operate with the same standard.
|
||||
|
||||
> If you want to jump into the details of how this work,
|
||||
> you should check out
|
||||
> [BIP 32](https://github.com/bitcoin/bips/blob/master/bip-0032.mediawiki).
|
||||
|
||||
Bitcoin-S supports generating keys in this fashion. Here's a
|
||||
full example of how to obtain a wallet seed, and then
|
||||
use that to generate further private and public keys:
|
||||
|
||||
```scala
|
||||
import scodec.bits._
|
||||
import org.bitcoins.core.crypto._
|
||||
import org.bitcoins.core.hd._
|
||||
|
||||
// the length of the entropy bit vector determine
|
||||
// how long our phrase ends up being
|
||||
// 256 bits of entropy results in 24 words
|
||||
val entropy: BitVector = MnemonicCode.getEntropy256Bits
|
||||
// entropy: BitVector = BitVector(256 bits, 0x102a49220ec3afbe50424890fa160dd1bf84514e458d1007f2ec82dd46e2d91d)
|
||||
|
||||
val mnemonicCode = MnemonicCode.fromEntropy(entropy)
|
||||
// mnemonicCode: MnemonicCode = Masked(MnemonicCodeImpl)
|
||||
|
||||
mnemonicCode.words // the phrase the user should write down
|
||||
// res0: Vector[String] = Vector(awake, false, embrace, budget, depend, tennis, donate, empower, movie, spawn, lock, pet, weapon, chunk, decorate, random, avoid, display, robot, aisle, stamp, imitate, good, prevent) // the phrase the user should write down
|
||||
|
||||
// the password argument is an optional, extra security
|
||||
// measure. all MnemonicCode instances will give you a
|
||||
// valid BIP39 seed, but different passwords will give
|
||||
// you different seeds. So you could have as many wallets
|
||||
// from the same seed as you'd like, by simply giving them
|
||||
// different passwords.
|
||||
val bip39Seed = BIP39Seed.fromMnemonic(mnemonicCode,
|
||||
password = "secret password")
|
||||
// bip39Seed: BIP39Seed = Masked(BIP39SeedImpl)
|
||||
|
||||
val xpriv = ExtPrivateKey.fromBIP39Seed(ExtKeyVersion.SegWitMainNetPriv,
|
||||
bip39Seed)
|
||||
// xpriv: ExtPrivateKey = Masked(ExtPrivateKeyImpl)
|
||||
val xpub = xpriv.extPublicKey
|
||||
// xpub: ExtPublicKey = zpub6jftahH18ngZwXWgKnZuhTPDTZmpnirTf8Egk51uGom33iFtJy8xkXjEeFvD1TdR4kWewyBqLMugDZyzerDn4Ukis2oY5UHLGanskzw7dma
|
||||
|
||||
// you can now use the generated xpriv to derive further
|
||||
// private or public keys
|
||||
|
||||
// this can be done with BIP89 paths (called SegWitHDPath in bitcoin-s)
|
||||
val segwitPath = SegWitHDPath.fromString("m/84'/0'/0'/0/0")
|
||||
// segwitPath: SegWitHDPath = m/84'/0'/0'/0/0
|
||||
|
||||
// alternatively:
|
||||
val otherSegwitPath =
|
||||
SegWitHDPath(HDCoinType.Bitcoin,
|
||||
accountIndex = 0,
|
||||
HDChainType.External,
|
||||
addressIndex = 0)
|
||||
// otherSegwitPath: SegWitHDPath = m/84'/0'/0'/0/0
|
||||
|
||||
segwitPath == otherSegwitPath
|
||||
// res1: Boolean = true
|
||||
```
|
||||
|
||||
## Generating new addresses without having access to the private key
|
||||
|
||||
One the coolest features of HD wallets is that it's possible
|
||||
to generate addresses offline, without having access to the
|
||||
private keys. This feature is commonly called watch-only
|
||||
wallets, where a wallet can import information about all
|
||||
your past and future transactions, without being able to
|
||||
spend or steal any of your money.
|
||||
|
||||
Let's see an example of this:
|
||||
|
||||
```scala
|
||||
import scala.util.Success
|
||||
import org.bitcoins.core.protocol.script._
|
||||
import org.bitcoins.core.protocol.Bech32Address
|
||||
import org.bitcoins.core.config.TestNet3
|
||||
|
||||
// first account -------┐
|
||||
// bitcoin ----------┐ |
|
||||
// segwit --------┐ | |
|
||||
val accountPath = BIP32Path.fromString("m/84'/0'/0'")
|
||||
// accountPath: BIP32Path = m/84'/0'/0'
|
||||
val accountXpub = {
|
||||
// this key is sensitive, keep away from prying eyes!
|
||||
val accountXpriv = xpriv.deriveChildPrivKey(accountPath)
|
||||
|
||||
// this key is not sufficient to spend from, but we
|
||||
// can generate addresses with it!
|
||||
accountXpriv.extPublicKey
|
||||
}
|
||||
// accountXpub: ExtPublicKey = zpub6qR7NyHhy8WjZ6a4iDoNfnGPMvs5qYNsSCEKYmM1x7SVwqp2wG46W9VzWnjkfiioHcdh74CUP9aF6wqhqguALVxGY3hXGnYUtyEFWSZTps9
|
||||
|
||||
// address no. 0 ---------------┐
|
||||
// external address ----------┐ |
|
||||
val firstAddressPath = SegWitHDPath.fromString("m/84'/0'/0'/0/0")
|
||||
// firstAddressPath: SegWitHDPath = m/84'/0'/0'/0/0
|
||||
val firstAccountAddress = {
|
||||
// this is a bit quirky, but we're not interesting in
|
||||
// deriving the complete path from our account xpub
|
||||
// instead, we're only interested in the part after
|
||||
// the account level (3rd level). the .diff() method
|
||||
// achieves that
|
||||
val Some(pathDiff) = accountPath.diff(firstAddressPath)
|
||||
|
||||
// deriving public keys from hardened extended keys
|
||||
// is not possible, that's why .deriveChildPubKey()
|
||||
// returns a Try[ExtPublicKey]. A hardened key is marked
|
||||
// by a ' after the number in the notation we use above.
|
||||
val Success(extPubKey) = accountXpub.deriveChildPubKey(pathDiff)
|
||||
val pubkey = extPubKey.key
|
||||
val scriptPubKey = P2WPKHWitnessSPKV0(pubkey)
|
||||
Bech32Address(scriptPubKey, TestNet3)
|
||||
}
|
||||
// firstAccountAddress: Bech32Address = tb1qlwuqstg4xxndk7d200e95x8hu5cg70ncmfqa60
|
||||
|
||||
// tada! We just generated an address you can send money to,
|
||||
// without having access to the private key!
|
||||
firstAccountAddress.value
|
||||
// res2: String = tb1qlwuqstg4xxndk7d200e95x8hu5cg70ncmfqa60
|
||||
|
||||
// you can now continue deriving addresses from the same public
|
||||
// key, by imitating what we did above. To get the next
|
||||
// HD path to generate an address at:
|
||||
val nextAddressPath: SegWitHDPath = firstAddressPath.next
|
||||
// nextAddressPath: SegWitHDPath = m/84'/0'/0'/0/1
|
||||
```
|
||||
|
||||
### Signing things with HD keys
|
||||
|
||||
Please see [sign.md](../crypto/sign.md) for information on how to sign things with HD keys.
|
||||
158
website/versioned_docs/version-1.8.0/core/txbuilder.md
Normal file
158
website/versioned_docs/version-1.8.0/core/txbuilder.md
Normal file
|
|
@ -0,0 +1,158 @@
|
|||
---
|
||||
id: version-1.8.0-txbuilder
|
||||
title: TxBuilder Example
|
||||
original_id: txbuilder
|
||||
---
|
||||
|
||||
Bitcoin-S features a transaction building API that allows you to construct and sign Bitcoin transactions. Here's an example of how to use it
|
||||
|
||||
|
||||
```scala
|
||||
implicit val ec: ExecutionContext = ExecutionContext.Implicits.global
|
||||
// ec: ExecutionContext = scala.concurrent.impl.ExecutionContextImpl$$anon$3@381c8be6[Running, parallelism = 8, size = 0, active = 0, running = 0, steals = 0, tasks = 0, submissions = 0]
|
||||
|
||||
// Initialize a transaction builder
|
||||
val builder = RawTxBuilder()
|
||||
// builder: RawTxBuilder = RawTxBuilder()
|
||||
|
||||
// generate a fresh private key that we are going to use in the scriptpubkey
|
||||
val privKey = ECPrivateKey.freshPrivateKey
|
||||
// privKey: ECPrivateKey = Masked(ECPrivateKey)
|
||||
val pubKey = privKey.publicKey
|
||||
// pubKey: ECPublicKey = ECPublicKey(02261c1ff1989748d9d27f26094e7a2aff6940013be8e470b096f6c57cd8236831)
|
||||
|
||||
// this is the script that the TxBuilder is going to create a
|
||||
// script signature that validly spends this scriptPubKey
|
||||
val creditingSpk = P2PKHScriptPubKey(pubKey = privKey.publicKey)
|
||||
// creditingSpk: P2PKHScriptPubKey = pkh(2c880c352e5b10e387055c19309f1534f2fc77af)
|
||||
val amount = 10000.satoshis
|
||||
// amount: Satoshis = 10000 sats
|
||||
|
||||
// this is the UTXO we are going to be spending
|
||||
val utxo =
|
||||
TransactionOutput(value = amount, scriptPubKey = creditingSpk)
|
||||
// utxo: TransactionOutput = TransactionOutput(10000 sats,pkh(2c880c352e5b10e387055c19309f1534f2fc77af))
|
||||
|
||||
// the private key that locks the funds for the script we are spending too
|
||||
val destinationPrivKey = ECPrivateKey.freshPrivateKey
|
||||
// destinationPrivKey: ECPrivateKey = Masked(ECPrivateKey)
|
||||
|
||||
// the amount we are sending -- 5000 satoshis -- to the destinationSPK
|
||||
val destinationAmount = 5000.satoshis
|
||||
// destinationAmount: Satoshis = 5000 sats
|
||||
|
||||
// the script that corresponds to destination private key, this is what is receiving the money
|
||||
val destinationSPK =
|
||||
P2PKHScriptPubKey(pubKey = destinationPrivKey.publicKey)
|
||||
// destinationSPK: P2PKHScriptPubKey = pkh(7455d9f20af11d6ee888f9509a0d52c647e16f84)
|
||||
|
||||
// this is where we are sending money too
|
||||
// we could add more destinations here if we
|
||||
// wanted to batch transactions
|
||||
val destinations = {
|
||||
val destination0 = TransactionOutput(value = destinationAmount,
|
||||
scriptPubKey = destinationSPK)
|
||||
|
||||
Vector(destination0)
|
||||
}
|
||||
// destinations: Vector[TransactionOutput] = Vector(TransactionOutput(5000 sats,pkh(7455d9f20af11d6ee888f9509a0d52c647e16f84)))
|
||||
|
||||
// Add the destinations to the tx builder
|
||||
builder ++= destinations
|
||||
// res0: RawTxBuilder = RawTxBuilder()
|
||||
|
||||
// we have to fabricate a transaction that contains the
|
||||
// UTXO we are trying to spend. If this were a real blockchain
|
||||
// we would need to reference the UTXO set
|
||||
val creditingTx = BaseTransaction(version = Int32.one,
|
||||
inputs = Vector.empty,
|
||||
outputs = Vector(utxo),
|
||||
lockTime = UInt32.zero)
|
||||
// creditingTx: BaseTransaction = BaseTransaction(Int32Impl(1),Vector(),Vector(TransactionOutput(10000 sats,pkh(2c880c352e5b10e387055c19309f1534f2fc77af))),UInt32Impl(0))
|
||||
|
||||
// this is the information we need from the crediting TX
|
||||
// to properly "link" it in the transaction we are creating
|
||||
val outPoint = TransactionOutPoint(creditingTx.txId, UInt32.zero)
|
||||
// outPoint: TransactionOutPoint = TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0)
|
||||
val input = TransactionInput(
|
||||
outPoint,
|
||||
EmptyScriptSignature,
|
||||
sequenceNumber = UInt32.zero)
|
||||
// input: TransactionInput = TransactionInputImpl(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),EmptyScriptSignature,UInt32Impl(0))
|
||||
|
||||
// Add a new input to our builder
|
||||
builder += input
|
||||
// res1: RawTxBuilder = RawTxBuilder()
|
||||
|
||||
// We can now generate a RawTxBuilderResult ready to be finalized
|
||||
val builderResult = builder.result()
|
||||
// builderResult: RawTxBuilderResult = RawTxBuilderResult(Int32Impl(2),Vector(TransactionInputImpl(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),EmptyScriptSignature,UInt32Impl(0))),Vector(TransactionOutput(5000 sats,pkh(7455d9f20af11d6ee888f9509a0d52c647e16f84))),UInt32Impl(0))
|
||||
|
||||
// this contains the information needed to analyze our input during finalization
|
||||
val inputInfo = P2PKHInputInfo(outPoint, amount, privKey.publicKey)
|
||||
// inputInfo: P2PKHInputInfo = P2PKHInputInfo(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),10000 sats,ECPublicKey(02261c1ff1989748d9d27f26094e7a2aff6940013be8e470b096f6c57cd8236831))
|
||||
|
||||
// this is how much we are going to pay as a fee to the network
|
||||
// for this example, we are going to pay 1 satoshi per byte
|
||||
val feeRate = SatoshisPerByte(1.satoshi)
|
||||
// feeRate: SatoshisPerByte = 1 sats/byte
|
||||
|
||||
val changePrivKey = ECPrivateKey.freshPrivateKey
|
||||
// changePrivKey: ECPrivateKey = Masked(ECPrivateKey)
|
||||
val changeSPK = P2PKHScriptPubKey(pubKey = changePrivKey.publicKey)
|
||||
// changeSPK: P2PKHScriptPubKey = pkh(f05a1269fb55b9da304f8e9a6a3c02eee359620b)
|
||||
|
||||
// We chose a finalizer that adds a change output to our tx based on a fee rate
|
||||
val finalizer = StandardNonInteractiveFinalizer(
|
||||
Vector(inputInfo),
|
||||
feeRate,
|
||||
changeSPK)
|
||||
// finalizer: StandardNonInteractiveFinalizer = StandardNonInteractiveFinalizer(Vector(P2PKHInputInfo(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),10000 sats,ECPublicKey(02261c1ff1989748d9d27f26094e7a2aff6940013be8e470b096f6c57cd8236831))),1 sats/byte,pkh(f05a1269fb55b9da304f8e9a6a3c02eee359620b))
|
||||
|
||||
// We can now finalize the tx builder result from earlier with this finalizer
|
||||
val unsignedTx: Transaction = finalizer.buildTx(builderResult)
|
||||
// unsignedTx: Transaction = BaseTransaction(Int32Impl(2),Vector(TransactionInputImpl(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),EmptyScriptSignature,UInt32Impl(0))),Vector(TransactionOutput(5000 sats,pkh(7455d9f20af11d6ee888f9509a0d52c647e16f84)), TransactionOutput(4775 sats,pkh(f05a1269fb55b9da304f8e9a6a3c02eee359620b))),UInt32Impl(0))
|
||||
|
||||
// We now turn to signing the unsigned transaction
|
||||
// this contains all the information we need to
|
||||
// validly sign the UTXO above
|
||||
val utxoInfo = ScriptSignatureParams(inputInfo = inputInfo,
|
||||
prevTransaction = creditingTx,
|
||||
signers = Vector(privKey),
|
||||
hashType =
|
||||
HashType.sigHashAll)
|
||||
// utxoInfo: ScriptSignatureParams[P2PKHInputInfo] = ScriptSignatureParams(P2PKHInputInfo(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),10000 sats,ECPublicKey(02261c1ff1989748d9d27f26094e7a2aff6940013be8e470b096f6c57cd8236831)),BaseTransaction(Int32Impl(1),Vector(),Vector(TransactionOutput(10000 sats,pkh(2c880c352e5b10e387055c19309f1534f2fc77af))),UInt32Impl(0)),Vector(Masked(ECPrivateKey)),SIGHASH_ALL(Int32Impl(1)))
|
||||
|
||||
// all of the UTXO spending information, since we only have
|
||||
// one input, this is just one element
|
||||
val utxoInfos: Vector[ScriptSignatureParams[InputInfo]] = Vector(utxoInfo)
|
||||
// utxoInfos: Vector[ScriptSignatureParams[InputInfo]] = Vector(ScriptSignatureParams(P2PKHInputInfo(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),10000 sats,ECPublicKey(02261c1ff1989748d9d27f26094e7a2aff6940013be8e470b096f6c57cd8236831)),BaseTransaction(Int32Impl(1),Vector(),Vector(TransactionOutput(10000 sats,pkh(2c880c352e5b10e387055c19309f1534f2fc77af))),UInt32Impl(0)),Vector(Masked(ECPrivateKey)),SIGHASH_ALL(Int32Impl(1))))
|
||||
|
||||
// Yay! Now we use the RawTxSigner object to sign the tx.
|
||||
// The 'sign' method is going produce a validly signed transaction
|
||||
// This is going to iterate through each of the UTXOs and use
|
||||
// the corresponding ScriptSignatureParams to produce a validly
|
||||
// signed input. This UTXO has:
|
||||
// 1: one input
|
||||
// 2: outputs (destination and change outputs)
|
||||
// 3: a fee rate of 1 satoshi/byte
|
||||
val signedTx: Transaction =
|
||||
RawTxSigner.sign(
|
||||
utx = unsignedTx,
|
||||
utxoInfos = utxoInfos,
|
||||
expectedFeeRate = feeRate
|
||||
)
|
||||
// signedTx: Transaction = BaseTransaction(Int32Impl(2),Vector(TransactionInputImpl(TransactionOutPoint(e44cf772914f525b7163e3a523dd3efa7d52a5d757aeb6adacd838d410f1ad93:0),P2PKHScriptSignature(ECPublicKeyBytes(ByteVector(33 bytes, 0x02261c1ff1989748d9d27f26094e7a2aff6940013be8e470b096f6c57cd8236831)), ECDigitalSignature(3044022014c360bbba112743031a01cbb4980f03c8e6e0c630cfb55d6ea933385b47b9660220412a91001d6b29c03042f9006e8f473b671b75883bb4061346e5ce6730fd6bbf01)),UInt32Impl(0))),Vector(TransactionOutput(5000 sats,pkh(7455d9f20af11d6ee888f9509a0d52c647e16f84)), TransactionOutput(4775 sats,pkh(f05a1269fb55b9da304f8e9a6a3c02eee359620b))),UInt32Impl(0))
|
||||
```
|
||||
|
||||
```scala
|
||||
signedTx.inputs.length
|
||||
// res2: Int = 1
|
||||
|
||||
signedTx.outputs.length
|
||||
// res3: Int = 2
|
||||
|
||||
//remember, you can call .hex on any bitcoin-s data structure to get the hex representation!
|
||||
signedTx.hex
|
||||
// res4: String = 020000000193adf110d438d8acadb6ae57d7a5527dfa3edd23a5e363715b524f9172f74ce4000000006a473044022014c360bbba112743031a01cbb4980f03c8e6e0c630cfb55d6ea933385b47b9660220412a91001d6b29c03042f9006e8f473b671b75883bb4061346e5ce6730fd6bbf012102261c1ff1989748d9d27f26094e7a2aff6940013be8e470b096f6c57cd8236831000000000288130000000000001976a9147455d9f20af11d6ee888f9509a0d52c647e16f8488aca7120000000000001976a914f05a1269fb55b9da304f8e9a6a3c02eee359620b88ac00000000
|
||||
```
|
||||
65
website/versioned_docs/version-1.8.0/crypto/sign.md
Normal file
65
website/versioned_docs/version-1.8.0/crypto/sign.md
Normal file
|
|
@ -0,0 +1,65 @@
|
|||
---
|
||||
id: version-1.8.0-sign
|
||||
title: Sign API
|
||||
original_id: sign
|
||||
---
|
||||
|
||||
### The [`Sign` API](/api/org/bitcoins/crypto/Sign)
|
||||
|
||||
This is the API we define to sign things with. It takes in an arbitrary byte vector and returns a `Future[ECDigitalSignature]`. The reason we incorporate `Future`s here is for extensibility of this API. We would like to provide implementations of this API for hardware devices, which need to be asynchrnous since they may require user input.
|
||||
|
||||
From [Sign.scala](/api/org/bitcoins/crypto/Sign):
|
||||
|
||||
```scala
|
||||
import scodec.bits._
|
||||
import org.bitcoins.crypto._
|
||||
import scala.concurrent._
|
||||
import scala.concurrent.duration._
|
||||
|
||||
trait Sign {
|
||||
def signFunction: ByteVector => Future[ECDigitalSignature]
|
||||
|
||||
def signFuture(bytes: ByteVector): Future[ECDigitalSignature] =
|
||||
signFunction(bytes)
|
||||
|
||||
def sign(bytes: ByteVector): ECDigitalSignature = {
|
||||
Await.result(signFuture(bytes), 30.seconds)
|
||||
}
|
||||
|
||||
def publicKey: ECPublicKey
|
||||
}
|
||||
```
|
||||
|
||||
The `ByteVector` that is input to the `signFunction` should be the hash that is output from [`TransactionSignatureSerializer`](/api/org/bitcoins/core/crypto/TransactionSignatureSerializer)'s `hashForSignature` method. Our in-memory [`BaseECKey`](/api/org/bitcoins/crypto/BaseECKey) types implement the `Sign` API.
|
||||
|
||||
If you wanted to implement a new `Sign` api for a hardware wallet, you can easily pass it into the `TxBuilder`/`Signer` classes to allow for you to use those devices to sign with Bitcoin-S.
|
||||
|
||||
This API is currently used to sign ordinary transactions with our [`Signer`](/api/org/bitcoins/core/wallet/signer/Signer)s. The `Signer` subtypes (i.e. `P2PKHSigner`) implement the specific functionality needed to produce a valid digital signature for their corresponding script type.
|
||||
|
||||
|
||||
### The [`ExtSign`](/api/org/bitcoins/crypto/Sign) API.
|
||||
|
||||
An [ExtKey](/api/org/bitcoins/core/crypto/ExtKey) is a data structure that can be used to generate more keys from a parent key. For more information look at [hd-keys.md](../core/hd-keys.md)
|
||||
|
||||
You can sign with `ExtPrivateKey` the same way you could with a normal `ECPrivateKey`.
|
||||
|
||||
```scala
|
||||
import org.bitcoins.core.hd._
|
||||
import org.bitcoins.core.crypto._
|
||||
|
||||
val extPrivKey = ExtPrivateKey(ExtKeyVersion.SegWitMainNetPriv)
|
||||
// extPrivKey: ExtPrivateKey = Masked(ExtPrivateKeyImpl)
|
||||
|
||||
extPrivKey.sign(DoubleSha256Digest.empty.bytes)
|
||||
// res0: ECDigitalSignature = ECDigitalSignature(304402200d093e8d339ebd7e340d4509b4fd7e53da75928644d40e681f0ec9e1b3fe5a3b0220208f9c8e6e403a95c26cca66823f2739cfbe1d9b5ab15ce39d23fd8635f0fd1b)
|
||||
|
||||
val path = BIP32Path(Vector(BIP32Node(0,false)))
|
||||
// path: BIP32Path = m/0
|
||||
|
||||
extPrivKey.sign(DoubleSha256Digest.empty.bytes,path)
|
||||
// res1: ECDigitalSignature = ECDigitalSignature(3044022050641ec9e6ac14017cb8c812e83e48ee6bb1862215f06ac9a88399be490dcdcc02203202049ce78e8965964d315024d97f6df41a066930cf024379fd5bfc7cc5c0ed)
|
||||
```
|
||||
|
||||
With `ExtSign`, you can use `ExtPrivateKey` to sign transactions inside of `TxBuilder` since `UTXOSpendingInfo` takes in `Sign` as a parameter.
|
||||
|
||||
You can also provide a `path` to use to derive a child `ExtPrivateKey`, and then sign with that child private key
|
||||
207
website/versioned_docs/version-1.8.0/getting-setup.md
Normal file
207
website/versioned_docs/version-1.8.0/getting-setup.md
Normal file
|
|
@ -0,0 +1,207 @@
|
|||
---
|
||||
id: version-1.8.0-getting-setup
|
||||
title: Getting Bitcoin-S installed on your machine
|
||||
original_id: getting-setup
|
||||
---
|
||||
|
||||
> This documentation is intended for setting up development of bitcoin-s.
|
||||
> If you want to just install bitcoin-s rather than develop,
|
||||
> see [getting-started](getting-started.md)
|
||||
|
||||
## Getting Setup With Bitcoin-S
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
<!-- END doctoc -->
|
||||
|
||||
- [Step 1: Developer Runtimes](#step-1--developer-runtimes)
|
||||
* [Scala/Java](#scala-java)
|
||||
* [Scala.js](#scalajs)
|
||||
- [Step 2: Bitcoin-S Repository](#step-2--bitcoin-s-repository)
|
||||
+ [Optional: Running full test suite](#optional--running-full-test-suite)
|
||||
- [Step 3: Configuration](#step-3--configuration)
|
||||
- [Step 4: Building the Server and Setting Up the CLI](#step-4--building-the-server-and-setting-up-the-cli)
|
||||
- [Step 5: Setting Up A Bitcoin-S Node](#step-5--setting-up-a-bitcoin-s-node)
|
||||
* [Neutrino Node](#neutrino-node)
|
||||
* [Bitcoind Backend](#bitcoind-backend)
|
||||
- [Step 6 (Optional): Moving To Testnet](#step-6--optional---moving-to-testnet)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
|
||||
## Step 1: Developer Runtimes
|
||||
|
||||
### Scala/Java
|
||||
To get started you will need Java, Scala, and some other nice tools installed, luckily the Scala team has an easy setup process!
|
||||
|
||||
Simply follow the instructions in [this short blog](https://www.scala-lang.org/2020/06/29/one-click-install.html) to get started.
|
||||
|
||||
If you don't like `curl`, you can use OS specific package managers to install coursier [here](https://get-coursier.io/docs/2.0.0-RC2/cli-overview.html#installation)
|
||||
|
||||
>bitcoin-s requires java9+ for development environments. If you do not have java9+ installed, you will not be able to build bitcoin-s.
|
||||
[You will run into this error if you are on java8 or lower](https://github.com/bitcoin-s/bitcoin-s/issues/3298)
|
||||
|
||||
If you follow the coursier route, [you can switch to a java11 version by running](https://get-coursier.io/docs/2.0.0-RC6-15/cli-java.html)
|
||||
|
||||
>cs java --jvm adopt:11 --setup
|
||||
|
||||
### Scala.js
|
||||
|
||||
We support publishing of [scala.js](https://www.scala-js.org/) artifacts.
|
||||
This library will compile Scala source code into javascript artifacts.
|
||||
|
||||
To be able to run scala js tests, you need to have the Node.js installed.
|
||||
You can install it from [here](https://nodejs.org/en/)
|
||||
|
||||
## Step 2: Bitcoin-S Repository
|
||||
|
||||
Now, it is time to clone the [Bitcoin-S repository](https://github.com/bitcoin-s/bitcoin-s/) by running
|
||||
|
||||
```bashrc
|
||||
git clone --depth 500 --recursive git@github.com:bitcoin-s/bitcoin-s.git
|
||||
```
|
||||
|
||||
or alternatively, if you do not have ssh setup with github, you can run
|
||||
|
||||
```bashrc
|
||||
git clone --depth 500 --recursive https://github.com/bitcoin-s/bitcoin-s.git
|
||||
```
|
||||
|
||||
|
||||
#### Optional: Running full test suite
|
||||
<details>
|
||||
> WARNING: This should not be done on low resource machines. Running the entire test suite requires at minimum of 4GB
|
||||
> of RAM on the machine you are running this on.
|
||||
|
||||
To run the entire test suite, you need to download all bitcoind instances and eclair instances. This is needed for unit tests
|
||||
or binding bitcoin-s to a bitcoind instance if you do not have locally running instances.
|
||||
|
||||
```bashrc
|
||||
sbt downloadBitcoind
|
||||
sbt downloadEclair
|
||||
```
|
||||
|
||||
If you want to run the entire test suite you can run the following command after you download bitcoind
|
||||
and eclair.
|
||||
|
||||
```bashrc
|
||||
sbt test
|
||||
```
|
||||
</details>
|
||||
|
||||
|
||||
## Step 3: Configuration
|
||||
|
||||
Now that we have the bitcoin-s repo setup, we want to create our application configurations.
|
||||
|
||||
First, create a `$HOME/.bitcoin-s` directory via `mkdir` or an equivalent command.
|
||||
|
||||
Next, create a `bitcoin-s.conf` file in `$HOME/.bitcoin-s`. [Here is an example configuration file](config/configuration.md#example-configuration-file). The only thing that you will _need_ to change is the `peers` list to which you will want to add `"localhost:18444"` if you want to run in regtest.
|
||||
|
||||
## Step 4: Building the Server and Setting Up the CLI
|
||||
|
||||
We are finally ready to start running some programs! Follow the [instructions here](applications/server.md#building-the-server) to build the server.
|
||||
|
||||
Then, follow [these instructions](applications/cli.md) to setup the CLI.
|
||||
|
||||
## Step 5: Setting Up A Bitcoin-S Node
|
||||
|
||||
There are 2 ways to use the bitcoin-s server. It can either be as a neutrino node or use bitcoind as a backend.
|
||||
This can be configured by the configuration option `bitcoin-s.node.mode` choosing either `neutrino` or `bitcoind`.
|
||||
|
||||
### Neutrino Node
|
||||
|
||||
<details>
|
||||
To use a neutrino server you need to be paired with a bitcoin node that can serve compact filters.
|
||||
[Suredbits](https://suredbits.com/) runs a mainnet and testnet node you can connect to them by setting your `peers` config option in the `$HOME/.bitcoin-s/bitcoin-s.conf` to:
|
||||
|
||||
Mainnet:
|
||||
|
||||
`bitcoin-s.node.peers = ["neutrino.suredbits.com:8333"]`
|
||||
|
||||
Testnet:
|
||||
|
||||
`bitcoin-s.node.peers = ["neutrino.testnet3.suredbits.com:18333"]`
|
||||
|
||||
If you would like to use your own node you can either use the bitcoind backend option or connect to your own compatible node.
|
||||
There is no released version of bitcoind that is neutrino compatible, so you will either have to compile the latest `master` yourself, or use the experimental version provided by running `sbt downloadBitcoind`.
|
||||
|
||||
After building your bitcoin-s server, properly configuring it to be in `neutrino` mode you can start your server with:
|
||||
|
||||
```bashrc
|
||||
./app/server/target/universal/stage/bin/bitcoin-s-server
|
||||
```
|
||||
|
||||
and once this is done, you should be able to communicate with the server using
|
||||
|
||||
```bashrc
|
||||
./app/cli/target/universal/stage/bin/bitcoin-s-cli getnewaddress
|
||||
```
|
||||
</details>
|
||||
|
||||
### Bitcoind Backend
|
||||
|
||||
<details>
|
||||
We recommend creating a directory someplace in which to run your `bitcoind` node. Once you have this directory created, add the following `bitcoin.conf` file to it:
|
||||
|
||||
```
|
||||
regtest=1
|
||||
server=1
|
||||
rpcuser=[your username here]
|
||||
rpcpassword=[your password here]
|
||||
daemon=1
|
||||
blockfilterindex=1
|
||||
peerblockfilters=1
|
||||
debug=1
|
||||
txindex=1
|
||||
```
|
||||
|
||||
If you already have a bitcoind node running and would like to connect your bitcoin-s server to it you can set your node's mode to `bitcoind`.
|
||||
|
||||
You will need to configure bitcoin-s to be able to find your bitcoind.
|
||||
If you would only like bitcoin-s to connect to bitcoind and start it itself then you only need to properly set the `rpcuser`, and `rpcpassword` options.
|
||||
If you would like bitcoin-s to launch bitcoind on start up you will need to set the other configuration options.
|
||||
These options should default to use the latest bitcoind downloaded from `sbt downloadBitcoind`.
|
||||
|
||||
```$xslt
|
||||
bitcoin-s {
|
||||
bitcoind-rpc {
|
||||
# bitcoind rpc username
|
||||
rpcuser = user
|
||||
# bitcoind rpc password
|
||||
rpcpassword = password
|
||||
|
||||
# Binary location of bitcoind
|
||||
binary = ${HOME}/.bitcoin-s/binaries/bitcoind/bitcoin-0.20.1/bin/bitcoind
|
||||
# bitcoind datadir
|
||||
datadir = ${HOME}/.bitcoin
|
||||
# bitcoind network binding
|
||||
bind = localhost
|
||||
# bitcoind p2p port
|
||||
port = 8333
|
||||
# bitcoind rpc binding
|
||||
rpcbind = localhost
|
||||
# bitcoind rpc port
|
||||
rpcport = 8332
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
## Step 6 (Optional): Moving To Testnet
|
||||
|
||||
To run your Bitcoin-S Server on testnet, simply change `network = testnet3` and change
|
||||
your `peers = ["neutrino.testnet3.suredbits.com:18333"] ` in your `.bitcoin-s/bitcoin-s.conf` file.
|
||||
This will allow you to connect to Suredbits' neutrino-enabled `bitcoind` node.
|
||||
Keep in mind then when you restart your server, it will begin initial sync which will take
|
||||
many hours as all block filters for all testnet blocks will be downloaded.
|
||||
If you wish to speed this process up,
|
||||
download [this snapshot](https://s3-us-west-2.amazonaws.com/www.suredbits.com/chaindb-testnet-2021-02-03.zip), unzip it and put the file in your `$HOME/.bitcoin-s/testnet3` directory and then from there, run
|
||||
|
||||
```bashrc
|
||||
$ unzip chaindb-testnet-2021-02-03.zip
|
||||
$ mv chaindb.sqlite ~/.bitcoin-s/testnet/
|
||||
```
|
||||
|
||||
This should take a couple minutes to execute, but once it is done, you will only have a short while left to sync once you start your server.
|
||||
127
website/versioned_docs/version-1.8.0/getting-started.md
Normal file
127
website/versioned_docs/version-1.8.0/getting-started.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
id: version-1.8.0-getting-started
|
||||
title: Intro and Getting Started
|
||||
original_id: getting-started
|
||||
---
|
||||
|
||||
## Philosophy
|
||||
|
||||
Bitcoin-S is a loosely coupled set of cryptocurrency libraries for the JVM. They work well together, but also can be used
|
||||
independently. This project's goal is NOT to be a full node implementation, rather a set of scalable cryptocurrency libraries
|
||||
that use industry standard tools (rather than esoteric tech often found in cryptocurrency) where possible to make the lives of professional
|
||||
software engineers, security engineers, devops engineers and accountants easier.
|
||||
We are rapidly iterating on development with the goal of getting to a set of stable APIs that only change when the underlying bitcoin protocol changes.
|
||||
|
||||
If you are a professional working a cryptocurrency business and
|
||||
have feedback on how to make your lives easier, please reach out on [slack](https://join.slack.com/t/suredbits/shared_invite/zt-eavycu0x-WQL7XOakzQo8tAy7jHHZUw),
|
||||
[gitter](https://gitter.im/bitcoin-s-core/) or [twitter](https://twitter.com/Chris_Stewart_5/)!
|
||||
|
||||
## Getting prebuilt artifacts
|
||||
|
||||
### Java binaries
|
||||
|
||||
<details>
|
||||
|
||||
#### Latest release
|
||||
|
||||
Please see the release page on github, you can find it [here](https://github.com/bitcoin-s/bitcoin-s/releases)
|
||||
|
||||
#### Master builds
|
||||
|
||||
We build installers for mac, linux and windows everytime a PR is merged to master.
|
||||
|
||||
You can find the latest builds at this link:
|
||||
|
||||
https://github.com/bitcoin-s/bitcoin-s/actions/workflows/release.yml
|
||||
|
||||
Here is what the installers look like
|
||||
|
||||
|
||||
|
||||
</details>
|
||||
|
||||
### Docker
|
||||
|
||||
<details>
|
||||
We publish docker images to docker hub on every PR merge and tag on github.
|
||||
You can obtain the images for both the app server and oracle server on these
|
||||
docker hub repos
|
||||
|
||||
[bitcoin-s-server docker hub repo](https://hub.docker.com/r/bitcoinscala/bitcoin-s-server/tags?page=1&ordering=last_updated)
|
||||
|
||||
[bitcoin-s-oracle-server docker hub repo](https://hub.docker.com/r/bitcoinscala/bitcoin-s-oracle-server/tags?page=1&ordering=last_updated)
|
||||
</details>
|
||||
|
||||
### Library jars
|
||||
|
||||
<details>
|
||||
Add this to your `build.sbt`:
|
||||
|
||||
```scala
|
||||
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-bitcoind-rpc" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-core" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-chain" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-dlc-oracle" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-eclair-rpc" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-fee-provider" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-key-manager" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-lnd-rpc" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-node" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-oracle-explorer-client" % "1.7.0"
|
||||
|
||||
libraryDependencies +="org.bitcoin-s" % "bitcoin-s-secp256k1jni" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-testkit-core" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-testkit" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-wallet" % "1.7.0"
|
||||
|
||||
libraryDependencies += "org.bitcoin-s" %% "bitcoin-s-zmq" % "1.7.0"
|
||||
|
||||
```
|
||||
|
||||
|
||||
### Nightly builds
|
||||
|
||||
You can also run on the bleeding edge of Bitcoin-S, by
|
||||
adding a snapshot build to your `build.sbt`. The most
|
||||
recent snapshot published is `1.7.0-156-4d6c4c7b-20210905-1056-SNAPSHOT`.
|
||||
|
||||
|
||||
|
||||
To fetch snapshots, you will need to add the correct
|
||||
resolver in your `build.sbt`:
|
||||
|
||||
```sbt
|
||||
resolvers += Resolver.sonatypeRepo("snapshots")
|
||||
```
|
||||
|
||||
The official maven repo for releases is
|
||||
|
||||
https://repo1.maven.org/maven2/org/bitcoin-s/
|
||||
|
||||
The repo for snapshots, which are published after everytime something is merged to master:
|
||||
|
||||
https://oss.sonatype.org/content/repositories/snapshots/org/bitcoin-s/
|
||||
|
||||
</details>
|
||||
|
||||
## Building JARs yourself
|
||||
|
||||
Please see [our setup docs](getting-setup.md)
|
||||
|
||||
## If you want to setup Bitcoin-S locally for development
|
||||
|
||||
Please see [our setup docs](getting-setup.md)
|
||||
124
website/versioned_docs/version-1.8.0/key-manager/key-manager.md
Normal file
124
website/versioned_docs/version-1.8.0/key-manager/key-manager.md
Normal file
|
|
@ -0,0 +1,124 @@
|
|||
---
|
||||
id: version-1.8.0-key-manager
|
||||
title: Key Manager
|
||||
original_id: key-manager
|
||||
---
|
||||
|
||||
|
||||
### Key Manager
|
||||
|
||||
The key manager module's goal is to encapsulate all private key interactions with the [wallet](../wallet/wallet.md) project.
|
||||
|
||||
As of this writing, there is only one type of `KeyManager` - [`BIP39KeyManager`](/api/org/bitcoins/keymanager/bip39/BIP39KeyManager).
|
||||
|
||||
The [`BIP39KeyManager`](/api/org/bitcoins/keymanager/bip39/BIP39KeyManager) stores a [`MnemonicCode`](/api/org/bitcoins/core/crypto/MnemonicCode) on disk which can be decrypted and used as a hot wallet.
|
||||
|
||||
Over the long run, we want to make it so that the wallet project needs to communicate with the key-manager to access private keys.
|
||||
|
||||
This means that ALL SIGNING should be done inside of the key-manager, and private keys should not leave the key manager.
|
||||
|
||||
This makes it easier to reason about the security characteristics of our private keys, and a way to provide a uniform interface for alternative key storage systems (hsm, cloud based key storage, etc) to be plugged into the bitcoin-s library.
|
||||
|
||||
#### Creating a key manager
|
||||
|
||||
The first thing you need create a key manager is some entropy.
|
||||
|
||||
A popular way for bitcoin wallet's to represent entropy is [BIP39](https://github.com/bitcoin/bips/blob/master/bip-0039.mediawiki) which you [can use in bitcoin-s](/api/org/bitcoins/core/crypto/BIP39Seed)
|
||||
|
||||
You can generate a `MnemonicCode` in bitcoin-s with the following code
|
||||
|
||||
```scala
|
||||
import org.bitcoins.core.crypto._
|
||||
|
||||
//get 256 bits of random entropy
|
||||
val entropy = MnemonicCode.getEntropy256Bits
|
||||
// entropy: scodec.bits.BitVector = BitVector(256 bits, 0xcb635b5bc8413aa3e1bfdb2767d3642c915b5c39af0cb5cfd69b9cb1d92cb009)
|
||||
|
||||
val mnemonic = MnemonicCode.fromEntropy(entropy)
|
||||
// mnemonic: MnemonicCode = Masked(MnemonicCodeImpl)
|
||||
|
||||
//you can print that mnemonic seed with this
|
||||
println(mnemonic.words)
|
||||
// Vector(slice, bracket, street, mountain, beauty, faint, manage, window, cherry, direct, suit, float, between, puppy, trade, thunder, remind, leaf, plunge, defense, budget, north, scan, color)
|
||||
```
|
||||
|
||||
Now that we have a `MnemonicCode` that was securely generated, we need to now create `KeyManagerParams` which tells us how to generate
|
||||
generate specific kinds of addresses for wallets.
|
||||
|
||||
`KeyManagerParams` takes 3 parameters:
|
||||
|
||||
1. `seedPath` there is where we store the `MnemonicCode` on your file system
|
||||
2. [`purpose`](/api/org/bitcoins/core/hd/HDPurpose) which represents what type of utxo this `KeyManager` is associated with. The specification for this is in [BIP43](https://github.com/bitcoin/bips/blob/master/bip-0043.mediawiki)
|
||||
3. [`network`](/api/org/bitcoins/core/config/NetworkParameters) what cryptocurrency network this key manager is associated with
|
||||
|
||||
|
||||
This controls how the root key is defined. The combination of `purpose` and `network` determine how the root `ExtKey` is serialized. For more information on how this works please see [hd-keys](../core/hd-keys.md)
|
||||
|
||||
Now we can construct a native segwit key manager for the regtest network!
|
||||
|
||||
```scala
|
||||
//this will create a temp directory with the prefix 'key-manager-example` that will
|
||||
//have a file in it called "encrypted-bitcoin-s-seed.json"
|
||||
val seedPath = Files.createTempDirectory("key-manager-example").resolve(WalletStorage.ENCRYPTED_SEED_FILE_NAME)
|
||||
// seedPath: Path = /var/folders/fg/scntn26d4h55x96zc456l0r40000gn/T/key-manager-example1673183639044643511/encrypted-bitcoin-s-seed.json
|
||||
|
||||
//let's create a native segwit key manager
|
||||
val purpose = HDPurposes.SegWit
|
||||
// purpose: HDPurpose = m/84'
|
||||
|
||||
//let's choose regtest as our network
|
||||
val network = RegTest
|
||||
// network: RegTest.type = RegTest
|
||||
|
||||
val kmParams = KeyManagerParams(seedPath, purpose, network)
|
||||
// kmParams: KeyManagerParams = KeyManagerParams(/var/folders/fg/scntn26d4h55x96zc456l0r40000gn/T/key-manager-example1673183639044643511/encrypted-bitcoin-s-seed.json,m/84',RegTest)
|
||||
|
||||
val aesPasswordOpt = Some(AesPassword.fromString("password"))
|
||||
// aesPasswordOpt: Some[AesPassword] = Some(Masked(AesPassword))
|
||||
|
||||
val km = BIP39KeyManager.initializeWithMnemonic(aesPasswordOpt, mnemonic, None, kmParams)
|
||||
// km: Either[KeyManagerInitializeError, BIP39KeyManager] = Right(org.bitcoins.keymanager.bip39.BIP39KeyManager@1633c6a6)
|
||||
|
||||
val rootXPub = km.right.get.getRootXPub
|
||||
// rootXPub: ExtPublicKey = vpub5SLqN2bLY4WeZYoPHeAUPnfNRvwcHsUv2TJZvaC2WMh8ejD6DXcngh8W2MutwRcJNNUXToVZ7ivpMb4723bTh3n2JWX3DdXRdCa4b5UiYZz
|
||||
|
||||
println(rootXPub)
|
||||
// vpub5SLqN2bLY4WeZYoPHeAUPnfNRvwcHsUv2TJZvaC2WMh8ejD6DXcngh8W2MutwRcJNNUXToVZ7ivpMb4723bTh3n2JWX3DdXRdCa4b5UiYZz
|
||||
```
|
||||
|
||||
Which should print something that looks like this
|
||||
|
||||
`vpub5SLqN2bLY4WeXxMqwJHJFBEwxSscGB2uDUnsTS3edVjZEwTrQDFDNqoR2xLqARQPabGaXsHSTenTRcqm2EnB9MpuC4vSk3LqSgNmGGZtuq7`
|
||||
|
||||
which is a native segwit `ExtPubKey` for the regtest network!
|
||||
|
||||
You can always change the `network` or `purpose` to support different things. You do _not_ need to initialize the key manager
|
||||
again after initializing it once. You can use the same `mnemonic` for different networks, which you control `KeyManagerParams`.
|
||||
|
||||
```scala
|
||||
//let's create a nested segwit key manager for mainnet
|
||||
val mainnetKmParams = KeyManagerParams(seedPath, HDPurposes.SegWit, MainNet)
|
||||
// mainnetKmParams: KeyManagerParams = KeyManagerParams(/var/folders/fg/scntn26d4h55x96zc456l0r40000gn/T/key-manager-example1673183639044643511/encrypted-bitcoin-s-seed.json,m/84',MainNet)
|
||||
|
||||
//we do not need to all `initializeWithMnemonic()` again as we have saved the seed to dis
|
||||
val mainnetKeyManager = BIP39KeyManager.fromMnemonic(mnemonic, mainnetKmParams, None, Instant.now)
|
||||
// mainnetKeyManager: BIP39KeyManager = org.bitcoins.keymanager.bip39.BIP39KeyManager@13413c18
|
||||
|
||||
val mainnetXpub = mainnetKeyManager.getRootXPub
|
||||
// mainnetXpub: ExtPublicKey = zpub6jftahH18ngZxjZrd5JyE93P7oXQ4MSuguPT49ma2PCes8U1EAH3Awm47BkEw4DyzvwkThsnxNM1tjWMtqFWszWRmsJjZGoNi6pe9Kym5i1
|
||||
|
||||
println(mainnetXpub)
|
||||
// zpub6jftahH18ngZxjZrd5JyE93P7oXQ4MSuguPT49ma2PCes8U1EAH3Awm47BkEw4DyzvwkThsnxNM1tjWMtqFWszWRmsJjZGoNi6pe9Kym5i1
|
||||
```
|
||||
|
||||
Which gives us something that looks like this
|
||||
|
||||
`zpub6jftahH18ngZw98KGjRo5XcxeKTQ2eztsvskb1dC9XF5TLimQquTs6Ry7nBBA425D9joXmfgJJCexmJ1u2SELJZJfRi95gcnXadLpZzYb5c`
|
||||
|
||||
which is a p2sh wrapped segwit `ExtPubKey` for the bitcoin main network!
|
||||
|
||||
#### Creating a key manager from existing mnemonic
|
||||
|
||||
To create a `KeyManager` from existing mnemonic you need to specify the `seedPath` and then construct the `KeyManagerParams` that you would like.
|
||||
|
||||
Finally you call `KeyManager.fromParams()` that reads the mnemonic from disk and create's the key manager
|
||||
143
website/versioned_docs/version-1.8.0/node/node.md
Normal file
143
website/versioned_docs/version-1.8.0/node/node.md
Normal file
|
|
@ -0,0 +1,143 @@
|
|||
---
|
||||
id: version-1.8.0-node
|
||||
title: Light Client
|
||||
original_id: node
|
||||
---
|
||||
|
||||
Bitcoin-s has node module that allows you to connect to the p2p network.
|
||||
|
||||
### Neutrino Node
|
||||
|
||||
Bitcoin-s has experimental support for neutrino which is a new lite client proposal on the bitcoin p2p network. You can
|
||||
read more about how neutrino works [here](https://suredbits.com/neutrino-what-is-it-and-why-we-need-it/). At this time,
|
||||
bitcoin-s only supports connecting to one trusted peer.
|
||||
|
||||
#### Limitations
|
||||
|
||||
Currently, the node does not have an active mempool.
|
||||
It is only aware of transactions it broadcasts and ones confirmed in blocks.
|
||||
|
||||
#### Callbacks
|
||||
|
||||
Bitcoin-S support call backs for the following events that happen on the bitcoin p2p network:
|
||||
|
||||
1. onTxReceived
|
||||
2. onBlockReceived
|
||||
3. onMerkleBlockReceived
|
||||
4. onCompactFilterReceived
|
||||
|
||||
That means every time one of these events happens on the p2p network, we will call your callback
|
||||
so that you can be notified of the event. These callbacks will be run after the message has been
|
||||
recieved and will execute sequentially. If any of them fail an error log will be output and the remainder of the callbacks will continue.
|
||||
Let's make an easy one
|
||||
|
||||
#### Example
|
||||
|
||||
Here is an example of constructing a neutrino node and registering a callback so you can be notified of an event.
|
||||
|
||||
To run the example, we need a bitcoind binary that has neutrino support.
|
||||
Bitcoin Core only has p2p neutrino support as of version 0.21.0.
|
||||
You will need to use a version of Bitcoin Core at least as old as 0.21.0.
|
||||
For your node to be able to service these filters you will need set
|
||||
`blockfilterindex=1` and `peerblockfilters=1` in your `bitcoin.conf` file.
|
||||
|
||||
|
||||
```scala
|
||||
implicit val system = ActorSystem(s"node-example")
|
||||
implicit val ec = system.dispatcher
|
||||
|
||||
//we also require a bitcoind instance to connect to
|
||||
//so let's start one (make sure you ran 'sbt downloadBitcoind')
|
||||
val instance = BitcoindRpcTestUtil.instance(versionOpt = Some(BitcoindVersion.Experimental))
|
||||
val p2pPort = instance.p2pPort
|
||||
val bitcoindF = BitcoindRpcTestUtil.startedBitcoindRpcClient(instance, Vector.newBuilder)
|
||||
|
||||
//contains information on how to connect to bitcoin's p2p info
|
||||
val peerF = bitcoindF.flatMap(b => NodeUnitTest.createPeer(b))
|
||||
|
||||
// set a data directory
|
||||
val prefix = s"node-example-${System.currentTimeMillis()}"
|
||||
val datadir = Files.createTempDirectory(prefix)
|
||||
|
||||
val tmpDir = BitcoinSTestAppConfig.tmpDir()
|
||||
// set the current network to regtest
|
||||
val config = ConfigFactory.parseString {
|
||||
s"""
|
||||
| bitcoin-s {
|
||||
| network = regtest
|
||||
| node {
|
||||
| mode = neutrino # neutrino, spv
|
||||
|
|
||||
| peers = ["127.0.0.1:$p2pPort"] # a list of peer addresses in form "hostname:portnumber"
|
||||
| # (e.g. "neutrino.testnet3.suredbits.com:18333")
|
||||
| # Port number is optional, the default value is 8333 for mainnet,
|
||||
| # 18333 for testnet and 18444 for regtest.
|
||||
| }
|
||||
| }
|
||||
|""".stripMargin
|
||||
}
|
||||
|
||||
implicit val appConfig = BitcoinSAppConfig(datadir, Vector(config))
|
||||
implicit val chainConfig = appConfig.chainConf
|
||||
implicit val nodeConfig = appConfig.nodeConf
|
||||
|
||||
val initNodeF = nodeConfig.start()
|
||||
|
||||
//the node requires a chainHandler to store block information
|
||||
//use a helper method in our testkit to create the chain project
|
||||
val chainApiF = for {
|
||||
chainHandler <- ChainUnitTest.createChainHandler()
|
||||
} yield chainHandler
|
||||
|
||||
|
||||
//yay! All setup done, let's create a node and then start it!
|
||||
val nodeF = for {
|
||||
chainApi <- chainApiF
|
||||
peer <- peerF
|
||||
} yield {
|
||||
val dataMessageHandler = DataMessageHandler(chainApi)
|
||||
NeutrinoNode(nodePeer = Vector(peer),
|
||||
dataMessageHandler = dataMessageHandler,
|
||||
nodeConfig = nodeConfig,
|
||||
chainConfig = chainConfig,
|
||||
actorSystem = system)
|
||||
}
|
||||
|
||||
//let's start it
|
||||
val startedNodeF = nodeF.flatMap(_.start())
|
||||
|
||||
//let's make a simple callback that print's the
|
||||
//blockhash everytime we receive a block on the network
|
||||
val blockReceivedFunc: OnBlockReceived = { block: Block =>
|
||||
Future.successful(
|
||||
println(s"Received blockhash=${block.blockHeader.hashBE}"))
|
||||
}
|
||||
|
||||
// Create callback
|
||||
val nodeCallbacks = NodeCallbacks.onBlockReceived(blockReceivedFunc)
|
||||
|
||||
// Add call to our node's config
|
||||
nodeConfig.addCallbacks(nodeCallbacks)
|
||||
|
||||
//let's test it out by generating a block with bitcoind!
|
||||
|
||||
val genBlockF = for {
|
||||
bitcoind <- bitcoindF
|
||||
addr <- bitcoind.getNewAddress
|
||||
hashes <- bitcoind.generateToAddress(1,addr)
|
||||
} yield hashes
|
||||
|
||||
//you should see our callback print a block hash
|
||||
//when running this code
|
||||
|
||||
//cleanup
|
||||
val cleanupF = for {
|
||||
_ <- genBlockF
|
||||
bitcoind <- bitcoindF
|
||||
node <- startedNodeF
|
||||
x = NeutrinoNodeConnectedWithBitcoind(node.asInstanceOf[NeutrinoNode],bitcoind)
|
||||
_ <- NodeUnitTest.destroyNodeConnectedWithBitcoind(x)
|
||||
} yield ()
|
||||
|
||||
Await.result(cleanupF, 60.seconds)
|
||||
```
|
||||
50
website/versioned_docs/version-1.8.0/node/tor.md
Normal file
50
website/versioned_docs/version-1.8.0/node/tor.md
Normal file
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
id: version-1.8.0-tor
|
||||
title: Setting up Tor with Light Client
|
||||
original_id: tor
|
||||
---
|
||||
|
||||
Bitcoin-s node can connect to the p2p network over Tor.
|
||||
|
||||
Before setting up Bitcoin-s node to use Tor you must have Tor installed and running.
|
||||
|
||||
To install Tor use this command on Debian based Linux systems
|
||||
|
||||
```shell
|
||||
sudo apt install tor
|
||||
```
|
||||
|
||||
or this command to install it on Mac OS X
|
||||
|
||||
```shell
|
||||
brew install tor
|
||||
```
|
||||
|
||||
You don't need a special configuration for Tor to be a SOCKS5 proxy for a Bitcoin-s node.
|
||||
However, you might want to uncomment this line in your `/etc/tor/torrc` (Linux) or
|
||||
`/usr/local/etc/tor/torrc` (Mac OS X) file to prevent your Tor node from using your computer
|
||||
as an exit point to the clearnet:
|
||||
|
||||
```
|
||||
ExitPolicy reject *:* # no exits allowed
|
||||
```
|
||||
|
||||
Start Tor on Linux machines:
|
||||
|
||||
```shell
|
||||
sudo systemctl start tor
|
||||
```
|
||||
|
||||
or Mac OS X:
|
||||
|
||||
```shell
|
||||
brew services start tor
|
||||
```
|
||||
|
||||
Next you need to enable SOCKS5 proxy support in your `~/.bitcoin-s/bitcoin-s.conf` file:
|
||||
|
||||
```
|
||||
bitcoin-s.node.proxy.enabled = true
|
||||
```
|
||||
|
||||
See https://github.com/bitcoin-s/bitcoin-s/blob/master/db-commons/src/main/resources/reference.conf for other proxy configuration parameters.
|
||||
|
|
@ -0,0 +1,63 @@
|
|||
---
|
||||
id: version-1.8.0-oracle-explorer-client
|
||||
title: Oracle Explorer Client
|
||||
original_id: oracle-explorer-client
|
||||
---
|
||||
|
||||
[Suredbits offers a tool called an Oracle Explorer](https://oracle.suredbits.com) for oracles to post their
|
||||
announcements and attestments at a later time.
|
||||
|
||||
Bitcoin-s provides an open source oracle explorer client for
|
||||
interacting with the oracle explorer.
|
||||
|
||||
### Environments
|
||||
|
||||
There are 2 live environments that can be used with the explorer client
|
||||
|
||||
1. ExplorerEnv.Production
|
||||
2. ExplorerEnv.Test
|
||||
|
||||
As the names indicate, one references the [production oracle explorer](https://oracle.suredbits.com)
|
||||
while the other references the [test environment](https://test.oracle.suredbits.com)
|
||||
|
||||
```scala
|
||||
implicit val system = ActorSystem("explorer-client-actor-system")
|
||||
|
||||
//use test environment for this little example
|
||||
val env = ExplorerEnv.Test
|
||||
val explorerClient = SbExplorerClient(env, proxyParams = None)
|
||||
|
||||
//list all announcemnts on the explorer
|
||||
val announcementsF: Future[Vector[SbAnnouncementEvent]] = explorerClient.listAnnouncements()
|
||||
|
||||
|
||||
//example announcement taken from
|
||||
//https://oracle.suredbits.com/event/e0a5624edbc854120982165b0eef53f0777a49febd79a0c21bf75e5582021e33
|
||||
val announcementHex = "fdd824c8bf634b2d76f6d8c6499aa977a7b0ae2b84bc206d800f8448e46d63d6ca31778ddb023e39df098c7e109b3d6ee7273d18be62e10f8481dae6531dbe3e0647f6e95d1bcfab252c6dd9edd7aea4c5eeeef138f7ff7346061ea40143a9f5ae80baa9fdd82264000190ef605e3450e16b47745e7a33e26ac9437f6ec2ed660d829a064dceee3699c8605fc700fdd806270005076e67616e6e6f75066d696f63696304647261770a6e6f2d636f6e74657374056f74686572124d696f6369632076204e67616e6e6f752032"
|
||||
val announcement = OracleAnnouncementV0TLV.fromHex(announcementHex)
|
||||
|
||||
//you can query by announcement
|
||||
val announcementF: Future[SbAnnouncementEvent] = explorerClient.getAnnouncement(announcement)
|
||||
|
||||
//or query by hash
|
||||
val sameAnnouncementF: Future[SbAnnouncementEvent] = explorerClient.getAnnouncement(announcement.sha256)
|
||||
|
||||
//you can post an announcement to the oracle explorer
|
||||
val oracleName = "Chris_Stewart_5"
|
||||
val description = "2021-03-24-sunny-in-chicago"
|
||||
val uriOpt = Some("https://twitter.com/Chris_Stewart_5")
|
||||
|
||||
val sbAnnouncement = CreateAnnouncementExplorer(announcement, oracleName, description, uriOpt)
|
||||
|
||||
val createdF = explorerClient.createAnnouncement(sbAnnouncement)
|
||||
|
||||
//and then you can follow up and post the attestations
|
||||
val attestationsHex =
|
||||
"fdd868821b323032312d30332d32342d73756e6e792d696e2d6368696361676f1d5dcdba2e64cb116cc0c375a0856298f0058b778f46bfe625ac6576204889e40001efdf735567ae0a00a515e313d20029de5d7525da7b8367bc843d28b672d4db4db5de4dbff689f3b742be634a9c92c615dbcf2eadbdd470f514b1ac250a30db6d03594553"
|
||||
|
||||
val attestations = OracleAttestmentV0TLV.fromHex(attestationsHex)
|
||||
|
||||
val announcementHash = announcement.sha256
|
||||
val sbAttestations = CreateAttestations(announcementHash, attestations)
|
||||
val createdAttestationsF = explorerClient.createAttestations(sbAttestations)
|
||||
```
|
||||
60
website/versioned_docs/version-1.8.0/rpc/eclair.md
Normal file
60
website/versioned_docs/version-1.8.0/rpc/eclair.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
id: version-1.8.0-rpc-eclair
|
||||
title: Eclair
|
||||
original_id: rpc-eclair
|
||||
---
|
||||
|
||||
This is a RPC client for [Eclair](https://github.com/acinq/eclair). It assumes that a bitcoind instance is running.
|
||||
|
||||
Currently this RPC client is written for [v0.5.0](https://github.com/ACINQ/eclair/releases/tag/v0.5.0) version of Eclair.
|
||||
|
||||
## Configuration of Eclair
|
||||
|
||||
Please see the configuration secion of the
|
||||
[Eclair README](https://github.com/acinq/eclair#configuring-eclair).
|
||||
|
||||
You can find the configuration we use for our testing infrastrture for eclair [here](https://github.com/bitcoin-s/bitcoin-s/blob/a043d3858ef33da51229ee59c478d2a6c9d5a46f/testkit/src/main/scala/org/bitcoins/testkit/eclair/rpc/EclairRpcTestUtil.scala#L98).
|
||||
|
||||
## Starting Eclair
|
||||
|
||||
You need to download the jar from the [eclair's github](https://github.com/ACINQ/eclair/releases/tag/v0.5.0).
|
||||
|
||||
To run Eclair by unzipping the `eclair-node-0.5.0-ac08560-bin.zip` and then running
|
||||
|
||||
```bash
|
||||
$ ./eclair-node-0.5.0-ac08560/bin/eclair-node.sh
|
||||
```
|
||||
|
||||
If you wish to start Eclair from the RPC client, you can do one of the following:
|
||||
|
||||
1. Construct a [`EclairRpcClient.binary`](https://github.com/bitcoin-s/bitcoin-s/blob/a043d3858ef33da51229ee59c478d2a6c9d5a46f/eclair-rpc/src/main/scala/org/bitcoins/eclair/rpc/client/EclairRpcClient.scala#L51) field set
|
||||
2. Set the [`ECLAIR_PATH`](https://github.com/bitcoin-s/bitcoin-s/blob/a043d3858ef33da51229ee59c478d2a6c9d5a46f/eclair-rpc/src/main/scala/org/bitcoins/eclair/rpc/client/EclairRpcClient.scala#L701) environment variable to the directory where the Eclair Jar is located.
|
||||
|
||||
We will default to using the `binary` field first when trying to start the jar, and the fallback to `ECLAIR_PATH`.
|
||||
|
||||
Here is an example of how to start eclair:
|
||||
|
||||
|
||||
```scala
|
||||
implicit val system = ActorSystem(s"eclair-rpc-${System.currentTimeMillis}")
|
||||
implicit val ec = system.dispatcher
|
||||
|
||||
val datadirPath = Paths.get("path", "to", "datadir")
|
||||
val binaryPath = Paths.get("path", "to", "eclair-node-0.5.0-ac08560", "bin", "eclair-node.sh")
|
||||
val instance = EclairInstance.fromDatadir(datadirPath.toFile, logbackXml = None, proxyParams = None)
|
||||
val client = new EclairRpcClient(instance, Some(binaryPath.toFile))
|
||||
|
||||
val startedF = client.start()
|
||||
|
||||
for {
|
||||
eclair <- startedF
|
||||
info <- eclair.getInfo
|
||||
} yield {
|
||||
println(s"Eclair info: $info")
|
||||
}
|
||||
```
|
||||
|
||||
### Connecting to the websocket
|
||||
|
||||
As of `v0.3.3` eclair supports a websocket endpoint. This means you can receive updates of what is happening with eclair
|
||||
in real time. You can see an example of us testing this [here](https://github.com/bitcoin-s/bitcoin-s/blob/a043d3858ef33da51229ee59c478d2a6c9d5a46f/eclair-rpc-test/src/test/scala/org/bitcoins/eclair/rpc/EclairRpcClientTest.scala#L591)
|
||||
60
website/versioned_docs/version-1.8.0/rpc/lnd.md
Normal file
60
website/versioned_docs/version-1.8.0/rpc/lnd.md
Normal file
|
|
@ -0,0 +1,60 @@
|
|||
---
|
||||
id: version-1.8.0-lnd-rpc
|
||||
title: LND
|
||||
original_id: lnd-rpc
|
||||
---
|
||||
|
||||
This is an RPC client for [LND](https://github.com/LightningNetwork/lnd). It assumes that a bitcoind instance is running.
|
||||
|
||||
Currently, this RPC client is written for [v0.13.1](https://github.com/lightningnetwork/lnd/releases/tag/v0.13.1-beta) version of LND.
|
||||
|
||||
## Configuration of LND
|
||||
|
||||
Please see the [sample configuration for LND](https://github.com/lightningnetwork/lnd/blob/v0.13.1-beta/sample-lnd.conf).
|
||||
|
||||
You can find the configuration we use for our testing infrastructure for lnd [here](https://github.com/bitcoin-s/bitcoin-s/blob/656e0928bf1bf4f511f60dec625699b454f29a1f/testkit/src/main/scala/org/bitcoins/testkit/lnd/LndRpcTestUtil.scala#L90).
|
||||
|
||||
## Starting LND
|
||||
|
||||
You need to download the binaries from the [LND's github](https://github.com/lightningnetwork/lnd/releases/tag/v0.13.1-beta).
|
||||
|
||||
To run lnd by unzipping the `lnd-linux-amd64-v0.13.1-beta.tar.gz` (or whichever platform you are on) and then running
|
||||
|
||||
```bash
|
||||
$ ./lnd-linux-amd64-v0.13.1-beta/lnd
|
||||
```
|
||||
|
||||
If you wish to start lnd from the RPC client, you can construct a [`LndRpcClient.binary`](https://github.com/bitcoin-s/bitcoin-s/blob/656e0928bf1bf4f511f60dec625699b454f29a1f/lnd-rpc/src/main/scala/org/bitcoins/lnd/rpc/LndRpcClient.scala#L35) field set
|
||||
|
||||
We will default to using the `binary` field first when trying to start the jar, and the fallback to the default datadir (`~/.lnd`).
|
||||
|
||||
Here is an example of how to start lnd:
|
||||
|
||||
|
||||
```scala
|
||||
implicit val system = ActorSystem(s"lnd-rpc-${System.currentTimeMillis}")
|
||||
implicit val ec = system.dispatcher
|
||||
|
||||
val datadirPath = Paths.get("path", "to", "datadir")
|
||||
val binaryPath = Paths.get("path", "to", "lnd-linux-amd64-v0.13.1-beta", "lnd")
|
||||
val instance = LndInstance.fromDataDir(datadirPath.toFile)
|
||||
val client = new LndRpcClient(instance, Some(binaryPath.toFile))
|
||||
|
||||
val startedF = client.start()
|
||||
|
||||
for {
|
||||
lnd <- startedF
|
||||
info <- lnd.getInfo
|
||||
} yield {
|
||||
println(s"Lnd info: $info")
|
||||
}
|
||||
```
|
||||
|
||||
### Updating to a new LND version
|
||||
|
||||
The lnd rpc module uses lnd's gRPC. This means when updating to the latest version, the `.proto` files will need to be updated.
|
||||
Bitcoin-S stores them in [lnd-rpc/src/main/protobuf](https://github.com/bitcoin-s/bitcoin-s/tree/master/lnd-rpc/src/main/protobuf).
|
||||
You can find the files to copy from LND [here](https://github.com/lightningnetwork/lnd/tree/master/lnrpc).
|
||||
|
||||
After updating the `proto` files you can run `sbt compile` and this will generate the corresponding class files, this should then give
|
||||
compile warnings for changed rpc functions.
|
||||
445
website/versioned_docs/version-1.8.0/secp256k1/add-to-jni.md
Normal file
445
website/versioned_docs/version-1.8.0/secp256k1/add-to-jni.md
Normal file
|
|
@ -0,0 +1,445 @@
|
|||
---
|
||||
id: version-1.8.0-jni-modify
|
||||
title: Adding to Secp256k1 JNI
|
||||
original_id: jni-modify
|
||||
---
|
||||
|
||||
Bitcoin-S uses a Java Native Interface (JNI) to execute functions in [secp256k1-zkp](https://github.com/ElementsProject/secp256k1-zkp) from java/scala. The native java bindings used to be a part of the secp256k1 library that was maintained by bitcoin-core, but it was [removed in October 2019](https://github.com/bitcoin-core/secp256k1/pull/682). We maintain a [fork of secp256k1](https://github.com/bitcoin-s/secp256k1) which forks off of bitcoin-core's `master` but re-introduces the jni. This is also the easiest way to add functionality from new projects such as [Schnorr signatures](https://github.com/bitcoin-core/secp256k1/pull/558) and [ECDSA adaptor signatures](https://github.com/ElementsProject/secp256k1-zkp/pull/117) by rebasing the bitcoin-s branch with the JNI on top of these experimental branches. That said, it is quite tricky to hook up new functionality in secp256k1 into bitcoin-s and specifically `NativeSecp256k1.java`. The following is a description of this process.
|
||||
|
||||
<!-- START doctoc generated TOC please keep comment here to allow auto update -->
|
||||
<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
|
||||
<!-- END doctoc -->
|
||||
|
||||
- [Adding a new function to NativeSecp256k1.java](#adding-a-new-function-to-nativesecp256k1java)
|
||||
- [Adding to `src/java/org_bitcoin_NativeSecp256k1.c`](#adding-to-srcjavaorg_bitcoin_nativesecp256k1c)
|
||||
- [Adding to `src/java/org_bitcoin_NativeSecp256k1.h`](#adding-to-srcjavaorg_bitcoin_nativesecp256k1h)
|
||||
- [Adding to `src/java/org/bitcoin/NativeSecp256k1.java`](#adding-to-srcjavaorgbitcoinnativesecp256k1java)
|
||||
- [Adding to `src/java/org/bitcoin/NativeSecp256k1Test.java`](#adding-to-srcjavaorgbitcoinnativesecp256k1testjava)
|
||||
- [Adding to Bitcoin-S](#adding-to-bitcoin-s)
|
||||
- [Further Work to Enable Typed Invocations and Nice Tests](#further-work-to-enable-typed-invocations-and-nice-tests)
|
||||
|
||||
<!-- END doctoc generated TOC please keep comment here to allow auto update -->
|
||||
|
||||
## Adding a new function to NativeSecp256k1.java
|
||||
|
||||
### Adding to `src/java/org_bitcoin_NativeSecp256k1.c`
|
||||
|
||||
1. Add an `#include` import at the top (if applicable)
|
||||
|
||||
If your secp256k1 functions are not already included, you will need to `#include` the header file (should be in the `secp256k1-zkp/include` directory).
|
||||
|
||||
2. Function signature
|
||||
|
||||
Your new function signature should begin with
|
||||
|
||||
```c
|
||||
SECP256K1_API jint JNICALL Java_org_bitcoin_NativeSecp256k1_
|
||||
```
|
||||
|
||||
followed by the secp256k1 function name where `_` are replaced with `_1` (it's a weird jni thing). Finally, you add a parameter list that begins with
|
||||
|
||||
```c
|
||||
(JNIEnv* env, jclass classObject, jobject byteBufferObject, jlong ctx_l
|
||||
```
|
||||
|
||||
and ends with any `jint`s in the case that any of the secp256k1 function inputs have variable length (such as public keys which can be either `33` or `65` bytes, or ECDSA signatures), and lastly any `jboolean`s in case there is some flag like `compressed` passed in.
|
||||
|
||||
As an example that includes everything, if you are making a call to `secp256k1_pubkey_tweak_add` which takes in public keys that could be `33` or `65` bytes and outputs a public key that will either be compressed or decompressed based on an input flag, then the function signature would be
|
||||
|
||||
```c
|
||||
SECP256K1_API jobjectArray JNICALL Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1add
|
||||
(JNIEnv* env, jclass classObject, jobject byteBufferObject, jlong ctx_l, jint publen, jboolean compressed)
|
||||
```
|
||||
|
||||
3. Reading `unsigned char*` inputs
|
||||
|
||||
It is now time to create pointers for each of the secp256k1 function inputs that where passed in via the `byteBufferObject`. We must first read in the `Secp256k1Context` with the line
|
||||
|
||||
```c
|
||||
secp256k1_context *ctx = (secp256k1_context*)(uintptr_t)ctx_l;
|
||||
```
|
||||
|
||||
and we can then initialize the first pointer to be the beginning of the `byteBufferObject` with the line
|
||||
|
||||
```c
|
||||
unsigned char* firstArg = (*env)->GetDirectBufferAddress(env, byteBufferObject);
|
||||
```
|
||||
|
||||
and subsequent arguments' pointers where the previous argument's length is known (say `32` bytes for example) can be instantiated using
|
||||
|
||||
```c
|
||||
unsigned char* prevArg = ...
|
||||
unsigned char* nextArg = (unsigned char*) (prevArg + 32);
|
||||
```
|
||||
|
||||
and in the case that a previous argument has variable length, then a `jint` has been provided as an input and can be used instead, such as in the example
|
||||
|
||||
```c
|
||||
unsigned char* prevArg = ...
|
||||
unsigned char* nextArg = (unsigned char*) (prevArg + publen);
|
||||
```
|
||||
|
||||
where `publen` is a `jint` passed to this C function.
|
||||
|
||||
As an example that includes everything, consider the function `secp256k1_ecdsa_verify` which takes as input a `32` byte message, a variable length signature and a public key (of length `33` or `65` bytes). Our function will begin with
|
||||
|
||||
```c
|
||||
{
|
||||
secp256k1_context *ctx = (secp256k1_context*)(uintptr_t)ctx_l;
|
||||
|
||||
unsigned char* data = (unsigned char*) (*env)->GetDirectBufferAddress(env, byteBufferObject);
|
||||
const unsigned char* sigdata = (unsigned char*) (data + 32);
|
||||
const unsigned char* pubdata = (unsigned char*) (sigdata + siglen);
|
||||
```
|
||||
|
||||
where `siglen` is a `jint` passed into the C function.
|
||||
|
||||
4. Initialize variables
|
||||
|
||||
Next we must declare all variables. We put all decelerations here as it is required by the C framework used by `libsecp256k1` that definitions and assignments/function calls cannot be interleaved.
|
||||
|
||||
Specifically you will need to declare any secp256k1 specific structs here as well as all outputs (such as `jobjectArrays` and `jByteArrays`). Generally speaking this will include all inputs which are not raw data (public keys, signatures, etc). Lastly, you will also have an `int ret` which will store `0` if an error occurred and `1` otherwise.
|
||||
|
||||
As an example that includes everything, consider again the function `secp256k1_pubkey_tweak_add` has the following declarations
|
||||
|
||||
```c
|
||||
jobjectArray retArray;
|
||||
jbyteArray pubArray, intsByteArray;
|
||||
unsigned char intsarray[2];
|
||||
unsigned char outputSer[65];
|
||||
size_t outputLen = 65;
|
||||
secp256k1_pubkey pubkey;
|
||||
int ret;
|
||||
```
|
||||
|
||||
Where `retArray` is eventually going to be the data returned, which will contain the `jbyteArray`s `pubArray` and `intsByteArray`, which will contain `outputSer` and `intsarray` respectively. Lastly `pubkey` will store a deserialized `secp256k1_pubkey` corresponding to the input `unsigned char*` public key.
|
||||
|
||||
5. Parse inputs when applicable
|
||||
|
||||
In the case where there are `unsigned char*` inputs which need to be deserialized into secp256k1 structs, this is done now. As an example, `secp256k1_pubkey_tweak_add` takes a public key as input:
|
||||
|
||||
```c
|
||||
unsigned char* pkey = (*env)->GetDirectBufferAddress(env, byteBufferObject);
|
||||
```
|
||||
|
||||
where a `jint publen` is passed in as a function parameter. This function already has a declaration for `secp256k1_pubkey pubkey;`. The first call made after the above declarations is
|
||||
|
||||
```c
|
||||
ret = secp256k1_ec_pubkey_parse(ctx, &pubkey, pkey, publen)
|
||||
```
|
||||
|
||||
and if further parsing is necessary, it is put inside of `if (ret) { ret = [further parsing here] }`.
|
||||
|
||||
6. Make calls to secp256k1 functions to instantiate outputs
|
||||
|
||||
It is finally time to actually call the secp256k1 function we are binding to the jni! This is done by simply calling `ret = [call to secp function here];` or `if (ret) { ret = [secp function call] };` if there were any inputs that needed to be parsed. Note that some secp256k1 functions return outputs by populating variables you should have declared and for which pointers are passed as inputs, while other functions will mutate their inputs rather than returning outputs.
|
||||
|
||||
7. Serialize variable length outputs if applicable
|
||||
|
||||
When dealing with variable length outputs such as signatures, you will likely need to serialize these outputs. This is done by having already instantiated such a variable as
|
||||
|
||||
```c
|
||||
unsigned char outputSer[72];
|
||||
size_t outputLen = 72;
|
||||
```
|
||||
|
||||
where in this case `72` is an upper bound on signature length. With these variables existing (as well as a `secp256k1_ecdsa_signature sig` which has been populated), we call a secp256k1 serialization function to populate `outputSer` and `outputLen` from `sig`
|
||||
|
||||
```c
|
||||
if(ret) {
|
||||
int ret2 = secp256k1_ecdsa_signature_serialize_der(ctx, outputSer, &outputLen, &sig);
|
||||
(void)ret2;
|
||||
}
|
||||
```
|
||||
|
||||
As you can see, in this case we do not which to alter the value returned in `ret` if serialization fails. If we did then `ret2` would not be introduced and we would instead do `ret = [serialize]`.
|
||||
|
||||
8. Populate return array when applicable
|
||||
|
||||
We now begin translating our serialized results back into Java entities. If you are returning any `int`s containing meta-data (usually `ret` is included here, as are the variable lengths of outputs when applicable), you will want an `unsigned char intsarray[n]` to be already declared where `n` is the number of pieces of meta-data. For example, in `secp256k1_ecdsa_sign`, we wish to return whether there were any errors (stored in `int ret`) and the output signature's length, `size_t outputLen`. Hence we have an `unsigned char intsarray[2]` and we populate it as follows
|
||||
|
||||
```c
|
||||
intsarray[0] = outputLen;
|
||||
intsarray[1] = ret;
|
||||
```
|
||||
|
||||
Next we populate the `jobjectArray` we wish to return, this will always begin with a call
|
||||
|
||||
```c
|
||||
retArray = (*env)->NewObjectArray(env, 2,
|
||||
(*env)->FindClass(env, "[B"),
|
||||
(*env)->NewByteArray(env, 1));
|
||||
```
|
||||
|
||||
to instantiate an empty return array. Next we instantiate our `jbyteArray`s with calls to
|
||||
|
||||
```c
|
||||
myByteArray = (*env)->NewByteArray(env, len);
|
||||
```
|
||||
|
||||
where `myByteArray` is replaced with a real name (such as `intsByteArray`) and `len` is replaced with the length of this array (either a constant or a populated `size_t` variable). Next we populate this array with our data by calling
|
||||
|
||||
```c
|
||||
(*env)->SetByteArrayRegion(env, myByteArray, 0, len, (jbyte*)myData);
|
||||
```
|
||||
|
||||
where `myData` is a C array of `unsigned char` (of length `len`). Lastly, we place `myByteArray` into its place in `retArray` with
|
||||
|
||||
```c
|
||||
(*env)->SetObjectArrayElement(env, retArray, index, myByteArray);
|
||||
```
|
||||
|
||||
where `index` is a constant (`0`, `1`, `2`, etc.) for the index of `myByteArray` within `retArray`. Note that you should follow our conventions and have index `0` contain the actual data to be returned and index `1` (and onward) contain any meta-data.
|
||||
|
||||
Please note that if you wish not to return such meta-data (such as if you wish to return only a `boolean`), then none of the code in this subsection is required
|
||||
|
||||
9. void `classObject`
|
||||
|
||||
Once we are ready to return, we first void the input `classObject` by making the call
|
||||
|
||||
```c
|
||||
(void)classObject;
|
||||
```
|
||||
|
||||
10. Return array when applicable, `ret` when applicable
|
||||
|
||||
Lastly, we return `retArray` in the case where we wish to return a `byte[]`, or `ret` in the case that we wish to return a `boolean`.
|
||||
|
||||
### Adding to `src/java/org_bitcoin_NativeSecp256k1.h`
|
||||
|
||||
Once your function is defined in `src/java/org_bitcoin_NativeSecp256k1.c`, you must define them in the corresponding header files by simply copying the function signature but without parameter names. For example, if `secp256k1_pubkey_tweak_add` has the function signature
|
||||
|
||||
```c
|
||||
SECP256K1_API jobjectArray JNICALL Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1add
|
||||
(JNIEnv* env, jclass classObject, jobject byteBufferObject, jlong ctx_l, jint publen, jboolean compressed)
|
||||
```
|
||||
|
||||
then in the header file we include
|
||||
|
||||
```c
|
||||
/*
|
||||
* Class: org_bitcoin_NativeSecp256k1
|
||||
* Method: secp256k1_pubkey_tweak_add
|
||||
* Signature: (Ljava/nio/ByteBuffer;JI)[[B
|
||||
*/
|
||||
SECP256K1_API jobjectArray JNICALL Java_org_bitcoin_NativeSecp256k1_secp256k1_1pubkey_1tweak_1add
|
||||
(JNIEnv *, jclass, jobject, jlong, jint, jboolean);
|
||||
```
|
||||
|
||||
### Adding to `src/java/org/bitcoin/NativeSecp256k1.java`
|
||||
|
||||
We are now done writing C code! We have completed an interface in C for the JNI to hook up to. However, we must now write the corresponding Java code which hides the Java to C (and back) conversions from other Java code. We accomplish this with a `class` of `static` methods called `NativeSecp256k1`.
|
||||
|
||||
1. Add `private static native` secp256k1 function
|
||||
|
||||
We begin by adding a `private static native` method at the bottom of the file corresponding to our secp256k1 function. Notice that the syntax for `native` methods is similar to that of Java abstract interface methods where instead of providing an implementation we simply end with a semi-colon.
|
||||
|
||||
For functions returning `boolean`s, we have their `native` methods return `int` (will be `0` or `1`). Otherwise, for functions returning `byte[]`s, we have their `native` methods return `byte[][]` (two dimensional array to allow for meta-data).
|
||||
|
||||
2. Method signature
|
||||
|
||||
Next we add a method to the `NativeSecp256k1` class
|
||||
|
||||
```java
|
||||
public static byte[] myFunc(byte[] input1, byte[] input2, boolean input3) throws AssertFailException
|
||||
```
|
||||
|
||||
where `boolean` could also be the return type instead of `byte[]`.
|
||||
|
||||
3. `checkArgument`s
|
||||
|
||||
We begin implementing this function by checking the input argument lengths using the `checkArument` function
|
||||
|
||||
```java
|
||||
checkArgument(input1.length == 32 && (input2.length == 33 || input2.length == 65));
|
||||
```
|
||||
|
||||
4. Initialize `ByteBuffer`
|
||||
|
||||
We now initialize the `ByteBuffer` which we will be passing through the JNI as an input. This is done with a call to
|
||||
|
||||
```java
|
||||
ByteBuffer byteBuff = nativeECDSABuffer.get();
|
||||
```
|
||||
|
||||
followed by allocation when necessary as follows
|
||||
|
||||
```java
|
||||
if (byteBuff == null || byteBuff.capacity() < input1.length + input2.length) {
|
||||
byteBuff = ByteBuffer.allocateDirect(input1.length + input2.length);
|
||||
byteBuff.order(ByteOrder.nativeOrder());
|
||||
nativeECDSABuffer.set(byteBuff);
|
||||
}
|
||||
```
|
||||
|
||||
where `input1.length + input2.length` is replaced by whatever the total `ByteBuffer` length needed.
|
||||
|
||||
5. Fill `ByteBuffer`
|
||||
|
||||
We now populate the `ByteBuffer` as follows
|
||||
|
||||
```java
|
||||
byteBuff.rewind();
|
||||
byteBuff.put(input1);
|
||||
byteBuff.put(input2);
|
||||
```
|
||||
|
||||
where generally, you will `rewind()` and then `put()` all inputs (in order).
|
||||
|
||||
6. Make `native` call
|
||||
|
||||
It is now time to make a call to our `native` C function.
|
||||
|
||||
In the case where we are returning a `byte[]`, this is done by first declaring a `byte[][]` to store the output and then locking the read lock, `r`. Then we call the `native` function within a `try` clause which releases the lock in the `finally` clause.
|
||||
|
||||
```java
|
||||
byte[][] retByteArray;
|
||||
r.lock();
|
||||
try {
|
||||
retByteArray = secp256k1_my_call(byteBuff, Secp256k1Context.getContext(), input3);
|
||||
} finally {
|
||||
r.unlock();
|
||||
}
|
||||
```
|
||||
|
||||
In the case where we are returning a `boolean`, simply make the call in the `try` and compare the output to `1` like so
|
||||
|
||||
```java
|
||||
r.lock();
|
||||
try {
|
||||
return secp256k1_my_bool_call(byteBuff, Secp256k1Context.getContext()) == 1;
|
||||
} finally {
|
||||
r.unlock();
|
||||
}
|
||||
```
|
||||
|
||||
If this is the case, you are now done and can ignore the following steps.
|
||||
|
||||
7. Parse outputs
|
||||
|
||||
`retByteArray` should now be populated and we want to read its two parts (data and meta-data). Getting the data should be as easy as
|
||||
|
||||
```java
|
||||
byte[] resultArr = retByteArr[0];
|
||||
```
|
||||
|
||||
while for each piece of meta-data, you can read the corresponding `int` as follows
|
||||
|
||||
```java
|
||||
int metaVal = new BigInteger(new byte[] { retByteArray[1][index] }).intValue();
|
||||
```
|
||||
|
||||
where `index` is replaced with the index in the meta-data array.
|
||||
|
||||
8. Validate outputs
|
||||
|
||||
In the case where we now have meta-data, we validate it with calls to `assertEquals`.
|
||||
|
||||
9. Return output
|
||||
|
||||
Finally, we return `resultArr`.
|
||||
|
||||
### Adding to `src/java/org/bitcoin/NativeSecp256k1Test.java`
|
||||
|
||||
I normally first build the C binaries and add to Bitcoin-S before coming back to this section because I use `sbt core/console` to generate values and make calls below, but this is not a requirement.
|
||||
|
||||
1. Generate values and make calls to `org.bitcoin.NativeSecp256k1` to generate inputs and their expected outputs
|
||||
|
||||
2. Create regression unit tests with these values in NativeSecp256k1Test
|
||||
|
||||
Note that you can use `DatatypeConverter.parseHexBinary` to convert `String` hex to a `byte[]`, and you can use `DatatypeConverter.printHexBinary` to convert a `byte[]` to its `String` hex. Lastly you will make assertions with calls to `assertEquals`.
|
||||
|
||||
3. Add test to `main`
|
||||
|
||||
### Adding to Bitcoin-S
|
||||
|
||||
1. Translate `NativeSecp256k1` and `NativeSecp256k1Test` to jni project
|
||||
|
||||
By translate I mean to say that you must copy the functions from those files to the corresponding files in the `bitcoin-s/secp256k1jni` project. For tests this will require changing the methods to be non-`static` as well as adding the `@Test` annotation above each method (rather than adding to a `main` method).
|
||||
|
||||
2. Configure and build `secp256k1`
|
||||
|
||||
You will need to go to the `bitcoin-s/secp256k1-zkp` directory in a terminal and running the following where you may need to add to the `./configure` command if you are introducing a new module.
|
||||
|
||||
__For Linux or OSx (64-bit)__
|
||||
|
||||
You will have to make sure `JAVA_HOME` is set, and build tools are installed, for Linux this requires:
|
||||
|
||||
```bashrc
|
||||
echo $JAVA_HOME
|
||||
sudo apt install build-essential autotools-dev libtool automake
|
||||
```
|
||||
|
||||
and for Mac this requires:
|
||||
|
||||
```bashrc
|
||||
brew install automake libtool
|
||||
```
|
||||
|
||||
You should then be able to build `libsecp256k1` with the following:
|
||||
|
||||
```bashrc
|
||||
./autogen.sh
|
||||
./configure --enable-jni --enable-experimental --enable-module-ecdh --enable-module-schnorrsig --enable-module-ecdsa-adaptor
|
||||
make CFLAGS="-std=c99"
|
||||
make check
|
||||
make check-java
|
||||
```
|
||||
|
||||
__For Windows (64-bit)__
|
||||
|
||||
Windows bindings are cross-built on Linux. You need to install the `mingw` toolchain and have `JAVA_HOME` point to a Windows JDK:
|
||||
|
||||
```bashrc
|
||||
sudo apt install g++-mingw-w64-x86-64
|
||||
sudo update-alternatives --config x86_64-w64-mingw32-g++
|
||||
```
|
||||
|
||||
You should then be able to build `libsecp256k1` with the following:
|
||||
|
||||
```bashrc
|
||||
echo "LDFLAGS = -no-undefined" >> Makefile.am
|
||||
./configure --host=x86_64-w64-mingw32 --enable-jni --enable-experimental --enable-module-ecdh --enable-module-schnorrsig --enable-module-ecdsa-adaptor && make clean && make CFLAGS="-std=c99"
|
||||
```
|
||||
|
||||
There may be some errors that can be ignored:
|
||||
- `Could not determine the host path corresponding to`
|
||||
- `redeclared without dllimport attribute: previous dllimport ignored`
|
||||
|
||||
3. Copy binaries into bitcoin-s natives for your system
|
||||
|
||||
You have now built the C binaries for your JNI bindings for your operating system and you should now find your operating system's directory in `bitcoin-s/secp256k1jni/natives` and replace its contents with the contents of `secp256k1-zkp/.libs` (which contains the compiled binaries).
|
||||
|
||||
4. Run `secp256k1jni` tests
|
||||
|
||||
If you have not yet implemented tests, you should now be able to go back and do so as calls to `NativeSecp256k1` should now succeed.
|
||||
|
||||
Once you have tests implemented, and assuming you've copied them correctly to the `bitcoin-s/secp256k1jni` project, you should be able to run them using
|
||||
|
||||
```bashrc
|
||||
sbt secp256k1jni/test
|
||||
```
|
||||
|
||||
### Further Work to Enable Typed Invocations and Nice Tests
|
||||
|
||||
1. Add new `NetworkElement`s where applicable
|
||||
|
||||
In the case where you are dealing in new kinds of data that are not yet defined in Bitcoin-S, you should add these as `case class`es extending the `NetworkElement` trait, and give them companion objects extending `Factory` for easy serialization and deserialization.
|
||||
|
||||
This step is not necessary if you are only dealing in raw data, `ECPrivateKey`s, `ECPublicKey`s, etc.
|
||||
|
||||
2. Add new typed functions to relevant data types where applicable
|
||||
|
||||
In the case where your new function should be a static method, find a good `object` (or introduce one) and give it a `def` which takes in typed arguments and outputs typed arguments (using `ByteVector` in all places dealing with raw data rather than using `Array[Byte]`). You will then implement these methods using calls to `NativeSecp256k1` methods and getting the inputs into `Array[Byte]` form by getting their `ByteVector`s (usually through a call to `_.bytes`) and then calling `_.toArray`.
|
||||
|
||||
You will then need to take the data returned and deserialize it.
|
||||
|
||||
In the case where your new function belongs naturally as an action performed by some existing or newly introduced type, you can implement your new function as a call made by that class as described for the previous case but where the class will pass a serialized version of itself into the `NativeSecp256k1` call.
|
||||
|
||||
It is often acceptable to implement the call in an `object` and then also add the call (via a call to the object, passing `this`) to the interface of relevant types.
|
||||
|
||||
3. Implement Bouncy Castle fallback in `BouncyCastleUtil.scala` if you can.
|
||||
|
||||
4. Add unit and property-based tests.
|
||||
|
||||
5. If you implemented Bouncy Castle fallback, add tests to `BouncyCastleSecp256k1Test` to compare implementations
|
||||
92
website/versioned_docs/version-1.8.0/secp256k1/secp256k1.md
Normal file
92
website/versioned_docs/version-1.8.0/secp256k1/secp256k1.md
Normal file
|
|
@ -0,0 +1,92 @@
|
|||
---
|
||||
id: version-1.8.0-secp256k1
|
||||
title: Secp256k1
|
||||
original_id: secp256k1
|
||||
---
|
||||
|
||||
[Libsecp256k1](https://github.com/bitcoin-core/secp256k1) is used to preform cryptographic operations on the secp256k1 curve.
|
||||
This is the curve that bitcoin uses. There is a _signficant_ speedup when using this library compared to java crypto libraries
|
||||
like bouncy castle.
|
||||
|
||||
In bitcoin-s, we support native binaries for libsecp256k1
|
||||
|
||||
1. [linux 32 bit](../../secp256k1jni/natives/linux_32)
|
||||
2. [linux 64 bit](../../secp256k1jni/natives/linux_64)
|
||||
3. [mac osx 64 bit](../../secp256k1jni/natives/osx_64)
|
||||
4. [windows 64 bit](../../secp256k1jni/natives/windows_64)
|
||||
|
||||
Bitcoin-s uses a zero dependency library called [`native-lib-loader`](https://github.com/scijava/native-lib-loader).
|
||||
That does the appropriate loading of the library onto your classpath to be accessed.
|
||||
|
||||
### Using libsecp256k1
|
||||
|
||||
To tell if you have access to libsecp256k1 you can do the following
|
||||
|
||||
|
||||
```scala
|
||||
val isEnabled = org.bitcoin.Secp256k1Context.isEnabled()
|
||||
|
||||
println(s"Secp256k1Context.isEnabled=${isEnabled}")
|
||||
```
|
||||
|
||||
If libsecp256k1 is enabled, you can use [NativeSecp256k1](/api/org/bitcoin/NativeSecp256k1)
|
||||
with static method defined in the class.
|
||||
|
||||
|
||||
```scala
|
||||
val privKey = ECPrivateKey.freshPrivateKey
|
||||
val pubKey = privKey.publicKey
|
||||
val dataToSign = DoubleSha256Digest.empty
|
||||
|
||||
val signature = NativeSecp256k1.sign(dataToSign.bytes.toArray, privKey.bytes.toArray)
|
||||
|
||||
val verify = NativeSecp256k1.verify(dataToSign.bytes.toArray, signature, pubKey.bytes.toArray)
|
||||
|
||||
println(s"Verified with NativeSecp256k1 signature=${verify}")
|
||||
|
||||
//you can also just directly sign with the ECKey interface:
|
||||
val signature2 = privKey.sign(dataToSign)
|
||||
|
||||
val verified2 = pubKey.verify(dataToSign, signature2)
|
||||
|
||||
println(s"Verified with NativeSecp256k1 again=${verified2}")
|
||||
```
|
||||
|
||||
### When libsecp256k1 isn't available, or you want to turn it off
|
||||
|
||||
There are two reasons you wouldn't want to use libsecp256k1
|
||||
|
||||
1. You don't trust the pre-compiled binaries we are using
|
||||
2. Your OS/arch is not supported
|
||||
|
||||
There are two ways you can circumvent libsecp256k1
|
||||
|
||||
1. Set `DISABLE_SECP256K1=true` in your environment variables. This will force `CryptoContext.default` to return false which will make Bitcoin-S act like `Secp256k1Context.isEnabled()` has returned false.
|
||||
2. Call Bouncy castle methods in `ECKey`.
|
||||
|
||||
Here is an example of calling bouncy castle methods in `ECKey`
|
||||
|
||||
```scala
|
||||
val privKey = ECPrivateKey.freshPrivateKey
|
||||
// privKey: ECPrivateKey = Masked(ECPrivateKey)
|
||||
// calls bouncy castle indirectly via CryptoContext
|
||||
val publicKey = privKey.publicKey
|
||||
// publicKey: ECPublicKey = ECPublicKey(03f1ed491e36174a5b4386414627bf647cefefbac9bef5ee656683ef37b4d46574)
|
||||
val dataToSign = DoubleSha256Digest.empty
|
||||
// dataToSign: DoubleSha256Digest = DoubleSha256Digest(0000000000000000000000000000000000000000000000000000000000000000)
|
||||
|
||||
// calls bouncy castle indirectly via CryptoContext
|
||||
val signature = privKey.sign(dataToSign.bytes)
|
||||
// signature: ECDigitalSignature = ECDigitalSignature(3045022100b945f4cc13bfb778c18431f9404e7979790edf15bd7d8c24ff1b2225f3f9f4f002200bbe5dd069dd80ebbb642c051be8c3859a2dd6926aed338c3e9ab6fe4986428e)
|
||||
|
||||
// calls bouncy castle indirectly via CryptoContext
|
||||
val verified = publicKey.verify(dataToSign.bytes, signature)
|
||||
// verified: Boolean = true
|
||||
|
||||
println(s"Verified with bouncy castle=${verified}")
|
||||
// Verified with bouncy castle=true
|
||||
```
|
||||
|
||||
### Building libsecp256k1
|
||||
|
||||
[See instructions here](add-to-jni.md#adding-to-bitcoin-s)
|
||||
171
website/versioned_docs/version-1.8.0/tor/tor.md
Normal file
171
website/versioned_docs/version-1.8.0/tor/tor.md
Normal file
|
|
@ -0,0 +1,171 @@
|
|||
---
|
||||
id: version-1.8.0-tor
|
||||
title: Tor Setup
|
||||
original_id: tor
|
||||
---
|
||||
|
||||
It is possible to run Bitcoin-S through tor.
|
||||
[Tor](https://www.torproject.org/) is an onion routed private network that allows us to send and receive messages in an
|
||||
anonymous manner. Using tor in conjunction with Bitcoin-S allows you to be more private when syncing the blockchain, as
|
||||
well as allows for sending and receiving DLC messages without the need for a static IP address or opening/forwarding of
|
||||
ports.
|
||||
|
||||
## Installing Tor
|
||||
|
||||
### Debian
|
||||
|
||||
You can install tor using `sudo apt install tor` if on a debian system.
|
||||
|
||||
After installing you can start it with `sudo systemctl start tor`
|
||||
|
||||
### Brew
|
||||
|
||||
You can install tor using `brew install tor` if on a mac osx system.
|
||||
|
||||
After installing you can start it with `brew services start tor`
|
||||
|
||||
### Other
|
||||
|
||||
Otherwise, you can install the Tor Browser from [here](https://www.torproject.org/download/).
|
||||
|
||||
## Starting Tor
|
||||
|
||||
To connect to onion addresses you need to enable the tor proxy. To do so you need to have tor currently running, this
|
||||
can be checked by using the command `sudo systemctl status tor`. This should give you an output similar to:
|
||||
|
||||
```bash
|
||||
$ sudo systemctl status tor
|
||||
● tor.service - Anonymizing overlay network for TCP (multi-instance-master)
|
||||
Loaded: loaded (/lib/systemd/system/tor.service; enabled; vendor preset: enabled)
|
||||
Active: active (exited) since Wed 2021-07-28 13:06:42 CDT; 48min ago
|
||||
Main PID: 804 (code=exited, status=0/SUCCESS)
|
||||
Tasks: 0 (limit: 18696)
|
||||
Memory: 0B
|
||||
CGroup: /system.slice/tor.service
|
||||
```
|
||||
|
||||
If the output says `Active: active`, then it is running and good to go.
|
||||
|
||||
On mac osx you can use the command `brew services list` to ensure tor is running. This should give you an output similar to:
|
||||
|
||||
```bash
|
||||
$ brew services list
|
||||
Name Status User Plist
|
||||
tor started $username /Users/username/Library/LaunchAgents/homebrew.mxcl.tor.plist
|
||||
```
|
||||
|
||||
If tor satus is `started`, then it is running and good to go.
|
||||
|
||||
## Enabling the Tor proxy
|
||||
|
||||
Enabling the tor proxy allows you to create outgoing connections over tor. This is needed if you want to sync the
|
||||
blockchain over tor, or to accept DLCs over tor.
|
||||
|
||||
To enable the tor proxy you simply need to set a couple config options after you have tor running.
|
||||
|
||||
You need to enable the proxy and set the host and port configuration options. If you are using the default settings you
|
||||
should only need to set `bitcoin-s.proxy.enabled = true`.
|
||||
These modifications need to be made to `$HOME/.bitcoin-s/bitcoin-s.conf` file.
|
||||
Create this file if it does not exist.
|
||||
|
||||
```$xslt
|
||||
bitcoin-s {
|
||||
proxy {
|
||||
# You can configure SOCKS5 proxy to use Tor for outgoing connections
|
||||
enabled = true
|
||||
sock5 = "127.0.0.1:9050"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Creating our own Tor hidden service
|
||||
|
||||
Enabling the tor hidden services allows for inbound connections over tor.
|
||||
This is needed if you want to create DLCs over tor.
|
||||
|
||||
To enable the tor hidden services you need to set a couple config options after you have tor running in your bitcoin-s
|
||||
config, as well as have tor configured for it.
|
||||
|
||||
### Configuring Tor
|
||||
|
||||
You may need to set up the Tor Control Port. On Linux distributions there may be some or all of the following settings
|
||||
in `/etc/tor/torrc` for linux or `/opt/homebrew/etc/tor/torrc` for mac, generally commented out by default (if not, add
|
||||
them):
|
||||
|
||||
```
|
||||
ControlPort 9051
|
||||
CookieAuthentication 1
|
||||
CookieAuthFileGroupReadable 1
|
||||
```
|
||||
|
||||
Add or uncomment those, save, and restart Tor (usually `systemctl restart tor`
|
||||
or `sudo systemctl restart tor` on most systemd-based systems, including recent Debian and Ubuntu, `brew services restart tor` on mac osx, or just restart the
|
||||
computer).
|
||||
|
||||
On some systems (such as Arch Linux), you may also need to add the following line:
|
||||
|
||||
```
|
||||
DataDirectoryGroupReadable 1
|
||||
```
|
||||
|
||||
You may also need permissions for the auth cookie file, this can be done doing
|
||||
|
||||
```bash
|
||||
sudo usermod -a -G debian-tor $USER
|
||||
```
|
||||
or on mac
|
||||
```
|
||||
sudo chmod 755 /usr/local/var/tor
|
||||
```
|
||||
|
||||
After changing these settings, you will need to restart your computer.
|
||||
|
||||
### Optional Settings
|
||||
If you experience repeated connection issues make sure to check the bitcoin-s.log file. If the logs show that Bitcoin-s is able to connect through the tor proxy (`connected to neutrino.suredbits.com/:8333 via SOCKS5 proxy /127.0.0.1:9050`) but is not able to connect through the tor controller (`TorController refused to connect` or similar) you may need to make additional changes to your torrc file. Find the location of your tor control_auth_cookie file and add the pathname for this file to your torrc file as show below.
|
||||
For mac osx:
|
||||
```
|
||||
CookieAuthFile /usr/local/var/tor/control_auth_cookie
|
||||
```
|
||||
|
||||
### Configuring Bitcoin-S
|
||||
|
||||
You need to enable tor and set the control option, `127.0.0.1:9051` is the default. If you are using the default
|
||||
settings you should only need to set `bitcoin-s.tor.enabled = true`.
|
||||
These modifications need to be made to `$HOME/.bitcoin-s/bitcoin-s.conf` file.
|
||||
Create this file if it does not exist.
|
||||
|
||||
```$xslt
|
||||
bitcoin-s {
|
||||
tor {
|
||||
# You can enable Tor for incoming connections
|
||||
enabled = true
|
||||
control = "127.0.0.1:9051"
|
||||
|
||||
# The password used to arrive at the HashedControlPassword for the control port.
|
||||
# If provided, the HASHEDPASSWORD authentication method will be used instead of
|
||||
# the SAFECOOKIE one.
|
||||
# password = securePassword
|
||||
|
||||
# The path to the private key of the onion service being created
|
||||
# privateKeyPath = /path/to/priv/key
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Manually Creating a Tor Hidden Service
|
||||
|
||||
Alternatively, you can manually create a tor hidden service.
|
||||
|
||||
You can also manually configure your node to be reachable from the Tor network. Add these lines to
|
||||
your `/etc/tor/torrc` (or equivalent config file, mac is located at `/opt/homebrew/etc/tor/torrc`):
|
||||
|
||||
```
|
||||
HiddenServiceDir /var/lib/tor/dlc-service/
|
||||
HiddenServicePort 2862 127.0.0.1:2862
|
||||
```
|
||||
|
||||
Then to get your host address simply do this after restarting your tor daemon.
|
||||
|
||||
```bash
|
||||
sudo cat /var/lib/tor/dlc-service/hostname
|
||||
```
|
||||
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
title: Wallet Callbacks
|
||||
id: version-1.8.0-wallet-callbacks
|
||||
original_id: wallet-callbacks
|
||||
---
|
||||
|
||||
#### Callbacks
|
||||
|
||||
Bitcoin-S support call backs for the following events that happen in the wallet:
|
||||
|
||||
1. onTransactionProcessed
|
||||
2. onTransactionBroadcast
|
||||
3. onReservedUtxos
|
||||
4. onNewAddressGenerated
|
||||
|
||||
That means every time one of these events happens, we will call your callback
|
||||
so that you can be notified of the event. These callbacks will be run after the message has been
|
||||
recieved and will execute synchronously. If any of them fail an error log will be output, and the remainder of the callbacks will continue.
|
||||
Let's make an easy one:
|
||||
|
||||
#### Example
|
||||
|
||||
Here is an example of constructing a wallet and registering a callback, so you can be notified of an event.
|
||||
|
||||
|
||||
```scala
|
||||
implicit val system: ActorSystem = ActorSystem("example")
|
||||
implicit val ec: ExecutionContextExecutor = system.dispatcher
|
||||
implicit val walletConf: WalletAppConfig =
|
||||
BitcoinSTestAppConfig.getNeutrinoTestConfig(Vector.empty).walletConf
|
||||
|
||||
// let's use a helper method to get a v19 bitcoind
|
||||
// and a ChainApi
|
||||
val bitcoind = BitcoindV19RpcClient(BitcoindInstance.fromConfigFile())
|
||||
val aesPasswordOpt = Some(AesPassword.fromString("password"))
|
||||
|
||||
// Create our key manager
|
||||
val keyManagerE = BIP39KeyManager.initialize(aesPasswordOpt = aesPasswordOpt,
|
||||
kmParams = walletConf.kmParams,
|
||||
bip39PasswordOpt = None)
|
||||
|
||||
val keyManager = keyManagerE match {
|
||||
case Right(keyManager) => keyManager
|
||||
case Left(err) =>
|
||||
throw new RuntimeException(s"Cannot initialize key manager err=$err")
|
||||
}
|
||||
|
||||
// Here is a super simple example of a callback, this could be replaced with anything, from
|
||||
// relaying the transaction on the network, finding relevant wallet outputs, verifying the transaction,
|
||||
// or writing it to disk
|
||||
val exampleProcessTx: OnTransactionProcessed = (tx: Transaction) =>
|
||||
Future.successful(println(s"Processed Tx: ${tx.txIdBE}"))
|
||||
|
||||
// Create our WalletCallbacks that
|
||||
val exampleCallbacks = WalletCallbacks(
|
||||
onTransactionProcessed = Vector(exampleProcessTx))
|
||||
|
||||
// Now we can create a wallet
|
||||
val wallet =
|
||||
Wallet(keyManager = keyManager,
|
||||
nodeApi = bitcoind,
|
||||
chainQueryApi = bitcoind,
|
||||
feeRateApi = ConstantFeeRateProvider(SatoshisPerVirtualByte.one),
|
||||
creationTime = Instant.now)
|
||||
|
||||
// Finally, we can add the callbacks to our wallet config
|
||||
walletConf.addCallbacks(exampleCallbacks)
|
||||
|
||||
// Then to trigger the event we can run
|
||||
val exampleTx = Transaction(
|
||||
"0200000000010258e87a21b56daf0c23be8e7070456c336f7cbaa5c8757924f545887bb2abdd7500000000da00473044022074018ad4180097b873323c0015720b3684cc8123891048e7dbcd9b55ad679c99022073d369b740e3eb53dcefa33823c8070514ca55a7dd9544f157c167913261118c01483045022100f61038b308dc1da865a34852746f015772934208c6d24454393cd99bdf2217770220056e675a675a6d0a02b85b14e5e29074d8a25a9b5760bea2816f661910a006ea01475221029583bf39ae0a609747ad199addd634fa6108559d6c5cd39b4c2183f1ab96e07f2102dab61ff49a14db6a7d02b0cd1fbb78fc4b18312b5b4e54dae4dba2fbfef536d752aeffffffff838d0427d0ec650a68aa46bb0b098aea4422c071b2ca78352a077959d07cea1d01000000232200208c2353173743b595dfb4a07b72ba8e42e3797da74e87fe7d9d7497e3b2028903ffffffff0270aaf00800000000160014d85c2b71d0060b09c9886aeb815e50991dda124d00e1f5050000000016001400aea9a2e5f0f876a588df5546e8742d1d87008f000400473044022062eb7a556107a7c73f45ac4ab5a1dddf6f7075fb1275969a7f383efff784bcb202200c05dbb7470dbf2f08557dd356c7325c1ed30913e996cd3840945db12228da5f01473044022065f45ba5998b59a27ffe1a7bed016af1f1f90d54b3aa8f7450aa5f56a25103bd02207f724703ad1edb96680b284b56d4ffcb88f7fb759eabbe08aa30f29b851383d20147522103089dc10c7ac6db54f91329af617333db388cead0c231f723379d1b99030b02dc21023add904f3d6dcf59ddb906b0dee23529b7ffb9ed50e5e86151926860221f0e7352ae00000000")
|
||||
wallet.processTransaction(exampleTx, None)
|
||||
```
|
||||
108
website/versioned_docs/version-1.8.0/wallet/wallet-rescan.md
Normal file
108
website/versioned_docs/version-1.8.0/wallet/wallet-rescan.md
Normal file
|
|
@ -0,0 +1,108 @@
|
|||
---
|
||||
title: Wallet Rescans
|
||||
id: version-1.8.0-wallet-rescan
|
||||
original_id: wallet-rescan
|
||||
---
|
||||
|
||||
With [BIP157](https://github.com/bitcoin/bips/blob/master/bip-0157.mediawiki) you can cache block filters locally to use
|
||||
later for rescans in the case you need to restore your wallets. Our [chain](../chain/chain.md) project gives us
|
||||
an API with the ability to query for filters.
|
||||
|
||||
### Rescan from CLI
|
||||
|
||||
To execute a rescan from the cli because you are restoring a wallet or it has gotten out of sync is fairly simple.
|
||||
|
||||
If you have an empty wallet it can be done by simply calling rescan
|
||||
```bash
|
||||
./bitcoin-s-cli rescan
|
||||
```
|
||||
|
||||
If your wallet is not empty then you will need to call it with the force command
|
||||
```bash
|
||||
./bitcoin-s-cli rescan --force
|
||||
```
|
||||
|
||||
You can also specify start and stop heights
|
||||
```bash
|
||||
./bitcoin-s-cli rescan --start <start height> --stop <stop height>
|
||||
```
|
||||
|
||||
By default, if you do not set the start height, the rescan will begin at your wallet's creation time.
|
||||
If you wish to ignore this and start from genesis use the `ignorecreationtime` flag
|
||||
```bash
|
||||
./bitcoin-s-cli rescan --ignorecreationtime
|
||||
```
|
||||
|
||||
### Code Example
|
||||
|
||||
You can rescan your wallet with filters with [`WalletApi.rescanNeutrinoWallet()`](https://github.com/bitcoin-s/bitcoin-s/blob/master/core/src/main/scala/org/bitcoins/core/api/wallet/NeutrinoWalletApi.scala#L77)
|
||||
|
||||
To run this example you need to make sure you have access to a bitcoind binary.
|
||||
You can download this with bitcoin-s by doing `sbt downloadBitcoind`
|
||||
|
||||
|
||||
```scala
|
||||
//we need an actor system and app config to power this
|
||||
implicit val system: ActorSystem = ActorSystem(s"wallet-rescan-example")
|
||||
implicit val ec: ExecutionContext = system.dispatcher
|
||||
implicit val appConfig: BitcoinSAppConfig = BitcoinSTestAppConfig.getNeutrinoTestConfig(Vector.empty)
|
||||
implicit val walletAppConfig: WalletAppConfig = appConfig.walletConf
|
||||
|
||||
val bip39PasswordOpt = None
|
||||
//ok now let's spin up a bitcoind and a bitcoin-s wallet with funds in it
|
||||
val walletWithBitcoindF = for {
|
||||
bitcoind <- BitcoinSFixture.createBitcoindWithFunds()
|
||||
walletWithBitcoind <- BitcoinSWalletTest.createWalletWithBitcoindCallbacks(bitcoind, bip39PasswordOpt)
|
||||
} yield walletWithBitcoind
|
||||
|
||||
val walletF = walletWithBitcoindF.map(_.wallet)
|
||||
|
||||
val bitcoindF = walletWithBitcoindF.map(_.bitcoind)
|
||||
|
||||
//let's see what our initial wallet balance is
|
||||
val initBalanceF = for {
|
||||
w <- walletF
|
||||
balance <- w.getBalance()
|
||||
} yield {
|
||||
println(s"Initial wallet balance=${balance}")
|
||||
balance
|
||||
}
|
||||
|
||||
//ok great! We have money in the wallet to start,
|
||||
//now let's delete our internal tables that hold our utxos
|
||||
//and addresses so that we end up with a 0 balance
|
||||
val clearedWalletF = for {
|
||||
w <- walletF
|
||||
_ <- initBalanceF
|
||||
clearedWallet <- w.clearAllUtxosAndAddresses()
|
||||
zeroBalance <- clearedWallet.getBalance()
|
||||
} yield {
|
||||
println(s"Balance after clearing utxos: ${zeroBalance}")
|
||||
clearedWallet
|
||||
}
|
||||
|
||||
//we need to pick how many addresses we want to generate off of our keychain
|
||||
//when doing a rescan, this means we are generating 100 addrsses
|
||||
//and then looking for matches. If we find a match, we generate _another_
|
||||
//100 fresh addresses and search those. We keep doing this until we find
|
||||
//100 addresses that do not contain a match.
|
||||
val addrBatchSize = 100
|
||||
//ok now that we have a cleared wallet, we need to rescan and find our fudns again!
|
||||
val rescannedBalanceF = for {
|
||||
w <- clearedWalletF
|
||||
_ <- w.fullRescanNeutrinoWallet(addrBatchSize)
|
||||
balanceAfterRescan <- w.getBalance()
|
||||
} yield {
|
||||
println(s"Wallet balance after rescan: ${balanceAfterRescan}")
|
||||
()
|
||||
}
|
||||
|
||||
//cleanup
|
||||
val cleanupF = for {
|
||||
_ <- rescannedBalanceF
|
||||
walletWithBitcoind <- walletWithBitcoindF
|
||||
_ <- BitcoinSWalletTest.destroyWalletWithBitcoind(walletWithBitcoind)
|
||||
} yield ()
|
||||
|
||||
Await.result(cleanupF, 60.seconds)
|
||||
```
|
||||
106
website/versioned_docs/version-1.8.0/wallet/wallet-sync.md
Normal file
106
website/versioned_docs/version-1.8.0/wallet/wallet-sync.md
Normal file
|
|
@ -0,0 +1,106 @@
|
|||
---
|
||||
title: Wallet Sync
|
||||
id: version-1.8.0-wallet-sync
|
||||
original_id: wallet-sync
|
||||
---
|
||||
|
||||
## High level wallet state
|
||||
|
||||
Our wallet infrastructure has a specific table called `state_descriptors`.
|
||||
This tracks chain state for our wallet.
|
||||
Here is an example of the contents of this table
|
||||
|
||||
>sqlite> select * from state_descriptors;
|
||||
SyncHeight|0000000000000000000134aa9e949ea1d053042b8dfa59bdc73b0322a88f009e 665741
|
||||
|
||||
If you look carefully in the second column, you will see a string encoding indicating
|
||||
what the wallet state is. In this case, the last block hash seen by the wallet is
|
||||
|
||||
>0000000000000000000134aa9e949ea1d053042b8dfa59bdc73b0322a88f009e
|
||||
|
||||
and height
|
||||
|
||||
>665741
|
||||
|
||||
If you have access to a wallet, you can call
|
||||
|
||||
[`wallet.getSyncDescriptorOpt`](https://github.com/bitcoin-s/bitcoin-s/blob/36b5fc142715f8ab3ad053465d53dc29ab319790/wallet/src/main/scala/org/bitcoins/wallet/Wallet.scala#L160) to get access to this information
|
||||
|
||||
#### Wallet state from the cli
|
||||
|
||||
Alternatively, you can retrieve this information with `bitcoin-s-cli`
|
||||
|
||||
```
|
||||
./bitcoin-s-cli walletinfo
|
||||
{
|
||||
"wallet": {
|
||||
"keymanager": {
|
||||
"rootXpub": "..."
|
||||
},
|
||||
"xpub": "...",
|
||||
"hdPath": "...",
|
||||
"height": 1906239,
|
||||
"blockHash": "00000000dcf1066b8cd764a6104a9b5e95a55cd31adf9107974b2581ac90fdb9"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Syncing a wallet
|
||||
|
||||
Bitcoin-s provides a utility object called [`WalletSync`](https://github.com/bitcoin-s/bitcoin-s/blob/f3e81d027dfdda79e26642d5c29d381874ee72da/wallet/src/main/scala/org/bitcoins/wallet/sync/WalletSync.scala#L10)
|
||||
that provides useful utilities for syncing a bitcoin-s wallet.
|
||||
|
||||
### Syncing wallet for with access to full blocks
|
||||
|
||||
Inside of `WalletSync` we have a method called [`WalletSync.syncFullBlocks`](https://github.com/bitcoin-s/bitcoin-s/blob/f3e81d027dfdda79e26642d5c29d381874ee72da/wallet/src/main/scala/org/bitcoins/wallet/sync/WalletSync.scala#L18)
|
||||
This method takes 4 parameters
|
||||
|
||||
- a [Wallet](https://github.com/bitcoin-s/bitcoin-s/blob/36b5fc142715f8ab3ad053465d53dc29ab319790/wallet/src/main/scala/org/bitcoins/wallet/Wallet.scala#L46) to sync
|
||||
- `getBlockHeaderFunc` is a function to retrieve a block header based on a blockHash
|
||||
- `getBestBlockHashFunc` is a function to retrieve the best block hash for our blockchain
|
||||
- `getBlockFunc` is a function to retrieve a full [`Block`](https://github.com/bitcoin-s/bitcoin-s/blob/8a148357d560a40bf21e7c0e3f4074cd276534fe/core/src/main/scala/org/bitcoins/core/protocol/blockchain/Block.scala#L18) that corresponds to a block hash
|
||||
|
||||
Given these for things, we can use [`WalletSync.syncFullBlocks`](https://github.com/bitcoin-s/bitcoin-s/blob/f3e81d027dfdda79e26642d5c29d381874ee72da/wallet/src/main/scala/org/bitcoins/wallet/sync/WalletSync.scala#L18) to sync our entire wallet.
|
||||
|
||||
Here is a code example
|
||||
|
||||
|
||||
```scala
|
||||
implicit val system: ActorSystem = ActorSystem(s"wallet-sync-example")
|
||||
implicit val ec: ExecutionContext = system.dispatcher
|
||||
|
||||
// this reads authentication credentials and
|
||||
// connection details from the default data
|
||||
// directory on your platform
|
||||
val client = BitcoindRpcClient.fromDatadir(binary=new File("/path/to/bitcoind"), datadir=new File("/path/to/bitcoind-datadir"))
|
||||
|
||||
//yay! Now we have a started bitcoind.
|
||||
//We will use this as our datasource for syncing our wallet
|
||||
val bitcoindRpcClientF: Future[BitcoindRpcClient] = client.start()
|
||||
|
||||
|
||||
//wait for bitcoind to get started
|
||||
val bitcoind = Await.result(bitcoindRpcClientF, 10.seconds)
|
||||
|
||||
val getBestBlockHashFunc = () => bitcoind.getBestBlockHash
|
||||
|
||||
val getBlockHeaderFunc = { hash: DoubleSha256DigestBE => bitcoind.getBlockHeaderRaw(hash) }
|
||||
|
||||
val getBlockFunc = {hash: DoubleSha256DigestBE => bitcoind.getBlockRaw(hash) }
|
||||
|
||||
//yay! We are now all setup. Using our 3 functions above and a wallet, we can now sync
|
||||
//a fresh wallet
|
||||
implicit val walletAppConfig = WalletAppConfig.fromDefaultDatadir()
|
||||
implicit val kmAppConfig = KeyManagerAppConfig.fromDefaultDatadir()
|
||||
val keyManager: BIP39KeyManager = {
|
||||
BIP39KeyManager.fromParams(walletAppConfig.kmParams,None,None).right.get
|
||||
}
|
||||
val feeRateProvider: FeeRateApi = MempoolSpaceProvider.fromBlockTarget(6, proxyParams = None)
|
||||
val wallet = Wallet(keyManager, bitcoind, bitcoind, feeRateProvider, keyManager.creationTime)
|
||||
|
||||
//yay! we have a synced wallet
|
||||
val syncedWalletF = WalletSync.syncFullBlocks(wallet,
|
||||
getBlockHeaderFunc,
|
||||
getBestBlockHashFunc,
|
||||
getBlockFunc)
|
||||
```
|
||||
98
website/versioned_sidebars/version-1.8.0-sidebars.json
Normal file
98
website/versioned_sidebars/version-1.8.0-sidebars.json
Normal file
|
|
@ -0,0 +1,98 @@
|
|||
{
|
||||
"version-1.8.0-docs": {
|
||||
"Getting Started": [
|
||||
"version-1.8.0-getting-started",
|
||||
"version-1.8.0-bips"
|
||||
],
|
||||
"Getting Setup": [
|
||||
"version-1.8.0-getting-setup"
|
||||
],
|
||||
"Applications": [
|
||||
"version-1.8.0-applications/cli",
|
||||
"version-1.8.0-applications/server",
|
||||
"version-1.8.0-applications/gui",
|
||||
"version-1.8.0-applications/server-systemd"
|
||||
],
|
||||
"Chain": [
|
||||
"version-1.8.0-chain/chain",
|
||||
"version-1.8.0-chain/filter-sync",
|
||||
"version-1.8.0-chain/chain-query-api"
|
||||
],
|
||||
"Configuration": [
|
||||
"version-1.8.0-config/configuration"
|
||||
],
|
||||
"Core Module": [
|
||||
"version-1.8.0-core/core-intro",
|
||||
"version-1.8.0-core/addresses",
|
||||
"version-1.8.0-core/hd-keys",
|
||||
"version-1.8.0-core/adding-spks",
|
||||
"version-1.8.0-core/spending-info",
|
||||
"version-1.8.0-core/psbts",
|
||||
"version-1.8.0-core/dlc",
|
||||
"version-1.8.0-core/txbuilder",
|
||||
"version-1.8.0-core/lightning-network"
|
||||
],
|
||||
"Crypto Module": [
|
||||
"version-1.8.0-crypto/crypto-intro",
|
||||
"version-1.8.0-crypto/sign",
|
||||
"version-1.8.0-crypto/adaptor-signatures"
|
||||
],
|
||||
"Fee Provider": [
|
||||
"version-1.8.0-fee-provider/fee-provider"
|
||||
],
|
||||
"Key Manager": [
|
||||
"version-1.8.0-key-manager/server-key-manager",
|
||||
"version-1.8.0-key-manager/key-manager"
|
||||
],
|
||||
"Node": [
|
||||
"version-1.8.0-node/node",
|
||||
"version-1.8.0-node/node-api"
|
||||
],
|
||||
"Wallet": [
|
||||
"version-1.8.0-wallet/wallet",
|
||||
"version-1.8.0-wallet/wallet-callbacks",
|
||||
"version-1.8.0-wallet/wallet-get-address",
|
||||
"version-1.8.0-wallet/address-tagging",
|
||||
"version-1.8.0-wallet/dlc",
|
||||
"version-1.8.0-wallet/wallet-rescan",
|
||||
"version-1.8.0-wallet/wallet-sync",
|
||||
"version-1.8.0-wallet/wallet-rpc",
|
||||
"version-1.8.0-wallet/backups",
|
||||
"version-1.8.0-wallet/wallet-election-example",
|
||||
"version-1.8.0-wallet/wallet-price-example"
|
||||
],
|
||||
"Tor": [
|
||||
"version-1.8.0-tor/tor"
|
||||
],
|
||||
"RPC Clients": [
|
||||
"version-1.8.0-rpc/rpc-clients-intro",
|
||||
"version-1.8.0-rpc/rpc-eclair",
|
||||
"version-1.8.0-rpc/rpc-bitcoind",
|
||||
"version-1.8.0-rpc/lnd-rpc"
|
||||
],
|
||||
"Secp256k1": [
|
||||
"version-1.8.0-secp256k1/secp256k1",
|
||||
"version-1.8.0-secp256k1/jni-modify"
|
||||
],
|
||||
"Testkit": [
|
||||
"version-1.8.0-testkit/testkit",
|
||||
"version-1.8.0-testkit/testkit-core"
|
||||
],
|
||||
"DLC Oracle": [
|
||||
"version-1.8.0-oracle/build-oracle-server",
|
||||
"version-1.8.0-oracle/oracle-server",
|
||||
"version-1.8.0-oracle/oracle-election-example",
|
||||
"version-1.8.0-oracle/oracle-price-example"
|
||||
],
|
||||
"Oracle Explorer Client": [
|
||||
"version-1.8.0-oracle-explorer-client/oracle-explorer-client"
|
||||
],
|
||||
"Contributing": [
|
||||
"version-1.8.0-contributing",
|
||||
"version-1.8.0-contributing-website"
|
||||
],
|
||||
"Security": [
|
||||
"version-1.8.0-security"
|
||||
]
|
||||
}
|
||||
}
|
||||
|
|
@ -1,4 +1,5 @@
|
|||
[
|
||||
"1.8.0",
|
||||
"1.7.0",
|
||||
"0.6.0",
|
||||
"0.5.0",
|
||||
|
|
|
|||
Loading…
Add table
Reference in a new issue