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

// To update the channel (commit tx or close tx) we need a signature for each
// input.
message anchor_spend {
  // From first anchor input.
  required signature sig0 = 1;
  // From second anchor input.
  required signature sig1 = 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.
  oneof locktime {
    uint32 locktime_seconds = 2;
    uint32 locktime_blocks = 3;
  }
  // Hash seed for revoking commitment transactions.
  required sha256_hash revocation_hash = 4;
  // How to pay money to us from commit_tx (also for escape txs)
  required bitcoin_pubkey final = 5;
  // How much transaction fee we'll pay for commitment txs.
  required uint64 commitment_fee = 6;
  // Key for commitment tx 2of2.
  required bitcoin_pubkey commitkey = 7;
  // How much we'll be putting into channel
  required uint64 total_input = 8;
  // Secret hash for escape transactions.
  required sha256_hash escape_hash = 9;
  // How many confirmations on anchor before we'll use channel.
  required uint32 min_confirms = 10;
}

// Give them the txid of our anchor transaction.
message open_anchor {
  required sha256_hash anchor_txid = 1;
  // Which output of anchor goes to this.
  required uint32 index = 2;
}

// Give them signatures for their escape transactions.
message open_escape_sigs {
  // Signature for their escape tx.
  required signature escape = 1;
  // Signature for their fast-escape tx.
  required signature fast_escape = 2;
}

// Supply signatures for commitment tx
message open_commit_sig {
  required anchor_spend sigs = 1;
}

// Indicates we've seen transaction 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;
  // FIXME: optional HTLC ops.
}

// OK, I accept that update; here's your signature.
message update_accept {
  // Signatures for your new commitment tx.
  required anchor_spend sigs = 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 {
  // Signatures for your new commitment tx.
  required anchor_spend sigs = 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 {
  // These are our signatures on a new transaction which spends the anchor
  // outputs to my open->final and your open->final, as per the last commit tx.
  required anchor_spend sigs = 1;
}

// OK, here's my sig so you can broadcast it too.  We're done.
message close_channel_complete {
  // These are my signatures for that same tx.
  required anchor_spend sigs = 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 = 203;
    open_escape_sigs open_escape_sigs = 205;
    open_commit_sig open_commit_sig = 202;
    open_complete open_complete = 204;
    // Updating (most common)
    update update = 1;
    update_accept update_accept = 2;
    update_signature update_signature = 3;
    update_complete update_complete = 4;
    // Closing
    close_channel close = 401;
    close_channel_complete close_complete = 402;

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