How is it structured? As of Bitcoin Core 0. A rolling average of the fee in satoshis paid per kilobyte for transactions to values confirmed within 3 to 6 blocks. Those headers bitcoin be immediately validated and values batch requested transaction until a headers message is received from the sync node with fewer than bitcoin, headerstransaction that it has no more headers to offer. There are a few different algorithms which can lead to different results.
Does that mean Alice sent Bob ten different infocoins? Attribute Type Description token string The token that created this job. Line 14 is somewhat complicated. Our Analytics API makes uncovering these patterns easy, enabling you to discover insights efficiently and programmatically. It sends these inventories in the inv message illustrated below. Bob discovers Alice paid too many satoshis. The primary disadvantage of offline wallets is hassle.
Please keep in mind that values will always be represented by hex-encoding on the blockchain, even if you transaction string as your data encoding ; to see it as your original plaintext, you have to convert it client-side. P2PKH values Alice spend satoshis to a typical Bitcoin addressand then lets Bob further spend those satoshis transaction a simple cryptographic key pair. JPE V66 6 Dec. Only returned if querying by HD wallet name instead of public address. A TXRef object represents summarized data about a transaction bitcoin or output. The same fact — no-one else could compose such a signed bitcoin — also gives Alice some limited protection from forgery.
Buy fees will be included in the created transaction and the recipient will receive the user defined amount. To create a multisig transaction, visit Multisig documentation.
Following transfers are allowed:. Lets the recipient of a money request complete the request by sending money to the user who requested the money. This can only be completed by the user to whom the request was made, not the user who sent the request. Lets a user cancel a money request. Money requests can be canceled by the sender or the recipient. Buy resource represents a purchase of bitcoin, bitcoin cash, litecoin or ethereum using a payment method either a bank or a fiat account.
Each committed buy also has an associated transaction. Buys can be started with commit: These buys will never complete and receive an associated transaction unless they are committed separately.
When using this endpoint, it is possible that our system will not be able to process the buy as normal. There are two ways to define buy amounts—you can use either the amount or the total parameter:. If you need to query the buy price without locking in the buy, you can use quote: This returns an unsaved buy and unlike commit: This option is useful when you need to show the detailed buy price quote for the user when they are filling a form or similar situation.
Sell resource represents a sell of bitcoin, bitcoin cash, litecoin or ethereum using a payment method either a bank or a fiat account.
Each committed sell also has an associated transaction. Sells can be started with commit: These sells will never complete and receive an associated transaction unless they are committed separately.
There are two ways to define sell amounts—you can use either the amount or the total parameter:. If you need to query the sell price without locking in the sell, you can use quote: This returns an unsaved sell and unlike commit: This option is useful when you need to show the detailed sell price quote for the user when they are filling a form or similar situation. Deposit resource represents a deposit of funds using a payment method e.
Each committed deposit also has an associated transaction. Deposits can be started with commit: These deposits will never complete and receive an associated transaction unless they are committed separately. Withdrawal resource represents a withdrawal of funds using a payment method e. Each committed withdrawal also has a associated transaction.
Withdrawal can be started with commit: These withdrawals will never complete and receive an associated transaction unless they are committed separately. Payment method resource represents the different kinds of payment methods that can be used when buying and selling bitcoin, bitcoin cash, litecoin or ethereum.
As fiat accounts can be used for buying and selling, they have an associated payment method. If the user has obtained optional wallet: As each one of these can have several limits you should always look for the lowest remaining value when performing the relevant action. The Order resource is used when merchants receive bitcoin payments for orders in bitcoin.
There are two representations of an order:. Creates a new merchant order. When a new order is created its amount is converted to bitcoin and the order is given a unique bitcoin address. Each order is valid for 15 minutes, during which a customer can pay for it. Each merchant order has a lifespan of 15 minutes, during which the payment can be made to the bitcoin address attached to the order. If a mispayment is made on an order, all subsequent payments to that order will be added to the array of mispayments.
If an order is paid received the correct payment on the first payment all subsequent payments to that order will be counted as mispayments. In order words, if payment 1 completes the order and then the order receives payment 2 for any arbitrary amount, only payment 2 will be in the mispayments array, and the order will keep its status as paid.
If an order expires and no payment is made then the order status is expired. If an order expires and a payment is made afterwards, the order status remains expired and the payment gets counted as a mispayment.
Refunds an order or a mispayment to an order. Returns a snapshot of the order data, updated with refund transaction details. This field is automatically present when the original incoming transaction was from a Coinbase user, or via the payment protocol. In these cases, we are able to provide a refund address automatically. Creates a new order for a checkout. This will create a new receiving bitcoin address and converts the original order amount to bitcoin.
Currency codes will conform to the ISO standard where possible. Currencies which have or had no representation in ISO may use a custom code e. Get current exchange rates. Default base currency is USD but it can be defined as any supported currency. Returned rates will define the exchange rate for one unit of the base currency. Note that exchange rates fluctuates so the price is only correct for seconds at the time.
If you need more accurate price estimate for a specific payment method or amount, see buy bitcoin endpoint and quote: If you need more accurate price estimate for a specific payment method or amount, see sell bitcoin endpoint and quote: Get the current market price for bitcoin. This is usually somewhere in between the buy and sell price. Introduction API Endpoint https: Authentication This API supports two modes of authentication: All API key requests must be signed and contain the following headers: Localization Coinbase API supports localization for error messages and other strings.
Accepted values are currently: Lists Similar to enumerable values, list values can be added or removed over time. Arguments Parameter Description limit optional Number of results per call. Default 25 order optional Result order. Now, the API returns a error with a descriptive id e. Now all codes can should lead to logging out the user. Expanding resources Show transactions curl https: Metadata Example request curl https: This information can be for example: Up to 24 keys Up to characters for the key alphanumeric characters, hyphens and underscores Up to characters for the value String, integer and boolean values only.
Decimals will be converted into strings Notifications Notification resource Example notification for new payment to a bitcoin address wallet: Each notification contains the following information: Type - Action that triggered the event Data - Data of the resource at the time of the event Additional data - Additional data associated with the event User - Owner of the resource useful with OAuth applications Account - Account of the resource Delivery information If notification delivery fails, it will be re-tried hourly up to three days.
Notification type Required permission Description ping None Ping notification can be send at any time to verify that the notification URL is functioning wallet: Related resource is available in resource key together with other available data.
Transaction types currently available: Currently available statuses are: Only available for certain types of transactions to hash, optional The receiving party of a debit transaction. Usually another resource but can also be another type like email. Only available for certain types of transactions from hash, optional The originating party of a credit transaction. Usually another resource but can also be another type like bitcoin network. Only available for certain types of transactions address hash, optional Associated bitcoin, bitcoin cash, litecoin or ethereum address for received payment application hash, optional Associated OAuth2 application List transactions Example request curl https: Fees can be added as a string, such as 0.
If a previous transaction with the same idem parameter already exists for this sender, that previous transaction will be returned and a new one will not be created. Transfer money between accounts Example request curl https: Following transfers are allowed: This will notify recipient with a new email.
There are two ways to define buy amounts—you can use either the amount or the total parameter: Use the commit call to complete it. There are two ways to define sell amounts—you can use either the amount or the total parameter: Currently available type values: There are two representations of an order: Fields Description id string Resource ID code string Client facing order code status string, enumerable Status of the order.
Refund an order Example request curl https: In order words, if payment 1 completes the order and then the order receives payment 2 for any arbitrary amount, only payment 2 will be in the mispayments array, and the order will keep its status as paid If an order expires and no payment is made then the order status is expired. Example request for mispayment curl https: There are three ways to refund an order: Use this endpoint with the mispayment parameter to refund a specific mispayment.
Use the send money endpoint to manually issue a partial refunds. If BTC , the original bitcoin amount will be sent back. If USD or another currency code if the order had a different native price , the amount of bitcoin sent back will be equivalent to the original USD value or other native value at the current exchange rate mispayment string Optional The ID of a mispayment to be refunded. Must be a valid bitcoin address. When creating a checkout ie. Once the user opens the payment page, an order object is automatically created for the checkout, with a lifespan of 15 minutes As orders expire, one checkout can have multiple orders A checkout resource can be used as a template to create orders For donations, merchants only need to have one constant checkout.
Input value must be an array of number values. You can also get historic prices with date parameter. A cursor for use in pagination. New payment has been made to a Bitcoin address. Automated merchant payout a sell has been sent to your bank account via our instant exchange feature.
Subscribing object to separate different notification subsribers in list notifications endpoint. Indicator if the transaction was instant exchanged received into a bitcoin address for a fiat account.
Information about bitcoin, bitcoin cash, litecoin or ethereum network including network transaction hash if transaction was on-blockchain. Only available for certain types of transactions. The receiving party of a debit transaction. The originating party of a credit transaction. A bitcoin address, bitcoin cash address, litecoin address, ethereum address, or an email of the recipient. Max length characters. Whether this send is to another financial institution or exchange.
The website of the financial institution or exchange. Type transfer is required when transferring bitcoin or ethereum between accounts. Status of the buy. The ID of the payment method that should be used for the buy. Whether or not you would still like to buy if you have to wait for your money to arrive to lock in a price.
If set to false , this buy will not be immediately completed. If set to true , response will return an unsave buy for detailed price quote.
Status of the sell. The ID of the payment method that should be used for the sell. Whether or not you would still like to sell if you have to wait for your money to arrive to lock in a price. If set to false , this sell will not be immediately completed. Nothing is appended if it is used with uncompressed public keys. Convert the result from a byte string into a Base58 string using Base58Check encoding. The process is easily reversible, using the Base58 decoding function, and removing the padding.
Mini private key format is a method for encoding a private key in under 30 characters, enabling keys to be embedded in a small physical space, such as physical bitcoin tokens, and more damage-resistant QR codes. In order to determine if a mini private key is well-formatted, a question mark is added to the private key. The SHA hash is calculated. This key restriction acts as a typo-checking mechanism. A user brute forces the process using random numbers until a well-formatted mini private key is produced.
In order to derive the full private key , the user simply takes a single SHA hash of the original mini private key. This process is one-way: A common tool to create and redeem these keys is the Casascius Bitcoin Address Utility. In their traditional uncompressed form, public keys contain an identification byte, a byte X coordinate, and a byte Y coordinate. Secpk1 actually modulos coordinates by a large prime, which produces a field of non-contiguous integers and a significantly less clear plot, although the principles are the same.
No data is lost by creating these compressed public keys —only a small amount of CPU is necessary to reconstruct the Y coordinate and access the uncompressed public key. Both uncompressed and compressed public keys are described in official secpk1 documentation and supported by default in the widely-used OpenSSL library. However, Bitcoin Core prior to 0. This creates a few complications, as the hashed form of an uncompressed key is different than the hashed form of a compressed key, so the same key works with two different P2PKH addresses.
For this reason, Bitcoin Core uses several different identifier bytes to help programs identify how keys should be used:. Private keys meant to be used with compressed public keys have 0x01 appended to them before being Base encoded.
See the private key encoding section above. These prefix bytes are all used in official secpk1 documentation. The hierarchical deterministic key creation and transfer protocol HD protocol greatly simplifies wallet backups, eliminates the need for repeated communication between multiple programs using the same wallet , permits creation of child accounts which can operate independently, gives each parent account the ability to monitor or control its children even if the child account is compromised, and divides each account into full-access and restricted-access parts so untrusted users or programs can be allowed to receive or monitor payments without being able to spend them.
The HD protocol takes advantage of the ECDSA public key creation function, point , which takes a large integer the private key and turns it into a graph point the public key:. This child public key is the same public key which would be created by the point function if you added the i value to the original parent private key and then found the remainder of that sum divided by a global constant used by all Bitcoin software p:. This means that two or more independent programs which agree on a sequence of integers can create a series of unique child key pairs from a single parent key pair without any further communication.
Moreover, the program which distributes new public keys for receiving payment can do so without any access to the private keys , allowing the public key distribution program to run on a possibly-insecure platform such as a public web server. Child public keys can also create their own child public keys grandchild public keys by repeating the child key derivation operations:.
Whether creating child public keys or further-descended public keys , a predictable sequence of integer values would be no better than using a single public key for all transactions, as anyone who knew one child public key could find all of the other child public keys created from the same parent public key. Instead, a random seed can be used to deterministically generate the sequence of integer values so that the relationship between the child public keys is invisible to anyone without that seed.
The HD protocol uses a single root seed to create a hierarchy of child, grandchild, and other descended keys with unlinkable deterministically-generated integer values. The parent chain code is bits of seemingly-random data. The index number is a bit integer specified by the program. In the normal form shown in the above illustration, the parent chain code , the parent public key , and the index number are fed into a one-way cryptographic hash HMAC-SHA to produce bits of deterministically-generated-but-seemingly-random data.
The seemingly-random bits on the righthand side of the hash output are used as a new child chain code. The seemingly-random bits on the lefthand side of the hash output are used as the integer value to be combined with either the parent private key or parent public key to, respectively, create either a child private key or child public key:. Specifying different index numbers will create different unlinkable child keys from the same parent keys. Repeating the procedure for the child keys using the child chain code will create unlinkable grandchild keys.
Because creating child keys requires both a key and a chain code , the key and chain code together are called the extended key. An extended private key and its corresponding extended public key have the same chain code. The top-level parent master private key and master chain code are derived from random data, as illustrated below.
A root seed is created from either bits, bits, or bits of random data. This root seed of as little as bits is the the only data the user needs to backup in order to derive every key created by a particular wallet program using particular settings. As of this writing, HD wallet programs are not expected to be fully compatible, so users must only use the same HD wallet program with the same HD-related settings for a particular root seed. The root seed is hashed to create bits of seemingly-random data, from which the master private key and master chain code are created together, the master extended private key.
The master public key is derived from the master private key using point , which, together with the master chain code , is the master extended public key. The master extended keys are functionally equivalent to other extended keys ; it is only their location at the top of the hierarchy which makes them special. Hardened extended keys fix a potential problem with normal extended keys. If an attacker gets a normal parent chain code and parent public key , he can brute-force all chain codes deriving from it.
If the attacker also obtains a child, grandchild, or further-descended private key , he can use the chain code to generate all of the extended private keys descending from that private key , as shown in the grandchild and great-grandchild generations of the illustration below. Perhaps worse, the attacker can reverse the normal child private key derivation formula and subtract a parent chain code from a child private key to recover the parent private key , as shown in the child and parent generations of the illustration above.
For this reason, the chain code part of an extended public key should be better secured than standard public keys and users should be advised against exporting even non-extended private keys to possibly-untrustworthy environments.
This can be fixed, with some tradeoffs, by replacing the the normal key derivation formula with a hardened key derivation formula. The normal key derivation formula, described in the section above, combines together the index number, the parent chain code , and the parent public key to create the child chain code and the integer value which is combined with the parent private key to create the child private key.
The hardened formula, illustrated above, combines together the index number, the parent chain code , and the parent private key to create the data used to generate the child chain code and child private key. This formula makes it impossible to create child public keys without knowing the parent private key.
Because of that, a hardened extended private key is much less useful than a normal extended private key —however, hardened extended private keys create a firewall through which multi-level key derivation compromises cannot happen. Because hardened child extended public keys cannot generate grandchild chain codes on their own, the compromise of a parent extended public key cannot be combined with the compromise of a grandchild private key to create great-grandchild extended private keys.
The HD protocol uses different index numbers to indicate whether a normal or hardened key should be generated. Index numbers from 0x00 to 0x7fffffff 0 to 2 31 -1 will generate a normal key; index numbers from 0x to 0xffffffff will generate a hardened key. Bitcoin developers typically use the ASCII apostrophe rather than the unicode prime symbol, a convention we will henceforth follow.
This compact description is further combined with slashes prefixed by m or M to indicate hierarchy and key type, with m being a private key and M being a public key. The following hierarchy illustrates prime notation and hardened key firewalls. Wallets following the BIP32 HD protocol only create hardened children of the master private key m to prevent a compromised child key from compromising the master key.
As there are no normal children for the master keys, the master public key is not used in HD wallets. All other keys can have normal children, so the corresponding extended public keys may be used instead.
The HD protocol also describes a serialization format for extended public keys and extended private keys. For details, please see the wallet section in the developer reference or BIP32 for the full HD protocol specification. Root seeds in the HD protocol are , , or bits of random data which must be backed up precisely. To make it more convenient to use non-digital backup methods, such as memorization or hand-copying, BIP39 defines a method for creating a bit root seed from a pseudo-sentence mnemonic of common natural-language words which was itself created from to bits of entropy and optionally protected by a password.
The passphrase can be of any length. It is simply appended to the mnemonic pseudo-sentence, and then both the mnemonic and password are hashed 2, times using HMAC-SHA, resulting in a seemingly-random bit seed. Because any input to the hash function creates a seemingly-random bit seed, there is no fundamental way to prove the user entered the correct password, possibly allowing the user to protect a seed even when under duress.
For implementation details, please see BIP If the wallet is encrypted, new keys are only generated while the wallet is unlocked. If a new key pair set is generated, used, and then lost prior to a backup, the stored satoshis are likely lost forever. Many older-style mobile wallets followed a similar format, but only generated a new private key upon user demand.
This wallet type is being actively phased out and discouraged from being used due to the backup hassle. Payment processing encompasses the steps spenders and receivers perform to make and accept payments in exchange for products or services. The basic steps have not changed since the dawn of commerce, but the technology has. This section will explain how receivers and spenders can, respectively, request and make payments using Bitcoin—and how they can deal with complications such as refunds and recurrent rebilling.
The following subsections will each address the three common steps and the three occasional or optional steps. It is worth mentioning that each of these steps can be outsourced by using third party APIs and services. Because of exchange rate variability between satoshis and national currencies fiat , many Bitcoin orders are priced in fiat but paid in satoshis , necessitating a price conversion.
Several organizations also aggregate data from multiple exchanges to create index prices, which are also available using HTTP-based APIs. Any applications which automatically calculate order totals using exchange rate data must take steps to ensure the price quoted reflects the current general market value of satoshis , or the applications could accept too few satoshis for the product or service being sold.
Alternatively, they could ask for too many satoshis , driving away potential spenders. To minimize problems, your applications may want to collect data from at least two separate sources and compare them to see how much they differ.
If the difference is substantial, your applications can enter a safe mode until a human is able to evaluate the situation. You may also want to program your applications to enter a safe mode if exchange rates are rapidly increasing or decreasing, indicating a possible problem in the Bitcoin market which could make it difficult to spend any satoshis received today.
Exchange rates lie outside the control of Bitcoin and related technologies, so there are no new or planned technologies which will make it significantly easier for your program to correctly convert order totals from fiat into satoshis. Because the exchange rate fluctuates over time, order totals pegged to fiat must expire to prevent spenders from delaying payment in the hope that satoshis will drop in price. Most widely-used payment processing systems currently expire their invoices after 10 to 20 minutes.
Shorter expiration periods increase the chance the invoice will expire before payment is received, possibly necessitating manual intervention to request an additional payment or to issue a refund. Longer expiration periods increase the chance that the exchange rate will fluctuate a significant amount before payment is received.
Before requesting payment, your application must create a Bitcoin address , or acquire an address from another program such as Bitcoin Core. Bitcoin addresses are described in detail in the Transactions section. Also described in that section are two important reasons to avoid using an address more than once —but a third reason applies especially to payment requests:.
Using a separate address for each incoming payment makes it trivial to determine which customers have paid their payment requests. Your applications need only track the association between a particular payment request and the address used in it, and then scan the block chain for transactions matching that address.
The next subsections will describe in detail the following four compatible ways to give the spender the address and amount to be paid. For increased convenience and compatibility, providing all of these options in your payment requests is recommended.
All wallet software lets its users paste in or manually enter an address and amount into a payment screen. This is, of course, inconvenient—but it makes an effective fallback option. Almost all desktop wallets can associate with bitcoin: URIs , so spenders can click a link to pre-fill the payment screen. This also works with many mobile wallets , but it generally does not work with web-based wallets unless the spender installs a browser extension or manually configures a URI handler.
Most mobile wallets support scanning bitcoin: URIs encoded in a QR code, and almost all wallets can display them for accepting payment. While also handy for online orders, QR Codes are especially useful for in-person purchases. Special care must be taken to avoid the theft of incoming payments. To specify an amount directly for copying and pasting, you must provide the address , the amount, and the denomination. An expiration time for the offer may also be specified.
Indicating the denomination is critical. Choosing between each unit is widely supported, but other software also lets its users select denomination amounts from some or all of the following options:. URI scheme defined in BIP21 eliminates denomination confusion and saves the spender from copying and pasting two separate values.
It also lets the payment request provide some additional information to the spender. Only the address is required, and if it is the only thing specified, wallets will pre-fill a payment request with it and let the spender enter an amount. The amount specified is always in decimal bitcoins BTC. Two other parameters are widely supported. The message parameter is generally used to describe the payment request to the spender. Both the label and the message must be URI encoded. All four parameters used together, with appropriate URI encoding, can be seen in the line-wrapped example below.
The URI scheme can be extended, as will be seen in the payment protocol section below, with both new optional and required parameters. Programs accepting URIs in any form must ask the user for permission before paying unless the user has explicitly disabled prompting as might be the case for micropayments.
QR codes are a popular way to exchange bitcoin: URIs in person, in images, or in videos. Most mobile Bitcoin wallet apps, and some desktop wallets , support scanning QR codes to pre-fill their payment screens. The figure below shows the same bitcoin: The QR code can include the label and message parameters—and any other optional parameters—but they were omitted here to keep the QR code small and easy to scan with unsteady or low-resolution mobile cameras.
The error correction is combined with a checksum to ensure the Bitcoin QR code cannot be successfully decoded with data missing or accidentally altered, so your applications should choose the appropriate level of error correction based on the space you have available to display the code.
Low-level damage correction works well when space is limited, and quartile-level damage correction helps ensure fast scanning when displayed on high-resolution screens. The payment protocol adds many important features to payment requests:. Allows spenders to submit transactions directly to receivers without going through the peer-to-peer network. This can speed up payment processing and work with planned features such as child-pays-for-parent transaction fees and offline NFC or Bluetooth-based payments.
To request payment using the payment protocol , you use an extended but backwards-compatible bitcoin: The r parameter tells payment-protocol-aware wallet programs to ignore the other parameters and fetch a PaymentRequest from the URL provided. An example CGI program and description of all the parameters which can be used in the Payment Protocol is provided in the Developer Examples Payment Protocol subsection.
In this subsection, we will briefly describe in story format how the Payment Protocol is typically used. Charlie, the client, is shopping on a website run by Bob, the businessman. An order total in satoshis , perhaps created by converting prices in fiat to prices in satoshis.
A pubkey script to which Charlie should send payment. URI for Charlie to click to pay. Charlie clicks on the bitcoin: URI in his browser. The unique public key created for the payment request can be used to create a unique identifier. It then creates a PaymentDetails message with the following information:.
The amount of the order in satoshis and the pubkey script to be paid. The time the PaymentDetails message was created plus the time it expires. That PaymentDetails message is put inside a PaymentRequest message. The Payment Protocol has been designed to allow other signing methods in the future.
Among other things, the Payment message contains:. In the case of a dispute, Charlie can generate a cryptographically-proven receipt out of the various signed or otherwise-proven information. The Bitcoin block chain can prove that the pubkey script specified by Bob was paid the specified number of satoshis. See the Refunds section below for more details.
A malicious spender can create one transaction that pays the receiver and a second one that pays the same input back to himself.
Only one of these transactions will be added to the block chain , and nobody can say for sure which one it will be. Two or more transactions spending the same input are commonly referred to as a double spend. Once the transaction is included in a block , double spends are impossible without modifying block chain history to replace the transaction, which is quite difficult. Using this system, the Bitcoin protocol can give each of your transactions an updating confidence score based on the number of blocks which would need to be modified to replace a transaction.
For each block , the transaction gains one confirmation. Since modifying blocks is quite difficult, higher confirmation scores indicate greater protection. The transaction has been broadcast but is still not included in any block. Zero confirmation transactions unconfirmed transactions should generally not be trusted without risk analysis. Although miners usually confirm the first transaction they receive, fraudsters may be able to manipulate the network into including their version of a transaction.
The transaction is included in the latest block and double-spend risk decreases dramatically. Transactions which pay sufficient transaction fees need 10 minutes on average to receive one confirmation. However, the most recent block gets replaced fairly often by accident, so a double spend is still a real possibility. The most recent block was chained to the block which includes the transaction.
As of March , two block replacements were exceedingly rare, and a two block replacement attack was impractical without expensive mining equipment. The network has spent about an hour working to protect the transaction against double spends and the transaction is buried under six blocks. Even a reasonably lucky attacker would require a large percentage of the total network hashing power to replace six blocks. Although this number is somewhat arbitrary, software handling high-value transactions, or otherwise at risk for fraud, should wait for at least six confirmations before treating a payment as accepted.
Bitcoin Core provides several RPCs which can provide your program with the confirmation score for transactions in your wallet or arbitrary transactions. For example, the listunspent RPC provides an array of every satoshi you can spend along with its confirmation score. Although confirmations provide excellent double-spend protection most of the time, there are at least three cases where double-spend risk analysis can be required:.
In the case when the program or its user cannot wait for a confirmation and wants to accept unconfirmed payments. In the case when the program or its user is accepting high value transactions and cannot wait for at least six confirmations or more.
In the case of an implementation bug or prolonged attack against Bitcoin which makes the system less reliable than expected. An interesting source of double-spend risk analysis can be acquired by connecting to large numbers of Bitcoin peers to track how transactions and blocks differ from each other. Some third-party APIs can provide you with this type of service.
For example, unconfirmed transactions can be compared among all connected peers to see if any UTXO is used in multiple unconfirmed transactions , indicating a double-spend attempt, in which case the payment can be refused until it is confirmed. Another example could be to detect a fork when multiple peers report differing block header hashes at the same block height. Your program can go into a safe mode if the fork extends for more than two blocks , indicating a possible problem with the block chain.
For more details, see the Detecting Forks subsection. Another good source of double-spend protection can be human intelligence. For example, fraudsters may act differently from legitimate customers, letting savvy merchants manually flag them as high risk.
Your program can provide a safe mode which stops automatic payment acceptance on a global or per-customer basis. Occasionally receivers using your applications will need to issue refunds. The obvious way to do that, which is very unsafe, is simply to return the satoshis to the pubkey script from which they came.
Alice wants to buy a widget from Bob, so Bob gives Alice a price and Bitcoin address. Alice opens her wallet program and sends some satoshis to that address. Bob discovers Alice paid too many satoshis.
Being an honest fellow, Bob refunds the extra satoshis to the mjSk… address. Now the refund is a unintentional donation to the company behind the centralized wallet , unless Alice opens a support ticket and proves those satoshis were meant for her. This leaves receivers only two correct ways to issue refunds:. If an address was copy-and-pasted or a basic bitcoin: URI was used, contact the spender directly and ask them to provide a refund address.
Many receivers worry that their satoshis will be less valuable in the future than they are now, called foreign exchange forex risk. If your application provides this business logic, it will need to choose which outputs to spend first. There are a few different algorithms which can lead to different results. A merge avoidance algorithm makes it harder for outsiders looking at block chain data to figure out how many satoshis the receiver has earned, spent, and saved.
When a receiver receives satoshis in an output , the spender can track in a crude way how the receiver spends those satoshis. This is called a merge , and the more a receiver merges outputs , the easier it is for an outsider to track how many satoshis the receiver has earned, spent, and saved.
Merge avoidance means trying to avoid spending unrelated outputs in the same transaction. For persons and businesses which want to keep their transaction data secret from other people, it can be an important strategy. A crude merge avoidance strategy is to try to always pay with the smallest output you have which is larger than the amount being requested.
For example, if you have four outputs holding, respectively, , , , and satoshis , you would pay a bill for satoshis with the satoshi output. This way, as long as you have outputs larger than your bills, you avoid merging. More advanced merge avoidance strategies largely depend on enhancements to the payment protocol which will allow payers to avoid merging by intelligently distributing their payments among multiple outputs provided by the receiver.
Since recent outputs are at the greatest risk of being double-spent , spending them before older outputs allows the spender to hold on to older confirmed outputs which are much less likely to be double-spent. If you spend an output from one unconfirmed transaction in a second transaction, the second transaction becomes invalid if transaction malleability changes the first transaction.
In either of the above cases, the receiver of the second transaction will see the incoming transaction notification disappear or turn into an error message.
However, after just a few blocks , a point of rapidly diminishing returns is reached. FIFO does have a small advantage when it comes to transaction fees , as older outputs may be eligible for inclusion in the 50, bytes set aside for no-fee-required high-priority transactions by miners running the default Bitcoin Core codebase.
However, with transaction fees being so low, this is not a significant advantage. The only practical use of FIFO is by receivers who spend all or most of their income within a few blocks , and who want to reduce the chance of their payments becoming accidentally invalid. Automated recurring payments are not possible with decentralized Bitcoin wallets.
Even if a wallet supported automatically sending non-reversible payments on a regular schedule, the user would still need to start the program at the appointed time, or leave it running all the time unprotected by encryption. This means automated recurring Bitcoin payments can only be made from a centralized server which handles satoshis on behalf of its spenders. In practice, receivers who want to set prices in fiat terms must also let the same centralized server choose the appropriate exchange rate.
Non-automated rebilling can be managed by the same mechanism used before credit-card recurring payments became common: In the future, extensions to the payment protocol and new wallet features may allow some wallet programs to manage a list of recurring transactions.
The spender will still need to start the program on a regular basis and authorize payment—but it should be easier and more secure for the spender than clicking an emailed invoice, increasing the chance receivers get paid on time.
Currently there are two primary methods of validating the block chain as a client: Full nodes and SPV clients. Other methods, such as server-trusting methods, are not discussed as they are not recommended. This security model assures the validity of the block chain by downloading and validating blocks from the genesis block all the way to the most recently discovered block.
Due to the computational difficulty required to generate a new block at the tip of the chain, the ability to fool a full node becomes very expensive after 6 confirmations. An alternative approach detailed in the original Bitcoin paper is a client that only downloads the headers of blocks during the initial syncing process and then requests transactions from full nodes as needed.
This scales linearly with the height of the block chain at only 80 bytes per block header , or up to 4. As described in the white paper, the merkle root in the block header along with a merkle branch can prove to the SPV client that the transaction in question is embedded in a block in the block chain. This does not guarantee validity of the transactions that are embedded. Instead it demonstrates the amount of work required to perform a double-spend attack. The SPV client knows the merkle root and associated transaction information, and requests the respective merkle branch from a full node.
Once the merkle branch has been retrieved, proving the existence of the transaction in the block , the SPV client can then look to block depth as a proxy for transaction validity and security. The cost of an attack on a user by a malicious node who inserts an invalid transaction grows with the cumulative difficulty built on top of that block , since the malicious node alone will be mining this forged chain.
If implemented naively, an SPV client has a few important weaknesses. First, while the SPV client can not be easily fooled into thinking a transaction is in a block when it is not, the reverse is not true. A full node can simply lie by omission, leading an SPV client to believe a transaction has not occurred.
This can be considered a form of Denial of Service. One mitigation strategy is to connect to a number of full nodes , and send the requests to each node. However this can be defeated by network partitioning or Sybil attacks, since identities are essentially free, and can be bandwidth intensive.
Care must be taken to ensure the client is not cut off from honest nodes. Second, the SPV client only requests transactions from full nodes corresponding to keys it owns. If the SPV client downloads all blocks and then discards unneeded ones, this can be extremely bandwidth intensive.
If they simply ask full nodes for blocks with specific transactions, this allows full nodes a complete view of the public addresses that correspond to the user.
This is a large privacy leak, and allows for tactics such as denial of service for clients, users, or addresses that are disfavored by those running full nodes , as well as trivial linking of funds. A client could simply spam many fake transaction requests, but this creates a large strain on the SPV client , and can end up defeating the purpose of thin clients altogether.
To mitigate the latter issue, Bloom filters have been implemented as a method of obfuscation and compression of block data requests.
A Bloom filter is a space-efficient probabilistic data structure that is used to test membership of an element. The data structure achieves great data compression at the expense of a prescribed false positive rate.
A Bloom filter starts out as an array of n bits all set to 0. A set of k random hash functions are chosen, each of which output a single integer between the range of 1 and n. When adding an element to the Bloom filter , the element is hashed k times separately, and for each of the k outputs, the corresponding Bloom filter bit at that index is set to 1.
Querying of the Bloom filter is done by using the same hash functions as before. If all k bits accessed in the bloom filter are set to 1, this demonstrates with high probability that the element lies in the set. Clearly, the k indices could have been set to 1 by the addition of a combination of other elements in the domain, but the parameters allow the user to choose the acceptable false positive rate.
Removal of elements can only be done by scrapping the bloom filter and re-creating it from scratch. Rather than viewing the false positive rates as a liability, it is used to create a tunable parameter that represents the desired privacy level and bandwidth trade-off.
A SPV client creates their Bloom filter and sends it to a full node using the message filterload , which sets the filter for which transactions are desired. The command filteradd allows addition of desired data to the filter without needing to send a totally new Bloom filter , and filterclear allows the connection to revert to standard block discovery mechanisms.
If the filter has been loaded, then full nodes will send a modified form of blocks , called a merkle block. The merkle block is simply the block header with the merkle branch associated with the set Bloom filter. An SPV client can not only add transactions as elements to the filter, but also public keys , data from signature scripts and pubkey scripts , and more. This enables P2SH transaction finding. If a user is more privacy-conscious, he can set the Bloom filter to include more false positives, at the expense of extra bandwidth used for transaction discovery.
If a user is on a tight bandwidth budget, he can set the false-positive rate to low, knowing that this will allow full nodes a clear view of what transactions are associated with his client.
Used in most Android wallets. Bloom filters were standardized for use via BIP Review the BIP for implementation details. There are future proposals such as Unspent Transaction Output UTXO commitments in the block chain to find a more satisfactory middle-ground for clients between needing a complete copy of the block chain , or trusting that a majority of your connected peers are not lying.
UTXO commitments would enable a very secure client using a finite amount of storage using a data structure that is authenticated in the block chain. These type of proposals are, however, in very early stages, and will require soft forks in the network. Until these types of operating modes are implemented, modes should be chosen based on the likely threat model, computing and bandwidth constraints, and liability in bitcoin value. The Bitcoin network protocol allows full nodes peers to collaboratively maintain a peer-to-peer network for block and transaction exchange.
Full nodes download and verify every block and transaction prior to relaying them to other nodes. Archival nodes are full nodes which store the entire blockchain and can serve historical blocks to other nodes. Pruned nodes are full nodes which do not store the entire blockchain. Many SPV clients also use the Bitcoin network protocol to connect to full nodes.
Consensus rules do not cover networking, so Bitcoin programs may use alternative networks and protocols, such as the high-speed block relay network used by some miners and the dedicated transaction information servers used by some wallets that provide SPV -level security.
To provide practical examples of the Bitcoin peer-to-peer network , this section uses Bitcoin Core as a representative full node and BitcoinJ as a representative SPV client. Both programs are flexible, so only default behavior is described. The response to the lookup should include one or more DNS A records with the IP addresses of full nodes that may accept new incoming connections. For example, using the Unix dig command:.
The DNS seeds are maintained by Bitcoin community members: In either case, nodes are added to the DNS seed if they run on the default Bitcoin ports of for mainnet or for testnet. For this reason, programs should not rely on DNS seeds exclusively. Once a program has connected to the network , its peers can begin to send it addr address messages with the IP addresses and port numbers of other peers on the network , providing a fully decentralized method of peer discovery.
Bitcoin Core keeps a record of known peers in a persistent on-disk database which usually allows it to connect directly to those peers on subsequent startups without having to use DNS seeds.
However, peers often leave the network or change IP addresses, so programs may need to make several different connection attempts at startup before a successful connection is made.
This can add a significant delay to the amount of time it takes to connect to the network , forcing a user to wait before sending a transaction or checking the status of payment. Bitcoin Core also tries to strike a balance between minimizing delays and avoiding unnecessary DNS seed use: Both Bitcoin Core and BitcoinJ also include a hardcoded list of IP addresses and port numbers to several dozen nodes which were active around the time that particular version of the software was first released.
Bitcoin Core will start attempting to connect to these nodes if none of the DNS seed servers have responded to a query within 60 seconds, providing an automatic fallback option. As a manual fallback option, Bitcoin Core also provides several command-line connection options, including the ability to get a list of peers from a specific node by IP address, or to make a persistent connection to a specific node by IP address.
See the -help text for details. BitcoinJ can be programmed to do the same thing. Connecting to a peer is done by sending a version message , which contains your version number, block , and current time to the remote node. The remote node responds with its own version message. Then both nodes send a verack message to the other node to indicate the connection has been established.
Once connected, the client can send to the remote node getaddr and addr messages to gather additional peers. In order to maintain a connection with a peer , nodes by default will send a message to peers before 30 minutes of inactivity.
If 90 minutes pass without a message being received by a peer , the client will assume that connection has closed. Before a full node can validate unconfirmed transactions and recently-mined blocks , it must download and validate all blocks from block 1 the block after the hardcoded genesis block to the current tip of the best block chain. In this case, a node can use the IBD method to download all the blocks which were produced since the last time it was online.
Bitcoin Core uses the IBD method any time the last block on its local best block chain has a block header time more than 24 hours in the past.
Bitcoin Core up until version 0. The goal is to download the blocks from the best block chain in sequence. The first time a node is started, it only has a single block in its local best block chain —the hardcoded genesis block block 0.
This node chooses a remote peer , called the sync node , and sends it the getblocks message illustrated below. In the header hashes field of the getblocks message , this new node sends the header hash of the only block it has, the genesis block 6fe2… in internal byte order. It also sets the stop hash field to all zeroes to request a maximum-size response.
Upon receipt of the getblocks message , the sync node takes the first and only header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with block inventories the maximum response to a getblocks message starting from block 1. It sends these inventories in the inv message illustrated below. Inventories are unique identifiers for information on the network.
Each inventory contains a type field and the unique identifier for an instance of the object. The block inventories appear in the inv message in the same order they appear in the block chain , so this first inv message contains inventories for blocks 1 through For example, the hash of block 1 is … as seen in the illustration above.
The IBD node uses the received inventories to request blocks from the sync node in the getdata message illustrated below. Upon receipt of the getdata message , the sync node replies with each of the blocks requested. Each block is put into serialized block format and sent in a separate block message.
The first block message sent for block 1 is illustrated below. When it has requested every block for which it has an inventory , it sends another getblocks message to the sync node requesting the inventories of up to more blocks. This second getblocks message contains multiple header hashes as illustrated below:. Upon receipt of the second getblocks message , the sync node searches its local best block chain for a block that matches one of the header hashes in the message, trying each hash in the order they were received.
If it finds a matching hash, it replies with block inventories starting with the next block from that point. But if there is no matching hash besides the stopping hash , it assumes the only block the two nodes have in common is block 0 and so it sends an inv starting with block 1 the same inv message seen several illustrations above. This fork detection becomes increasingly useful the closer the IBD node gets to the tip of the block chain. When the IBD node receives the second inv message , it will request those blocks using getdata messages.
The sync node will respond with block messages. Then the IBD node will request more inventories with another getblocks message —and the cycle will repeat until the IBD node is synced to the tip of the block chain. At that point, the node will accept blocks sent through the regular block broadcasting described in a later subsection.
The primary advantage of blocks-first IBD is its simplicity. The primary disadvantage is that the IBD node relies on a single sync node for all of its downloading. This has several implications:. All requests are made to the sync node , so if the sync node has limited upload bandwidth, the IBD node will have slow download speeds. The sync node can send a non-best but otherwise valid block chain to the IBD node.
Bitcoin Core ships with several block chain checkpoints at various block heights selected by developers to help an IBD node detect that it is being fed an alternative block chain history—allowing the IBD node to restart its download earlier in the process. Closely related to the download restarts, if the sync node sends a non-best but otherwise valid block chain , the chain will be stored on disk, wasting space and possibly filling up the disk drive with useless data. Orphan blocks are stored in memory while they await validation, which may lead to high memory use.
All of these problems are addressed in part or in full by the headers-first IBD method used in Bitcoin Core 0. The table below summarizes the messages mentioned throughout this subsection.
The links in the message field will take you to the reference page for that message. The goal is to download the headers for the best header chain , partially validate them as best as possible, and then download the corresponding blocks in parallel. This solves several problems with the older blocks-first IBD method.
In the header hashes field of the getheaders message , the new node sends the header hash of the only block it has, the genesis block 6fe2… in internal byte order. Upon receipt of the getheaders message , the sync node takes the first and only header hash and searches its local best block chain for a block with that header hash. It finds that block 0 matches, so it replies with 2, header the maximum response starting from block 1.
It sends these header hashes in the headers message illustrated below. The IBD node can partially validate these block headers by ensuring that all fields follow consensus rules and that the hash of the header is below the target threshold according to the nBits field. Full validation still requires all transactions from the corresponding block.
After the IBD node has partially validated the block headers , it can do two things in parallel:. Those headers can be immediately validated and another batch requested repeatedly until a headers message is received from the sync node with fewer than 2, headers , indicating that it has no more headers to offer.
As of this writing, headers sync can be completed in fewer than round trips, or about 32 MB of downloaded data. Once the IBD node receives a headers message with fewer than 2, headers from the sync node , it sends a getheaders message to each of its outbound peers to get their view of best header chain. By comparing the responses, it can easily determine if the headers it has downloaded belong to the best header chain reported by any of its outbound peers. While the IBD node continues downloading headers , and after the headers finish downloading, the IBD node will request and download each block.
The IBD node can use the block header hashes it computed from the header chain to create getdata messages that request the blocks it needs by their inventory. Although not all full nodes may store all blocks. This allows it to fetch blocks in parallel and avoid having its download speed constrained to the upload speed of a single sync node.
To spread the load between multiple peers , Bitcoin Core will only request up to 16 blocks at a time from a single peer. Combined with its maximum of 8 outbound connections, this means headers-first Bitcoin Core will request a maximum of blocks simultaneously during IBD the same maximum number that blocks-first Bitcoin Core requested from its sync node.
Once the IBD node is synced to the tip of the block chain , it will accept blocks sent through the regular block broadcasting described in a later subsection. When a miner discovers a new block , it broadcasts the new block to its peers using one of the following methods:.
The miner can reasonably bypass the standard relay method in this way because it knows none of its peers already have the just-discovered block. The most common responses are:. Each blocks-first BF peer that wants the block replies with a getdata message requesting the full block.
Each headers-first HF peer that wants the block replies with a getheaders message containing the header hash of the highest- height header on its best header chain , and likely also some headers further back on the best header chain to allow fork detection. That message is immediately followed by a getdata message requesting the full block. By requesting headers first, a headers-first peer can refuse orphan blocks as described in the subsection below.
Each Simplified Payment Verification SPV client that wants the block replies with a getdata message typically requesting a merkle block. A HF peer receiving this message will partially validate the block header as it would during headers-first IBD , then request the full block contents with a getdata message if the header is valid. The relay node then responds to the getdata request with the full or filtered block data in a block or merkleblock message , respectively. A HF node may signal that it prefers to receive headers instead of inv announcements by sending a special sendheaders message during the connection handshake.
This protocol for block broadcasting was proposed in BIP and has been implemented in Bitcoin Core since version 0. By default, Bitcoin Core broadcasts blocks using direct headers announcement to any peers that have signalled with sendheaders and uses standard block relay for all peers that have not. Bitcoin Core will accept blocks sent using any of the methods described above. Full nodes validate the received block and then advertise it to their peers using the standard block relay method described above.
The condensed table below highlights the operation of the messages described above Relay, BF, HF, and SPV refer to the relay node , a blocks-first node , a headers-first node , and an SPV client ; any refers to a node using any block retrieval method. When a blocks-first node downloads an orphan block , it will not validate it. Instead, it will send a getblocks message to the node which sent the orphan block ; the broadcasting node will respond with an inv message containing inventories of any blocks the downloading node is missing up to ; the downloading node will request those blocks with a getdata message ; and the broadcasting node will send those blocks with a block message.
The downloading node will validate those blocks , and once the parent of the former orphan block has been validated, it will validate the former orphan block. Headers-first nodes avoid some of this complexity by always requesting block headers with the getheaders message before requesting a block with the getdata message. If, despite this, the block received in the block message is an orphan block , a headers-first node will discard it immediately.
However, orphan discarding does mean that headers-first nodes will ignore orphan blocks sent by miners in an unsolicited block push. In order to send a transaction to a peer , an inv message is sent. If a getdata response message is received, the transaction is sent using tx. The peer receiving this transaction also forwards the transaction in the same manner, given that it is a valid transaction. Full peers may keep track of unconfirmed transactions which are eligible to be included in the next block.
Because unconfirmed transactions have no permanent status in Bitcoin, Bitcoin Core stores them in non-persistent memory, calling them a memory pool or mempool. When a peer shuts down, its memory pool is lost except for any transactions stored by its wallet. This means that never-mined unconfirmed transactions tend to slowly disappear from the network as peers restart or as they purge some transactions to make room in memory for others.
Transactions which are mined into blocks that later become stale blocks may be added back into the memory pool.