taprpc: make type of proof explicit in RPC

taprpc/assetwalletrpc/assetwallet.swagger.json

@@ -668,7 +668,8 @@
         },
         "new_proof_blob": {
           "type": "string",
-          "format": "byte"
+          "format": "byte",
+          "description": "The new individual transition proof (not a full proof file) that proves\nthe inclusion of the new asset within the new AnchorTx."
         },
         "split_commit_root_hash": {
           "type": "string",

taprpc/taprootassets.proto

@@ -504,6 +504,8 @@ message TransferOutput {
 
     uint64 amount = 4;
 
+    // The new individual transition proof (not a full proof file) that proves
+    // the inclusion of the new asset within the new AnchorTx.
     bytes new_proof_blob = 5;
 
     bytes split_commit_root_hash = 6;
@@ -684,6 +686,8 @@ message DecodeAddrRequest {
 }
 
 message ProofFile {
+    // The raw proof file encoded as bytes. Must be a file and not just an
+    // individual mint/transfer proof.
     bytes raw_proof = 1;
 
     string genesis_point = 2;
@@ -693,7 +697,9 @@ message DecodedProof {
     // The index depth of the decoded proof, with 0 being the latest proof.
     uint32 proof_at_depth = 1;
 
-    // The total number of proofs contained in the raw proof.
+    // The total number of proofs contained in the decoded proof file (this will
+    // always be 1 if a single mint/transition proof was given as the raw_proof
+    // instead of a file).
     uint32 number_of_proofs = 2;
 
     // The asset referenced in the proof.
@@ -734,14 +740,21 @@ message DecodedProof {
 
 message VerifyProofResponse {
     bool valid = 1;
+
+    // The decoded last proof in the file if the proof file was valid.
     DecodedProof decoded_proof = 2;
 }
 
 message DecodeProofRequest {
-    // The raw proof in bytes to decode, which may contain multiple proofs.
+    // The raw proof bytes to decode. This can be a full proof file or a single
+    // mint/transition proof. If it is a full proof file, the proof_at_depth
+    // field will be used to determine which individual proof within the file to
+    // decode.
     bytes raw_proof = 1;
 
-    // The index depth of the decoded proof, with 0 being the latest proof.
+    // The index depth of the decoded proof, with 0 being the latest proof. This
+    // is ignored if the raw_proof is a single mint/transition proof and not a
+    // proof file.
     uint32 proof_at_depth = 2;
 
     // An option to include previous witnesses in decoding.

taprpc/taprootassets.swagger.json

@@ -1203,12 +1203,12 @@
         "raw_proof": {
           "type": "string",
           "format": "byte",
-          "description": "The raw proof in bytes to decode, which may contain multiple proofs."
+          "description": "The raw proof bytes to decode. This can be a full proof file or a single\nmint/transition proof. If it is a full proof file, the proof_at_depth\nfield will be used to determine which individual proof within the file to\ndecode."
         },
         "proof_at_depth": {
           "type": "integer",
           "format": "int64",
-          "description": "The index depth of the decoded proof, with 0 being the latest proof."
+          "description": "The index depth of the decoded proof, with 0 being the latest proof. This\nis ignored if the raw_proof is a single mint/transition proof and not a\nproof file."
         },
         "with_prev_witnesses": {
           "type": "boolean",
@@ -1239,7 +1239,7 @@
         "number_of_proofs": {
           "type": "integer",
           "format": "int64",
-          "description": "The total number of proofs contained in the raw proof."
+          "description": "The total number of proofs contained in the decoded proof file (this will\nalways be 1 if a single mint/transition proof was given as the raw_proof\ninstead of a file)."
         },
         "asset": {
           "$ref": "#/definitions/taprpcAsset",
@@ -1589,7 +1589,8 @@
       "properties": {
         "raw_proof": {
           "type": "string",
-          "format": "byte"
+          "format": "byte",
+          "description": "The raw proof file encoded as bytes. Must be a file and not just an\nindividual mint/transfer proof."
         },
         "genesis_point": {
           "type": "string"
@@ -1738,7 +1739,8 @@
         },
         "new_proof_blob": {
           "type": "string",
-          "format": "byte"
+          "format": "byte",
+          "description": "The new individual transition proof (not a full proof file) that proves\nthe inclusion of the new asset within the new AnchorTx."
         },
         "split_commit_root_hash": {
           "type": "string",
@@ -1789,7 +1791,8 @@
           "type": "boolean"
         },
         "decoded_proof": {
-          "$ref": "#/definitions/taprpcDecodedProof"
+          "$ref": "#/definitions/taprpcDecodedProof",
+          "description": "The decoded last proof in the file if the proof file was valid."
         }
       }
     }

taprpc/universerpc/universe.proto

@@ -234,7 +234,8 @@ message AssetLeaf {
     // TODO(roasbeef): only needed for display? can get from proof below ^
 
     // The asset issuance proof, which proves that the asset specified above
-    // was issued properly.
+    // was issued properly. This is always just an individual mint/transfer
+    // proof and never a proof file.
     bytes issuance_proof = 2;
 }
 

taprpc/universerpc/universe.swagger.json

@@ -1296,7 +1296,7 @@
         "issuance_proof": {
           "type": "string",
           "format": "byte",
-          "description": "The asset issuance proof, which proves that the asset specified above\nwas issued properly."
+          "description": "The asset issuance proof, which proves that the asset specified above\nwas issued properly. This is always just an individual mint/transfer\nproof and never a proof file."
         }
       }
     },