altcoinj/core/src/bitcoin.proto

/** Copyright 2013 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/*
 * Authors: Jim Burton, Miron Cuperman
 */
 
/* Notes:
 * - Endianness: All byte arrays that represent numbers (such as hashes and private keys) are Big Endian
 * - To regenerate after editing, run mvn clean package -DupdateProtobuf
 */

package wallet;

option java_package = "org.bitcoinj.wallet";
option java_outer_classname = "Protos";

message PeerAddress {
  required bytes ip_address = 1;
  required uint32 port = 2;
  required uint64 services = 3;
}

/**
 * The data to store a private key encrypted with Scrypt and AES
 *
 */
message EncryptedPrivateKey {
  required bytes initialisation_vector = 1;       // The initialisation vector for the AES encryption (16 bytes)
  required bytes encrypted_private_key = 2;       // The encrypted private key
}

/**
 * A key used to control Bitcoin spending.
 *
 * Either the private key, the public key or both may be present.  It is recommended that
 * if the private key is provided that the public key is provided too because deriving it is slow.
 *
 * If only the public key is provided, the key can only be used to watch the blockchain and verify
 * transactions, and not for spending.
 */
message Key {
  enum Type {
    ORIGINAL = 1;              // Unencrypted - Original bitcoin secp256k1 curve
    ENCRYPTED_SCRYPT_AES = 2;  // Encrypted with Scrypt and AES - - Original bitcoin secp256k1 curve
  }
  required Type type = 1;

  // The private EC key bytes without any ASN.1 wrapping.
  optional bytes private_key = 2;

  // The message containing the encrypted private EC key information.
  // When an EncryptedPrivateKey is present then the (unencrypted) private_key will be a zero length byte array or contain all zeroes.
  // This is for security of the private key information.
  optional EncryptedPrivateKey encrypted_private_key = 6;

  // The public EC key derived from the private key. We allow both to be stored to avoid mobile clients having to
  // do lots of slow EC math on startup.
  optional bytes public_key = 3;

  // User-provided label associated with the key.
  optional string label = 4;

  // Timestamp stored as millis since epoch. Useful for skipping block bodies before this point.
  optional int64 creation_timestamp = 5;
}

message Script {
    required bytes program = 1;

    // Timestamp stored as millis since epoch. Useful for skipping block bodies before this point
    // when watching for scripts on the blockchain.
    required int64 creation_timestamp = 2;
}

message TransactionInput {
  // Hash of the transaction this input is using.
  required bytes transaction_out_point_hash = 1;
  // Index of transaction output used by this input.
  required uint32 transaction_out_point_index = 2;
  // Script that contains the signatures/pubkeys.
  required bytes script_bytes = 3;
  // Sequence number. Currently unused, but intended for contracts in future.
  optional uint32 sequence = 4;
}

message TransactionOutput {
  required int64 value = 1;
  required bytes script_bytes = 2;    // script of transaction output
  // If spent, the hash of the transaction doing the spend.
  optional bytes spent_by_transaction_hash = 3;
  // If spent, the index of the transaction input of the transaction doing the spend.
  optional int32 spent_by_transaction_index = 4;
}

/**
 * A description of the confidence we have that a transaction cannot be reversed in the future.
 *
 * Parsing should be lenient, since this could change for different applications yet we should
 * maintain backward compatibility.
 */
message TransactionConfidence {
  enum Type {
    UNKNOWN = 0;
    BUILDING = 1; // In best chain.  If and only if appeared_at_height is present.
    PENDING = 2; // Unconfirmed and sitting in the networks memory pools, waiting to be included in the chain.
    NOT_IN_BEST_CHAIN = 3; // Deprecated: equivalent to PENDING.
    DEAD = 4; // Either if overriding_transaction is present or transaction is dead coinbase
  }

  // This is optional in case we add confidence types to prevent parse errors - backwards compatible.
  optional Type type = 1;

  // If type == BUILDING then this is the chain height at which the transaction was included.
  optional int32 appeared_at_height = 2;

  // If set, hash of the transaction that double spent this one into oblivion. A transaction can be double spent by
  // multiple transactions in the case of several inputs being re-spent by several transactions but we don't
  // bother to track them all, just the first. This only makes sense if type = DEAD.
  optional bytes overriding_transaction = 3;

  // If type == BUILDING then this is the depth of the transaction in the blockchain.
  // Zero confirmations: depth = 0, one confirmation: depth = 1 etc.
  optional int32 depth = 4;

  // If type == BUILDING then this is the cumulative workDone for the block the transaction appears in, together with
  // all blocks that bury it.
  optional int64 work_done = 5;

  repeated PeerAddress broadcast_by = 6;

  // Where did we get this transaction from? Knowing the source may help us to risk analyze pending transactions.
  enum Source {
    SOURCE_UNKNOWN = 0;  // We don't know where it came from, or this is a wallet from the future.
    SOURCE_NETWORK = 1;  // We received it from a network broadcast. This is the normal way to get payments.
    SOURCE_SELF = 2;     // We made it ourselves, so we know it should be valid.
    // In future:
    // - direct from trusted counterparty, eg via bluetooth/wifi direct
    // - direct from untrusted counterparty
    // - from a wallet that uses trusted computing/secure hardware that won't create double spends
  }
  optional Source source = 7;
}

/** A bitcoin transaction */

