core-lightning/lightning.proto

syntax = "proto2";

// The outer layer handles encryption, authentication and message
// boundaries.

//
// Helper Types
//

// Protobufs don't have fixed-length fields, so these are a hack.
message sha256_hash {
  required fixed64 a = 1;
  required fixed64 b = 2;
  required fixed64 c = 3;
  required fixed64 d = 4;
}

message signature {
  required fixed64 r1 = 1;
  required fixed64 r2 = 2;
  required fixed64 r3 = 3;
  required fixed64 r4 = 4;
  required fixed64 s1 = 5;
  required fixed64 s2 = 6;
  required fixed64 s3 = 7;
  required fixed64 s4 = 8;
}

message locktime {
  oneof locktime {
    uint32 seconds = 1;
    uint32 blocks = 2;
  }
}

// Pubkey for commitment transaction input.
message bitcoin_pubkey {
  // Either 65 or 33 bytes.
  required bytes key = 1;
}

// How much a node charges (or pays!) for sending.
message funding {
  // Base amount (in satoshi).
  optional int64 fixed = 1 [ default = 0 ];
  // This is charge per millionth of a satoshi.
  optional int32 per_micro_satoshi = 2 [ default = 0 ];
}

//
// Packet Types
//

// Set channel params.
message open_channel {
  // Relative locktime for outputs going to us.
  required locktime delay = 1;
  // Hash for revoking first commitment transaction.
  required sha256_hash revocation_hash = 2;
  // Pubkey for anchor to pay into commitment tx.
  required bitcoin_pubkey commit_key = 3;
  // How to pay money to us from commit_tx.
  required bitcoin_pubkey final_key = 4;

  enum anchor_offer {
    // I will create the anchor
    WILL_CREATE_ANCHOR = 1;
    // I won't create the anchor
    WONT_CREATE_ANCHOR = 2;
  }
  required anchor_offer anch = 5;

  // How far must anchor be buried before we consider channel live?
  optional uint32 min_depth = 6 [ default = 0 ];

  // How much fee would I like on commitment tx?
  required uint64 commitment_fee = 7;
}

// Whoever is supplying anchor sends this.
message open_anchor {
  // Transaction ID of anchor.
  required sha256_hash txid = 1;
  // Which output is going to the 2 of 2.
  required uint32 output_index = 2;
  // Amount of anchor output.
  required uint64 amount = 3;

  // Signature for your initial commitment tx.
  required signature commit_sig = 4;
}

// Reply: signature for your initial commitment tx
message open_commit_sig {
  required signature sig = 1;
}

// Indicates we've seen anchor reach min-depth.
message open_complete {
  // Block it went into.
  optional sha256_hash blockid = 1;
  // FIXME: add a merkle proof plus block headers here?
}

// Let's spend some money in the channel!
message update {
  // Hash for which I will supply preimage to revoke this.
  required sha256_hash revocation_hash = 1;
  // Change in current payment to-me (implies reverse to-you).
  required sint64 delta_msat = 2;
}

// Start a new commitment tx to add an HTLC me -> you.
message update_add_htlc {
  // Hash for which I will supply preimage to revoke this commitment tx.
  required sha256_hash revocation_hash = 1;
  // Amount for htlc (millisatoshi)
  required uint32 amount_msat = 2;
  // Hash for HTLC R value.
  required sha256_hash r_hash = 3;
  // Time at which HTLC expires (absolute)
  required locktime expiry = 4;
  // FIXME: Routing information.
}

// We can't do this HTLC, sorry (instead of update_accept)
message update_decline_htlc {
  oneof reason {
    funding insufficient_funds = 1;
    bool cannot_route = 2;
  };
}

// Complete your HTLC: I have the R value, pay me!
message update_fulfill_htlc {
  // Hash for which I will supply preimage to revoke this commitment tx.
  required sha256_hash revocation_hash = 1;
  // HTLC R value.
  required sha256_hash r = 2;
}

// Remove my HTLC: it has timed out, before you got the R value.
message update_timedout_htlc {
  // Hash for which I will supply preimage to revoke this commitment tx.
  required sha256_hash revocation_hash = 1;
  // Hash for HTLC R value.
  required sha256_hash r_hash = 2;
}

// Remove your HTLC: routing has failed upstream
message update_routefail_htlc {
  // Hash for which I will supply preimage to revoke this commitment tx.
  required sha256_hash revocation_hash = 1;
  // Hash for HTLC R value.
  required sha256_hash r_hash = 2;
}

// OK, I accept that update; here's your signature.
message update_accept {
  // Signature for your new commitment tx.
  required signature sig = 1;
  // Hash for which I will supply preimage to revoke this new commit tx.
  required sha256_hash revocation_hash = 2;
}

// Thanks for accepting, here's my last bit.
message update_signature {
  // Signature for your new commitment tx.
  required signature sig = 1;
  // Hash preimage which revokes old commitment tx.
  required sha256_hash revocation_preimage = 2;
}

// Complete the update.
message update_complete {
  // Hash preimage which revokes old commitment tx.
  required sha256_hash revocation_preimage = 1;
}

// Begin cooperative close of channel.
message close_channel {
  // This is our signature a new transaction which spends the anchor
  // output to my open->final and your open->final,
  // as per the last commit tx.
  required signature sig = 1;
  // Fee to pay for close transaction.
  required uint64 close_fee = 2;
}

// OK, here's my sig so you can broadcast it too.  We're done.
message close_channel_complete {
  // This is my signature for that same tx.
  required signature sig = 1;
}

// Received close_channel_complete, you can close now.
message close_channel_ack {
}

// This means we're going to hang up; it's to help diagnose only! 
message error {
  optional string problem = 1;
}

// This is the union which defines all of them
message pkt {
  oneof pkt {
    // Opening
    open_channel open = 20;
    open_anchor open_anchor = 21;
    open_commit_sig open_commit_sig = 22;
    open_complete open_complete = 23;
    // Updating (most common)
    update update = 1;
    update_add_htlc update_add_htlc = 2;
    update_accept update_accept = 3;
    update_signature update_signature = 4;
    update_complete update_complete = 5;
    update_decline_htlc update_decline_htlc = 6;
    update_fulfill_htlc update_fulfill_htlc = 7;
    update_timedout_htlc update_timedout_htlc = 8;
    update_routefail_htlc update_routefail_htlc = 9;
    // Closing
    close_channel close = 30;
    close_channel_complete close_complete = 31;
    close_channel_ack close_ack = 32;

    // Unexpected issue.
    error error = 40;
  }
}