package trisa.api.v1beta1

Get desktop application:
View/edit binary Protocol Buffers messages

The TRISAHealth service is optional but highly recommended for VASP members to implement. The Status endpoint allows the TRISA Directory Service to perform health checks with VASP's TRISA Node and report the service conditions of the TRISA network. Because a down TRISA node will prevent travel rule compliant virtual asset transactions, the health service is intended to quickly identify network problems and notify members as quickly as possible. NOTE: the TRISAHealth service must also be behind mTLS so that the health check service can verify the identity certificates being used for the TRISANetwork service.

• rpc Status (HealthCheck, ServiceState)

  api.proto:52

  message HealthCheck

  api.proto:296

  • uint32 attempts = 1

    The number of failed health checks that proceeded the current check.

  • string last_checked_at = 2

    The timestamp of the last health check, successful or otherwise.

  message ServiceState

  api.proto:304

  • ServiceState.Status status = 1

    Current service status as defined by the recieving system. The system is obliged to respond with the closest matching status in a best-effort fashion. Alerts will be triggered on service status changes if the system does not respond and the previous system state was not unknown.

  • string not_before = 2

    Suggest to the directory service when to check the health status again.

  • string not_after = 3

The TRISANetwork service defines the peer-to-peer interactions between VASPs that are necessary to conduct compliance information exchanges. All TRISA members must implement all services described by the TRISA protocol to ensure that exchanges are conducted correctly and securely. The primary RPCs are Transfer and TransferStream which allow VASPs to exchange compliance information before conducting a virtual asset transaction. The other RPCs facilitate Transfers, allowing address confirmations prior to a transfer and public key exchange so that transaction envelopes can be encrypted and signed.

• rpc ConfirmAddress (Address, AddressConfirmation)

  api.proto:33

  Address confirmation allows an originator VASP to establish that a beneficiary VASP has control of a crypto wallet address, prior to sending transaction information with sensitive PII data.

  message AddressConfirmation

  api.proto:204

  AddressConfirmation is returned by the counterparty after receiving an Address proof-of-control query. The counterparty should echo the address received (updating it as necessary) then specify controlled_by_entity as true if it is controlled by the receiving party or false and include an error if it is not. This is sufficient for simple address confirmation. For other

  • optional Address address = 1

    The address that is being confirmed by the counterparty.

  • bool controlled_by_entity = 2

    Specify true if the crypto address is controlled by the counterparty; specifying this as true is sufficient for simple address confirmation. If the counterparty cannot or will not perform the address confirmation they can mark this field as false and include an error code and message. Counterparties that will never do address confirmation should return a gRPC Unimplemented status code to this RPC.

  • optional Error error = 3

    Rejection errors should be specified in the response if the counterparty cannot or will not perform an address confirmation. Generally the error codes that are returned here are UNKNOWN_WALLET_ADDRESS, UNSUPPORTED_NETWORK, UNSUPPORTED_ADDRESS_CONFIRMATION, or CANNOT_CONFIRM_CONTROL_OF_ADDRESS -- but other codes may be used if necessary.

  • oneof confirmation_details

    If the confirmation type is key/token or on-chain then additional details must be specified for the address confirmation. If the confirmation type is simple, then this field may be left empty.

    • KeyTokenConfirm key_token = 8

    • OnChainConfirm on_chain = 9

• rpc KeyExchange (SigningKey, SigningKey)

  api.proto:39

  The encrypted transaction envelope uses asymmetric (public/private) encryption to exchange a symmetric key and signature for the transaction blob. To facilitate transaction signatures, VASPs must be able to exchange public signing keys if they have not already obtained them from the directory service.

  message SigningKey

  api.proto:280

  SigningKey provides metadata for decoding a PEM encoded PKIX public key for RSA encryption and transaction signing. The SigningKey is a lightweight version of the Certificate information stored in the Directory Service.

  • int64 version = 1

    x.509 metadata information for ease of reference without parsing the key.

  • bytes signature = 2

  • string signature_algorithm = 3

  • string public_key_algorithm = 4

  • string not_before = 8

    Validity information

  • string not_after = 9

  • bool revoked = 10

  • bytes data = 11

    The serialized public key to PKIX, ASN.1 DER form.

• rpc Transfer (SecureEnvelope, SecureEnvelope)

  api.proto:27

  To conduct an information exchange prior to a virtual asset transaction, an originating VASP will send an encrypted transaction envelope to the beneficiary VASP containing a unique ID for the transaction, the encrypted transaction bundle, and metadata associated with the transaction cipher. In response, the beneficiary will validate the transaction request, then return the beneficiary's transaction information using the same unique transaction ID. The TRISANetwork provides both a unary RPC for simple, single transactions and a transaction stream for high throughput transaction workloads.

