Block (core 0.15 API)

java.lang.Object
- org.bitcoinj.core.Message
- - org.bitcoinj.core.Block

```
public class Block
extends Message
```
A block is a group of transactions, and is one of the fundamental data structures of the Bitcoin system. It records a set of Transactions together with some data that links it into a place in the global block chain, and proves that a difficult calculation was done over its contents. See the Bitcoin technical paper for more detail on blocks.

To get a block, you can either build one from the raw bytes you can get from another implementation, or request one specifically using Peer.getBlock(Sha256Hash), or grab one from a downloaded BlockChain.

Instances of this class are not safe for use by multiple threads.

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Block.VerifyFlag
Flags used to control which elements of block validation are done on received blocks.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Block.VerifyFlag` Flags used to control which elements of block validation are done on received blocks.

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`BLOCK_HEIGHT_GENESIS` Height of the first block
`static int`	`BLOCK_HEIGHT_UNKNOWN` Value to use if the block height is unknown
`static long`	`BLOCK_VERSION_BIP34` Block version introduced in BIP 34: Height in coinbase
`static long`	`BLOCK_VERSION_BIP65` Block version introduced in BIP 65: OP_CHECKLOCKTIMEVERIFY
`static long`	`BLOCK_VERSION_BIP66` Block version introduced in BIP 66: Strict DER signatures
`static long`	`BLOCK_VERSION_GENESIS`
`static long`	`EASIEST_DIFFICULTY_TARGET` A value for difficultyTarget (nBits) that allows half of all possible hash solutions.
`static int`	`HEADER_SIZE` How many bytes are required to represent a block header WITHOUT the trailing 00 length byte.
`protected boolean`	`headerBytesValid`
`static int`	`MAX_BLOCK_SIGOPS` A "sigop" is a signature verification operation.
`static int`	`MAX_BLOCK_SIZE` A constant shared by the entire network: how large in bytes a block is allowed to be.
`protected int`	`optimalEncodingMessageSize`
`protected boolean`	`transactionBytesValid`

Fields inherited from class org.bitcoinj.core.Message
cursor, length, MAX_SIZE, offset, params, payload, protocolVersion, recached, serializer, UNKNOWN_LENGTH

Constructor Summary

Constructors
Constructor and Description
`Block(NetworkParameters params, byte[] payloadBytes)` Deprecated. Use `MessageSerializer.makeBlock(byte[])` instead.
`Block(NetworkParameters params, byte[] payloadBytes, int offset, Message parent, MessageSerializer serializer, int length)` Construct a block object from the Bitcoin wire format.
`Block(NetworkParameters params, byte[] payloadBytes, int offset, MessageSerializer serializer, int length)` Construct a block object from the Bitcoin wire format.
`Block(NetworkParameters params, byte[] payloadBytes, MessageSerializer serializer, int length)` Construct a block object from the Bitcoin wire format.
`Block(NetworkParameters params, long version, Sha256Hash prevBlockHash, Sha256Hash merkleRoot, long time, long difficultyTarget, long nonce, java.util.List<Transaction> transactions)` Construct a block initialized with all the given fields.

Method Summary

All Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`addTransaction(Transaction t)` Adds a transaction to this block.
`byte[]`	`bitcoinSerialize()` Special handling to check if we have a valid byte array for both header and transactions
`protected void`	`bitcoinSerializeToStream(java.io.OutputStream stream)` Serializes this message to the provided stream.
`protected boolean`	`checkProofOfWork(boolean throwException)` Returns true if the hash of the block is OK (lower than difficulty target).
`Block`	`cloneAsHeader()` Returns a copy of the block, but without any transactions.
`protected void`	`copyBitcoinHeaderTo(Block block)` Copy the block without transactions into the provided empty block.
`Block`	`createNextBlock(Address to)`
`Block`	`createNextBlock(Address to, Coin value)`
`Block`	`createNextBlock(Address to, long version, long time, int blockHeight)` Returns a solved block that builds on top of this one.
`Block`	`createNextBlock(Address to, TransactionOutPoint prevOut)`
`Block`	`createNextBlockWithCoinbase(long version, byte[] pubKey, Coin coinbaseValue, int height)`
`boolean`	`equals(java.lang.Object o)`
`Coin`	`getBlockInflation(int height)` A utility method that calculates how much new Bitcoin would be created by the block at the given height.
`long`	`getDifficultyTarget()` Returns the difficulty of the proof of work that this block should meet encoded in compact form.
`java.math.BigInteger`	`getDifficultyTargetAsInteger()` Returns the difficulty target as a 256 bit value that can be compared to a SHA-256 hash.
`Sha256Hash`	`getHash()` Returns the hash of the block (which for a valid, solved block should be below the target).
`java.lang.String`	`getHashAsString()` Returns the hash of the block (which for a valid, solved block should be below the target) in the form seen on the block explorer.
`Sha256Hash`	`getMerkleRoot()` Returns the merkle root in big endian form, calculating it from transactions if necessary.
`long`	`getNonce()` Returns the nonce, an arbitrary value that exists only to make the hash of the block header fall below the difficulty target.
`int`	`getOptimalEncodingMessageSize()`
`Sha256Hash`	`getPrevBlockHash()` Returns the hash of the previous block in the chain, as defined by the block header.
`java.util.Date`	`getTime()` Returns the time at which the block was solved and broadcast, according to the clock of the solving node.
`long`	`getTimeSeconds()` Returns the time at which the block was solved and broadcast, according to the clock of the solving node.
`java.util.List<Transaction>`	`getTransactions()` Returns an immutable list of transactions held in this block, or null if this object represents just a header.
`long`	`getVersion()` Returns the version of the block data structure as defined by the Bitcoin protocol.
`Sha256Hash`	`getWitnessRoot()` Returns the witness root in big endian form, calculating it from transactions if necessary.
`java.math.BigInteger`	`getWork()` Returns the work represented by this block.
`int`	`hashCode()`
`boolean`	`hasTransactions()` Return whether this block contains any transactions.
`boolean`	`isBIP34()` Returns whether this block conforms to BIP34: Height in Coinbase.
`boolean`	`isBIP65()` Returns whether this block conforms to BIP65: OP_CHECKLOCKTIMEVERIFY.
`boolean`	`isBIP66()` Returns whether this block conforms to BIP66: Strict DER signatures.
`protected void`	`parse()`
`protected void`	`parseTransactions(int transactionsOffset)` Parse transactions from the block.
`void`	`setDifficultyTarget(long compactForm)` Sets the difficulty target in compact form.
`void`	`setNonce(long nonce)` Sets the nonce and clears any cached data.
`void`	`setTime(long time)`
`void`	`solve()` Finds a value of nonce that makes the blocks hash lower than the difficulty target.
`java.lang.String`	`toString()` Returns a multi-line string containing a description of the contents of the block.
`protected void`	`unCache()` To be called before any change of internal values including any setters.
`void`	`verify(int height, java.util.EnumSet<Block.VerifyFlag> flags)` Verifies both the header and that the transactions hash to the merkle root.
`void`	`verifyHeader()` Checks the block data to ensure it follows the rules laid out in the network parameters.
`void`	`verifyTransactions(int height, java.util.EnumSet<Block.VerifyFlag> flags)` Checks the block contents

Methods inherited from class org.bitcoinj.core.Message
adjustLength, bitcoinSerialize, getMessageSize, getParams, hasMoreBytes, isCached, isRecached, readByteArray, readBytes, readHash, readInt64, readStr, readUint32, readUint64, readVarInt, readVarInt, unsafeBitcoinSerialize

Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, wait, wait, wait

- Field Detail
  - HEADER_SIZE
```
public static final int HEADER_SIZE
```
    How many bytes are required to represent a block header WITHOUT the trailing 00 length byte.
    
    See Also:
    
    Constant Field Values
  - MAX_BLOCK_SIZE
```
public static final int MAX_BLOCK_SIZE
```
    A constant shared by the entire network: how large in bytes a block is allowed to be. One day we may have to upgrade everyone to change this, so Bitcoin can continue to grow. For now it exists as an anti-DoS measure to avoid somebody creating a titanically huge but valid block and forcing everyone to download/store it forever.
    
    See Also:
    
    Constant Field Values
  - MAX_BLOCK_SIGOPS
```
public static final int MAX_BLOCK_SIGOPS
```
    A "sigop" is a signature verification operation. Because they're expensive we also impose a separate limit on the number in a block to prevent somebody mining a huge block that has way more sigops than normal, so is very expensive/slow to verify.
    
    See Also:
    
    Constant Field Values
  - EASIEST_DIFFICULTY_TARGET
```
public static final long EASIEST_DIFFICULTY_TARGET
```
    A value for difficultyTarget (nBits) that allows half of all possible hash solutions. Used in unit testing.
    
    See Also:
    
    Constant Field Values
  - BLOCK_HEIGHT_UNKNOWN
```
public static final int BLOCK_HEIGHT_UNKNOWN
```
    Value to use if the block height is unknown
    
    See Also:
    
    Constant Field Values
  - BLOCK_HEIGHT_GENESIS
```
public static final int BLOCK_HEIGHT_GENESIS
```
    Height of the first block
    
    See Also:
    
    Constant Field Values
  - BLOCK_VERSION_GENESIS
```
public static final long BLOCK_VERSION_GENESIS
```
    See Also:
    
    Constant Field Values
  - BLOCK_VERSION_BIP34
```
public static final long BLOCK_VERSION_BIP34
```
    Block version introduced in BIP 34: Height in coinbase
    
    See Also:
    
    Constant Field Values
  - BLOCK_VERSION_BIP66
```
public static final long BLOCK_VERSION_BIP66
```
    Block version introduced in BIP 66: Strict DER signatures
    
    See Also:
    
    Constant Field Values
  - BLOCK_VERSION_BIP65
```
public static final long BLOCK_VERSION_BIP65
```
    Block version introduced in BIP 65: OP_CHECKLOCKTIMEVERIFY
    
    See Also:
    
    Constant Field Values
  - headerBytesValid
```
protected boolean headerBytesValid
```
  - transactionBytesValid
```
protected boolean transactionBytesValid
```
  - optimalEncodingMessageSize
```
protected int optimalEncodingMessageSize
```
- Constructor Detail
  - Block
```
@Deprecated
public Block(NetworkParameters params,
                         byte[] payloadBytes)
                  throws ProtocolException
