From 7f95ca117729cf9c1c5cbaf7d98023d4674d6cd8 Mon Sep 17 00:00:00 2001 From: ffranr Date: Tue, 5 Nov 2024 16:11:34 +0000 Subject: [PATCH] rfqrpc: improve doc for endpoint AddAssetBuyOrder --- taprpc/rfqrpc/rfq.proto | 20 +++++++++++++++++ taprpc/rfqrpc/rfq.swagger.json | 2 ++ taprpc/rfqrpc/rfq_grpc.pb.go | 40 ++++++++++++++++++++++++++++++++++ 3 files changed, 62 insertions(+) diff --git a/taprpc/rfqrpc/rfq.proto b/taprpc/rfqrpc/rfq.proto index 792176f60..5c6dd99b1 100644 --- a/taprpc/rfqrpc/rfq.proto +++ b/taprpc/rfqrpc/rfq.proto @@ -8,6 +8,26 @@ service Rfq { /* tapcli: `rfq buyorder` AddAssetBuyOrder is used to add a buy order for a specific asset. If a buy order already exists for the asset, it will be updated. + + A buy order instructs the RFQ (Request For Quote) system to request a quote + from a peer for the acquisition of an asset. + + The normal use of a buy order is as follows: + 1. Alice, operating a wallet node, wants to receive a Tap asset as payment + by issuing a Lightning invoice. + 2. Alice has an asset channel established with Bob's edge node. + 3. Before issuing the invoice, Alice needs to agree on an exchange rate with + Bob, who will facilitate the asset transfer. + 4. To obtain the best exchange rate, Alice creates a buy order specifying + the desired asset. + 5. Alice's RFQ subsystem processes the buy order and sends buy requests to + relevant peers to find the best rate. In this example, Bob is the only + available peer. + 6. Once Bob provides a satisfactory quote, Alice accepts it. + 7. Alice issues the Lightning invoice, which Charlie will pay. + 8. Instead of paying Alice directly, Charlie pays Bob. + 9. Bob then forwards the agreed amount of the Tap asset to Alice over their + asset channel. */ rpc AddAssetBuyOrder (AddAssetBuyOrderRequest) returns (AddAssetBuyOrderResponse); diff --git a/taprpc/rfqrpc/rfq.swagger.json b/taprpc/rfqrpc/rfq.swagger.json index 6433189f1..9e51313af 100644 --- a/taprpc/rfqrpc/rfq.swagger.json +++ b/taprpc/rfqrpc/rfq.swagger.json @@ -157,6 +157,7 @@ "/v1/taproot-assets/rfq/buyorder/asset-id/{asset_specifier.asset_id_str}": { "post": { "summary": "tapcli: `rfq buyorder`\nAddAssetBuyOrder is used to add a buy order for a specific asset. If a buy\norder already exists for the asset, it will be updated.", + "description": "A buy order instructs the RFQ (Request For Quote) system to request a quote\nfrom a peer for the acquisition of an asset.\n\nThe normal use of a buy order is as follows:\n1. Alice, operating a wallet node, wants to receive a Tap asset as payment\nby issuing a Lightning invoice.\n2. Alice has an asset channel established with Bob's edge node.\n3. Before issuing the invoice, Alice needs to agree on an exchange rate with\nBob, who will facilitate the asset transfer.\n4. To obtain the best exchange rate, Alice creates a buy order specifying\nthe desired asset.\n5. Alice's RFQ subsystem processes the buy order and sends buy requests to\nrelevant peers to find the best rate. In this example, Bob is the only\navailable peer.\n6. Once Bob provides a satisfactory quote, Alice accepts it.\n7. Alice issues the Lightning invoice, which Charlie will pay.\n8. Instead of paying Alice directly, Charlie pays Bob.\n9. Bob then forwards the agreed amount of the Tap asset to Alice over their\nasset channel.", "operationId": "Rfq_AddAssetBuyOrder", "responses": { "200": { @@ -240,6 +241,7 @@ "/v1/taproot-assets/rfq/buyorder/group-key/{asset_specifier.group_key_str}": { "post": { "summary": "tapcli: `rfq buyorder`\nAddAssetBuyOrder is used to add a buy order for a specific asset. If a buy\norder already exists for the asset, it will be updated.", + "description": "A buy order instructs the RFQ (Request For Quote) system to request a quote\nfrom a peer for the acquisition of an asset.\n\nThe normal use of a buy order is as follows:\n1. Alice, operating a wallet node, wants to receive a Tap asset as payment\nby issuing a Lightning invoice.\n2. Alice has an asset channel established with Bob's edge node.\n3. Before issuing the invoice, Alice needs to agree on an exchange rate with\nBob, who will facilitate the asset transfer.\n4. To obtain the best exchange rate, Alice creates a buy order specifying\nthe desired asset.\n5. Alice's RFQ subsystem processes the buy order and sends buy requests to\nrelevant peers to find the best rate. In this example, Bob is the only\navailable peer.\n6. Once Bob provides a satisfactory quote, Alice accepts it.\n7. Alice issues the Lightning invoice, which Charlie will pay.\n8. Instead of paying Alice directly, Charlie pays Bob.\n9. Bob then forwards the agreed amount of the Tap asset to Alice over their\nasset channel.", "operationId": "Rfq_AddAssetBuyOrder2", "responses": { "200": { diff --git a/taprpc/rfqrpc/rfq_grpc.pb.go b/taprpc/rfqrpc/rfq_grpc.pb.go index 65cfbde9e..f3adbe75d 100644 --- a/taprpc/rfqrpc/rfq_grpc.pb.go +++ b/taprpc/rfqrpc/rfq_grpc.pb.go @@ -21,6 +21,26 @@ type RfqClient interface { // tapcli: `rfq buyorder` // AddAssetBuyOrder is used to add a buy order for a specific asset. If a buy // order already exists for the asset, it will be updated. + // + // A buy order instructs the RFQ (Request For Quote) system to request a quote + // from a peer for the acquisition of an asset. + // + // The normal use of a buy order is as follows: + // 1. Alice, operating a wallet node, wants to receive a Tap asset as payment + // by issuing a Lightning invoice. + // 2. Alice has an asset channel established with Bob's edge node. + // 3. Before issuing the invoice, Alice needs to agree on an exchange rate with + // Bob, who will facilitate the asset transfer. + // 4. To obtain the best exchange rate, Alice creates a buy order specifying + // the desired asset. + // 5. Alice's RFQ subsystem processes the buy order and sends buy requests to + // relevant peers to find the best rate. In this example, Bob is the only + // available peer. + // 6. Once Bob provides a satisfactory quote, Alice accepts it. + // 7. Alice issues the Lightning invoice, which Charlie will pay. + // 8. Instead of paying Alice directly, Charlie pays Bob. + // 9. Bob then forwards the agreed amount of the Tap asset to Alice over their + // asset channel. AddAssetBuyOrder(ctx context.Context, in *AddAssetBuyOrderRequest, opts ...grpc.CallOption) (*AddAssetBuyOrderResponse, error) // tapcli: `rfq sellorder` // AddAssetSellOrder is used to add a sell order for a specific asset. If a @@ -137,6 +157,26 @@ type RfqServer interface { // tapcli: `rfq buyorder` // AddAssetBuyOrder is used to add a buy order for a specific asset. If a buy // order already exists for the asset, it will be updated. + // + // A buy order instructs the RFQ (Request For Quote) system to request a quote + // from a peer for the acquisition of an asset. + // + // The normal use of a buy order is as follows: + // 1. Alice, operating a wallet node, wants to receive a Tap asset as payment + // by issuing a Lightning invoice. + // 2. Alice has an asset channel established with Bob's edge node. + // 3. Before issuing the invoice, Alice needs to agree on an exchange rate with + // Bob, who will facilitate the asset transfer. + // 4. To obtain the best exchange rate, Alice creates a buy order specifying + // the desired asset. + // 5. Alice's RFQ subsystem processes the buy order and sends buy requests to + // relevant peers to find the best rate. In this example, Bob is the only + // available peer. + // 6. Once Bob provides a satisfactory quote, Alice accepts it. + // 7. Alice issues the Lightning invoice, which Charlie will pay. + // 8. Instead of paying Alice directly, Charlie pays Bob. + // 9. Bob then forwards the agreed amount of the Tap asset to Alice over their + // asset channel. AddAssetBuyOrder(context.Context, *AddAssetBuyOrderRequest) (*AddAssetBuyOrderResponse, error) // tapcli: `rfq sellorder` // AddAssetSellOrder is used to add a sell order for a specific asset. If a