feat!: Add support for credit cancelling (#385)

CHANGELOG.md

@@ -7,6 +7,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
+* add support for credit cancelling (#385)
 * record retirement locations of ecocredit (#328)
 
 ## [1.0.0] - 2021-04-13

docs/modules/ecocredit/README.md

@@ -13,31 +13,32 @@ be your guide!
 
 ### Ecocredit Transactions
 
-```sh 
+```sh
 $ regen tx ecocredit --help
 # Ecocredit module transactions
-# 
+#
 # Usage:
 #   regen tx ecocredit [flags]
 #   regen tx ecocredit [command]
-# 
+#
 # Available Commands:
+#   cancel        Cancels a specified amount of credits from the account of the transaction author (--from)
 #   create_batch  Issues a new credit batch
 #   create_class  Creates a new credit class
-#   retire        Retires a specified amounts of credits from the account of the transaction author (--from)
+#   retire        Retires a specified amount of credits from the account of the transaction author (--from)
 #   send          Sends credits from the transaction author (--from) to the recipient
 #   set_precision Allows an issuer to increase the decimal precision of a credit batch
 ```
 ### Ecocredit Queries
 
-```sh 
+```sh
 $ regen q ecocredit --help
 # Query commands for the ecocredit module
-# 
+#
 # Usage:
 #   regen query ecocredit [flags]
 #   regen query ecocredit [command]
-# 
+#
 # Available Commands:
 #   balance     Retrieve the tradable and retired balances of the credit batch
 #   batch_info  Retrieve the credit issuance batch info

go.mod

@@ -18,7 +18,7 @@ require (
 	github.com/tendermint/tendermint v0.34.11
 	github.com/tendermint/tm-db v0.6.4
 	golang.org/x/crypto v0.0.0-20210616213533-5ff15b29337e // indirect
-	google.golang.org/genproto v0.0.0-20210629200056-84d6f6074151 // indirect
+	google.golang.org/genproto v0.0.0-20210701191553-46259e63a0a9 // indirect
 )
 
 replace google.golang.org/grpc => google.golang.org/grpc v1.33.2

go.sum

@@ -1234,8 +1234,8 @@ google.golang.org/genproto v0.0.0-20210310155132-4ce2db91004e/go.mod h1:FWY/as6D
 google.golang.org/genproto v0.0.0-20210319143718-93e7006c17a6/go.mod h1:FWY/as6DDZQgahTzZj3fqbO1CbirC29ZNUFHwi0/+no=
 google.golang.org/genproto v0.0.0-20210402141018-6c239bbf2bb1/go.mod h1:9lPAdzaEmUacj36I+k7YKbEc5CXzPIeORRgDAUOu28A=
 google.golang.org/genproto v0.0.0-20210602131652-f16073e35f0c/go.mod h1:UODoCrxHCcBojKKwX1terBiRUaqAsFqJiF615XL43r0=
-google.golang.org/genproto v0.0.0-20210629200056-84d6f6074151 h1:H/uPzsolsGjhl3CVT6Wb7bK+mf+hmkEvUVu+FBKyNlc=
-google.golang.org/genproto v0.0.0-20210629200056-84d6f6074151/go.mod h1:yiaVoXHpRzHGyxV3o4DktVWY4mSUErTKaeEOq6C3t3U=
+google.golang.org/genproto v0.0.0-20210701191553-46259e63a0a9 h1:HBPuvo39L0DgfVn9eHR3ki/RjZoUFWa+em77e7KFDfs=
+google.golang.org/genproto v0.0.0-20210701191553-46259e63a0a9/go.mod h1:yiaVoXHpRzHGyxV3o4DktVWY4mSUErTKaeEOq6C3t3U=
 google.golang.org/grpc v1.33.2 h1:EQyQC3sa8M+p6Ulc8yy9SWSS2GVwyRc83gAbG8lrl4o=
 google.golang.org/grpc v1.33.2/go.mod h1:JMHMWHQWaTccqQQlmk3MJZS+GWXOdAesneDmEnv2fbc=
 google.golang.org/protobuf v0.0.0-20200109180630-ec00e32a8dfd/go.mod h1:DFci5gLYBciE7Vtevhsrf46CRTquxDuWsQurQQe4oz8=

proto/regen/ecocredit/v1alpha1/events.proto

@@ -28,8 +28,8 @@ message EventCreateBatch {
   // issuer is the account address of the issuer of the credit batch.
   string issuer = 3;
 
-  // total_units is the total number of units in the credit batch.
-  string total_units = 4 [ (gogoproto.moretags) = "yaml:\"total_units\"" ];
+  // total_amount is the total number of credits in the credit batch.
+  string total_amount = 4 [ (gogoproto.moretags) = "yaml:\"total_amount\"" ];
 }
 
 // EventReceive is an event emitted when credits are received either upon
@@ -47,13 +47,13 @@ message EventReceive {
   // batch_denom is the unique ID of credit batch.
   string batch_denom = 3 [ (gogoproto.moretags) = "yaml:\"batch_denom\"" ];
 
-  // units is the decimal number of both tradable and retired credits received.
-  string units = 4;
+  // amount is the decimal number of both tradable and retired credits received.
+  string amount = 4;
 }
 
-// EventRetire is an event emitted when credits are retired. An separate event
-// is emitted for each batch_denom in the case where credits from multiple
-// batches have been retired at once for easy indexing.
+// EventRetire is an event emitted when credits are retired. When credits are
+// retired from multiple batches in the same transaction, a separate event is
+// emitted for each batch_denom. This allows for easier indexing.
 message EventRetire {
 
   // retirer is the account which has done the "retiring". This will be the
@@ -64,8 +64,8 @@ message EventRetire {
   // batch_denom is the unique ID of credit batch.
   string batch_denom = 2 [ (gogoproto.moretags) = "yaml:\"batch_denom\"" ];
 
-  // units is the decimal number of credits that have been retired.
-  string units = 3;
+  // amount is the decimal number of credits that have been retired.
+  string amount = 3;
 
   // location is the location of the beneficiary or buyer of the retired
   // credits. It is a string of the form
@@ -74,3 +74,19 @@ message EventRetire {
   // alphanumeric characters.
   string location = 4;
 }
+
+// EventCancel is an event emitted when credits are cancelled. When credits are
+// cancelled from multiple batches in the same transaction, a separate event is
+// emitted for each batch_denom. This allows for easier indexing.
+message EventCancel {
+
+  // canceller is the account which has cancelled the credits, which should be
+  // the holder of the credits.
+  string canceller = 1;
+
+  // batch_denom is the unique ID of credit batch.
+  string batch_denom = 2 [ (gogoproto.moretags) = "yaml:\"batch_denom\"" ];
+
+  // amount is the decimal number of credits that have been cancelled.
+  string amount = 3;
+}

proto/regen/ecocredit/v1alpha1/query.proto

@@ -23,7 +23,7 @@ service Query {
   rpc Supply(QuerySupplyRequest) returns (QuerySupplyResponse);
 
   // Precision queries the number of decimal places that can be used to
-  // represent credit batch units. See Tx/SetPrecision for more details.
+  // represent credits in a batch. See Tx/SetPrecision for more details.
   rpc Precision(QueryPrecisionRequest) returns (QueryPrecisionResponse);
 }
 
@@ -68,12 +68,12 @@ message QueryBalanceRequest {
 // QueryBalanceResponse is the Query/Balance response type.
 message QueryBalanceResponse {
 
-  // tradable_units is the decimal number of tradable units.
-  string tradable_units = 1
-      [ (gogoproto.moretags) = "yaml:\"tradable_units\"" ];
+  // tradable_amount is the decimal number of tradable credits.
+  string tradable_amount = 1
+      [ (gogoproto.moretags) = "yaml:\"tradable_amount\"" ];
 
-  // retired_units is the decimal number of retired units.
-  string retired_units = 2 [ (gogoproto.moretags) = "yaml:\"retired_units\"" ];
+  // retired_amount is the decimal number of retired credits.
+  string retired_amount = 2 [ (gogoproto.moretags) = "yaml:\"retired_amount\"" ];
 }
 
 // QuerySupplyRequest is the Query/Supply request type.
@@ -86,11 +86,11 @@ message QuerySupplyRequest {
 // QuerySupplyResponse is the Query/Supply response type.
 message QuerySupplyResponse {
 
-  // tradable_units is the decimal number of tradable units in the batch supply.
+  // tradable_supply is the decimal number of tradable credits in the batch supply.
   string tradable_supply = 1
       [ (gogoproto.moretags) = "yaml:\"tradable_supply\"" ];
 
-  // retired_supply is the decimal number of retired units in the batch supply.
+  // retired_supply is the decimal number of retired credits in the batch supply.
   string retired_supply = 2
       [ (gogoproto.moretags) = "yaml:\"retired_supply\"" ];
 }
@@ -106,7 +106,7 @@ message QueryPrecisionRequest {
 message QueryPrecisionResponse {
 
   // max_decimal_places is the maximum number of decimal places that can be used
-  // to represent some quantity of credit units. It is an experimental feature
+  // to represent some quantity of credits. It is an experimental feature
   // to concretely explore an idea proposed in
   // https://github.com/cosmos/cosmos-sdk/issues/7113.
   uint32 max_decimal_places = 1

proto/regen/ecocredit/v1alpha1/tx.proto

@@ -25,6 +25,11 @@ service Msg {
   // Retire retires a specified number of credits in the holder's account.
   rpc Retire(MsgRetireRequest) returns (MsgRetireResponse);
 
+  // Cancel removes a number of credits from the holder's account and also
+  // deducts them from the tradable supply, effectively cancelling their
+  // issuance on Regen Ledger
+  rpc Cancel(MsgCancelRequest) returns (MsgCancelResponse);
+
   // SetPrecision allows an issuer to increase the decimal precision of a credit
   // batch. It is an experimental feature to concretely explore an idea proposed
   // in https://github.com/cosmos/cosmos-sdk/issues/7113. The number of decimal
@@ -92,19 +97,19 @@ message MsgCreateBatchRequest {
     // recipient is the account of the recipient.
     string recipient = 1;
 
-    // tradable_units are the units of credits in this issuance that can be
+    // tradable_amount is the number of credits in this issuance that can be
     // traded by this recipient. Decimal values are acceptable.
-    string tradable_units = 2
-        [ (gogoproto.moretags) = "yaml:\"tradable_units\"" ];
+    string tradable_amount = 2
+        [ (gogoproto.moretags) = "yaml:\"tradable_amount\"" ];
 
-    // retired_units are the units of credits in this issuance that are
+    // retired_amount is the number of credits in this issuance that are
     // effectively retired by the issuer on receipt. Decimal values are
     // acceptable.
-    string retired_units = 3
-        [ (gogoproto.moretags) = "yaml:\"retired_units\"" ];
+    string retired_amount = 3
+        [ (gogoproto.moretags) = "yaml:\"retired_amount\"" ];
 
     // retirement_location is the location of the beneficiary or buyer of the
-    // retired credits. This must be provided if retired_units is positive. It
+    // retired credits. This must be provided if retired_amount is positive. It
     // is a string of the form
     // <country-code>[-<sub-national-code>[ <postal-code>]], with the first two
     // fields conforming to ISO 3166-2, and postal-code being up to 64
@@ -131,28 +136,30 @@ message MsgSendRequest {
   string recipient = 2;
 
   // credits are the credits being sent.
-  repeated SendUnits credits = 3;
+  repeated SendCredits credits = 3;
 
-  // SendUnits are the tradable and retired units of a credit batch to send.
-  message SendUnits {
+  // SendCredits specifies a batch and the number of credits being transferred.
+  // This is split into tradable credits, which will remain tradable on receipt,
+  // and retired credits, which will be retired on receipt.
+  message SendCredits {
 
     // batch_denom is the unique ID of the credit batch.
     string batch_denom = 1 [ (gogoproto.moretags) = "yaml:\"batch_denom\"" ];
 
-    // tradable_units are the units of credits in this issuance that can be
-    // traded by this recipient. Decimal values are acceptable within the
+    // tradable_amount is the number of credits in this transfer that can be
+    // traded by the recipient. Decimal values are acceptable within the
     // precision returned by Query/Precision.
-    string tradable_units = 2
-        [ (gogoproto.moretags) = "yaml:\"tradable_units\"" ];
+    string tradable_amount = 2
+        [ (gogoproto.moretags) = "yaml:\"tradable_amount\"" ];
 
-    // retired_units are the units of credits in this transfer that are
-    // effectively retired by the recipient on receipt. Decimal values are
+    // retired_amount is the number of credits in this transfer that are
+    // effectively retired by the issuer on receipt. Decimal values are
     // acceptable within the precision returned by Query/Precision.
-    string retired_units = 3
-        [ (gogoproto.moretags) = "yaml:\"retired_units\"" ];
+    string retired_amount = 3
+        [ (gogoproto.moretags) = "yaml:\"retired_amount\"" ];
 
     // retirement_location is the location of the beneficiary or buyer of the
-    // retired credits. This must be provided if retired_units is positive. It
+    // retired credits. This must be provided if retired_amount is positive. It
     // is a string of the form
     // <country-code>[-<sub-national-code>[ <postal-code>]], with the first two
     // fields conforming to ISO 3166-2, and postal-code being up to 64
@@ -172,18 +179,18 @@ message MsgRetireRequest {
   string holder = 1;
 
   // credits are the credits being retired.
-  repeated RetireUnits credits = 2;
+  repeated RetireCredits credits = 2;
 
-  // RetireUnits are the units of the batch being retired.
-  message RetireUnits {
+  // RetireCredits specifies a batch and the number of credits being retired.
+  message RetireCredits {
 
     // batch_denom is the unique ID of the credit batch.
     string batch_denom = 1 [ (gogoproto.moretags) = "yaml:\"batch_denom\"" ];
 
-    // retired_units are the units of credits being retired.
+    // amount is the number of credits being retired.
     // Decimal values are acceptable within the precision returned by
     // Query/Precision.
-    string units = 2;
+    string amount = 2;
   }
 
   // location is the location of the beneficiary or buyer of the retired
@@ -197,6 +204,31 @@ message MsgRetireRequest {
 // MsgRetireRequest is the Msg/Retire response type.
 message MsgRetireResponse {}
 
+// MsgCancelRequest is the Msg/Cancel request type.
+message MsgCancelRequest {
+
+  // holder is the credit holder address.
+  string holder = 1;
+
+  // credits are the credits being cancelled.
+  repeated CancelCredits credits = 2;
+
+  // CancelCredits specifies a batch and the number of credits being cancelled.
+  message CancelCredits {
+
+    // batch_denom is the unique ID of the credit batch.
+    string batch_denom = 1 [ (gogoproto.moretags) = "yaml:\"batch_denom\"" ];
+
+    // amount is the number of credits being cancelled.
+    // Decimal values are acceptable within the precision returned by
+    // Query/Precision.
+    string amount = 2;
+  }
+}
+
+// MsgCancelResponse is the Msg/Cancel response type.
+message MsgCancelResponse {}
+
 // MsgRetireRequest is the Msg/SetPrecision request type.
 message MsgSetPrecisionRequest {
 
@@ -207,7 +239,7 @@ message MsgSetPrecisionRequest {
   string batch_denom = 2 [ (gogoproto.moretags) = "yaml:\"batch_denom\"" ];
 
   // max_decimal_places is the new maximum number of decimal places that can be
-  // used to represent some quantity of credit units. It is an experimental
+  // used to represent some quantity of credits. It is an experimental
   // feature to concretely explore an idea proposed in
   // https://github.com/cosmos/cosmos-sdk/issues/7113.
   uint32 max_decimal_places = 3

proto/regen/ecocredit/v1alpha1/types.proto

@@ -35,12 +35,21 @@ message BatchInfo {
   // issuer is the issuer of the credit batch.
   string issuer = 3;
 
-  // total_units is the total number of units in the credit batch and is
-  // immutable.
-  string total_units = 4 [ (gogoproto.moretags) = "yaml:\"total_units\"" ];
+  // total_amount is the total number of active credits in the credit batch.
+  // Some of the issued credits may be cancelled and will be removed from
+  // total_amount and tracked in amount_cancelled. total_amount and
+  // amount_cancelled will always sum to the original amount of credits that
+  // were issued.
+  string total_amount = 4 [ (gogoproto.moretags) = "yaml:\"total_amount\"" ];
 
   // metadata is any arbitrary metadata to attached to the credit batch.
   bytes metadata = 5;
+
+  // amount_cancelled is the number of credits in the batch that have been
+  // cancelled, effectively undoing there issuance. The sum of total_amount and
+  // amount_cancelled will always sum to the original amount of credits that
+  // were issued.
+  string amount_cancelled = 6;
 }
 
 // Params defines the updatable global parameters of the ecocredit module for