rpc.proto

syntax = "proto3";

// The following RPC methods implements methods found in lnd so that
// lnd doesn't need to hold any private keys and can instead use this
// gRPC service to sign transactions and get wallet information.
service Pine {
  // SignMessage signs a message using the user's private key.
  rpc SignMessage(SignMessageRequest) returns (SignMessageResponse) {}

  // ListUnspentWitness returns a list of unspent transaction outputs from
  // the user's wallet.
  rpc ListUnspentWitness(ListUnspentWitnessRequest) returns (ListUnspentWitnessResponse) {}

  // LockOutpoint marks an unspent transaction output as reserved excluding
  // it from coin selection.
  rpc LockOutpoint(LockOutpointRequest) returns (LockOutpointResponse) {}

  // UnlockOutpoint unmarks an unspent transaction output as reserved making
  // it eligible for coin selection.
  rpc UnlockOutpoint(UnlockOutpointRequest) returns (UnlockOutpointResponse) {}

  // NewAddress returns the next external or internal address for the wallet.
  rpc NewAddress(NewAddressRequest) returns (NewAddressResponse) {}

  // IsOurAddress returns whether or not the passed address belongs to the
  // user's wallet.
  rpc IsOurAddress(IsOurAddressRequest) returns (IsOurAddressResponse) {}

  // FetchInputInfo returns information about a transaction output.
  rpc FetchInputInfo(FetchInputInfoRequest) returns (FetchInputInfoResponse) {}

  // SignOutputRaw signs a transaction.
  rpc SignOutputRaw(SignOutputRawRequest) returns (SignOutputRawResponse) {}

  // ComputeInputScript computes an input script for a transaction.
  rpc ComputeInputScript(ComputeInputScriptRequest) returns (ComputeInputScriptResponse) {}

  // GetRevocationRootKey returns a private key to be used as a revocation root.
  // TODO: Create an API for getting revocation secrets instead of exposing private keys.
  rpc GetRevocationRootKey(GetRevocationRootKeyRequest) returns (GetRevocationRootKeyResponse) {}

  // DeriveNextKey returns a key descriptor for the next key for the specified key family.
  rpc DeriveNextKey(DeriveNextKeyRequest) returns (DeriveNextKeyResponse) {}

  // DeriveKey returns a key descriptor for a private key specified by
  // the passed key locator.
  rpc DeriveKey(DeriveKeyRequest) returns (DeriveKeyResponse) {}
}

message SignMessageRequest {
  // Message to sign.
  bytes message = 1;

  // Public key of the private key to sign with (65 bytes uncompressed).
  bytes publicKey = 2;
}

message SignMessageResponse {
  // Signature of the given message (DER-encoded).
  bytes signature = 1;
}

message ListUnspentWitnessRequest {
  int32 minConfirmations = 1;
  int32 maxConfirmations = 2;
}

message ListUnspentWitnessResponse {
  repeated Utxo utxos = 1;
}

message Utxo {
  uint32 addressType = 1;
  int64 value = 2; // In satoshis
  int64 confirmations = 3;
  bytes pkScript = 4;
  bytes transactionHash = 5;
  uint32 vout = 6; // Index of the output in the transaction
}

message LockOutpointRequest {
  bytes hash = 1; // Hash of the output's transaction
  uint32 index = 2; // Index of the output in the transaction
}

message LockOutpointResponse {}

message UnlockOutpointRequest {
  bytes hash = 1; // Hash of the output's transaction
  uint32 index = 2; // Index of the output in the transaction
}

message UnlockOutpointResponse {}

message NewAddressRequest {
  uint32 type = 1; // Address type of new address
  bool change = 2; // If true, an internal address is returned
}

message NewAddressResponse {
  string address = 1; // base58check encoded
}

message IsOurAddressRequest {
  string address = 1;
}

message IsOurAddressResponse {
  bool isOurAddress = 1;
}

message FetchInputInfoRequest {
  bytes hash = 1; // Hash of the output's transaction
  uint32 index = 2; // Index of the output in the transaction
}

message FetchInputInfoResponse {
  Utxo utxo = 1;
}

message SignOutputRawRequest {
  Transaction transaction = 1;
  SignDescriptor signDescriptor = 2;
}

message SignOutputRawResponse {
  // Witness signature without the hash type flag.
  bytes signature = 1;
}

message ComputeInputScriptRequest {
  Transaction transaction = 1;
  SignDescriptor signDescriptor = 2;
}

message ComputeInputScriptResponse {
  repeated bytes witness = 1;
  bytes signatureScript = 2;
}

message Transaction {
  int32 version = 1;
  repeated TransactionInput inputs = 2;
  repeated TransactionOutput outputs = 3;
  uint32 lockTime = 4;
}

message TransactionInput {
  bytes transactionHash = 1;
  uint32 index = 2;
  bytes signatureScript = 3;
  repeated bytes witness = 4;
  uint32 sequence = 5;
}

message TransactionOutput {
  int64 value = 1; // In satoshis
  bytes pkScript = 2;
}

message SignDescriptor {
  KeyDescriptor keyDescriptor = 1;
  bytes singleTweak = 2;
  bytes doubleTweak = 3;
  bytes witnessScript = 4;
  TransactionOutput output = 5;
  uint32 hashType = 6; // Enum, see src/methods/signOutputRaw.js for mapping
  TransactionSigHashes sigHashes = 7;
  uint32 inputIndex = 8;
}

message KeyDescriptor {
  KeyLocator keyLocator = 1;
  bytes publicKey = 2; // 65 bytes uncompressed
}

message KeyLocator {
  // BIP43 path: m/1017'/coinType'/keyFamily/0/index
  uint32 keyFamily = 1;
  uint32 index = 2;
}

message TransactionSigHashes {
  bytes hashPrevOuts = 1;
  bytes hashSequence = 2;
  bytes hashOutputs = 3;
}

message GetRevocationRootKeyRequest {}

message GetRevocationRootKeyResponse {
  bytes privateKey = 1;
}

message DeriveNextKeyRequest {
  uint32 keyFamily = 1;
}

message DeriveNextKeyResponse {
  KeyDescriptor keyDescriptor = 1;
}

message DeriveKeyRequest {
  KeyLocator keyLocator = 1;
}

message DeriveKeyResponse {
  KeyDescriptor keyDescriptor = 1;
}