```
    Deprecated. Use MessageSerializer.makeBlock(byte[]) instead.
    
    Constructs a block object from the Bitcoin wire format.
    
    Throws:
    
    ProtocolException
  - Block
```
public Block(NetworkParameters params,
             byte[] payloadBytes,
             MessageSerializer serializer,
             int length)
      throws ProtocolException
```
    Construct a block object from the Bitcoin wire format.
    
    Parameters:
    
    params - NetworkParameters object.
    
    payloadBytes - the payload to extract the block from.
    
    serializer - the serializer to use for this message.
    
    length - The length of message if known. Usually this is provided when deserializing of the wire as the length will be provided as part of the header. If unknown then set to Message.UNKNOWN_LENGTH
    
    Throws:
    
    ProtocolException
  - Block
```
public Block(NetworkParameters params,
             byte[] payloadBytes,
             int offset,
             MessageSerializer serializer,
             int length)
      throws ProtocolException
```
    Construct a block object from the Bitcoin wire format.
    
    Parameters:
    
    params - NetworkParameters object.
    
    payloadBytes - the payload to extract the block from.
    
    offset - The location of the first payload byte within the array.
    
    serializer - the serializer to use for this message.
    
    length - The length of message if known. Usually this is provided when deserializing of the wire as the length will be provided as part of the header. If unknown then set to Message.UNKNOWN_LENGTH
    
    Throws:
    
    ProtocolException
  - Block
```
public Block(NetworkParameters params,
             byte[] payloadBytes,
             int offset,
             @Nullable
             Message parent,
             MessageSerializer serializer,
             int length)
      throws ProtocolException
