api.proto

syntax = "proto3";

package rvasp.v1;
option go_package = "github.com/trisacrypto/testnet/pkg/rvasp/pb/v1;api";

// The TRISA Demo service uses a bidirectional stream to allow a websockets service to
// display messages and commands in real time. Commands implement the same RPCs as the
// TRISA Integration service, using a wrapper format. Messages from the rVASP are sent
// to the UI to show messaging progress.
service TRISADemo {
    rpc LiveUpdates (stream Command) returns (stream Message);
}

// The TRISA Integration service can be used by VASPs as they develop their own internal
// implementations of the InterVASP protocol. The integration service provides one
// primary RPC - Transfer, which gets the rVASP to kick off an InterVASP transfer
// request. The rVASP also implements the InterVASP protocol to receive transactions and
// provides a helper RPC, AccountStatus to get back all transactions the rVASP has seen
// for debugging purposes.
service TRISAIntegration {
    rpc Transfer (TransferRequest) returns (TransferReply);
    rpc AccountStatus (AccountRequest) returns (AccountReply);
    rpc Status (Empty) returns (ServerStatus);
}

// Allows for standardized error handling for demo purposes.
message Error {
    int32 code = 1;
    string message = 2;
}

// Identity maps a wallet address, email, and VASP provider and is used to store
// originator and beneficiary data as well as the KYC information that is collected
// during the TRISA protocol exchange in JSON format.
message Account {
    string wallet_address = 1;
    string email = 2;
    string provider = 3;
}

// Describes a simple transaction between an originator and beneficiary.
// NOTE: this is an rVASP-specific transaction that is used for debugging.
message Transaction {
    Account originator = 1;     // Source described by wallet address or email of originator
    Account beneficiary = 2;    // Target described by wallet address or email of beneficiary
    float amount = 3;           // amount of the transaction
    string timestamp = 4;       // timestamp of completion on the account provider side
    string envelope_id = 5;     // envelope ID from TRISA (not included between TRISA peers)
    string identity = 6;        // identity payload from TRISA (not included between TRISA peers)
    TransactionState state = 7; // state of the transaction
    string asset_type = 8;      // the type of virtual asset (for example, "Bitcoin")
}

// Describes the current state of a transaction.
enum TransactionState {
    INVALID = 0; // Not a valid transaction state
    AWAITING_REPLY = 1; // (Async) Originator is awaiting a response from the beneficiary
    PENDING_SENT = 2; // (Async) Beneficiary has sent a pending message to the originator
    AWAITING_FULL_TRANSFER = 3; // (Async) Beneficiary is awaiting a complete transfer request from the originator
    PENDING_RECEIVED = 4; // (Async) Originator has received a pending message from the beneficiary
    PENDING_ACKNOWLEDGED = 5; // (Async) Beneficiary has acknowledged the originator transaction
    ACCEPTED = 6; // (Async) Originator has received the transaction acknowledgement from the beneficiary
    FAILED = 7; // The transaction has failed
    EXPIRED = 8; // The asynchronous transaction has expired before completion
    REJECTED = 9; // The transaction has been rejected
    COMPLETED = 10; // The transaction is completed
}

// Initiates a transfer from the specified account to the specified wallet address or
// email address for a known wallet at some other rVASP.
message TransferRequest {
    string account = 1;           // email address or crypto wallet of the account to debit
    string beneficiary = 2;       // email address or crypto wallet to look up beneficiary with
    float amount = 3;             // amount to transfer to the beneficiary (will be truncated to 2 decimal points)
    string originating_vasp = 4;  // common name of the originating VASP for demo UI error handling (optional)
    string beneficiary_vasp = 5;  // common name of the beneficiary VASP for demo UI error handling or external demo lookup (optional if external_demo is false)
    bool check_beneficiary = 6;   // if set, confirm that the beneficiary wallet belongs to the beneficiary VASP (optional)
    string asset_type = 8;        // the type of virtual asset for multi-asset chains
}

// The transfer reply will contain the details of the transaction initiated or completed
// or an error if there are insufficient funds or the account or beneficiary could not
// be looked up. Errors encountered during the TRISA protocol may also be returned.
message TransferReply {
    Error error = 1;              // populated with an error encountered during the transfer or from the response envelope
    Transaction transaction = 2;
}

// Account request is used to fetch the status information of the account as well as
// all the transactions associated with the account (unless otherwise requested).
// TODO: implement transaction pagination.
message AccountRequest {
    string account = 1;         // email address of the account to get information for.
    bool no_transactions = 2;   // do not return list of transactions, just status info.
    uint32 page = 3;            // not implemented yet
    uint32 per_page = 4;        // not implemented yet
}

// Returns the account information and balance as well as transactions ordered from
// most to least recent. An error is returned if the account cannot be found.
message AccountReply {
    Error error = 1;              // Only used in live stream
    string name = 2;
    string email = 3;
    string wallet_address = 4;
    float balance = 5;
    uint64 completed = 6;
    uint64 pending = 7;
    repeated Transaction transactions = 8;
}

// Specifies the RPC the command is wrapping in the bidirectional stream.
enum RPC {
    NORPC = 0;
    TRANSFER = 1;
    ACCOUNT = 2;
}

// Specifies the category the message is related to for rVASP UI colorization
enum MessageCategory {
    LEDGER = 0;
    TRISADS = 1;
    TRISAP2P = 2;
    BLOCKCHAIN = 3;
    ERROR = 4;
}

// A wrapper for the TransferRequet and AccountRequest RPCs to be sent via streaming.
message Command {
    RPC type = 1;       // what type of command is being sent to the rVASP
    uint64 id = 2;      // client side message id for req/rep tracking
    string client = 3;  // unique ID so the rVASP can correctly dispatch messages

    // only one of these fields can be set, and the field that is set should
    // match the RPC type described above.
    oneof request {
        TransferRequest transfer = 11;
        AccountRequest account = 12;
    }
}

// Message is either a wrapper for a TransferReply or AccountReply RPCs or it is a live
// update message sent from the rVASP to show the communication interactions of the
// InterVASP protocol. If it is a wrapper, then type will be > 0 and the ID will match
// the id of the command request sent by the client. Otherwise both of these fields will
// be zero and the update string will be populated.
message Message {
    RPC type = 1;
    uint64 id = 2;
    string update = 3;
    string timestamp = 4;
    MessageCategory category = 5;

    // if type and id are greater than zero, one of these fields will be set, matching
    // the RPC type described above.
    oneof reply {
        TransferReply transfer = 11;
        AccountReply account = 12;
    }
}


message Empty{}


message ServerStatus {
    enum Status {
        UNKNOWN = 0;
        ONLINE = 1;
        MAINTENANCE = 2;
        UNHEALTHY = 3;
        OFFLINE = 4;
    }

    Status status = 1;
    string version = 2;
    string common_name = 3;
    string not_before = 4;
    string not_after = 5;
}