• rpc TransferStream (stream SecureEnvelope, stream SecureEnvelope)

  api.proto:28

Address specifies a crypto address that requires a proof-of-control verification. There are three types of verification: simple, key-based, and on-chain. In simple address confirmation, the counterparty simply replies y/n if they control the address. In key-based control, a token encrypted with the public keys is sent to the counterparty which must decrypt it with the private key and return it. In on-chain proof-of-control, a transaction is placed on the chain for some small random amount of the specified asset, random enough that it can be confirmed by the originator.

Used as request type in: TRISANetwork.ConfirmAddress

Used as field type in: AddressConfirmation

• ConfirmationType confirmation = 1

  Required fields for all address confirmation RPCs that identify the crypto address and network that needs to be validated as well as the requested type.

• string crypto_address = 2

• string network = 3

• string asset_type = 4

  Optional details that may be necessary for the specific chain such as the asset type for chains that support multiple assets or a memo/destination tag.

• string tag = 5

• oneof confirmation_details

  If the confirmation type is key/token or on-chain then additional details must be specified for the address confirmation. If the confirmation type is simple, then this field may be left empty.

  • KeyTokenQuery key_token = 8

  • OnChainQuery on_chain = 9

Used in: Address

• UNKNOWN = 0

• SIMPLE = 1

• KEYTOKEN = 2

• ONCHAIN = 3

Used in: AddressConfirmation, SecureEnvelope

• Error.Code code = 1

  Error codes are standardized in the TRISA network to prevent confusion and to allow easy identification of rejections or other problems so that the repair of the connection or information exchange can be expedited.

• string message = 2

  Human readable message stating the reason for the error, should be loggable and actionable. Both standardized and unique/detail messages are acceptable.

• bool retry = 3

  If the message that caused the error should be retried with a fix; otherwise the rejection is permenant and the request should not be retried.

• optional google.protobuf.Any details = 4

  Any additional data or reasons for the rejection, e.g. a parent error, a diff, a location for redirect, etc. The payload of the additional data should be described by the error code.

Used in: Error

• UNHANDLED = 0

  Errors 0-49 are reserved for service-specific errors Default error - something very bad happened.

• UNAVAILABLE = 1

  Generic error - could not handle request, retry later.

• SERVICE_DOWN_TIME = 1

  Alias: Sygna BVRC Rejected Type

• BVRC002 = 1

  Alias: Sygna BVRC Rejected Code

• MAINTENANCE = 2

  The service is currently in maintenance mode and cannot respond.

• UNIMPLEMENTED = 3

  The RPC is not currently implemented by the TRISA node.

• INTERNAL_ERROR = 49

  Request could not be processed by recipient.

• BVRC999 = 49

  Alias: Sygna BVRC Rejected Code

• REJECTED = 50

  Errors 50-99 are reserved for transaction rejections. Default rejection - no specified reason for rejecting the transaction.

• UNKNOWN_WALLET_ADDRESS = 51

  VASP does not control the specified wallet address.

• UNKNOWN_IDENTITY = 52

  VASP does not have KYC information for the specified wallet address.

• UNKOWN_IDENTITY = 52

  Typo left for backwards compatibility.

• UNKNOWN_ORIGINATOR = 53

  Specifically, the Originator account cannot be identified.

• UNKOWN_BENEFICIARY = 54

  Specifically, the Beneficiary account cannot be identified.

• BENEFICIARY_NAME_UNMATCHED = 54

  Alias: Sygna BVRC Rejected Type

• BVRC007 = 54

  Alias: Sygna BVRC Rejected Code

• UNSUPPORTED_CURRENCY = 60

  VASP cannot support the fiat currency or coin described in the transaction.

• BVRC001 = 60

  Alias: Sygna BVRC Rejected Code

• UNSUPPORTED_NETWORK = 60

  Alias: helpful if the chain is not a currency

• EXCEEDED_TRADING_VOLUME = 61

  No longer able to receive more transaction inflows

• BVRC003 = 61

  Alias: Sygna BVRC Rejected Code

• UNSUPPORTED_ADDRESS_CONFIRMATION = 75

  VASP will not support the requested confirmation type

• CANNOT_CONFIRM_CONTROL_OF_ADDRESS = 76

  VASP cannot confirm they control the requested address, but doesn't necessarily indicate that they do not control the address.