```
    Construct a block object from the Bitcoin wire format. Used in the case of a block contained within another message (i.e. for AuxPoW header).
    
    Parameters:
    
    params - NetworkParameters object.
    
    payloadBytes - Bitcoin protocol formatted byte array containing message content.
    
    offset - The location of the first payload byte within the array.
    
    parent - The message element which contains this block, maybe null for no parent.
    
    serializer - the serializer to use for this block.
    
    length - The length of message if known. Usually this is provided when deserializing of the wire as the length will be provided as part of the header. If unknown then set to Message.UNKNOWN_LENGTH
    
    Throws:
    
    ProtocolException
  - Block
```
public Block(NetworkParameters params,
             long version,
             Sha256Hash prevBlockHash,
             Sha256Hash merkleRoot,
             long time,
             long difficultyTarget,
             long nonce,
             java.util.List<Transaction> transactions)
```
    Construct a block initialized with all the given fields.
    
    Parameters:
    
    params - Which network the block is for.
    
    version - This should usually be set to 1 or 2, depending on if the height is in the coinbase input.
    
    prevBlockHash - Reference to previous block in the chain or Sha256Hash.ZERO_HASH if genesis.
    
    merkleRoot - The root of the merkle tree formed by the transactions.
    
    time - UNIX time when the block was mined.
    
    difficultyTarget - Number which this block hashes lower than.
    
    nonce - Arbitrary number to make the block hash lower than the target.
    
    transactions - List of transactions including the coinbase.
- Method Detail
  - getBlockInflation
```
public Coin getBlockInflation(int height)
```
    A utility method that calculates how much new Bitcoin would be created by the block at the given height. The inflation of Bitcoin is predictable and drops roughly every 4 years (210,000 blocks). At the dawn of the system it was 50 coins per block, in late 2012 it went to 25 coins per block, and so on. The size of a coinbase transaction is inflation plus fees.
    
    The half-life is controlled by NetworkParameters.getSubsidyDecreaseBlockCount().
  - parseTransactions
```
protected void parseTransactions(int transactionsOffset)
                          throws ProtocolException
