Require new force_transfer access to do forced transfers. (#1831)

* [1829]: Add ACCESS_FORCE_TRANSFER entry to the Access enum.

* [1829]: Add some clarifications to the access entries.

* [1829]: Check the new force-transfer permission when doing a forced transfer.

* [1829]: Add changelog entry.

* [1892]: Clarify the deposit and withdraw permissions a bit.

CHANGELOG.md

@@ -37,6 +37,15 @@ Ref: https://keepachangelog.com/en/1.0.0/
 
 ## [Unreleased]
 
+### Improvements
+
+* Add new force_transfer access that is required for an account to do a forced transfer ([#1829](https://github.com/provenance-io/provenance/issues/1829)).
+
+### API Breaking
+
+* Accounts that have transfer access in a marker are no longer allowed to do forced transfers ([#1829](https://github.com/provenance-io/provenance/issues/1829)).
+  Accounts must now have the force_transfer access for that.
+
 ### Dependencies
 
 - Bump `codecov/codecov-action` from 3 to 4 ([#1828](https://github.com/provenance-io/provenance/pull/1828))

client/docs/swagger-ui/swagger.yaml

@@ -42452,25 +42452,38 @@ paths:
                           - ACCESS_DELETE
                           - ACCESS_ADMIN
                           - ACCESS_TRANSFER
+                          - ACCESS_FORCE_TRANSFER
                         default: ACCESS_UNSPECIFIED
                         description: >-
                           Access defines the different types of permissions that
                           a marker supports granting to an address.
 
                            - ACCESS_UNSPECIFIED: ACCESS_UNSPECIFIED defines a no-op vote option.
-                           - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker
+                           - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker.
                            - ACCESS_BURN: ACCESS_BURN is the ability to decrease the supply of the marker using coin held by the marker.
-                           - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to set a marker reference to this marker in the metadata/scopes module
-                           - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to remove marker references to this marker in from metadata/scopes or
-                          transfer coin from this marker account to another
-                          account.
-                           - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state. This
-                          access also allows cancelled markers to be marked for
-                          deletion
+                           - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to transfer funds from another account to this marker account
+                          or to set a reference to this marker in the
+                          metadata/scopes module.
+                           - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to transfer funds from this marker account to another account
+                          or to remove a reference to this marker in the
+                          metadata/scopes module.
+                           - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state.
+                          This access also allows cancelled markers to be marked
+                          for deletion.
                            - ACCESS_ADMIN: ACCESS_ADMIN is the ability to add access grants for accounts to the list of marker permissions.
-                           - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to invoke a send operation using the marker module to facilitate exchange.
+                          This access also gives the ability to update the
+                          marker's denom metadata.
+                           - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to manage transfer settings and broker transfers of the marker.
+                          Accounts with this access can:
+                           - Update the marker's required attributes.
+                           - Update the send-deny list.
+                           - Use the transfer or bank send endpoints to move marker funds out of their own account.
                           This access right is only supported on RESTRICTED
                           markers.
+                           - ACCESS_FORCE_TRANSFER: ACCESS_FORCE_TRANSFER is the ability to transfer restricted coins from a 3rd-party account without their signature.
+                          This access right is only supported on RESTRICTED
+                          markers and only has meaning when
+                          allow_forced_transfer is true.
                   description: >-
                     AccessGrant associates a collection of permissions with an
                     address for delegated marker account control.
@@ -97148,22 +97161,32 @@ definitions:
       - ACCESS_DELETE
       - ACCESS_ADMIN
       - ACCESS_TRANSFER
+      - ACCESS_FORCE_TRANSFER
     default: ACCESS_UNSPECIFIED
     description: >-
       Access defines the different types of permissions that a marker supports
       granting to an address.
 
        - ACCESS_UNSPECIFIED: ACCESS_UNSPECIFIED defines a no-op vote option.
-       - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker
+       - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker.
        - ACCESS_BURN: ACCESS_BURN is the ability to decrease the supply of the marker using coin held by the marker.
-       - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to set a marker reference to this marker in the metadata/scopes module
-       - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to remove marker references to this marker in from metadata/scopes or
-      transfer coin from this marker account to another account.
-       - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state. This
-      access also allows cancelled markers to be marked for deletion
+       - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to transfer funds from another account to this marker account
+      or to set a reference to this marker in the metadata/scopes module.
+       - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to transfer funds from this marker account to another account
+      or to remove a reference to this marker in the metadata/scopes module.
+       - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state.
+      This access also allows cancelled markers to be marked for deletion.
        - ACCESS_ADMIN: ACCESS_ADMIN is the ability to add access grants for accounts to the list of marker permissions.
-       - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to invoke a send operation using the marker module to facilitate exchange.
+      This access also gives the ability to update the marker's denom metadata.
+       - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to manage transfer settings and broker transfers of the marker.
+      Accounts with this access can:
+       - Update the marker's required attributes.
+       - Update the send-deny list.
+       - Use the transfer or bank send endpoints to move marker funds out of their own account.
       This access right is only supported on RESTRICTED markers.
+       - ACCESS_FORCE_TRANSFER: ACCESS_FORCE_TRANSFER is the ability to transfer restricted coins from a 3rd-party account without their signature.
+      This access right is only supported on RESTRICTED markers and only has
+      meaning when allow_forced_transfer is true.
   provenance.marker.v1.AccessGrant:
     type: object
     properties:
@@ -97182,22 +97205,34 @@ definitions:
             - ACCESS_DELETE
             - ACCESS_ADMIN
             - ACCESS_TRANSFER
+            - ACCESS_FORCE_TRANSFER
           default: ACCESS_UNSPECIFIED
           description: >-
             Access defines the different types of permissions that a marker
             supports granting to an address.
 
              - ACCESS_UNSPECIFIED: ACCESS_UNSPECIFIED defines a no-op vote option.
-             - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker
+             - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker.
              - ACCESS_BURN: ACCESS_BURN is the ability to decrease the supply of the marker using coin held by the marker.
-             - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to set a marker reference to this marker in the metadata/scopes module
-             - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to remove marker references to this marker in from metadata/scopes or
-            transfer coin from this marker account to another account.
-             - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state. This
-            access also allows cancelled markers to be marked for deletion
+             - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to transfer funds from another account to this marker account
+            or to set a reference to this marker in the metadata/scopes module.
+             - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to transfer funds from this marker account to another account
+            or to remove a reference to this marker in the metadata/scopes
+            module.
+             - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state.
+            This access also allows cancelled markers to be marked for deletion.
              - ACCESS_ADMIN: ACCESS_ADMIN is the ability to add access grants for accounts to the list of marker permissions.
-             - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to invoke a send operation using the marker module to facilitate exchange.
+            This access also gives the ability to update the marker's denom
+            metadata.
+             - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to manage transfer settings and broker transfers of the marker.
+            Accounts with this access can:
+             - Update the marker's required attributes.
+             - Update the send-deny list.
+             - Use the transfer or bank send endpoints to move marker funds out of their own account.
             This access right is only supported on RESTRICTED markers.
+             - ACCESS_FORCE_TRANSFER: ACCESS_FORCE_TRANSFER is the ability to transfer restricted coins from a 3rd-party account without their signature.
+            This access right is only supported on RESTRICTED markers and only
+            has meaning when allow_forced_transfer is true.
     description: >-
       AccessGrant associates a collection of permissions with an address for
       delegated marker account control.
@@ -97320,22 +97355,36 @@ definitions:
                   - ACCESS_DELETE
                   - ACCESS_ADMIN
                   - ACCESS_TRANSFER
+                  - ACCESS_FORCE_TRANSFER
                 default: ACCESS_UNSPECIFIED
                 description: >-
                   Access defines the different types of permissions that a
                   marker supports granting to an address.
 
                    - ACCESS_UNSPECIFIED: ACCESS_UNSPECIFIED defines a no-op vote option.
-                   - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker
+                   - ACCESS_MINT: ACCESS_MINT is the ability to increase the supply of a marker.
                    - ACCESS_BURN: ACCESS_BURN is the ability to decrease the supply of the marker using coin held by the marker.
-                   - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to set a marker reference to this marker in the metadata/scopes module
-                   - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to remove marker references to this marker in from metadata/scopes or
-                  transfer coin from this marker account to another account.
-                   - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state. This
-                  access also allows cancelled markers to be marked for deletion
+                   - ACCESS_DEPOSIT: ACCESS_DEPOSIT is the ability to transfer funds from another account to this marker account
+                  or to set a reference to this marker in the metadata/scopes
+                  module.
+                   - ACCESS_WITHDRAW: ACCESS_WITHDRAW is the ability to transfer funds from this marker account to another account
+                  or to remove a reference to this marker in the metadata/scopes
+                  module.
+                   - ACCESS_DELETE: ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state.
+                  This access also allows cancelled markers to be marked for
+                  deletion.
                    - ACCESS_ADMIN: ACCESS_ADMIN is the ability to add access grants for accounts to the list of marker permissions.
-                   - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to invoke a send operation using the marker module to facilitate exchange.
+                  This access also gives the ability to update the marker's
+                  denom metadata.
+                   - ACCESS_TRANSFER: ACCESS_TRANSFER is the ability to manage transfer settings and broker transfers of the marker.
+                  Accounts with this access can:
+                   - Update the marker's required attributes.
+                   - Update the send-deny list.
+                   - Use the transfer or bank send endpoints to move marker funds out of their own account.
                   This access right is only supported on RESTRICTED markers.
+                   - ACCESS_FORCE_TRANSFER: ACCESS_FORCE_TRANSFER is the ability to transfer restricted coins from a 3rd-party account without their signature.
+                  This access right is only supported on RESTRICTED markers and
+                  only has meaning when allow_forced_transfer is true.
           description: >-
             AccessGrant associates a collection of permissions with an address
             for delegated marker account control.

docs/proto-docs.md

@@ -4125,13 +4125,14 @@ Access defines the different types of permissions that a marker supports grantin
 | Name | Number | Description |
 | ---- | ------ | ----------- |
 | ACCESS_UNSPECIFIED | 0 | ACCESS_UNSPECIFIED defines a no-op vote option. |
-| ACCESS_MINT | 1 | ACCESS_MINT is the ability to increase the supply of a marker |
+| ACCESS_MINT | 1 | ACCESS_MINT is the ability to increase the supply of a marker. |
 | ACCESS_BURN | 2 | ACCESS_BURN is the ability to decrease the supply of the marker using coin held by the marker. |
-| ACCESS_DEPOSIT | 3 | ACCESS_DEPOSIT is the ability to set a marker reference to this marker in the metadata/scopes module |
-| ACCESS_WITHDRAW | 4 | ACCESS_WITHDRAW is the ability to remove marker references to this marker in from metadata/scopes or transfer coin from this marker account to another account. |
-| ACCESS_DELETE | 5 | ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state. This access also allows cancelled markers to be marked for deletion |
-| ACCESS_ADMIN | 6 | ACCESS_ADMIN is the ability to add access grants for accounts to the list of marker permissions. |
-| ACCESS_TRANSFER | 7 | ACCESS_TRANSFER is the ability to invoke a send operation using the marker module to facilitate exchange. This access right is only supported on RESTRICTED markers. |
+| ACCESS_DEPOSIT | 3 | ACCESS_DEPOSIT is the ability to transfer funds from another account to this marker account or to set a reference to this marker in the metadata/scopes module. |
+| ACCESS_WITHDRAW | 4 | ACCESS_WITHDRAW is the ability to transfer funds from this marker account to another account or to remove a reference to this marker in the metadata/scopes module. |
+| ACCESS_DELETE | 5 | ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state. This access also allows cancelled markers to be marked for deletion. |
+| ACCESS_ADMIN | 6 | ACCESS_ADMIN is the ability to add access grants for accounts to the list of marker permissions. This access also gives the ability to update the marker's denom metadata. |
+| ACCESS_TRANSFER | 7 | ACCESS_TRANSFER is the ability to manage transfer settings and broker transfers of the marker. Accounts with this access can: - Update the marker's required attributes. - Update the send-deny list. - Use the transfer or bank send endpoints to move marker funds out of their own account. This access right is only supported on RESTRICTED markers. |
+| ACCESS_FORCE_TRANSFER | 8 | ACCESS_FORCE_TRANSFER is the ability to transfer restricted coins from a 3rd-party account without their signature. This access right is only supported on RESTRICTED markers and only has meaning when allow_forced_transfer is true. |
 
 
  <!-- end enums -->

proto/provenance/marker/v1/accessgrant.proto

@@ -26,21 +26,30 @@ message AccessGrant {
 enum Access {
   // ACCESS_UNSPECIFIED defines a no-op vote option.
   ACCESS_UNSPECIFIED = 0 [(gogoproto.enumvalue_customname) = "Unknown"];
-  // ACCESS_MINT is the ability to increase the supply of a marker
+  // ACCESS_MINT is the ability to increase the supply of a marker.
   ACCESS_MINT = 1 [(gogoproto.enumvalue_customname) = "Mint"];
   // ACCESS_BURN is the ability to decrease the supply of the marker using coin held by the marker.
   ACCESS_BURN = 2 [(gogoproto.enumvalue_customname) = "Burn"];
-  // ACCESS_DEPOSIT is the ability to set a marker reference to this marker in the metadata/scopes module
+  // ACCESS_DEPOSIT is the ability to transfer funds from another account to this marker account
+  // or to set a reference to this marker in the metadata/scopes module.
   ACCESS_DEPOSIT = 3 [(gogoproto.enumvalue_customname) = "Deposit"];
-  // ACCESS_WITHDRAW is the ability to remove marker references to this marker in from metadata/scopes or
-  // transfer coin from this marker account to another account.
+  // ACCESS_WITHDRAW is the ability to transfer funds from this marker account to another account
+  // or to remove a reference to this marker in the metadata/scopes module.
   ACCESS_WITHDRAW = 4 [(gogoproto.enumvalue_customname) = "Withdraw"];
-  // ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state. This
-  // access also allows cancelled markers to be marked for deletion
+  // ACCESS_DELETE is the ability to move a proposed, finalized or active marker into the cancelled state.
+  // This access also allows cancelled markers to be marked for deletion.
   ACCESS_DELETE = 5 [(gogoproto.enumvalue_customname) = "Delete"];
   // ACCESS_ADMIN is the ability to add access grants for accounts to the list of marker permissions.
+  // This access also gives the ability to update the marker's denom metadata.
   ACCESS_ADMIN = 6 [(gogoproto.enumvalue_customname) = "Admin"];
-  // ACCESS_TRANSFER is the ability to invoke a send operation using the marker module to facilitate exchange.
+  // ACCESS_TRANSFER is the ability to manage transfer settings and broker transfers of the marker.
+  // Accounts with this access can:
+  //  - Update the marker's required attributes.
+  //  - Update the send-deny list.
+  //  - Use the transfer or bank send endpoints to move marker funds out of their own account.
   // This access right is only supported on RESTRICTED markers.
   ACCESS_TRANSFER = 7 [(gogoproto.enumvalue_customname) = "Transfer"];
+  // ACCESS_FORCE_TRANSFER is the ability to transfer restricted coins from a 3rd-party account without their signature.
+  // This access right is only supported on RESTRICTED markers and only has meaning when allow_forced_transfer is true.
+  ACCESS_FORCE_TRANSFER = 8 [(gogoproto.enumvalue_customname) = "ForceTransfer"];
 }