inx.proto

syntax = "proto3";

package inx;
option go_package = "github.com/iotaledger/inx/go;inx";

service INX {
  // Node
  rpc ReadNodeStatus(NoParams) returns (NodeStatus);
  rpc ListenToNodeStatus(NodeStatusRequest) returns (stream NodeStatus);
  rpc ReadNodeConfiguration(NoParams) returns (NodeConfiguration);
  rpc ReadActiveRootBlocks(NoParams) returns (RootBlocksResponse);

  // Commitments
  rpc ListenToCommitments(SlotRangeRequest) returns (stream Commitment);
  rpc ReadCommitment(CommitmentRequest) returns (Commitment);
  rpc ForceCommitUntil(SlotRequest) returns (NoParams);

  // Blocks
  rpc ListenToBlocks(NoParams) returns (stream Block);
  rpc ListenToAcceptedBlocks(NoParams) returns (stream BlockMetadata);
  rpc ListenToConfirmedBlocks(NoParams) returns (stream BlockMetadata);
  rpc SubmitBlock(RawBlock) returns (BlockId);
  rpc ReadBlock(BlockId) returns (RawBlock);
  rpc ReadBlockMetadata(BlockId) returns (BlockMetadata);
  rpc ReadAcceptedBlocks(SlotRequest) returns (stream BlockWithMetadata);

  // Transactions
  rpc ReadTransactionMetadata(TransactionId) returns (TransactionMetadata);

  // Block Issuance
  rpc ReadBlockIssuance(BlockIssuanceRequest) returns (BlockIssuanceResponse);
  rpc ValidatePayload(RawPayload) returns (PayloadValidationResponse);

  // UTXO
  rpc ReadUnspentOutputs(NoParams) returns (stream UnspentOutput);

  // Committee
  rpc ReadIsCommitteeMember(AccountInfoRequest) returns (BoolResponse);
  rpc ReadIsCandidate(AccountInfoRequest) returns (BoolResponse);
  rpc ReadIsValidatorAccount(AccountInfoRequest) returns (BoolResponse);

  // A stream that yields updates to the ledger. A `LedgerUpdate` represents a batch to be applied to the ledger.
  // It first sends a `BEGIN`, then all the consumed outputs, then all the created outputs and finally an `END`.
  // `BEGIN` and `END` will also be sent for slots that did not mutate the ledger.
  // The counts in the batch markers can be used to sanity check that everything arrived and to pre-allocate space if needed.
  rpc ListenToLedgerUpdates(SlotRangeRequest) returns (stream LedgerUpdate);
  rpc ListenToAcceptedTransactions(NoParams) returns (stream AcceptedTransaction);

  rpc ReadOutput(OutputId) returns (OutputResponse);

  // REST API
  rpc RegisterAPIRoute(APIRouteRequest) returns (NoParams);
  rpc UnregisterAPIRoute(APIRouteRequest) returns (NoParams);
  rpc PerformAPIRequest(APIRequest) returns (APIResponse);
}

message NoParams {}

// Node
message NodeConfiguration {
  BaseToken base_token = 1;
  repeated RawProtocolParameters protocol_parameters = 2;
}

message BaseToken {
  string name = 1;
  string ticker_symbol = 2;
  string unit = 3;
  string subunit = 4;
  uint32 decimals = 5;
}

message NodeStatus {
  bool is_healthy = 1;
  bool is_bootstrapped = 2;
  uint32 last_accepted_block_slot = 3;
  uint32 last_confirmed_block_slot = 4;
  Commitment latest_commitment = 5;
  Commitment latest_finalized_commitment = 6;
  uint32 pruning_epoch = 7;
  bool has_pruned = 8;
}

message NodeStatusRequest {
  uint32 cooldown_in_milliseconds = 1;
}

message RawProtocolParameters {
  uint32 protocol_version = 1;
  uint32 start_epoch = 2;
  bytes params = 3;
}

// Commitments
message RawCommitment {
  bytes data = 1;
}

message CommitmentId {
  bytes id = 1;
}

message CommitmentRequest {
  uint32 commitment_slot = 1;
  CommitmentId commitment_id = 2;
}

message SlotRequest {
  uint32 slot = 1;
}

message SlotRangeRequest {
  // start_slot is the initial slot to get. Use 0 to start from the current node status.
  uint32 start_slot = 1;
  // end_slot is the last slot to get (inclusive). Use 0 to keep getting new confirmed slots.
  uint32 end_slot = 2;
}