```
    Parse transactions from the block.
    
    Parameters:
    
    transactionsOffset - Offset of the transactions within the block. Useful for non-Bitcoin chains where the block header may not be a fixed size.
    
    Throws:
    
    ProtocolException
  - parse
```
protected void parse()
              throws ProtocolException
```
    Specified by:
    
    parse in class Message
    
    Throws:
    
    ProtocolException
  - getOptimalEncodingMessageSize
```
public int getOptimalEncodingMessageSize()
```
  - bitcoinSerialize
```
public byte[] bitcoinSerialize()
```
    Special handling to check if we have a valid byte array for both header and transactions
    
    Overrides:
    
    bitcoinSerialize in class Message
    
    Returns:
    
    a freshly allocated serialized byte array
  - bitcoinSerializeToStream
```
protected void bitcoinSerializeToStream(java.io.OutputStream stream)
                                 throws java.io.IOException
```
    Description copied from class: Message
    
    Serializes this message to the provided stream. If you just want the raw bytes use bitcoinSerialize().
    
    Overrides:
    
    bitcoinSerializeToStream in class Message
    
    Throws:
    
    java.io.IOException
  - unCache
```
protected void unCache()
```
    Description copied from class: Message
    
    To be called before any change of internal values including any setters. This ensures any cached byte array is removed.
    
    Child messages of this object(e.g. Transactions belonging to a Block) will not have their internal byte caches invalidated unless they are also modified internally.
    
    Overrides:
    
    unCache in class Message
  - getHashAsString
```
public java.lang.String getHashAsString()
```
    Returns the hash of the block (which for a valid, solved block should be below the target) in the form seen on the block explorer. If you call this on block 1 in the mainnet chain you will get "00000000839a8e6886ab5951d76f411475428afc90947ee320161bbf18eb6048".
  - getHash
```
public Sha256Hash getHash()
```
    Returns the hash of the block (which for a valid, solved block should be below the target). Big endian.
    
    Overrides:
    
    getHash in class Message
  - getWork
```
public java.math.BigInteger getWork()
                             throws VerificationException
