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 rval {
  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 {
  // Must be 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 authenticate {
  // Which node this is.
  required bitcoin_pubkey node_id = 1;
  // Signature of your session key. */
  required signature session_sig = 2;
};

// We're authenticated.  Here's what we've received already.
message init {
  // How many update_commit and update_revocation messages already received
  required uint64 ack = 1;
  // What features do we support (odd) and require (even)
  optional bytes features = 2;
};

// 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;
  // Hash for revoking second commitment transaction.
  required sha256_hash next_revocation_hash = 8;
  // 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 initial_fee_rate = 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;
}

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

message route_step {
  // Where to next?
  oneof next {
    // Actually, this is the last one
    bool end = 1;
    // Next lightning node.
    bitcoin_pubkey bitcoin = 2;
    // Other realms go here...
  }

  // How much to forward (difference is fee)
  required uint32 amount = 4;
};

message route {
  repeated route_step steps = 1;
};

message routing {
  required bytes info = 1;
}

// Start a new commitment tx to add an HTLC me -> you.
message update_add_htlc {
  // Unique identifier for this HTLC.
  required uint64 id = 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;
  // Onion-wrapped routing information.
  required routing route = 5;
}

// Complete your HTLC: I have the R value, pay me!
message update_fulfill_htlc {
  // Which HTLC
  required uint64 id = 1;
  // HTLC R value.
  required rval r = 2;
}

// This is encrypted in fail_reason.
message fail_info {
  required bitcoin_pubkey id = 1;
  required uint32 error_code = 2;
  optional string reason = 3;
}

message fail_reason {
  required bytes info = 1;
}

message update_fail_htlc {
  // Which HTLC
  required uint64 id = 1;
  // Reason for failure (for relay to initial node)
  required fail_reason reason = 2;
}

// Fee rate change proposal
message update_fee {
  required uint32 fee_rate = 1;
}

// Commit all the staged changes.
message update_commit {
  // Signature for your new commitment tx (if any outputs are HTLCs or to you)
  optional signature sig = 1;
}

// Complete the update.
message update_revocation {
  // Hash preimage which revokes old commitment tx.
  required sha256_hash revocation_preimage = 1;
  // Revocation hash for my next commit transaction
  required sha256_hash next_revocation_hash = 2;
}

// Start clearing out the channel HTLCs so we can close it
message close_shutdown {
  // Output script for mutual close tx.
  required bytes scriptPubkey = 1;
}

message close_signature {
  // Fee in satoshis.
  required uint64 close_fee = 1;
  // Signature on the close transaction.
  required signature sig = 2;
}

// 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 {
    // Start of connection
    authenticate auth = 50;
    init init = 51;

    // 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_add_htlc update_add_htlc = 2;
    update_fulfill_htlc update_fulfill_htlc = 3;
    update_fail_htlc update_fail_htlc = 4;
    update_fee update_fee = 5;
    update_commit update_commit = 6;
    update_revocation update_revocation = 7;

    // Closing
    close_shutdown close_shutdown = 30;
    close_signature close_signature = 31;

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