perun-wallet.proto

syntax = "proto3";

import "wire.proto";
import "google/protobuf/empty.proto";

package perunservice;

// ChannelService running as a background worker providing core functionality
// to interact with Perun channels.
service ChannelService {
  // Initiate channel opening.
  rpc OpenChannel(ChannelOpenRequest) returns (ChannelOpenResponse);
  // Initiate some channel update.
  rpc UpdateChannel(ChannelUpdateRequest) returns (ChannelUpdateResponse);
  // Initiate channel closing.
  rpc CloseChannel(ChannelCloseRequest) returns (ChannelCloseResponse);
}

// Generic rejected message. Returned by any endpoint on failure.
message Rejected {
  string reason = 1;
}

message ChannelOpenRequest {
  // The identity of the requester.
  bytes requester = 1;
  // Identity of the peer to open the channel with.
  bytes peer = 2;
  // The desired allocation of funds within said channel.
  perunwire.Allocation allocation = 3;
  // The duration of the challenge period.
  uint64 challenge_duration = 4;
}

message ChannelOpenResponse {
  oneof msg {
    Rejected rejected = 1;
    bytes channel_id = 2;
  }
}

message ChannelUpdateRequest {
  // The state with which the channel should be updated.
  perunwire.State state = 1;
}

message SuccessfulUpdate {
  // The state with which the channel was updated.
  perunwire.State state = 1;
  // The channel id of the channel which was updated.
  bytes channel_id = 2;
}

message ChannelUpdateResponse {
  oneof msg {
    Rejected rejected = 1;
    SuccessfulUpdate update = 2;
  }
}

message ChannelCloseRequest {
  // The channel id of the channel to be closed.
  bytes channel_id = 1;
}

message SuccessfulClose {
  // The channel id of the channel which was closed.
  bytes channel_id = 1;
}

message ChannelCloseResponse {
  oneof msg {
    Rejected rejected = 1;
    SuccessfulClose close = 2;
  }
}

// WalletService is the wallet which integrates PerunChannels. It has to
// provide an interface which can be called by the `ChannelService` if channel
// updates happen and require user interaction.
service WalletService {
  // Requesting a channel opening from the wallet. This happens if the Perun
  // channel service received a channel opening request from another peer.
  // This method lets the wallet know that it should ask the user whether or
  // not to accept the channel opening request.
  rpc OpenChannel(OpenChannelRequest) returns (OpenChannelResponse);

  // The Perun channel service calls this method if it received a channel
  // update request from another peer. The wallet might use this channel update
  // request containing the proposed/new channel state to shown it in the
  // front-end. The wallet might use this update event to query the user
  // whether or not to accept the channel update.
  rpc UpdateNotification(UpdateNotificationRequest) returns (UpdateNotificationResponse);

  // Request a signature on the given message by some wallet.
  rpc SignMessage(SignMessageRequest) returns (SignMessageResponse);

  // Request a signature on the given transaction by some wallet.
  rpc SignTransaction(SignTransactionRequest) returns (SignTransactionResponse);

  // Request a list outpoints from a wallet at least matching the requested
  // amount of possibly different assets. This can be called by the Perun
  // channel backend if it builds transactions.
  rpc GetAssets(GetAssetsRequest) returns (GetAssetsResponse);
}

// Called by the Perun channel service if it received a channel opening request
// from another peer. The proposed channel state is passed to the wallet which
// might use it to show it in to the user.
message OpenChannelRequest {
  // The state with which the channel should be opened.
  perunwire.LedgerChannelProposalMsg proposal = 1;
}

message OpenChannelResponse {
  oneof msg {
    Rejected rejected = 1;
    // The NonceShare generated by the wallet.
    bytes nonce_share = 2;
  }
}

message CloseChannelRequest {
  // The channel id of the channel to be closed.
  bytes channel_id = 2;
  // The state with which the channel should be closed.
  perunwire.State state = 1;
}

message ForceCloseChannelRequest {
  // The channel id of the channel to be closed.
  bytes channel_id = 2;
  // The state with which the channel should be closed.
  perunwire.State state = 1;
}

message ChallengeEventRequest {
  // The channel id of the channel which was challenged.
  bytes channel_id = 1;
  // The state with which the channel was challenged.
  perunwire.State state = 2;
}

message UpdateNotificationRequest {
  // The state with which the channel should be updated.
  perunwire.State state = 1;
}

message UpdateNotificationResponse {
  // Whether or not the channel update was accepted by the user.
  bool accepted = 1;
}

message SignMessageRequest {
  // The public key expected to sign the given message.
  bytes pubkey = 1;
  // The message to be signed.
  bytes data = 2;
}

message SignMessageResponse {
  oneof msg {
    Rejected rejected = 1;
    bytes signature = 2;
  }
}

message GetAssetsRequest {
  // The requested assets.
  perunwire.Balances assets = 1;
}

message Asset {
  // The asset id of the asset.
  bytes asset_id = 1;
}

message UnmatchableAssetsResponse {
  // The index of the unmatchable assets from the original request.
  uint32 asset_idx = 1;
  // A possible reason if more information is available.
  string reason = 2;
}

message GetAssetsResponse {
  oneof msg {
    UnmatchableAssetsResponse rejected = 2;
  }
}

message SignTransactionRequest {
  bytes identifier = 1;
  // The transaction to be signed.
  bytes transaction = 2;
}

message SignTransactionResponse {
  oneof msg {
    Rejected rejected = 1;
    // The signed transaction.
    bytes transaction = 2;
  }
}