tapass 0.0.0-stage → 0.2.0

package/protos/taprpc/tapchannelrpc/tapchannel.proto

@@ -0,0 +1,490 @@
+syntax = "proto3";
+
+package tapchannelrpc;
+
+option go_package = "github.com/lightninglabs/taproot-assets/taprpc/tapchannelrpc";
+
+import "rfqrpc/rfq.proto";
+import "lightning.proto";
+import "routerrpc/router.proto";
+import "taprootassets.proto";
+
+service TaprootAssetChannels {
+    /* litcli: `ln fundchannel`
+    FundChannel initiates the channel funding negotiation with a peer for the
+    creation of a channel that contains a specified amount of a given asset.
+    */
+    rpc FundChannel (FundChannelRequest) returns (FundChannelResponse);
+
+    /*
+    Deprecated.
+    EncodeCustomRecords allows RPC users to encode Taproot Asset channel related
+    data into the TLV format that is used in the custom records of the lnd
+    payment or other channel related RPCs. This RPC is completely stateless and
+    does not perform any checks on the data provided, other than pure format
+    validation.
+    */
+    rpc EncodeCustomRecords (EncodeCustomRecordsRequest)
+        returns (EncodeCustomRecordsResponse) {
+        option deprecated = true;
+    };
+
+    /* litcli: `ln sendpayment`
+    SendPayment is a wrapper around lnd's routerrpc.SendPaymentV2 RPC method
+    with asset specific parameters. It allows RPC users to send asset keysend
+    payments (direct payments) or payments to an invoice with a specified asset
+    amount.
+    */
+    rpc SendPayment (SendPaymentRequest) returns (stream SendPaymentResponse);
+
+    /* litcli: `ln addinvoice`
+    AddInvoice is a wrapper around lnd's lnrpc.AddInvoice method with asset
+    specific parameters. It allows RPC users to create invoices that correspond
+    to the specified asset amount. If a peer pubkey is specified, then only that
+    peer will be used for RFQ negotiations. If none is specified then RFQ quotes
+    for all peers with suitable asset channels will be created.
+    */
+    rpc AddInvoice (AddInvoiceRequest) returns (AddInvoiceResponse);
+
+    /* litcli: `ln decodeassetinvoice`
+    DecodeAssetPayReq is similar to lnd's lnrpc.DecodePayReq, but it accepts an
+    asset ID or group key and returns the invoice amount expressed in asset
+    units along side the normal information.
+    */
+    rpc DecodeAssetPayReq (AssetPayReq) returns (AssetPayReqResponse);
+
+    /* litcli: `ln listinvoices`
+    ListInvoices is a wrapper around lnd's lnrpc.ListInvoices method that only
+    returns invoices that involve at least one Taproot Asset. The full lnd
+    invoice is returned along with the decoded asset amounts that the invoice's
+    HTLCs carry, so that callers don't need to parse the custom channel data
+    themselves. All request fields behave the same way as they do for lnd's
+    lnrpc.ListInvoices RPC method.
+    */
+    rpc ListInvoices (ListInvoicesRequest) returns (ListInvoicesResponse);
+
+    /* litcli: `ln listpayments`
+    ListPayments is a wrapper around lnd's lnrpc.ListPayments method that only
+    returns payments that involve at least one Taproot Asset. The full lnd
+    payment is returned along with the decoded asset amounts that the payment's
+    HTLCs carry, so that callers don't need to parse the custom channel data
+    themselves. All request fields behave the same way as they do for lnd's
+    lnrpc.ListPayments RPC method.
+    */
+    rpc ListPayments (ListPaymentsRequest) returns (ListPaymentsResponse);
+
+    /* litcli: `ln subscribeinvoices`
+    SubscribeInvoices is a wrapper around lnd's lnrpc.SubscribeInvoices method
+    that only streams invoices that involve at least one Taproot Asset. The full
+    lnd invoice is returned along with the decoded asset amounts that the
+    invoice's HTLCs carry, so that callers don't need to parse the custom
+    channel data themselves. All request fields behave the same way as they do
+    for lnd's lnrpc.SubscribeInvoices RPC method.
+    */
+    rpc SubscribeInvoices (SubscribeInvoicesRequest)
+        returns (stream AssetInvoice);
+
+    /* litcli: `ln subscribepayments`
+    SubscribePayments is a wrapper around lnd's routerrpc.TrackPayments method
+    that only streams payment updates that involve at least one Taproot Asset.
+    The full lnd payment is returned along with the decoded asset amounts that
+    the payment's HTLCs carry, so that callers don't need to parse the custom
+    channel data themselves. All request fields behave the same way as they do
+    for lnd's routerrpc.TrackPayments RPC method.
+    */
+    rpc SubscribePayments (SubscribePaymentsRequest)
+        returns (stream AssetPayment);
+
+    /* litcli: `ln trackpayment`
+    TrackPayment is a wrapper around lnd's routerrpc.TrackPaymentV2 method that
+    only streams payment updates that involve at least one Taproot Asset. The
+    full lnd payment is returned along with the decoded asset amounts that the
+    payment's HTLCs carry, so that callers don't need to parse the custom
+    channel data themselves. All request fields behave the same way as they do
+    for lnd's routerrpc.TrackPaymentV2 RPC method.
+    */
+    rpc TrackPayment (TrackPaymentRequest) returns (stream AssetPayment);
+}
+
+message FundChannelRequest {
+    // The asset amount to fund the channel with. The BTC amount is fixed and
+    // cannot be customized (for now).
+    uint64 asset_amount = 1;
+
+    // The asset ID to use for the channel funding.
+    bytes asset_id = 2;
+
+    // The public key of the peer to open the channel with. Must already be
+    // connected to this peer.
+    bytes peer_pubkey = 3;
+
+    // The channel funding fee rate in sat/vByte.
+    uint32 fee_rate_sat_per_vbyte = 4;
+
+    // The number of satoshis to give the remote side as part of the initial
+    // commitment state. This is equivalent to first opening a channel and then
+    // sending the remote party funds, but all done in one step. Therefore, this
+    // is equivalent to a donation to the remote party, unless they reimburse
+    // the funds in another way (outside the protocol).
+    int64 push_sat = 5;
+
+    // The group key to use for the channel. This can be used instead of the
+    // asset_id to allow assets from a fungible group to be used for the channel
+    // funding instead of just assets from a single minting tranche (asset_id).
+    bytes group_key = 6;
+}
+
+message FundChannelResponse {
+    // The channel funding transaction ID.
+    string txid = 1;
+
+    // The index of the channel funding output in the funding transaction.
+    int32 output_index = 2;
+}
+
+message RouterSendPaymentData {
+    // The string encoded asset ID to amount mapping. Instructs the router to
+    // use these assets in the given amounts for the payment. Can be empty for
+    // a payment of an invoice, if the RFQ ID is set instead.
+    map<string, uint64> asset_amounts = 1;
+
+    // The RFQ ID to use for the payment. Can be empty for a direct keysend
+    // payment that doesn't involve any conversion (and thus no RFQ).
+    bytes rfq_id = 2;
+}
+
+message EncodeCustomRecordsRequest {
+    oneof input {
+        // The custom records to encode for a payment request.
+        RouterSendPaymentData router_send_payment = 1;
+    }
+}
+
+message EncodeCustomRecordsResponse {
+    // The encoded custom records in TLV format.
+    map<uint64, bytes> custom_records = 1;
+}
+
+message SendPaymentRequest {
+    // The asset ID to use for the payment. This must be set for both invoice
+    // and keysend payments, unless RFQ negotiation was already done beforehand
+    // and payment_request.first_hop_custom_records already contains valid RFQ
+    // data. Mutually exclusive to group_key.
+    bytes asset_id = 1;
+
+    // The asset amount to send in a keysend payment. This amount is ignored for
+    // invoice payments as the asset amount is negotiated through RFQ with the
+    // peer, depending on the invoice amount. This can also be left unset if RFQ
+    // negotiation was already done beforehand and
+    // payment_request.first_hop_custom_records already contains valid RFQ data.
+    uint64 asset_amount = 2;
+
+    // The node identity public key of the peer to ask for a quote for sending
+    // out the assets and converting them to satoshis. If set, only a quote with
+    // this peer may be negotiated to carry out the payment.
+    bytes peer_pubkey = 3;
+
+    // The full lnd payment request to send. All fields behave the same way as
+    // they do for lnd's routerrpc.SendPaymentV2 RPC method (see the API docs
+    // at https://lightning.engineering/api-docs/api/lnd/router/send-payment-v2
+    // for more details).
+    // To send a keysend payment, the payment_request.dest_custom_records must
+    // contain a valid keysend record (key 5482373484 and a 32-byte preimage
+    // that corresponds to the payment hash).
+    routerrpc.SendPaymentRequest payment_request = 4;
+
+    // The rfq id to use for this payment. If the user sets this value then the
+    // payment will immediately be dispatched, skipping the rfq negotiation
+    // phase, and using the following rfq id instead.
+    bytes rfq_id = 5;
+
+    // If a small invoice should be paid that is below the amount that always
+    // needs to be sent out to carry a single asset unit, then by default the
+    // payment is rejected. If this flag is set, then the payment will be
+    // allowed to proceed, even if it is uneconomical, meaning that more sats
+    // are sent out to the network than the invoice amount plus routing fees
+    // require to be paid.
+    bool allow_overpay = 6;
+
+    // The group key which dictates which assets may be used for this payment.
+    // Mutually exclusive to asset_id.
+    bytes group_key = 7;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the payment to the price oracle. This can include information
+    // about the wallet end user that initiated the transaction, or any
+    // authentication information that the price oracle can use to give out a
+    // more accurate (or discount) asset rate. Though not verified or enforced
+    // by tapd, the suggested format for this field is a JSON string.
+    // This field is optional and can be left empty if no metadata is available.
+    // The maximum length of this field is 32'768 bytes.
+    string price_oracle_metadata = 8;
+}
+
+message AcceptedSellQuotes {
+    // If swapping of assets is necessary to carry out the payment, a number of
+    // RFQ quotes may be negotiated for that purpose. The following field
+    // contains all the sell orders that were negotiated with our peers.
+    repeated rfqrpc.PeerAcceptedSellQuote accepted_sell_orders = 1;
+}
+
+message SendPaymentResponse {
+    oneof result {
+        // In case channel assets need to be swapped to another asset, an asset
+        // sell order is negotiated with the channel peer. The result will be
+        // the first message in the response stream. If no swap is needed, the
+        // payment results will be streamed directly.
+        // Deprecated. This will now only contain the first quote that was
+        // negotiated. Since the introduction of multi-rfq we now negotiate
+        // multiple quotes in the context of a payment. Use the new field named
+        // "accepted_sell_orders" to retrieve all of them.
+        rfqrpc.PeerAcceptedSellQuote accepted_sell_order = 1;
+
+        // If swapping of assets is necessary to carry out the payment, a number
+        // of RFQ quotes may be negotiated for that purpose. The following field
+        // contains all the sell orders that were negotiated with our peers.
+        AcceptedSellQuotes accepted_sell_orders = 3;
+
+        // The payment result of a single payment attempt. Multiple attempts
+        // may be returned per payment request until either the payment
+        // succeeds or the payment times out.
+        lnrpc.Payment payment_result = 2;
+    }
+}
+
+message HodlInvoice {
+    // The payment hash of the HODL invoice to be created.
+    bytes payment_hash = 1;
+}
+
+message AddInvoiceRequest {
+    // The asset ID to use for the invoice. Mutually exclusive to group_key.
+    bytes asset_id = 1;
+
+    // The asset amount to receive.
+    uint64 asset_amount = 2;
+
+    // The node identity public key of the peer to ask for a quote for receiving
+    // assets and converting them from satoshis. When specified only quotes with
+    // this peer will be negotiated.
+    bytes peer_pubkey = 3;
+
+    // The full lnd invoice request to send. All fields behave the same way as
+    // they do for lnd's lnrpc.AddInvoice RPC method (see the API docs at
+    // https://lightning.engineering/api-docs/api/lnd/lightning/add-invoice
+    // for more details).
+    //
+    // Only one of the asset_amount/value/value_msat may be set to dictate the
+    // value of the invoice. When using asset_amount, the value/value_msat
+    // fields will be overwritten by the satoshi (or milli-satoshi) equivalent
+    // of the asset amount, after negotiating a quote with a peer that supports
+    // the given asset ID.
+    //
+    // If the value/value_msat are used, we still receive assets, but they will
+    // exactly evaluate to the defined amount in sats/msats.
+    lnrpc.Invoice invoice_request = 4;
+
+    // If set, then this will make the invoice created a hodl invoice, which
+    // won't be settled automatically. Instead, users will need to use the
+    // invoicesrpc.SettleInvoice call to manually settle the invoice.
+    HodlInvoice hodl_invoice = 5;
+
+    // The group key which dictates which assets may be accepted for this
+    // invoice. If set, any asset that belongs to this group may be accepted to
+    // settle this invoice. Mutually exclusive to asset_id.
+    bytes group_key = 6;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the invoice to the price oracle. This can include information
+    // about the wallet end user that initiated the transaction, or any
+    // authentication information that the price oracle can use to give out a
+    // more accurate (or discount) asset rate. Though not verified or enforced
+    // by tapd, the suggested format for this field is a JSON string.
+    // This field is optional and can be left empty if no metadata is available.
+    // The maximum length of this field is 32'768 bytes.
+    string price_oracle_metadata = 7;
+
+    // Reserved: was rfq_id.
+    reserved 8;
+
+    // Optional minimum asset amount the peer must accept.
+    // Forwarded to AddAssetBuyOrder. When omitted, defaults
+    // to the full asset amount (full-fill expected). Set
+    // explicitly to 0 to accept any partial fill.
+    optional uint64 asset_min_amt = 9;
+
+    // Optional rate floor (asset units per BTC) as a
+    // fixed-point number. Forwarded to AddAssetBuyOrder.
+    rfqrpc.FixedPoint asset_rate_limit = 10;
+
+    // Execution policy (IOC default, FOK). Forwarded to
+    // AddAssetBuyOrder.
+    rfqrpc.ExecutionPolicy execution_policy = 11;
+}
+
+message AddInvoiceResponse {
+    // The quote for the purchase of assets that was accepted by the peer.
+    rfqrpc.PeerAcceptedBuyQuote accepted_buy_quote = 1;
+
+    // The result of the invoice creation.
+    lnrpc.AddInvoiceResponse invoice_result = 2;
+}
+
+message AssetPayReq {
+    // The asset ID that will be used to resolve the invoice's satoshi amount.
+    // Mutually exclusive to group_key.
+    bytes asset_id = 1;
+
+    // The normal LN invoice that whose amount will be mapped to units of the
+    // asset ID.
+    string pay_req_string = 2;
+
+    // The group key that will be used to resolve the invoice's satoshi amount.
+    // Mutually exclusive to asset_id.
+    bytes group_key = 3;
+
+    // An optional text field that can be used to provide additional metadata
+    // about the invoice to the price oracle. This can include information
+    // about the wallet end user that initiated the transaction, or any
+    // authentication information that the price oracle can use to give out a
+    // more accurate (or discount) asset rate. Though not verified or enforced
+    // by tapd, the suggested format for this field is a JSON string.
+    // This field is optional and can be left empty if no metadata is available.
+    // The maximum length of this field is 32'768 bytes.
+    string price_oracle_metadata = 4;
+}
+
+message AssetPayReqResponse {
+    // The invoice amount, expressed in asset units.
+    uint64 asset_amount = 1;
+
+    // The decimal display corresponding to the asset_id.
+    taprpc.DecimalDisplay decimal_display = 2;
+
+    // The group the asset ID belong to, if applicable.
+    taprpc.AssetGroup asset_group = 3;
+
+    // Always populated. For group-key queries, the asset_id reflects the
+    // resolved tranche's genesis ID.
+    taprpc.GenesisInfo genesis_info = 4;
+
+    // The normal decoded payment request.
+    lnrpc.PayReq pay_req = 5;
+}
+
+message AssetAmount {
+    // The asset ID (genesis ID of the tranche) the amount refers to.
+    bytes asset_id = 1;
+
+    // The amount, expressed in units of the asset identified by asset_id.
+    uint64 amount = 2;
+
+    // The tweaked group key the asset belongs to, in compressed form. Empty
+    // for assets that aren't part of a group, or whose group is unknown to
+    // this tapd instance. Populated so callers that work in terms of group
+    // keys (e.g. wallets backing a fungible group of tranches) don't need a
+    // separate lookup per result.
+    bytes group_key = 3;
+}
+
+message ListInvoicesRequest {
+    // The standard lnd invoice listing request. All fields behave the same way
+    // as they do for lnd's lnrpc.ListInvoices RPC method (see the API docs at
+    // https://lightning.engineering/api-docs/api/lnd/lightning/list-invoices
+    // for more details). Pagination is performed by lnd over all invoices; the
+    // returned set is then filtered down to only those that involve assets, so
+    // a page may contain fewer asset invoices than the requested maximum.
+    lnrpc.ListInvoiceRequest request = 1;
+}
+
+message SubscribeInvoicesRequest {
+    // The standard lnd invoice subscription request. All fields behave the same
+    // way as they do for lnd's lnrpc.SubscribeInvoices RPC method (see the API
+    // docs at
+    // https://lightning.engineering/api-docs/api/lnd/lightning/subscribe-invoices
+    // for more details). Invoice index replay is performed by lnd over all
+    // invoices; the returned stream is then filtered down to only those that
+    // involve assets.
+    lnrpc.InvoiceSubscription request = 1;
+}
+
+message AssetInvoice {
+    // The full lnd invoice, including any custom channel data on its HTLCs.
+    lnrpc.Invoice invoice = 1;
+
+    // The asset amounts carried by the invoice's HTLCs, aggregated per asset
+    // ID across all of the invoice's HTLCs. Empty for invoices that have not
+    // been (partially) settled with assets yet.
+    repeated AssetAmount asset_amounts = 2;
+}
+
+message ListInvoicesResponse {
+    // The list of asset invoices that matched the request.
+    repeated AssetInvoice invoices = 1;
+
+    // The index of the last item in the set of returned invoices. This can be
+    // used to seek further, pagination style. Mirrors the value returned by
+    // lnd's lnrpc.ListInvoices.
+    uint64 last_index_offset = 2;
+
+    // The index of the first item in the set of returned invoices. This can be
+    // used to seek backwards, pagination style. Mirrors the value returned by
+    // lnd's lnrpc.ListInvoices.
+    uint64 first_index_offset = 3;
+}
+
+message ListPaymentsRequest {
+    // The standard lnd payment listing request. All fields behave the same way
+    // as they do for lnd's lnrpc.ListPayments RPC method (see the API docs at
+    // https://lightning.engineering/api-docs/api/lnd/lightning/list-payments
+    // for more details). Pagination is performed by lnd over all payments; the
+    // returned set is then filtered down to only those that involve assets, so
+    // a page may contain fewer asset payments than the requested maximum.
+    lnrpc.ListPaymentsRequest request = 1;
+}
+
+message SubscribePaymentsRequest {
+    // The standard lnd payment tracking request. All fields behave the same way
+    // as they do for lnd's routerrpc.TrackPayments RPC method (see the API docs
+    // at https://lightning.engineering/api-docs/api/lnd/router/track-payments
+    // for more details). The payment update stream is produced by lnd over all
+    // active payments; the returned stream is then filtered down to only those
+    // that involve assets.
+    routerrpc.TrackPaymentsRequest request = 1;
+}
+
+message TrackPaymentRequest {
+    // The standard lnd payment tracking request. All fields behave the same way
+    // as they do for lnd's routerrpc.TrackPaymentV2 RPC method (see the API
+    // docs at
+    // https://lightning.engineering/api-docs/api/lnd/router/track-payment-v2
+    // for more details). The payment update stream is produced by lnd for the
+    // requested payment; the returned stream is then filtered down to only
+    // updates that involve assets.
+    routerrpc.TrackPaymentRequest request = 1;
+}
+
+message AssetPayment {
+    // The full lnd payment, including any custom channel data on its HTLCs.
+    lnrpc.Payment payment = 1;
+
+    // The asset amounts carried by the payment, aggregated per asset ID across
+    // all non-failed HTLC attempts. Empty for payments that did not (yet) move
+    // any assets.
+    repeated AssetAmount asset_amounts = 2;
+}
+
+message ListPaymentsResponse {
+    // The list of asset payments that matched the request.
+    repeated AssetPayment payments = 1;
+
+    // The index of the first item in the set of returned payments. This can be
+    // used to seek backwards, pagination style. Mirrors the value returned by
+    // lnd's lnrpc.ListPayments.
+    uint64 first_index_offset = 2;
+
+    // The index of the last item in the set of returned payments. This can be
+    // used to seek further, pagination style. Mirrors the value returned by
+    // lnd's lnrpc.ListPayments.
+    uint64 last_index_offset = 3;
+}

