Bitcoin Forum

service Bitcoin {
  // AddtoContext either creates or updates a context specified by past Context messages.
  // The Context message sent can only contain fields labelled Load below.
  rpc AddtoContext(Context) returns Context;

  // Returns a Context message containing all data needed to restore the context without scanning the block chain
  rpc DumpContext(context_id) returns Context;

  // Remove all data associated with a context from memory.
  rpc RemoveContext(context_id);

  // SetContext specified what fields the client would like notifications for.  Every field that is included in the passed Notification message will be set to receive notifications.  This replaces the current notification set each time called.
  rpc SetNotify(Notification);

  // Get the complete context data filtered by SetNotify, commonly called before GetNotifications
  rpc GetContext(context_id) returns Context;

  // One mechanism to receive notifications.  Each call would return a Notification message containing all data that has changed since the last call.
  rpc GetNotifications() returns Notification;
}


message Notification {
  optional Global global;
  repeated Context contexts;
}

message Global {
  optional PeerInfo peers;
  optional BlockChain chain;
}

message Context {
  required bytes context_id;

  repeated PublicKey keys;
  repeated PublicKey keys_delete;
  repeated scriptPublicKey scripts;
  repeated scriptPublicKey scripts_delete;
  repeated Transaction transactions;
  repeated Transaction transactions_delete;
  // Add more repeated fields for additional transaction criteria

  // For setting notifications (SetNotify) the deleted fields are not valid and each item can only be specified once making it equivalent to optional instead of repeated in that case.
}

message PublicKey {
  // All PublicKey messages must contain either a public_key or i if the message is a child of another PublicKey message.
  optional bytes public_key;        // Load, not required if included as child in other PublicKey message
  optional bytes chain_code;      // Load, Specified for BIP 32 addresses

  optional int32 i;                        // Load, Specified for BIP 32 addresses

  optional int32 i_look_ahead;    // Load, Specified for BIP 32 addresses

  repeated PublicKey children;    // Load, Only used for BIP 32 addresses, this field is not accepted to set notifications.

  repeated Transaction tx_received;
  repeated Transaction tx_sent;

  repeated Transaction tx_received_defunct;
  repeated Transaction tx_sent_defunct;
  // Defunct list is mutually exclusive with regular list of transactions.  If a transaction is made invalid (e.g. double spend) a notification will be sent with that transaction in the defunct list to signify it has been removed from the regular list.

  // Contains total balance from all transactions including child transactions
  optional int64 balance;
  optional int64 received;

  optional int32 confirmations;  // Minimum confirmations of all transactions including children

  optional int32 scan_progress;
}

message scriptPublicKey {
  optional bytes script;
  optional bytes script_hash;

  repeated Transaction tx_received;
  repeated Transaction tx_sent;

  repeated Transaction tx_received_defunct;
  repeated Transaction tx_sent_defunct;
  // Defunct list is mutually exclusive with regular list of transactions.  If a transaction is made invalid (e.g. double spend) a notification will be sent with that transaction in the defunct list to signify it has been removed from the regular list.

  // Contains total balance from all transactions including child transactions
  optional int64 balance;
  optional int64 received;

  optional int32 confirmations;  // Minimum confirmations of all transactions including children

  optional int32 scan_progress; 
}


message Transaction {
  optional bytes raw_transaction;

  // Identify transaction
  optional bytes txid;                // Load, used to allow daemon to quickly find relevant transactions when loading context
  optional bytes block_hash;    // Load
  optional int32 transaction_no;  // Load, Transaction location in block

  optional int32 confirmations;

  optional int64 amount;
  optional int64 fee;
}

message BlockChain {
  optional uint32 height_from_peers;  // Best block height based on response from peers
  optional uint32 backtrack; // Used to fetch a specified number of blocks from the main chain to the current best block
  repeated Block main_chain;
  repeated Block orphaned;
  // main_chain and orphaned is mutually exclusive so adding the same block to one implies it is not included in the other
}

message Block {
  optional bytes raw_block;
  optional uint32 height
  optional byte hash;
  optional byte previous;
  optional byte root;

  // More block info
}

message PeerInfo {
  optional int32 count;
  Peer {
    optional bytes address;
    optional int32  services;
    optional int64 lastsend;
    optional int64 lastrecv;
    optional int64 conntime;
    optional int32 version;
    optional string subver;
    optional bool inbound;
    optional int64 releasetime;
    optional int32 startingheight;
    optional int32 banscore;
  }
  repeated Peer peers;
}

Context: {
  context_id: Unique id for wallet possibly first key in pool
  keys: [{
    public_key: Public key matching wallet private key
  }] // Repeat for each key in the wallet
}

Notification {
  global: {
    peers: {
      count: 1  // Receive notification anytime the number of peers changes
    }
    chain: {
      height_from_peers: 1  // Receive notification of the expected newest block high in the chain
      main_chain: {
        height: 1  // Receive notification of the newest block height after that new block is accepted
      }
    }
  }
  contexts: [{
    context_id: same context from AddToContext
    keys: [
    {
      public_key: 1  // Include public key so the notification can be identified
      tx_in: {
        raw_transaction: 1  // Send full transaction when its output matches the public_key
        // Could receive notification for other fields describing the transaction.
      }
      tx_out: {
        raw_transaction: 1  // Send full transaction when its input matches the public_key
      }
    }]
}

Notification {
  global: {
    peers: {
      count: 16 // Number of peers changed
    }
  }
  contexts: [{
    context_id: same context from AddToContext
    keys: [
    {
      public_key:
      tx_in: [{
        raw_transaction: raw transaction data
      }]
      tx_out: [{
        raw_transaction: raw transaction data
      }]
    }]
  }]
}

Notification {
  global: {
    blocks: {
      main_chain: {
        hash: 1     
      }
    }
  }
}

Notification {
  global {
    blocks: {
      main_chain: {
        hash: Best block hash
      }
    }
  }
}

Context: {
  context_id: Unique id for wallet possibly first key in pool
  keys: [{
    public_key: master node key
    chain_code: chain code
    children: [{
      i: 0  // Look at the 0 chain
      i_look_ahead: 0 // Don't look for any other keys at this level
      children: [{
        i: 0  // External Chain by BIP 32
        children: [{
          i: 0
          i_look_ahead: 2
        }]
      }, {
        i: 1  // Internal Chain by BIP 32
      children: [{
          i: 0
          i_look_ahead: 2
        }]
      }]
    }]
  }] // Repeat for each key in the wallet
}

Notification {
  contexts: [{
    context_id: same context from AddToContext
    keys: {
      i: 1

      // We are only interested in the amount received for each key, not the full transactions
      received: 1
      confirmations: 1
    }
  }]
}

Notification {
  contexts: [{
    context_id: same context from AddToContext
    keys: [
    {
      children: [{
        i: 0  // Internal chain
        received: 100000000  // One bitcoin received.
        confirmations: 0  // New notification will be sent each time confirmations changes
        children: [{
          i: 0 // Transaction on first address on Internal chain
          received: 100000000  // One bitcoin received.
          confirmations: 0
        }]
      }]
    }]
}