message Commitment {
  CommitmentId commitment_id = 1;
  RawCommitment commitment = 2;
}

message CommitmentAndProtocolParameters {
  Commitment commitment = 1;
  RawProtocolParameters current_protocol_parameters = 2;
}

// Blocks
message RawBlock {
  bytes data = 1;
}

message BlockId {
  bytes id = 1;
}

message Block {
  BlockId block_id = 1;
  RawBlock block = 2;
}

message BlockWithMetadata {
  BlockMetadata metadata = 1;
  RawBlock block = 2;
}

message BlockMetadata {
  BlockId block_id = 1;
  enum BlockState {
    BLOCK_STATE_UNKNOWN = 0;
    BLOCK_STATE_PENDING = 1;
    BLOCK_STATE_ACCEPTED = 2;
    BLOCK_STATE_CONFIRMED = 3;
    BLOCK_STATE_FINALIZED = 4;
    BLOCK_STATE_DROPPED = 5;
    BLOCK_STATE_ORPHANED = 6;
  }
  BlockState block_state = 2;
}

message TransactionMetadata {
  TransactionId transaction_id = 1;
  enum TransactionState {
    TRANSACTION_STATE_UNKNOWN = 0;
    TRANSACTION_STATE_PENDING = 1;
    TRANSACTION_STATE_ACCEPTED = 2;
    TRANSACTION_STATE_COMMITTED = 3;
    TRANSACTION_STATE_FINALIZED = 4;
    TRANSACTION_STATE_FAILED = 5;
  }
  TransactionState transaction_state = 2;
  uint32 earliest_attachment_slot = 3;
  enum TransactionFailureReason {
    TRANSACTION_FAILURE_REASON_NONE = 0;

    TRANSACTION_FAILURE_REASON_CONFLICT_REJECTED = 1;
    TRANSACTION_FAILURE_REASON_ORPHANED = 2;

    TRANSACTION_FAILURE_REASON_INPUT_ALREADY_SPENT = 3;
    TRANSACTION_FAILURE_REASON_INPUT_CREATION_AFTER_TX_CREATION = 4;
    TRANSACTION_FAILURE_REASON_UNLOCK_SIGNATURE_INVALID = 5;

    TRANSACTION_FAILURE_REASON_CHAIN_ADDRESS_UNLOCK_INVALID = 6;
    TRANSACTION_FAILURE_REASON_DIRECT_UNLOCKABLE_ADDRESS_UNLOCK_INVALID = 7;
    TRANSACTION_FAILURE_REASON_MULTI_ADDRESS_UNLOCK_INVALID = 8;

    TRANSACTION_FAILURE_REASON_COMMITMENT_INPUT_REFERENCE_INVALID = 9;
    TRANSACTION_FAILURE_REASON_BIC_INPUT_REFERENCE_INVALID = 10;
    TRANSACTION_FAILURE_REASON_REWARD_INPUT_REFERENCE_INVALID = 11;

    TRANSACTION_FAILURE_REASON_STAKING_REWARD_CALCULATION_FAILURE = 12;
    TRANSACTION_FAILURE_REASON_DELEGATION_REWARD_CALCULATION_FAILURE = 13;

    TRANSACTION_FAILURE_REASON_INPUT_OUTPUT_BASE_TOKEN_MISMATCH = 14;

    TRANSACTION_FAILURE_REASON_MANA_OVERFLOW = 15;
    TRANSACTION_FAILURE_REASON_INPUT_OUTPUT_MANA_MISMATCH = 16;
    TRANSACTION_FAILURE_REASON_MANA_DECAY_CREATION_INDEX_EXCEEDS_TARGET_INDEX = 17;

    TRANSACTION_FAILURE_REASON_NATIVE_TOKEN_SUM_UNBALANCED = 18;

    TRANSACTION_FAILURE_REASON_SIMPLE_TOKEN_SCHEME_MINTED_MELTED_TOKEN_DECREASE = 19;
    TRANSACTION_FAILURE_REASON_SIMPLE_TOKEN_SCHEME_MINTING_INVALID = 20;
    TRANSACTION_FAILURE_REASON_SIMPLE_TOKEN_SCHEME_MELTING_INVALID = 21;
    TRANSACTION_FAILURE_REASON_SIMPLE_TOKEN_SCHEME_MAXIMUM_SUPPLY_CHANGED = 22;
    TRANSACTION_FAILURE_REASON_SIMPLE_TOKEN_SCHEME_GENESIS_INVALID = 23;

    TRANSACTION_FAILURE_REASON_MULTI_ADDRESS_LENGTH_UNLOCK_LENGTH_MISMATCH = 24;
    TRANSACTION_FAILURE_REASON_MULTI_ADDRESS_UNLOCK_THRESHOLD_NOT_REACHED = 25;

    TRANSACTION_FAILURE_REASON_SENDER_FEATURE_NOT_UNLOCKED = 26;

    TRANSACTION_FAILURE_REASON_ISSUER_FEATURE_NOT_UNLOCKED = 27;

    TRANSACTION_FAILURE_REASON_STAKING_REWARD_INPUT_MISSING = 28;
    TRANSACTION_FAILURE_REASON_STAKING_COMMITMENT_INPUT_MISSING = 29;
    TRANSACTION_FAILURE_REASON_STAKING_REWARD_CLAIMING_INVALID = 30;
    TRANSACTION_FAILURE_REASON_STAKING_FEATURE_REMOVED_BEFORE_UNBONDING = 31;
    TRANSACTION_FAILURE_REASON_STAKING_FEATURE_MODIFIED_BEFORE_UNBONDING = 32;
    TRANSACTION_FAILURE_REASON_STAKING_START_EPOCH_INVALID = 33;
    TRANSACTION_FAILURE_REASON_STAKING_END_EPOCH_TOO_EARLY = 34;

    TRANSACTION_FAILURE_REASON_BLOCK_ISSUER_COMMITMENT_INPUT_MISSING = 35;
    TRANSACTION_FAILURE_REASON_BLOCK_ISSUANCE_CREDIT_INPUT_MISSING = 36;
    TRANSACTION_FAILURE_REASON_BLOCK_ISSUER_NOT_EXPIRED = 37;
    TRANSACTION_FAILURE_REASON_BLOCK_ISSUER_EXPIRY_TOO_EARLY = 38;
    TRANSACTION_FAILURE_REASON_MANA_MOVED_OFF_BLOCK_ISSUER_ACCOUNT = 39;
    TRANSACTION_FAILURE_REASON_ACCOUNT_LOCKED = 40;

    TRANSACTION_FAILURE_REASON_TIMELOCK_COMMITMENT_INPUT_MISSING = 41;
    TRANSACTION_FAILURE_REASON_TIMELOCK_NOT_EXPIRED = 42;

    TRANSACTION_FAILURE_REASON_EXPIRATION_COMMITMENT_INPUT_MISSING = 43;
    TRANSACTION_FAILURE_REASON_EXPIRATION_NOT_UNLOCKABLE = 44;

    TRANSACTION_FAILURE_REASON_RETURN_AMOUNT_NOT_FUL_FILLED = 45;

    TRANSACTION_FAILURE_REASON_NEW_CHAIN_OUTPUT_HAS_NON_ZEROED_ID = 46;
    TRANSACTION_FAILURE_REASON_CHAIN_OUTPUT_IMMUTABLE_FEATURES_CHANGED = 47;

    TRANSACTION_FAILURE_REASON_IMPLICIT_ACCOUNT_DESTRUCTION_DISALLOWED = 48;
    TRANSACTION_FAILURE_REASON_MULTIPLE_IMPLICIT_ACCOUNT_CREATION_ADDRESSES = 49;

    TRANSACTION_FAILURE_REASON_ACCOUNT_INVALID_FOUNDRY_COUNTER = 50;

    TRANSACTION_FAILURE_REASON_ANCHOR_INVALID_STATE_TRANSITION = 51;
    TRANSACTION_FAILURE_REASON_ANCHOR_INVALID_GOVERNANCE_TRANSITION = 52;

    TRANSACTION_FAILURE_REASON_FOUNDRY_TRANSITION_WITHOUT_ACCOUNT = 53;
    TRANSACTION_FAILURE_REASON_FOUNDRY_SERIAL_INVALID = 54;

    TRANSACTION_FAILURE_REASON_DELEGATION_COMMITMENT_INPUT_MISSING = 55;
    TRANSACTION_FAILURE_REASON_DELEGATION_REWARD_INPUT_MISSING = 56;
    TRANSACTION_FAILURE_REASON_DELEGATION_REWARDS_CLAIMING_INVALID = 57;
    TRANSACTION_FAILURE_REASON_DELEGATION_OUTPUT_TRANSITIONED_TWICE = 58;
    TRANSACTION_FAILURE_REASON_DELEGATION_MODIFIED = 59;
    TRANSACTION_FAILURE_REASON_DELEGATION_START_EPOCH_INVALID = 60;
    TRANSACTION_FAILURE_REASON_DELEGATION_AMOUNT_MISMATCH = 61;
    TRANSACTION_FAILURE_REASON_DELEGATION_END_EPOCH_NOT_ZERO = 62;
    TRANSACTION_FAILURE_REASON_DELEGATION_END_EPOCH_INVALID = 63;

    TRANSACTION_FAILURE_REASON_CAPABILITIES_NATIVE_TOKEN_BURNING_NOT_ALLOWED = 64;
    TRANSACTION_FAILURE_REASON_CAPABILITIES_MANA_BURNING_NOT_ALLOWED = 65;
    TRANSACTION_FAILURE_REASON_CAPABILITIES_ACCOUNT_DESTRUCTION_NOT_ALLOWED = 66;
    TRANSACTION_FAILURE_REASON_CAPABILITIES_ANCHOR_DESTRUCTION_NOT_ALLOWED = 67;
    TRANSACTION_FAILURE_REASON_CAPABILITIES_FOUNDRY_DESTRUCTION_NOT_ALLOWED = 68;
    TRANSACTION_FAILURE_REASON_CAPABILITIES_NFT_DESTRUCTION_NOT_ALLOWED = 69;

    TRANSACTION_FAILURE_REASON_SEMANTIC_VALIDATION_FAILED = 255;
  }
  TransactionFailureReason transaction_failure_reason = 4;
  string transaction_failure_details = 5;
}

