feat(platform)!: a document batch proof carries the owner's credit balance

book/src/sdk/put-operations.md

@@ -255,6 +255,22 @@ The wait includes full proof verification: the SDK verifies a GroveDB proof that
 the state transition was actually applied. This is not just checking a status flag --
 it is cryptographic proof of inclusion.
 
+From protocol version 14 the proof of an owned, fee-paying transition (document
+and token batches, contract creates and updates, identity updates and key limit
+updates, contract moderation) also carries the credit balance of the owner
+after it, read from the same state as the result, so a wallet learns what the
+write left it with without a second query. The verified
+`StateTransitionProofOutcome` hands it out through `owner_balance()` (`None`
+for a proof made at an earlier version or a transition without an owner);
+`wait_for_document_and_owner_balance` and
+`put_to_platform_and_wait_for_response_with_owner_balance` return it next to
+the document. The balance is a snapshot at the proof's block: it may already
+include later transitions of the same identity. A wait that asks for no proof
+but sets `request_user_balance` gets the owner's balance back unverified, as
+the response's `success_with_owner_balance` result, read from a Drive state at
+or past the block that executed the write; that works for any transition with
+an owner.
+
 ### Timeout Handling
 
 `wait_for_response` supports an optional timeout:

packages/dapi-grpc/clients/platform/v0/nodejs/platform_protoc.js

@@ -728,6 +728,7 @@ goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultR
 goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.VersionCase', null, { proto });
 goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForStateTransitionResultRequestV0', null, { proto });
 goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse', null, { proto });
+goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance', null, { proto });
 goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.VersionCase', null, { proto });
 goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0', null, { proto });
 goog.exportSymbol('proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.ResultCase', null, { proto });
@@ -4847,6 +4848,27 @@ if (goog.DEBUG && !COMPILED) {
    */
   proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.displayName = 'proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse';
 }
+/**
+ * Generated by JsPbCodeGenerator.
+ * @param {Array=} opt_data Optional initial data array, typically from a
+ * server response, or constructed directly in Javascript. The array is used
+ * in place and becomes part of the constructed object. It is not cloned.
+ * If no data is provided, the constructed object will be empty, but still
+ * valid.
+ * @extends {jspb.Message}
+ * @constructor
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance = function(opt_data) {
+  jspb.Message.initialize(this, opt_data, 0, -1, null, null);
+};
+goog.inherits(proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance, jspb.Message);
+if (goog.DEBUG && !COMPILED) {
+  /**
+   * @public
+   * @override
+   */
+  proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.displayName = 'proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance';
+}
 /**
  * Generated by JsPbCodeGenerator.
  * @param {Array=} opt_data Optional initial data array, typically from a
@@ -54661,7 +54683,8 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForState
 proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForStateTransitionResultRequestV0.toObject = function(includeInstance, msg) {
   var f, obj = {
     stateTransitionHash: msg.getStateTransitionHash_asB64(),
-    prove: jspb.Message.getBooleanFieldWithDefault(msg, 2, false)
+    prove: jspb.Message.getBooleanFieldWithDefault(msg, 2, false),
+    requestUserBalance: jspb.Message.getBooleanFieldWithDefault(msg, 3, false)
   };
 
   if (includeInstance) {
@@ -54706,6 +54729,10 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForState
       var value = /** @type {boolean} */ (reader.readBool());
       msg.setProve(value);
       break;
+    case 3:
+      var value = /** @type {boolean} */ (reader.readBool());
+      msg.setRequestUserBalance(value);
+      break;
     default:
       reader.skipField();
       break;
@@ -54749,6 +54776,13 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForState
       f
     );
   }
+  f = message.getRequestUserBalance();
+  if (f) {
+    writer.writeBool(
+      3,
+      f
+    );
+  }
 };
 
 
@@ -54812,6 +54846,24 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForState
 };
 
 