package/protos/taprpc/tapcommon.proto

@@ -0,0 +1,47 @@
+syntax = "proto3";
+
+package taprpc;
+
+option go_package = "github.com/lightninglabs/taproot-assets/taprpc";
+
+// Represents a Bitcoin transaction outpoint.
+message OutPoint {
+    /*
+    Raw bytes representing the transaction id. Must be in
+    internal byte order (little-endian), i.e. reversed
+    compared to the human-readable (RPC/block explorer)
+    hex encoding.
+    */
+    bytes txid = 1;
+
+    /*
+    The index of the output on the transaction.
+    */
+    uint32 output_index = 2;
+}
+
+// A transaction outpoint annotated with TAP-level asset metadata. It uniquely
+// identifies an asset anchored at a specific outpoint.
+message AssetOutPoint {
+    // The outpoint of the asset anchor, represented as a string in the
+    // format "<txid>:<vout>". The <txid> is the transaction ID of the UTXO,
+    // hex-encoded and byte-reversed (i.e., the internal little-endian
+    // 32-byte value is reversed to big-endian hex format) to match standard
+    // Bitcoin RPC and UI conventions.
+    string anchor_out_point = 1;
+
+    // The asset ID of the asset anchored at the outpoint.
+    bytes asset_id = 2;
+
+    // The script key of the asset. This is the taproot output key that the
+    // asset is locked to.
+    bytes script_key = 3;
+}
+
+enum SortDirection {
+    // Sort results in descending order.
+    SORT_DIRECTION_DESC = 0;
+
+    // Sort results in ascending order.
+    SORT_DIRECTION_ASC = 1;
+}

