transaction.proto

syntax = "proto3";

package trisa.data.generic.v1beta1;
option go_package = "github.com/trisacrypto/trisa/pkg/trisa/data/generic/v1beta1;generic";


// Generic Transaction message for TRISA transaction payloads. The goal of this payload
// is to provide enough information to link Travel Rule Compliance information in the
// identity payload with a transaction on the blockchain or network. All fields are
// optional, this message serves as a convenience for parsing transaction payloads.
message Transaction {
    string txid = 1;              // a transaction ID unique to the chain/network
    string originator = 2;        // crypto address of the originator
    string beneficiary = 3;       // crypto address of the beneficiary
    double amount = 4;            // amount of the transaction
    string network = 5;           // the chain/network of the transaction
    string timestamp = 6;         // RFC 3339 timestamp of the transaction
    string extra_json = 7;        // any extra data as a JSON formatted object
    string asset_type = 8;        // the type of virtual asset for multi-asset chains
    string tag = 9;               // optional memo/destination-tag required by some ledgers to identify transactions
}

message Asset {
    Identifier identifier = 1;        // the identifier being used, e.g. "DTI" or "SLIP0044"
    string symbol = 2;            // the symbol of the asset used for the identifier
}

enum Identifier {
    SYMBOL = 0;                 // the identifier is a coin/token symbol
    DTI = 1;                    // the Digital Token Identifier (DTI) for the asset
    SLIP0044 = 2;               // the SLIP0044 identifier for the asset
}

// A control flow message to support asynchronous TRISA transfers. Pending messages can
// be returned as an intermediate response during a compliance transfer if further
// processing is required before a response can be sent. The Pending message should
// provide information to the originator about when they can expect a response via the
// reply_not_before and reply_not_after timestamps. The Pending message should also
// provide collation information such as the envelope_id and original transaction so
// that the response message can be matched to the original request.
message Pending {
    string envelope_id = 1;       // the TRISA envelope ID that refers to the compliance communication
    string received_by = 2;       // the name of the recipient or recipient VASP
    string received_at = 3;       // the RFC3339 formatted timestamp when the request was received
    string message = 4;           // an optional message to respond with to the counterparty
    string reply_not_after = 5;   // the RFC3339 formatted timestamp when the response will be returned by
    string reply_not_before = 6;  // the RFC339 formatted timestamp that the response will not be sent before
    string extra_json = 7;        // any extra data as a JSON formatted object
    Transaction transaction = 15; // the original transaction for reference
}

// Sunrise is a control flow message to indicate that the message was sent over a side
// channel to the TRISA protocol such as via email or phone. The Sunrise message
// is only saved locally to indicate a record of an out-of-band communication and is not
// sent in a TRISA payload.
message Sunrise {
    string envelope_id = 1;                 // the TRISA envelope ID for reference
    string counterparty = 2;                // the name of the counterparty or counterparty VASP the messages were sent to
    repeated SunriseMessage messages = 3;   // the list of recipients that the message was sent to
    string extra_json = 14;                 // any extra data as a JSON formatted object
    Transaction transaction = 15;           // the original transaction for reference
}

// SunriseMessages may be sent to multiple contacts via different channels (e.g. via
// an email or phone call to the compliance officer and general contact).
message SunriseMessage {
    string recipient = 1;         // the name of the recipient or recipient VASP
    string email = 2;             // the email address of the recipient
    string phone = 3;             // the phone number of the recipient
    string channel = 4;           // the name of the method or channel the message was sent over (e.g. email or phone)
    string sent_at = 5;           // the RFC3339 formatted timestamp when the message was sent
    string reply_not_before = 6;  // the RFC339 formatted timestamp that the response is expected before message expiration
}

// When a TRP message is received by a TRISA node the "pending reply" is implicit in
// the response. Therefore instead of storing a Pending message, the TRISA node will
// store a TRP transaction with additional metadata about the TRP/OpenVASP exchage.
message TRP {
    // The headers of the message
    string envelope_id = 1;         // in TRP parlance, the "request identifier" (extracted from headers)
    TRPInfo headers = 2;            // the TRP API metadata for the transaction

    // The TRP Message sent in the body of the request or reply
    oneof message {
        TRPInquiry inquiry = 3;
        TRPApproved approved = 4;
        TRPRejected rejected = 5;
        TRPConfirmed confirmed = 6;
        TRPCanceled canceled = 7;
    }

    // Extensions and parsed TRISA information
    string extensions = 14;         // any extensions data as a JSON formatted string
    Transaction transaction = 15;   // the TRISA reference transaction
}

// TRPInfo stores the API metadata for the TRP transaction.
message TRPInfo {
    string version = 1;             // the TRP API version used in the message
    string request_identifier = 2;  // the request identifier (envelope ID)
    repeated string extensions = 3; // The names of any extensions uses in the request
}

// A TRPInquiry contains the asset, amount, and callback information.
message TRPInquiry {
    map<string, string> asset = 1;  // the asset identifier(s) for the transaction
    double amount = 2;              // the amount of the transaction
    string callback = 3;            // the callback URL to respond to
}


// TRPResolution contains the response to an approved/rejected TRP inquiry.
message TRPApproved {
    string address = 1;            // some payment address
    string callback = 2;           // callback to send transaction ID to.
}

message TRPRejected {
    string rejected = 1;           // the human readable reason for rejection or null
}

message TRPConfirmed {
    string txid = 1;               // the transaction ID of the confirmed transaction on the chain
}

message TRPCanceled {
    string canceled = 1;           // the human readable reason for cancellation or null
}

// DEPRECATED: the ConfirmationReceipt message was deemed to cause confusion as it could
// signal that the confirmation payload was received and the transfer is concluded. Use
// the Pending message instead to signal that this is a control flow message.
message ConfirmationReceipt {
    string envelope_id = 1;       // the TRISA envelope ID for reference
    string received_by = 2;       // name of the recipient or recipient VASP
    string received_at = 3;       // RFC 3339 timestamp of the receipt of request
    string message = 4;           // A generic message to respond with
    bool response_required = 5;   // If the message requires an additional transfer message
}