altcoinj/core/src/bitcoin.proto

/** Copyright 2012 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 (a.k.a. network order)
 */

package wallet;

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

/**
 * A key use 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; // Original bitcoin secp256k1 curve
  }
  required Type type = 1;

  // The private EC key bytes without any ASN.1 wrapping.
  optional bytes private_key = 2;
  // 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 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 int32 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.
    NOT_SEEN_IN_CHAIN = 2; // Pending inclusion in best chain.
    NOT_IN_BEST_CHAIN = 3; // In non-best chain, pending inclusion in best chain.
    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;
}

/** 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).
  repeated bytes block_hash = 8;

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

/** 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 {
  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;

  repeated Key key = 3;
  repeated Transaction transaction = 4;
  repeated Extension extension = 10; 
} // end of Wallet