package/protos/taprpc/tapdevrpc/tapdev.proto

@@ -0,0 +1,120 @@
+syntax = "proto3";
+
+import "taprootassets.proto";
+
+package tapdevrpc;
+
+option go_package = "github.com/lightninglabs/taproot-assets/taprpc/tapdevrpc";
+
+service TapDev {
+    /* tapcli: `dev importproof`
+    Deprecated, use the new taprpc.RegisterTransfer RPC instead! ImportProof
+    attempts to import a proof file into the daemon. If successful,
+    a new asset will be inserted on disk, spendable using the specified target
+    script key, and internal key.
+    NOTE: This RPC will be removed with the next major release.
+    */
+    rpc ImportProof (ImportProofRequest) returns (ImportProofResponse) {
+        option deprecated = true;
+    };
+
+    /*
+    SubscribeSendAssetEventNtfns registers a subscription to the event
+    notification stream which relates to the asset sending process.
+    */
+    rpc SubscribeSendAssetEventNtfns (SubscribeSendAssetEventNtfnsRequest)
+        returns (stream SendAssetEvent);
+
+    /*
+    SubscribeReceiveAssetEventNtfns registers a subscription to the event
+    notification stream which relates to the asset receive process.
+    */
+    rpc SubscribeReceiveAssetEventNtfns (SubscribeReceiveAssetEventNtfnsRequest)
+        returns (stream ReceiveAssetEvent);
+}
+
+message ImportProofRequest {
+    bytes proof_file = 1;
+
+    string genesis_point = 2;
+}
+
+message ImportProofResponse {
+}
+
+message SubscribeSendAssetEventNtfnsRequest {
+}
+
+message SendAssetEvent {
+    oneof event {
+        // An event which indicates that a send state is about to be executed.
+        ExecuteSendStateEvent execute_send_state_event = 1;
+
+        // An event which indicates that the proof transfer backoff wait period
+        // will start imminently.
+        ProofTransferBackoffWaitEvent proof_transfer_backoff_wait_event = 2;
+    }
+}
+
+message ExecuteSendStateEvent {
+    // Execute timestamp (microseconds).
+    int64 timestamp = 1;
+
+    // The send state that is about to be executed.
+    string send_state = 2;
+}
+
+// ProofTransferType is the type of proof transfer attempt. The transfer is
+// either a proof delivery to the transfer counterparty or receiving a proof
+// from the transfer counterparty. Note that the transfer counterparty is
+// usually the proof courier service.
+enum ProofTransferType {
+    // This value indicates that the proof transfer attempt is a delivery to the
+    // transfer counterparty.
+    PROOF_TRANSFER_TYPE_SEND = 0;
+
+    // This value indicates that the proof transfer attempt is a receive from
+    // the transfer counterparty.
+    PROOF_TRANSFER_TYPE_RECEIVE = 1;
+}
+
+message ProofTransferBackoffWaitEvent {
+    // Transfer attempt timestamp (microseconds).
+    int64 timestamp = 1;
+
+    // Backoff is the active backoff wait duration.
+    int64 backoff = 2;
+
+    // Tries counter is the number of tries we've made so far during the
+    // course of the current backoff procedure to deliver the proof to the
+    // receiver.
+    int64 tries_counter = 3;
+
+    // The type of proof transfer attempt.
+    ProofTransferType transfer_type = 4;
+}
+
+message SubscribeReceiveAssetEventNtfnsRequest {
+}
+
+message AssetReceiveCompleteEvent {
+    // Event creation timestamp.
+    int64 timestamp = 1;
+
+    // The address that received the asset.
+    taprpc.Addr address = 2;
+
+    // The outpoint of the transaction that was used to receive the asset.
+    string outpoint = 3;
+}
+
+message ReceiveAssetEvent {
+    oneof event {
+        // An event which indicates that the proof transfer backoff wait period
+        // will start imminently.
+        ProofTransferBackoffWaitEvent proof_transfer_backoff_wait_event = 1;
+
+        // An event which indicates that an asset receive process has finished.
+        AssetReceiveCompleteEvent asset_receive_complete_event = 2;
+    }
+}