// Block Issuance
message BlockIssuanceRequest {
  uint32 max_strong_parents_count = 1;
  uint32 max_weak_parents_count = 2;
  uint32 max_shallow_like_parents_count = 3;
}

message BlockIssuanceResponse {
  repeated BlockId strong_parents = 1;
  repeated BlockId weak_parents = 2;
  repeated BlockId shallow_like_parents = 3;
  uint64 latest_parent_block_issuing_time = 4;
  uint32 latest_finalized_slot = 5;
  Commitment latest_commitment = 6;
}

message RawPayload {
  bytes data = 1;
}

message PayloadValidationResponse {
  bool is_valid = 1;
  string error = 2;
}

message RootBlocksResponse {
  repeated RootBlock root_blocks = 1;
}

message RootBlock {
  BlockId block_id = 1;
  CommitmentId commitment_id = 2;
}

// UTXO
message TransactionId {
  bytes id = 1;
}

message OutputId {
  bytes id = 1;
}

message OutputResponse {
  CommitmentId latest_commitment_id = 1;
  oneof payload {
    LedgerOutput output = 2;
    LedgerSpent spent = 3;
  }
}

message UnspentOutput {
  CommitmentId latest_commitment_id = 1;
  LedgerOutput output = 2;
}

message RawOutput {
  bytes data = 1;
}