• COMPLIANCE_CHECK_FAIL = 90

  An internal compliance check has failed or black listing has occurred

• BVRC004 = 90

  Alias: Sygna BVRC Rejected Code

• NO_COMPLIANCE = 91

  VASP not able to implement travel rule compliance.

• HIGH_RISK = 92

  VASP unwilling to conduct the transaction because of a risk assessment.

• OUT_OF_NETWORK = 99

  Wallet address or transaction is not available on this network.

• FORBIDDEN = 100

  Errors 100-149 are reserved for authentication or cryptography failures. Default access denied - no specified reason for forbidding the transaction.

• NO_SIGNING_KEY = 101

  Could not sign transaction because no signing key is available.

• CERTIFICATE_REVOKED = 102

  Could not sign transaction because keys have been revoked.

• UNVERIFIED = 103

  Could not verify certificates with any certificate authority.

• UNTRUSTED = 104

  A trusted connection could not be established.

• INVALID_SIGNATURE = 105

  An HMAC signature could not be verified

• INVALID_KEY = 106

  The transaction bundle cannot be decrypted with the specified key

• ENVELOPE_DECODE_FAIL = 107

  Could not decode or decrypt private transaction data

• PRIVATE_INFO_DECODE_FAIL = 107

  Alias: Sygna BVRC Rejected Type

• BVRC005 = 107

  Alias: Sygna BVRC Rejected Code

• UNHANDLED_ALGORITHM = 108

  The algorithm specified by the encryption or signature is not implemented

• BAD_REQUEST = 150

  Errors 150-199 are reserved for repairing exchange information. Generic bad request - usually implies retry when reuqest is fixed.

• UNPARSEABLE_IDENTITY = 151

  Could not parse the identity record; specify the type in extra

• PRIVATE_INFO_WRONG_FORMAT = 151

  Alias: Sygna BVRC Rejected Type

• BVRC006 = 151

  Alias: Sygna BVRC Rejected Code

• UNPARSEABLE_TRANSACTION = 152

  Could not parse the transaction data record; specify the type in extra

• MISSING_FIELDS = 153

  There are missing required fields in the transaction data, a list of these fields is specified in extra.

• INCOMPLETE_IDENTITY = 154

  The identity record is not complete enough for compliance purposes of the receiving VASPs. Required fields or format specified in extra.

• VALIDATION_ERROR = 155

  There was an error validating a field in the transaction data (specified in extra)

• COMPLIANCE_PERIOD_EXCEEDED = 198

  If the review period has exceeded the required compliance timeline

• CANCELED = 199

  Cancel the ongoing TRISA exchange as no longer required or no longer able to send funds on the chain. No further response expected.

• CANCEL_TRANSACTION = 199

Used in: AddressConfirmation

• bytes decrypted_token = 1

  The decrypted token to confirm to the user that the counterparty has control of the private keys of the crypto address.

Used in: Address

• bytes token = 1

  A token encrypted by the public key of the wallet address.

• string public_key_algorithm = 4

  The algorithm used to encrypt the token.

• string public_key_signature = 12

  The signature of the public key, used to identify the key pair.

Used in: AddressConfirmation

• string not_before = 1

  The RFC3339 encoded timestamp of when transaction will be visible.

• double amount = 2

  The actual amount posted in the transaction for verification.

• string txid = 3

  The transaction ID of the confirmation, if available

Used in: Address

• string beneficiary_address = 1

  The beneficiary address of the wallet to send the proof of control amount to.

• double amount = 2

  Amount of the transaction (usually a small amount) - this is the nonce value.

• string not_after = 3

  The RFC3339 encoded timestamp of when the transaction must be posted by.

Payload contains the compliance identity information that must be exchanged in a secure fashion, transaction information for both counterparties to uniquely identify the transaction on the chain, and timestamps that are used for regulatory non-repudiation. This payload is serialized and encrypted to be sent in the SecureEnvelope as well as digitally signed to ensure that the payload has not been tampered with after transmission. The internal message types of the payload are purposefully generic to allow flexibility with the data needs for different exchanges.

• optional google.protobuf.Any identity = 1

  Identity contains any valid identity structure. The expected format is the IVMS101 IdentityPayload which contains the originator and beneficiary identities, the originator and beneficiary VASP identities, as well as the transfer path of any intermediate VASPs. The identity payload can be bidirectional (containing both originator and beneficiary identities) or unidirectional - containing only the identity of the sender. In the bidirectional case, the identity may be purposefully partial to allow the recipient to fill in the details. In the unidirectional case, the identities must be collated after.

