org.bitcoinj.wallet

Class WalletProtobufSerializer

java.lang.Object

org.bitcoinj.wallet.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.

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	WalletProtobufSerializer.WalletFactory

Field Summary

Fields

Modifier and Type	Field and Description
static int	CURRENT_WALLET_VERSION Current version used for serializing wallets.
protected java.util.Map<com.google.protobuf.ByteString,Transaction>	txMap

Constructor Summary

Constructors

Constructor and Description
WalletProtobufSerializer()
WalletProtobufSerializer(WalletProtobufSerializer.WalletFactory factory)

Method Summary

Modifier and Type	Method and Description
static Sha256Hash	byteStringToHash(com.google.protobuf.ByteString bs)
static com.google.protobuf.ByteString	hashToByteString(Sha256Hash hash)
static boolean	isWallet(java.io.InputStream is) Cheap test to see if input stream is a wallet.
static Protos.Wallet	parseToProto(java.io.InputStream input) Returns the loaded protocol buffer from the given byte stream.
Wallet	readWallet(java.io.InputStream input, boolean forceReset, WalletExtension[] extensions) Loads wallet data from the given protocol buffer and inserts it into the given Wallet object.
Wallet	readWallet(java.io.InputStream input, WalletExtension... walletExtensions) Loads wallet data from the given protocol buffer and inserts it into the given Wallet object.
Wallet	readWallet(NetworkParameters params, WalletExtension[] extensions, Protos.Wallet walletProto) Loads wallet data from the given protocol buffer and inserts it into the given Wallet object.
Wallet	readWallet(NetworkParameters params, WalletExtension[] extensions, Protos.Wallet walletProto, boolean forceReset) Loads wallet data from the given protocol buffer and inserts it into the given Wallet object.
void	setKeyChainFactory(KeyChainFactory keyChainFactory)
void	setRequireAllExtensionsKnown(boolean value) If this property is set to true, the wallet will fail to load if any found extensions are unknown..
void	setRequireMandatoryExtensions(boolean value) If this property is set to false, then unknown mandatory extensions will be ignored instead of causing load errors.
void	setWalletWriteBufferSize(int walletWriteBufferSize) Change buffer size for writing wallet to output stream.
Protos.Wallet	walletToProto(Wallet wallet) Converts the given wallet to the object representation of the protocol buffers.
java.lang.String	walletToText(Wallet wallet) Returns the given wallet formatted as text.
void	writeWallet(Wallet wallet, java.io.OutputStream output) Formats the given wallet (transactions and keys) to the given output stream in protocol buffer format.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

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

Constructor Detail

WalletProtobufSerializer

public WalletProtobufSerializer()

WalletProtobufSerializer

public WalletProtobufSerializer(WalletProtobufSerializer.WalletFactory factory)

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 although it can also be parsed using TextFormat.merge(CharSequence, Message.Builder), 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