core-lightning/lightning.proto

// 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;
}

//
// Packet Types
//

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

  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 = 6;

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

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

// 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 = 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
  required uint64 amount = 2;
  // Hash for HTLC R value.
  required sha256_hash r_hash = 3;
  // Time at which HTLC expires (absolute)
  required locktime locktime = 4;
  // FIXME: Routing information.
}

// Complete an HTLC
message update_complete_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 = 3;
}

// Remove an HTLC
message update_remove_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 = 3;
}

// Respond to an HTLC remove request: not yet.
// Expect a remove_htlc later.
message update_remove_htlc_delay {
  // Hash for HTLC R value.
  required sha256_hash r_hash = 1;
}

  // 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 = 3;
}

// 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;
}

// 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 = 201;
    open_anchor open_anchor = 202;
    open_commit_sig open_commit_sig = 203;
    open_complete open_complete = 204;
    // 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_complete_htlc update_complete_htlc = 6;
    update_remove_htlc update_remove_htlc = 7;
    update_remove_htlc_delay update_remove_htlc_delay = 8;
    // Closing
    close_channel close = 401;
    close_channel_complete close_complete = 402;

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