```
    Returns the work represented by this block.
    Work is defined as the number of tries needed to solve a block in the average case. Consider a difficulty target that covers 5% of all possible hash values. Then the work of the block will be 20. As the target gets lower, the amount of work goes up.
    
    Throws:
    
    VerificationException
  - cloneAsHeader
```
public Block cloneAsHeader()
```
    Returns a copy of the block, but without any transactions.
  - copyBitcoinHeaderTo
```
protected final void copyBitcoinHeaderTo(Block block)
```
    Copy the block without transactions into the provided empty block.
  - toString
```
public java.lang.String toString()
```
    Returns a multi-line string containing a description of the contents of the block. Use for debugging purposes only.
    
    Overrides:
    
    toString in class java.lang.Object
  - solve
```
public void solve()
```
    Finds a value of nonce that makes the blocks hash lower than the difficulty target. This is called mining, but solve() is far too slow to do real mining with. It exists only for unit testing purposes.
    This can loop forever if a solution cannot be found solely by incrementing nonce. It doesn't change extraNonce.
  - getDifficultyTargetAsInteger
```
public java.math.BigInteger getDifficultyTargetAsInteger()
                                                  throws VerificationException
```
    Returns the difficulty target as a 256 bit value that can be compared to a SHA-256 hash. Inside a block the target is represented using a compact form. If this form decodes to a value that is out of bounds, an exception is thrown.
    
    Throws:
    
    VerificationException
  - checkProofOfWork
```
protected boolean checkProofOfWork(boolean throwException)
                            throws VerificationException
```
    Returns true if the hash of the block is OK (lower than difficulty target).
    
    Throws:
    
    VerificationException
  - verifyHeader
```
public void verifyHeader()
                  throws VerificationException
```
    Checks the block data to ensure it follows the rules laid out in the network parameters. Specifically, throws an exception if the proof of work is invalid, or if the timestamp is too far from what it should be. This is not everything that is required for a block to be valid, only what is checkable independent of the chain and without a transaction index.
    
    Throws:
    
    VerificationException
  - verifyTransactions
```
public void verifyTransactions(int height,
                               java.util.EnumSet<Block.VerifyFlag> flags)
                        throws VerificationException
```
    Checks the block contents
    
    Parameters:
    
    height - block height, if known, or -1 otherwise. If valid, used to validate the coinbase input script of v2 and above blocks.
    
    flags - flags to indicate which tests should be applied (i.e. whether to test for height in the coinbase transaction).
    
    Throws:
    
    VerificationException - if there was an error verifying the block.
  - verify
```
public void verify(int height,
                   java.util.EnumSet<Block.VerifyFlag> flags)
            throws VerificationException
```
    Verifies both the header and that the transactions hash to the merkle root.
    
    Parameters:
    
    height - block height, if known, or -1 otherwise.
    
    flags - flags to indicate which tests should be applied (i.e. whether to test for height in the coinbase transaction).
    
    Throws:
    
    VerificationException - if there was an error verifying the block.
  - equals
```
public boolean equals(java.lang.Object o)
```
    Overrides:
    
    equals in class java.lang.Object
  - hashCode
```
public int hashCode()
```
    Overrides:
    
    hashCode in class java.lang.Object
  - getMerkleRoot
```
public Sha256Hash getMerkleRoot()
```
    Returns the merkle root in big endian form, calculating it from transactions if necessary.
  - getWitnessRoot
```
public Sha256Hash getWitnessRoot()
```
    Returns the witness root in big endian form, calculating it from transactions if necessary.
  - addTransaction
```
public void addTransaction(Transaction t)
```
    Adds a transaction to this block. The nonce and merkle root are invalid after this.
  - getVersion
```
public long getVersion()
```
    Returns the version of the block data structure as defined by the Bitcoin protocol.
  - getPrevBlockHash
```
public Sha256Hash getPrevBlockHash()
```
    Returns the hash of the previous block in the chain, as defined by the block header.
  - getTimeSeconds
```
public long getTimeSeconds()
```
    Returns the time at which the block was solved and broadcast, according to the clock of the solving node. This is measured in seconds since the UNIX epoch (midnight Jan 1st 1970).
  - getTime
```
public java.util.Date getTime()
```
    Returns the time at which the block was solved and broadcast, according to the clock of the solving node.
  - setTime
```
public void setTime(long time)
```
  - getDifficultyTarget
```
public long getDifficultyTarget()
```
    Returns the difficulty of the proof of work that this block should meet encoded in compact form. The BlockChain verifies that this is not too easy by looking at the length of the chain when the block is added. To find the actual value the hash should be compared against, use getDifficultyTargetAsInteger(). Note that this is not the same as the difficulty value reported by the Bitcoin "getdifficulty" RPC that you may see on various block explorers. That number is the result of applying a formula to the underlying difficulty to normalize the minimum to 1. Calculating the difficulty that way is currently unsupported.
  - setDifficultyTarget
```
public void setDifficultyTarget(long compactForm)
```
    Sets the difficulty target in compact form.
  - getNonce
```
public long getNonce()
```
    Returns the nonce, an arbitrary value that exists only to make the hash of the block header fall below the difficulty target.
  - setNonce
```
public void setNonce(long nonce)
```
    Sets the nonce and clears any cached data.
  - getTransactions
```
@Nullable
public java.util.List<Transaction> getTransactions()
```
    Returns an immutable list of transactions held in this block, or null if this object represents just a header.
  - createNextBlock
```
public Block createNextBlock(Address to,
                             long version,
                             long time,
                             int blockHeight)
