Package org.bitcoinj.wallet

Class WalletProtobufSerializer

java.lang.Object
org.bitcoinj.wallet.WalletProtobufSerializer
public class WalletProtobufSerializer extends Object
Serialize and de-serialize a wallet to a byte stream containing a protocol buffer. Protocol buffers are a data interchange format developed by Google with an efficient binary representation, a type safe specification language and compilers that generate code to work with those data structures for many languages. Protocol buffers can have their format evolved over time: conceptually they represent data using (tag, length, value) tuples. The format is defined by the wallet.proto file in the bitcoinj source distribution.

This class is used through its static methods. The most common operations are writeWallet and readWallet, which do the obvious operations on Output/InputStreams. You can use a ByteArrayInputStream and equivalent ByteArrayOutputStream if you'd like byte arrays instead. The protocol buffer can also be manipulated in its object form if you'd like to modify the flattened data structure before serialization to binary.

You can extend the wallet format with additional fields specific to your application if you want, but make sure to either put the extra data in the provided extension areas, or select tag numbers that are unlikely to be used by anyone else.

  • Field Details

    • CURRENT_WALLET_VERSION

      public static final int CURRENT_WALLET_VERSION
      Current version used for serializing wallets. A version higher than this is considered from the future.

    • txMap

      protected Map<com.google.protobuf.ByteString,Transaction> txMap

  • Constructor Details

  • Method Details

    • setKeyChainFactory

      public void setKeyChainFactory(KeyChainFactory keyChainFactory)

    • setRequireMandatoryExtensions

      public void setRequireMandatoryExtensions(boolean value)
      If this property is set to false, then unknown mandatory extensions will be ignored instead of causing load errors. You should only use this if you know exactly what you are doing, as the extension data will NOT be round-tripped, possibly resulting in a corrupted wallet if you save it back out again.

    • setRequireAllExtensionsKnown

      public void setRequireAllExtensionsKnown(boolean value)
      If this property is set to true, the wallet will fail to load if any found extensions are unknown..

    • setWalletWriteBufferSize

      public void setWalletWriteBufferSize(int walletWriteBufferSize)
      Change buffer size for writing wallet to output stream. Default is CodedOutputStream.DEFAULT_BUFFER_SIZE
      Parameters:
      walletWriteBufferSize - - buffer size in bytes

    • writeWallet

      public void writeWallet(Wallet wallet, OutputStream output) throws IOException
      Formats the given wallet (transactions and keys) to the given output stream in protocol buffer format.

      Equivalent to walletToProto(wallet).writeTo(output);

      Throws:
      IOException

    • walletToText

      public String walletToText(Wallet wallet)
      Returns the given wallet formatted as text. The text format is that used by protocol buffers and it is designed more for debugging than storage. It is not well specified and wallets are largely binary data structures anyway, consisting as they do of keys (large random numbers) and Transactions which also mostly contain keys and hashes.

    • walletToProto

      public Protos.Wallet walletToProto(Wallet wallet)
      Converts the given wallet to the object representation of the protocol buffers. This can be modified, or additional data fields set, before serialization takes place.

    • hashToByteString

      public static com.google.protobuf.ByteString hashToByteString(Sha256Hash hash)

    • byteStringToHash

      public static Sha256Hash byteStringToHash(com.google.protobuf.ByteString bs)

    • readWallet

      public Wallet readWallet(InputStream input, @Nullable WalletExtension... walletExtensions) throws UnreadableWalletException

      Loads wallet data from the given protocol buffer and inserts it into the given Wallet object. This is primarily useful when you wish to pre-register extension objects. Note that if loading fails the provided Wallet object may be in an indeterminate state and should be thrown away.

      A wallet can be unreadable for various reasons, such as inability to open the file, corrupt data, internally inconsistent data, a wallet extension marked as mandatory that cannot be handled and so on. You should always handle UnreadableWalletException and communicate failure to the user in an appropriate manner.

      Throws:
      UnreadableWalletException - thrown in various error conditions (see description).

    • readWallet

      public Wallet readWallet(InputStream input, boolean forceReset, @Nullable WalletExtension[] extensions) throws UnreadableWalletException

      Loads wallet data from the given protocol buffer and inserts it into the given Wallet object. This is primarily useful when you wish to pre-register extension objects. Note that if loading fails the provided Wallet object may be in an indeterminate state and should be thrown away. Do not simply call this method again on the same Wallet object with forceReset set true. It won't work.

      If forceReset is true, then no transactions are loaded from the wallet, and it is configured to replay transactions from the blockchain (as if the wallet had been loaded and Wallet.reset() had been called immediately thereafter).

      A wallet can be unreadable for various reasons, such as inability to open the file, corrupt data, internally inconsistent data, a wallet extension marked as mandatory that cannot be handled and so on. You should always handle UnreadableWalletException and communicate failure to the user in an appropriate manner.

      Throws:
      UnreadableWalletException - thrown in various error conditions (see description).

    • readWallet

      public Wallet readWallet(NetworkParameters params, @Nullable WalletExtension[] extensions, Protos.Wallet walletProto) throws UnreadableWalletException

      Loads wallet data from the given protocol buffer and inserts it into the given Wallet object. This is primarily useful when you wish to pre-register extension objects. Note that if loading fails the provided Wallet object may be in an indeterminate state and should be thrown away.

      A wallet can be unreadable for various reasons, such as inability to open the file, corrupt data, internally inconsistent data, a wallet extension marked as mandatory that cannot be handled and so on. You should always handle UnreadableWalletException and communicate failure to the user in an appropriate manner.

      Throws:
      UnreadableWalletException - thrown in various error conditions (see description).

    • readWallet

      public Wallet readWallet(NetworkParameters params, @Nullable WalletExtension[] extensions, Protos.Wallet walletProto, boolean forceReset) throws UnreadableWalletException

      Loads wallet data from the given protocol buffer and inserts it into the given Wallet object. This is primarily useful when you wish to pre-register extension objects. Note that if loading fails the provided Wallet object may be in an indeterminate state and should be thrown away. Do not simply call this method again on the same Wallet object with forceReset set true. It won't work.

      If forceReset is true, then no transactions are loaded from the wallet, and it is configured to replay transactions from the blockchain (as if the wallet had been loaded and Wallet.reset() had been called immediately thereafter).

      A wallet can be unreadable for various reasons, such as inability to open the file, corrupt data, internally inconsistent data, a wallet extension marked as mandatory that cannot be handled and so on. You should always handle UnreadableWalletException and communicate failure to the user in an appropriate manner.

      Throws:
      UnreadableWalletException - thrown in various error conditions (see description).

    • parseToProto

      public static Protos.Wallet parseToProto(InputStream input) throws IOException
      Returns the loaded protocol buffer from the given byte stream. You normally want Wallet.loadFromFile(File, WalletExtension...) instead - this method is designed for low level work involving the wallet file format itself.
      Throws:
      IOException

    • isWallet

      public static boolean isWallet(InputStream is)
      Cheap test to see if input stream is a wallet. This checks for a magic value at the beginning of the stream.
      Parameters:
      is - input stream to test
      Returns:
      true if input stream is a wallet