Package org.bitcoinj.wallet

Class WalletProtobufSerializer

  • public class WalletProtobufSerializer
extends java.lang.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.

    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 Detail

      • 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 java.util.Map<com.google.protobuf.ByteString,​Transaction> txMap

    • Method Detail

      • 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,
                        java.io.OutputStream output)
                 throws java.io.IOException
        Formats the given wallet (transactions and keys) to the given output stream in protocol buffer format.

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

        Throws:
        java.io.IOException

      • walletToText

        public java.lang.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​(java.io.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​(java.io.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​(java.io.InputStream input)
                                  throws java.io.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:
        java.io.IOException

      • isWallet

        public static boolean isWallet​(java.io.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