• optional google.protobuf.Any transaction = 2

  Transaction contains network specific information about the exchange or transfer. It can also contain transfer control messages such as Pending messages to facilitate multi-message compliance exchanges. These messages must all be digtially signed for auditing purposes.

• string sent_at = 3

  Timestamps that describe when the payload was originally sent and when it was accepted or received by the counterparty. These timestamps must be in the payload so that they are digitally signed for non-repudiation. Both timestamps should be RFC-3339 formatted strings with timezone information.

• string received_at = 4

Encrypted transaction envelope that is the outer layer of the TRISA information exchange protocol and facilitates the secure storage of KYC data in a transaction. The envelope specifies a unique id to reference the transaction out-of-band (e.g in the blockchain layer) and provides the necessary information so that only the originator and the beneficiary can decrypt the trnasaction data.

Used as request type in: TRISANetwork.Transfer, TRISANetwork.TransferStream

Used as response type in: TRISANetwork.Transfer, TRISANetwork.TransferStream

• string id = 1

  The transaction identifier generated by the sender. Any message concerning the same blockhain transaction requires the same envelope ID on both sending and responding RPCs.

• bytes payload = 2

  Encrypted payload that contains the IVMS 101 IdentityPayload for compliance and a generic transaction payload that is used to identify the transaction on the blockchain or perform flow control messages in TRISA itself. This payload should be encrypted using the encryption algorithm and key defined below.

• bytes encryption_key = 3

  Encryption key used to encrypt the compliance payload, usually generated on a per-envelope basis. To seal the envelope, this key should be encrypted with the public key of the recipient. If this key is in the clear, the sealed flag should be false.

• string encryption_algorithm = 4

  The encryption algorithm used to encrypt the compliance payload. This string should provide enough information for the recipient to understand how to decrypt the payload including algorithm, variants, block length, etc.

• bytes hmac = 5

  HMAC signature calculated from encrypted encrypted compliance payload using the hmac algorithm and secret defined below. This signature provides non-repudiation to regulators and counterparties that ensure the envelope has not been tampered with after receipt, particularly when comparing two envelopes.

• bytes hmac_secret = 6

  The HMAC secret used to calculate the HMAC signature. To seal the envelope, this secret should be encrypted with the public key of the recipient. If this secret is in the clear, the sealed flag should be false.

• string hmac_algorithm = 7

  The algorithm used to calculate the HMAC signature. This string should provide enough information for the recipient to understand how to compute the HMAC including algorithm, block length, hashing function, etc.

• optional Error error = 9

  Rejection/TRISA errors should be specified in the SecureEnvelope for correct compliance processing and not returned as a gRPC error. E.g. if the counterparty wishes to send a TRISA error, they should send an OK gRPC response with the error in this field. Networking errors such as unavailable, mTLS failure, or timeouts are handled separately from compliance-related errors.

• string timestamp = 10

  The RFC-3339 formatted timestamp at nanosecond resolution. Used to order SecureEnvelopes related to the same transaction. While this timestamp is likely the same as the sent_at timestamp in the compliance payload, it does not serve the same purpose. The compliance payload timestamps are for non-repudiation, whereas this timestamp is for envelope and communication management.

• bool sealed = 11

  Metadata related to the public key cryptography that seal the envelope by encrypting the encryption key and hmac secret such that only the recipient can fully decrypt the envelope. If the envelope is sealed, it indicates that the encryption key and hmac secret are encrypted with a public key, whose signature can be used for the recipient to identify the key pair required for decryption.

• string public_key_signature = 12

• TransferState transfer_state = 13

  The state refers to the condition that the sending party feels that the secure envelope exchange is in. This can optionally be used to signal to the counterparty the intent of a transfer message

Used in: ServiceState

• UNKNOWN = 0

• HEALTHY = 1

• UNHEALTHY = 2

• DANGER = 3

• OFFLINE = 4

• MAINTENANCE = 5

Used in: SecureEnvelope

• UNSPECIFIED = 0

  the transfer state is unknown or not specified

• STARTED = 1

  this is the first message in the TRISA workflow

• PENDING = 2

  action is required by the sending party

• REVIEW = 3

  action is required by the receiving party (rarely used)

• REPAIR = 4

  some state of the travel rule exchange requires repair

• ACCEPTED = 5

  the travel rule exchange is accepted and awaiting the transaction

• COMPLETED = 6

  the travel rule and on-chain transaction have been completed

• REJECTED = 7

  the travel rule exchange is rejected and should not proceed