nuts-foundation/nuts-node

/*
 * Copyright (C) 2021. Nuts community
 *
 * This program is free software: you can redistribute it and/or modify
 * it under the terms of the GNU General Public License as published by
 * the Free Software Foundation, either version 3 of the License, or
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
 * GNU General Public License for more details.
 *
 * You should have received a copy of the GNU General Public License
 * along with this program.  If not, see <https://www.gnu.org/licenses/>.
 *
 */
syntax = "proto3";

option go_package = "github.com/nuts-foundation/nuts-node/network/transport/v2";

package v2;

service Protocol {
  rpc Stream (stream Envelope) returns (stream Envelope) {
  }
}

message Envelope {
  oneof Message {
    // broadcast
    Gossip gossip = 101;
    Diagnostics diagnosticsBroadcast = 102;

    // request, starts a conversation with a new ID
    State state = 201;
    TransactionListQuery transactionListQuery = 202;
    TransactionRangeQuery transactionRangeQuery = 203;
    TransactionPayloadQuery transactionPayloadQuery = 204;

    // response, contains conversationID from request
    TransactionSet transactionSet = 301;
    TransactionList transactionList = 302;
    TransactionPayload transactionPayload = 304;
  }
}

// Transaction represents a transaction on the DAG.
message Transaction {
  // data contains the data of the transaction, which is a JWS as specified by RFC004.
  bytes data = 2;
  // payload contains the payload when it may be attached but wasn't so in the transaction already
  optional bytes payload = 3;
}

// Gossip is a message broadcast to inform peers of the node's DAG state and recent additions to it (if any).
// The message has no response, but the peer may decide to follow up with State or TransactionListQuery.
message Gossip {
  // XOR contains the XOR'ed value of all transaction references on the sender's DAG.
  bytes XOR = 1;
  // LC contains the highest transaction Lamport Clock value of the sender.
  uint32 LC = 2;
  // transactions is a list of transactions recently added to the DAG
  repeated bytes transactions = 3;
}

// State is a request for the peer's DAG state up to the given LC value
message State {
  // conversationID contains the token used to identify the response
  bytes conversationID = 1;
  // XOR contains the XOR'ed value of ALL transaction references on the sender's DAG.
  bytes XOR = 2;
  // LC contains the Lamport Clock value (inclusive) for which the node requests an IBLT
  uint32 LC = 3;
}

// TransactionSet sends an IBLT in response to a State message
message TransactionSet {
  // conversationID contains the token used to identify the response
  bytes conversationID = 1;
  // LCReq contains the LC value that was sent in the State message
  uint32 LCReq = 2;
  // LC contains the highest transaction Lamport Clock value from the sender of this message.
  uint32 LC = 3;
  // IBLT contains the serialized IBLT. The first byte indicates the serialization format of the IBLT.
  bytes IBLT = 4;
}

// TransactionListQuery is a request for transactions by references
message TransactionListQuery {
  // conversationID contains the token used to identify the response
  bytes conversationID = 1;
  // refs is the list of requested transactions by reference
  repeated bytes refs = 2;
}

// TransactionRangeQuery is a request for transactions by LC range
message TransactionRangeQuery {
  // conversationID contains the token used to identify the response
  bytes conversationID = 1;
  // start indicates the start of the requested Lamport Clock range (inclusive)
  uint32 start = 2;
  // end indicates the end of the requested Lamport Clock range (exclusive)
  uint32 end = 3;
}

// TransactionList contains a list of transactions requested in TransactionListQuery or TransactionRangeQuery
message TransactionList {
  // conversationID contains the token used to identify the response
  bytes conversationID = 1;
  // transactions contains the list of requested transactions. Transactions MUST be sorted by LC value
  repeated Transaction transactions = 2;
  // totalMessages is the number of messages that are in the TransactionList sequence with this conversationID
  uint32 totalMessages = 3;
  // messageNumber identifies which message this is in the sequence. Uses 1-based indexing
  uint32 messageNumber = 4;
}

// TransactionPayloadQuery is a message used to query the payload of a transaction.
message TransactionPayloadQuery {
  // conversationID contains the token used to identify the response
  bytes conversationID = 1;
  // transactionRef contains the reference (hash) of the transaction, which payload the node would like to receive, as specified by RFC004.
  bytes transactionRef = 2;
}

// TransactionPayload is the response message for TransactionPayloadQuery
message TransactionPayload {
  // conversationID contains the token used to identify the response
  bytes conversationID = 1;
  // transactionRef contains the reference to the transaction which' payload was requested.
  bytes transactionRef = 2;
  // data contains the actual payload.
  bytes data = 10;
}

// Diagnostics is a message to inform peers of the local node's state. All fields are optional.
message Diagnostics {
  // uptime contains the uptime (time since the node started) in seconds.
  uint32 uptime = 1;
  // peerID contains the ID of the node.
  string peerID = 2;
  // peers contains the peer IDs of the node's peers.
  repeated string peers = 3;
  // numberOfTransactions contains the total number of transactions on the node's DAG.
  uint32 numberOfTransactions = 4;
  // softwareVersion contains an indication of the software version of the node. It's recommended to use a (Git) commit ID that uniquely resolves to a code revision, alternatively a semantic version could be used (e.g. 1.2.5).
  string softwareVersion = 10;
  // softwareID contains an identification of the particular Nuts implementation of the node.
  // For open source implementations it's recommended to specify URL to the public, open source repository.
  // Proprietary implementations could specify the product or vendor's name.
  string softwareID = 11;
}