<!DOCTYPE html><htmllang="en"><head><metacharSet="utf-8"/><metahttp-equiv="X-UA-Compatible"content="IE=edge"/><title>Core module · bitcoin-s</title><metaname="viewport"content="width=device-width, initial-scale=1.0"/><metaname="generator"content="Docusaurus"/><metaname="description"content="The `core` module is the core (duh!) functionality of Bitcoin-S. The goal is to provide basic"/><metaname="docsearch:version"content="0.1.0"/><metaname="docsearch:language"content="en"/><metaproperty="og:title"content="Core module · bitcoin-s"/><metaproperty="og:type"content="website"/><metaproperty="og:url"content="https://bitcoin-s.org/"/><metaproperty="og:description"content="The `core` module is the core (duh!) functionality of Bitcoin-S. The goal is to provide basic"/><metaproperty="og:image"content="https://bitcoin-s.org/img/undraw_online.svg"/><metaname="twitter:card"content="summary"/><metaname="twitter:image"content="https://bitcoin-s.org/img/undraw_tweetstorm.svg"/><linkrel="shortcut icon"href="/img/favicon.ico"/><linkrel="stylesheet"href="https://cdn.jsdelivr.net/docsearch.js/1/docsearch.min.css"/><linkrel="stylesheet"href="//cdnjs.cloudflare.com/ajax/libs/highlight.js/9.12.0/styles/default.min.css"/><script>
</script></nav></div><divclass="container mainContainer docsContainer"><divclass="wrapper"><divclass="post"><headerclass="postHeader"><aclass="edit-page-link button"href="https://github.com/bitcoin-s/bitcoin-s/blob/master/docs/core/core-intro.md"target="_blank"rel="noreferrer noopener">Edit</a><h1id="__docusaurus"class="postHeaderTitle">Core module</h1></header><article><div><span><p>The <code>core</code> module is the core (duh!) functionality of Bitcoin-S. The goal is to provide basic
<p>Every bitcoin protocol data structure (and some other data structures) extends <ahref="/api/org/bitcoins/core/protocol/NetworkElement"><code>NetworkElement</code></a>. <code>NetworkElement</code> provides methods to convert the data structure to hex or byte representation. When paired with <ahref="/api/org/bitcoins/core/util/Factory"><code>Factory</code></a> we can easily serialize and deserialize data structures.</p>
<p>Most data structures have companion objects that extends <code>Factory</code> to be able to easily create protocol data structures. An example of this is the <ahref="/api/org/bitcoins/core/protocol/script/ScriptPubKey"><code>ScriptPubKey</code></a> companion object. You can use this companion object to create a <code>ScriptPubKey</code> from a hex string or a byte array.</p>
<li><ahref="/api/org/bitcoins/core/protocol"><code>protocol</code></a> - basic protocol data structures. Useful for serializing/deserializing things</li>
<li><ahref="/api/org/bitcoins/core/crypto"><code>crypto</code></a> - cryptograhic functionality used in Bitcoin and Lightning</li>
<li><ahref="/api/org/bitcoins/core/script"><code>script</code></a> - an implementation of <ahref="https://en.bitcoin.it/wiki/Script">Script</a> - the programming language in Bitcoin</li>
<li><ahref="/api/org/bitcoins/core/wallet"><code>wallet</code></a> - implements signing logic for Bitcoin transactions. This module is not named well as there is <strong>NO</strong> functionality to persist wallet state to disk as it stands. This will most likely be renamed in the future.</li>
<li><ahref="/api/org/bitcoins/core/config"><code>config</code></a> - Contains information about a chain's genesis block and DNS seeds</li>
<li><ahref="/api/org/bitcoins/core/number"><code>number</code></a> - Implements number types that are native in C, i.e. <code>UInt8</code>, <code>UInt32</code>, <code>UInt64</code>, etc.</li>
<li><ahref="/api/org/bitcoins/core/currency"><code>currency</code></a> - Implements currency units in the Bitcoin protocol</li>
<li><ahref="/api/org/bitcoins/core/bloom"><code>bloom</code></a> - Implements <ahref="https://en.wikipedia.org/wiki/Bloom_filter">Bloom filters</a> and <ahref="https://bitcoin.org/en/glossary/merkle-block">merkle blocks</a> needed for <ahref="https://github.com/bitcoin/bips/blob/master/bip-0037.mediawiki">BIP37</a></li>
<li><ahref="/api/org/bitcoins/core/hd"><code>hd</code></a> - Contains implementations of hierarchical deterministic (HD) paths, that when combined with <code>ExtPrivKey</code> and <code>ExtPubKey</code> in <code>crypto</code> can implement BIP32, BIP44, BIP49 and BIP84.</li>
<p>This gives us an example of a hex encoded Bitcoin transaction that is deserialized to a native Scala object called a <ahref="/api/org/bitcoins/core/protocol/transaction/Transaction"><code>Transaction</code></a>. You could also serialize the transaction to bytes using <code>tx.bytes</code> instead of <code>tx.hex</code>. These methods are available on every data structure that extends NetworkElement, like <ahref="/api/org/bitcoins/core/crypto/ECPrivateKey"><code>ECPrivateKey</code></a>, <ahref="/api/org/bitcoins/core/protocol/script/ScriptPubKey"><code>ScriptPubKey</code></a>, <ahref="/api/org/bitcoins/core/protocol/script/ScriptWitness"><code>ScriptWitness</code></a>, and <ahref="/api/org/bitcoins/core/protocol/blockchain/Block"><code>Block</code></a>.</p>
<p>Bitcoin Core supports building unsigned transactions and then signing them with a set of private keys. The first important thing to look at is <ahref="/api/org/bitcoins/core/wallet/utxo/UTXOSpendingInfo"><code>UTXOSpendingInfo</code></a>. This contains all of the information needed to create a validly signed <ahref="/api/org/bitcoins/core/protocol/script/ScriptSignature"><code>ScriptSignature</code></a> that spends this output.</p>
<p>Our <ahref="/api/org/bitcoins/core/wallet/builder/TxBuilder"><code>TxBuilder</code></a> class requires you to provide the following:</p>
<ol>
<li><code>destinations</code> - the places we are sending bitcoin to. These are <ahref="/api/org/bitcoins/core/protocol/transaction/TransactionOutput">TransactionOutputs</a> you are sending coins too</li>
<li><code>utxos</code> - these are the <ahref="/api/org/bitcoins/core/wallet/utxo/UTXOSpendingInfo">UTXOs</a> used to fund your transaction. These must exist in your wallet, and you must know how to spend them (i.e. have the private key)</li>
<li><code>feeRate</code> - the fee rate you want to pay for this transaction</li>
<li><code>changeSPK</code> - where the change (i.e. <code>creditingAmount - destinationAmount - fee</code>) from the transaction will be sent</li>
<li><code>network</code> - the network(/api/org/bitcoins/core/config/NetworkParameters) we are transacting on</li>
</ol>
<p>After providing this information, you can generate a validly signed bitcoin transaction by calling the <code>sign</code> method.</p>
<p>To see a complete example of this, see <ahref="/docs/0.1.0/core/txbuilder">our <code>TxBuilder</code> example</a></p>
<p>This is the API we define to sign things with. It takes in an arbitrary byte vector and returns a <code>Future[ECDigitalSignature]</code>. The reason we incorporate <code>Future</code>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.</p>
<p>The <code>ByteVector</code> that is input to the <code>signFunction</code> should be the hash that is output from <ahref="/api/org/bitcoins/core/crypto/TransactionSignatureSerializer"><code>TransactionSignatureSerializer</code></a>'s <code>hashForSignature</code> method. Our in-memory <ahref="/api/org/bitcoins/core/crypto/ECKey"><code>ECKey</code></a> types implement the <code>Sign</code> API.</p>
<p>If you wanted to implement a new <code>Sign</code> api for a hardware wallet, you can easily pass it into the <code>TxBuilder</code>/<code>Signer</code> classes to allow for you to use those devices to sign with Bitcoin-S.</p>
<p>This API is currently used to sign ordinary transactions with our <ahref="/api/org/bitcoins/core/wallet/signer/Signer"><code>Signer</code></a>s. The <code>Signer</code> subtypes (i.e. <code>P2PKHSigner</code>) implement the specific functionality needed to produce a valid digital signature for their corresponding script type.</p>
<p>Transactions are run through the interpreter to check their validity. These are packaged up into an object called <code>ScriptProgram</code>, which contains the following:</p>
<ul>
<li>The transaction that is being checked</li>
<li>The specific input index that it is checking</li>
<li>The <code>scriptPubKey</code> for the crediting transaction</li>
<li>The flags used to verify the script</li>
</ul>
<p>Here is an example of a transaction spending a <code>scriptPubKey</code> which is correctly evaluated with our interpreter implementation:</p>
