Simple Summary
This specification provides the messaging details for a simple virtual asset transfer between two parties as part of a Transaction Authorization Protocol flow.
Abstract
This TAIP contains a specification for a metadata message about a virtual asset transaction for use as part of the Authorization Flow in TAP.
The primary type of transaction this defines supports the transfer of an amount of a fungible or non-fungible token from an originator to a beneficiary.
This TAIP only specifies the specifics of a Transfer rather than the complete Authorization Flow, as defined in TAIP-4.
Motivation
The Asset Transfer is a simple chain-agnostic representation of a typical virtual asset transaction and its parties. The vast majority of transactions performed by both custodial services and self-hosted wallets fall under this classification.
This specification builds on existing Chain Agnostic standards such as CAIP-10 Account Identifiers and CAIP-19 Asset Identifiers.
For developers of new blockchain protocols and token standards, make sure that you implement these and list them on the Chainagnostic Namespaces page for reference.
Specification
Asset Transfers are implemented in the body of a TAIP-2 message.
DIDComm type URI
The preliminary URI to be used in the TAIP-2 type header should be
https://tap.rsvp/schema/taip-3#Transfer
.
Message Body
As specified in TAIP-2 the message body is JSON-LD. The following attributes are defined:
@context
- REQUIRED the JSON-LD contexthttps://tap.rsvp/schema/1.0
(provisional)@type
- REQUIRED the JSON-LD typehttps://tap.rsvp/schema/1.0#Transfer
(provisional)asset
- REQUIRED the CAIP-19 identifier of the assetamount
- OPTIONAL for NFTs and REQUIRED for fungible tokens. Specified as a string with the full amount as a decimal representation of the tokenoriginator
- OPTIONAL an object representing the originating (aka the sender) party (see TAIP-6)beneficiary
- OPTIONAL an object representing the beneficiary (aka the recipient) party (see TAIP-6)settlementId
- OPTIONAL a CAIP-220 identifier of the underlying settlement transaction on a blockchain. For more details see below.agents
- REQUIRED an array of identity objects representing the agents who help execute the transaction. See TAIP-5 for more.
Many of the attributes are optional and through the process of authorization can be expanded and modified collaboratively by the agents of a transaction.
Transfer Amounts
The amount of a transfer is specified as amount
and represents the decimal value of the asset. This approach is more intuitive for most users and application developers. It is the responsibility of library and tool developers to handle any necessary conversions when interacting with blockchain protocols that may require amounts in their smallest units.
As an example, ETH 1.23
should be encoded as "1.23"
.
settlementId
Use a simplified version of the format proposed by CAIP-220
block_address: chain_id + ":" [ + "block:"]? + "txn/" + transaction_id?
chain_id: [-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,32} (See [CAIP-2][])
transaction_id: [-%a-zA-Z0-9]{1,128}
eg:
eip155:1:tx/0x3edb98c24d46d148eb926c714f4fbaa117c47b0c0821f38bfce9763604457c33
Agent Roles
Agents can have specific roles vital to the execution of a transaction.
The following two roles can be used as attributes on Agents listed in the agents array:
SettlementAddress
, The blockchain wallet agent to settle a transaction toSourceAddress
The blockchain wallet agent used to send the transaction from
Neither of these is required but can be used to specify the blockchain wallets up front.
Rationale
This message type is designed to be as general and chain agnostic as possible and compatible with as little meta-data as possible, together with any required meta-data, that is useful for improving usability, safety, and record-keeping for a transaction.
Note this is designed to be used as an initial request message. The body attributes can be used as a representation of the internal state of a transaction by an agent, but do intentionally not represent the shared state.
It is also not intended to cover more complex transaction use cases, such as non-token transfer-related smart contract calls. This TAIP is encouraged to be forked and modified to create similar requests for Swaps, lending, and other everyday use cases.
Test Cases
The following is a minimal request for a transfer of 1.23 ETH from a trading
firm to the ethereum wallet with the address
0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
:
{
"from": "did:web:originator.sample",
"type": "https://tap.rsvp/schema/1.0#Transfer",
"id": "...",
"to": ["did:pkh:eip155:1:0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb"],
"body": {
"@context": "https://tap.rsvp/schema/1.0",
"@type": "https://tap.rsvp/schema/1.0#Transfer",
"asset": "eip155:1/slip44:60",
"originator": {
"@id": "did:web:originator.sample"
},
"amount": "1.23",
"agents": [
{
"@id": "did:web:originator.sample"
},
{
"@id": "did:pkh:eip155:1:0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
"role": "settlementAddress"
}
]
}
}
The following is a request for a transfer of 1.23 ETH from a crypto exchange
from a customer to the ethereum wallet with the address
0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb
:
{
"from": "did:web:originator.vasp",
"type": "https://tap.rsvp/schema/1.0#Transfer",
"id": "...",
"to": [
"did:web:beneficiary.vasp",
"did:pkh:eip155:1:0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb"
],
"body": {
"@context": "https://tap.rsvp/schema/1.0",
"@type": "https://tap.rsvp/schema/1.0#Transfer",
"asset": "eip155:1/slip44:60",
"originator": {
"@id": "did:eg:bob"
},
"amount": "1.23",
"agents": [
{
"@id": "did:web:originator.vasp"
},
{
"@id": "did:pkh:eip155:1:0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
"role": "settlementAddress"
}
]
}
}
The following is a request for a transfer of 1.23 ETH from a crypto exchange from a customer to a customer at another hosted wallet, which does not include settlement information. This allows the parties negotiate settlement as part of the authorization flow:
{
"from": "did:web:originator.vasp",
"type": "https://tap.rsvp/schema/1.0#Transfer",
"id": "...",
"to": [
"did:web:beneficiary.vasp",
"did:pkh:eip155:1:0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb"
],
"body": {
"@context": "https://tap.rsvp/schema/1.0",
"@type": "https://tap.rsvp/schema/1.0#Transfer",
"asset": "eip155:1/slip44:60",
"originator": {
"@id": "did:eg:bob"
},
"beneficiary": {
"@id": "sms:+15105550101"
},
"amount": "1.23",
"agents": [
{
"@id": "did:web:originator.vasp"
},
{
"@id": "did:web:beneficiary.vasp"
}
]
}
}
The following is an example of a reasonably complete transaction already settled. An Agent could create these to backfill information about an already settled transaction.
{
"from": "did:web:originator.vasp",
"type": "https://tap.rsvp/schema/1.0#Transfer",
"id": "...",
"to": [
"did:web:beneficiary.vasp",
"did:pkh:eip155:1:0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb"
],
"body": {
"@context": "https://tap.rsvp/schema/1.0",
"@type": "https://tap.rsvp/schema/1.0#Transfer",
"originator": {
"@id": "did:eg:bob"
},
"beneficiary": {
"@id": "did:eg:alice"
},
"asset": "eip155:1/slip44:60",
"amount": "1.23",
"settlementId": "eip155:1:tx/0x3edb98c24d46d148eb926c714f4fbaa117c47b0c0821f38bfce9763604457c33",
"agents": [
{
"@id": "did:web:originator.vasp"
},
{
"@id": "did:beneficiary.vasp"
},
{
"@id": "did:pkh:eip155:1:0x1234a96D359eC26a11e2C2b3d8f8B8942d5Bfcdb",
"role": "settlementAddress"
}
]
}
}
Security Considerations
It is essential to understand that this represents a request to perform a transaction, and requires all parties to verify all information in it to authorize and settle a transaction safely. The agents are responsible for confirming this information, even post-settlement.
Privacy Considerations
This message can contain PII about end-users. Agents must understand their privacy duties under national law to safeguard their customers' PII. As part of a TAIP-4 authorization flow, agents SHOULD evaluate the data privacy of any other agent before sharing PII with them.
Agents SHOULD minimize the use of end-user PII in this message, but it can be encrypted to specific trusted parties or agents separately. See TAIP-8 for more.
References
- TAIP-2 Defines the TAP Message structure
- TAIP-4 Defines the Transaction Authorization Protocol
- TAIP-5 Describes Transaction Agents
- TAIP-6 Describes Transaction Parties
- TAIP-8 Selective disclosure of PII
- CAIP-10 Describes chainagnostic Account ID Specification
- CAIP-19 Describes Chainagnostic Asset ID Specification
- JSON JavaScript Object Notation
- JSON-LD JSON Linked Data
Copyright
Copyright and related rights waived via CC0.