+/**
+ * optional bool request_user_balance = 3;
+ * @return {boolean}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForStateTransitionResultRequestV0.prototype.getRequestUserBalance = function() {
+  return /** @type {boolean} */ (jspb.Message.getBooleanFieldWithDefault(this, 3, false));
+};
+
+
+/**
+ * @param {boolean} value
+ * @return {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForStateTransitionResultRequestV0} returns this
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForStateTransitionResultRequestV0.prototype.setRequestUserBalance = function(value) {
+  return jspb.Message.setProto3BooleanField(this, 3, value);
+};
+
+
 /**
  * optional WaitForStateTransitionResultRequestV0 v0 = 1;
  * @return {?proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultRequest.WaitForStateTransitionResultRequestV0}
@@ -54989,6 +55041,136 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.serializeBi
 
 
 
+
+
+if (jspb.Message.GENERATE_TO_OBJECT) {
+/**
+ * Creates an object representation of this proto.
+ * Field names that are reserved in JavaScript and will be renamed to pb_name.
+ * Optional fields that are not set will be set to undefined.
+ * To access a reserved field use, foo.pb_<name>, eg, foo.pb_default.
+ * For the list of reserved names please see:
+ *     net/proto2/compiler/js/internal/generator.cc#kKeyword.
+ * @param {boolean=} opt_includeInstance Deprecated. whether to include the
+ *     JSPB instance for transitional soy proto support:
+ *     http://goto/soy-param-migration
+ * @return {!Object}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.prototype.toObject = function(opt_includeInstance) {
+  return proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.toObject(opt_includeInstance, this);
+};
+
+
+/**
+ * Static version of the {@see toObject} method.
+ * @param {boolean|undefined} includeInstance Deprecated. Whether to include
+ *     the JSPB instance for transitional soy proto support:
+ *     http://goto/soy-param-migration
+ * @param {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance} msg The msg instance to transform.
+ * @return {!Object}
+ * @suppress {unusedLocalVariables} f is only used for nested messages
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.toObject = function(includeInstance, msg) {
+  var f, obj = {
+    ownerBalance: jspb.Message.getFieldWithDefault(msg, 1, "0")
+  };
+
+  if (includeInstance) {
+    obj.$jspbMessageInstance = msg;
+  }
+  return obj;
+};
+}
+
+
+/**
+ * Deserializes binary data (in protobuf wire format).
+ * @param {jspb.ByteSource} bytes The bytes to deserialize.
+ * @return {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.deserializeBinary = function(bytes) {
+  var reader = new jspb.BinaryReader(bytes);
+  var msg = new proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance;
+  return proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.deserializeBinaryFromReader(msg, reader);
+};
+
+
+/**
+ * Deserializes binary data (in protobuf wire format) from the
+ * given reader into the given message object.
+ * @param {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance} msg The message object to deserialize into.
+ * @param {!jspb.BinaryReader} reader The BinaryReader to use.
+ * @return {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.deserializeBinaryFromReader = function(msg, reader) {
+  while (reader.nextField()) {
+    if (reader.isEndGroup()) {
+      break;
+    }
+    var field = reader.getFieldNumber();
+    switch (field) {
+    case 1:
+      var value = /** @type {string} */ (reader.readUint64String());
+      msg.setOwnerBalance(value);
+      break;
+    default:
+      reader.skipField();
+      break;
+    }
+  }
+  return msg;
+};
+
+
+/**
+ * Serializes the message to binary data (in protobuf wire format).
+ * @return {!Uint8Array}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.prototype.serializeBinary = function() {
+  var writer = new jspb.BinaryWriter();
+  proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.serializeBinaryToWriter(this, writer);
+  return writer.getResultBuffer();
+};
+
+
+/**
+ * Serializes the given message to binary data (in protobuf wire
+ * format), writing to the given BinaryWriter.
+ * @param {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance} message
+ * @param {!jspb.BinaryWriter} writer
+ * @suppress {unusedLocalVariables} f is only used for nested messages
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.serializeBinaryToWriter = function(message, writer) {
+  var f = undefined;
+  f = message.getOwnerBalance();
+  if (parseInt(f, 10) !== 0) {
+    writer.writeUint64String(
+      1,
+      f
+    );
+  }
+};
+
+
+/**
+ * optional uint64 owner_balance = 1;
+ * @return {string}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.prototype.getOwnerBalance = function() {
+  return /** @type {string} */ (jspb.Message.getFieldWithDefault(this, 1, "0"));
+};
+
+
+/**
+ * @param {string} value
+ * @return {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance} returns this
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.prototype.setOwnerBalance = function(value) {
+  return jspb.Message.setProto3StringIntField(this, 1, value);
+};
+
+
+
 /**
  * Oneof group definitions for this message. Each group defines the field
  * numbers belonging to that group. When of these fields' value is set, all
@@ -54997,15 +55179,16 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.serializeBi
  * @private {!Array<!Array<number>>}
  * @const
  */
-proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.oneofGroups_ = [[1,2]];
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.oneofGroups_ = [[1,2,4]];
 
 /**
  * @enum {number}
  */
 proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.ResultCase = {
   RESULT_NOT_SET: 0,
   ERROR: 1,
-  PROOF: 2
+  PROOF: 2,
+  SUCCESS_WITH_OWNER_BALANCE: 4
 };
 
 /**
@@ -55048,6 +55231,7 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStat
   var f, obj = {
     error: (f = msg.getError()) && proto.org.dash.platform.dapi.v0.StateTransitionBroadcastError.toObject(includeInstance, f),
     proof: (f = msg.getProof()) && proto.org.dash.platform.dapi.v0.Proof.toObject(includeInstance, f),
+    successWithOwnerBalance: (f = msg.getSuccessWithOwnerBalance()) && proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.toObject(includeInstance, f),
     metadata: (f = msg.getMetadata()) && proto.org.dash.platform.dapi.v0.ResponseMetadata.toObject(includeInstance, f)
   };
 
@@ -55095,6 +55279,11 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStat
       reader.readMessage(value,proto.org.dash.platform.dapi.v0.Proof.deserializeBinaryFromReader);
       msg.setProof(value);
       break;
+    case 4:
+      var value = new proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance;
+      reader.readMessage(value,proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.deserializeBinaryFromReader);
+      msg.setSuccessWithOwnerBalance(value);
+      break;
     case 3:
       var value = new proto.org.dash.platform.dapi.v0.ResponseMetadata;
       reader.readMessage(value,proto.org.dash.platform.dapi.v0.ResponseMetadata.deserializeBinaryFromReader);
@@ -55145,6 +55334,14 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStat
       proto.org.dash.platform.dapi.v0.Proof.serializeBinaryToWriter
     );
   }
+  f = message.getSuccessWithOwnerBalance();
+  if (f != null) {
+    writer.writeMessage(
+      4,
+      f,
+      proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance.serializeBinaryToWriter
+    );
+  }
   f = message.getMetadata();
   if (f != null) {
     writer.writeMessage(
@@ -55230,6 +55427,43 @@ proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStat
 };
 
 
+/**
+ * optional SuccessWithOwnerBalance success_with_owner_balance = 4;
+ * @return {?proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.prototype.getSuccessWithOwnerBalance = function() {
+  return /** @type{?proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance} */ (
+    jspb.Message.getWrapperField(this, proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance, 4));
+};
+
+
+/**
+ * @param {?proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.SuccessWithOwnerBalance|undefined} value
+ * @return {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0} returns this
+*/
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.prototype.setSuccessWithOwnerBalance = function(value) {
+  return jspb.Message.setOneofWrapperField(this, 4, proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.oneofGroups_[0], value);
+};
+
+
+/**
+ * Clears the message field making it undefined.
+ * @return {!proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0} returns this
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.prototype.clearSuccessWithOwnerBalance = function() {
+  return this.setSuccessWithOwnerBalance(undefined);
+};
+
+
+/**
+ * Returns whether this field is set.
+ * @return {boolean}
+ */
+proto.org.dash.platform.dapi.v0.WaitForStateTransitionResultResponse.WaitForStateTransitionResultResponseV0.prototype.hasSuccessWithOwnerBalance = function() {
+  return jspb.Message.getField(this, 4) != null;
+};
+
+
 /**
  * optional ResponseMetadata metadata = 3;
  * @return {?proto.org.dash.platform.dapi.v0.ResponseMetadata}