message Transaction {
  /**
   * This is a bitfield oriented enum, with the following bits:
   * 
   * bit 0 - spent
   * bit 1 - appears in alt chain
   * bit 2 - appears in best chain
   * bit 3 - double-spent
   * bit 4 - pending (we would like the tx to go into the best chain)
   * 
   * Not all combinations are interesting, just the ones actually used in the enum.
   */
  enum Pool {
    UNSPENT = 4; // In best chain, not all outputs spent
    SPENT = 5; // In best chain, all outputs spent
    INACTIVE = 2; // In non-best chain, not our transaction
    DEAD = 10; // Double-spent by a transaction in the best chain
    PENDING = 16; // Our transaction, not in any chain
    PENDING_INACTIVE = 18; // In non-best chain, our transaction
  }

  // See Wallet.java for detailed description of pool semantics
  required int32 version = 1;
  required bytes hash = 2;

  // If pool is not present, that means either:
  //  - This Transaction is either not in a wallet at all (the proto is re-used elsewhere)
  //  - Or it is stored but for other purposes, for example, because it is the overriding transaction of a double spend.
  //  - Or the Pool enum got a new value which your software is too old to parse.
  optional Pool pool = 3;

  optional uint32 lock_time = 4; // The nLockTime field is useful for contracts.
  optional int64 updated_at = 5; // millis since epoch the transaction was last updated

  repeated TransactionInput transaction_input = 6;
  repeated TransactionOutput transaction_output = 7;

  // A list of blocks in which the transaction has been observed (on any chain). Also, a number used to disambiguate
  // ordering within a block.
  repeated bytes block_hash = 8;
  repeated int32 block_relativity_offsets = 11;

  // Data describing where the transaction is in the chain.
  optional TransactionConfidence confidence = 9;

  // For what purpose the transaction was created.
  enum Purpose {
    // Old wallets or the purpose genuinely is a mystery (e.g. imported from some external source).
    UNKNOWN = 0;
    // Created in response to a user request for payment. This is the normal case.
    USER_PAYMENT = 1;
    // Created automatically to move money from rotated keys.
    KEY_ROTATION = 2;
    // In future: de/refragmentation, privacy boosting/mixing, child-pays-for-parent fees, etc.
  }
  optional Purpose purpose = 10 [default = UNKNOWN];

  // Next tag: 12
}

/** The parameters used in the scrypt key derivation function.
 *  The default values are taken from http://www.tarsnap.com/scrypt/scrypt-slides.pdf.
 *  They can be increased - n is the number of iterations performed and
 *  r and p can be used to tweak the algorithm - see:
 *  http://stackoverflow.com/questions/11126315/what-are-optimal-scrypt-work-factors
 */
message ScryptParameters {
  required bytes salt = 1;                        // Salt to use in generation of the wallet password (8 bytes)
  optional int64 n = 2 [default = 16384];         // CPU/ memory cost parameter
  optional int32 r = 3 [default = 8];             // Block size parameter
  optional int32 p = 4 [default = 1];             // Parallelisation parameter
}

/** An extension to the wallet */
message Extension {
  required string id = 1;   // like org.whatever.foo.bar
  required bytes data = 2;
  // If we do not understand a mandatory extension, abort to prevent data loss.
  // For example, this could be applied to a new type of holding, such as a contract, where
  // dropping of an extension in a read/write cycle could cause loss of value.
  required bool mandatory = 3;
}

/** A bitcoin wallet */
message Wallet {
  /**
   * The encryption type of the wallet.
   *
   * The encryption type is UNENCRYPTED for wallets where the wallet does not support encryption - wallets prior to
   * encryption support are grandfathered in as this wallet type.
   * When a wallet is ENCRYPTED_SCRYPT_AES the keys are either encrypted with the wallet password or are unencrypted.
   */
  enum EncryptionType {
    UNENCRYPTED = 1;                 // All keys in the wallet are unencrypted
    ENCRYPTED_SCRYPT_AES = 2;        // All keys are encrypted with a passphrase based KDF of scrypt and AES encryption
  }

  required string network_identifier = 1; // the network used by this wallet
  // org.bitcoin.production = production network (Satoshi genesis block)
  // org.bitcoin.test = test network (Andresen genesis block)

  // The SHA256 hash of the head of the best chain seen by this wallet.
  optional bytes last_seen_block_hash = 2;
  // The height in the chain of the last seen block.
  optional uint32 last_seen_block_height = 12;
  optional int64 last_seen_block_time_secs = 14;

  repeated Key key = 3;
  repeated Transaction transaction = 4;
  repeated Script watched_script = 15;

  optional EncryptionType encryption_type = 5 [default=UNENCRYPTED];
  optional ScryptParameters encryption_parameters = 6;

  // The version number of the wallet - used to detect wallets that were produced in the future
  // (i.e the wallet may contain some future format this protobuf/ code does not know about)
  optional int32 version = 7;

  // deprecated - do not recycle this numeric identifier
  // optional int32 minor_version = 8;

  repeated Extension extension = 10;

  // A UTF8 encoded text description of the wallet that is intended for end user provided text.
  optional string description = 11;

  // (The field number 12 is used by last_seen_block_height)

  // UNIX time in seconds since the epoch. If set, then any keys created before this date are assumed to be no longer
  // wanted. Money sent to them will be re-spent automatically to the first key that was created after this time. It
  // can be used to recover a compromised wallet, or just as part of preventative defence-in-depth measures.
  optional uint64 key_rotation_time = 13;

  // Next tag: 16
}