```
    Returns a solved block that builds on top of this one. This exists for unit tests.
  - createNextBlock
```
public Block createNextBlock(@Nullable
                             Address to,
                             TransactionOutPoint prevOut)
```
  - createNextBlock
```
public Block createNextBlock(@Nullable
                             Address to,
                             Coin value)
```
  - createNextBlock
```
public Block createNextBlock(@Nullable
                             Address to)
```
  - createNextBlockWithCoinbase
```
public Block createNextBlockWithCoinbase(long version,
                                         byte[] pubKey,
                                         Coin coinbaseValue,
                                         int height)
```
  - hasTransactions
```
public boolean hasTransactions()
```
    Return whether this block contains any transactions.
    
    Returns:
    
    true if the block contains transactions, false otherwise (is purely a header).
  - isBIP34
```
public boolean isBIP34()
```
    Returns whether this block conforms to BIP34: Height in Coinbase.
  - isBIP66
```
public boolean isBIP66()
```
    Returns whether this block conforms to BIP66: Strict DER signatures.
  - isBIP65
```
public boolean isBIP65()
```
    Returns whether this block conforms to BIP65: OP_CHECKLOCKTIMEVERIFY.

Class Block

Nested Class Summary

Field Summary

Fields inherited from class org.bitcoinj.core.Message

Constructor Summary

Method Summary

Methods inherited from class org.bitcoinj.core.Message

Methods inherited from class java.lang.Object

Field Detail

HEADER_SIZE

MAX_BLOCK_SIZE

MAX_BLOCK_SIGOPS

EASIEST_DIFFICULTY_TARGET

BLOCK_HEIGHT_UNKNOWN

BLOCK_HEIGHT_GENESIS

BLOCK_VERSION_GENESIS

BLOCK_VERSION_BIP34

BLOCK_VERSION_BIP66

BLOCK_VERSION_BIP65

headerBytesValid

transactionBytesValid

optimalEncodingMessageSize

Constructor Detail

Block

Block

Block

Block

Block

Method Detail

getBlockInflation

parseTransactions

parse

getOptimalEncodingMessageSize

bitcoinSerialize

bitcoinSerializeToStream

unCache

getHashAsString

getHash

getWork

cloneAsHeader

copyBitcoinHeaderTo

toString

solve

getDifficultyTargetAsInteger

checkProofOfWork

verifyHeader

verifyTransactions

verify

equals

hashCode

getMerkleRoot

getWitnessRoot

addTransaction

getVersion

getPrevBlockHash

getTimeSeconds

getTime

setTime

getDifficultyTarget

setDifficultyTarget

getNonce

setNonce

getTransactions

createNextBlock

createNextBlock

createNextBlock

createNextBlock

createNextBlockWithCoinbase

hasTransactions

isBIP34

isBIP66

isBIP65