message RawOutputIDProof {
  bytes data = 1;
}

message LedgerOutput {
  OutputId output_id = 1;
  BlockId block_id = 2;
  uint32 slot_booked = 3;
  CommitmentId commitment_id_included = 4;
  RawOutput output = 5;
  RawOutputIDProof output_id_proof = 6;
}

message LedgerSpent {
  LedgerOutput output = 1;
  CommitmentId commitment_id_spent = 2;
  TransactionId transaction_id_spent = 3;
  uint32 slot_spent = 4;
}

message LedgerUpdate {
  message Marker {
    CommitmentId commitment_id = 1;
    enum MarkerType {
      BEGIN = 0;
      END = 1;
    }
    MarkerType marker_type = 2;
    uint32 consumed_count = 3;
    uint32 created_count = 4;
  }

  oneof op {
    Marker batch_marker = 1;
    LedgerSpent consumed = 2;
    LedgerOutput created = 3;
  }
}

message AcceptedTransaction {
  TransactionId transaction_id = 1;
  uint32 slot = 2;
  repeated LedgerSpent consumed = 3;
  repeated LedgerOutput created = 4;
}

// Committee
message AccountInfoRequest {
  bytes account_id = 1;
  uint32 account_slot = 2;
}

message BoolResponse {
  bool value = 1;
}

// REST API
message APIRouteRequest {
  string route = 1;
  string host = 2;
  uint32 port = 3;
  string path = 4;
}

message APIRequest {
  string method = 1;
  string path = 2;
  map<string, string> headers = 3;
  bytes body = 4;
}

message APIResponse {
  uint32 code = 1;
  map<string, string>  headers = 2;
  bytes body = 3;
}