Eco-credit Module Proof of Concept Init (#125)

* Add proto files

* docs

* Update proto/regen/ecocredit/v1alpha1/tx.proto

Co-authored-by: Marie Gauthier <marie.gauthier63@gmail.com>

* update docs

* docs

* proto-gen

* lint

* Update proto/regen/ecocredit/v1alpha1/tx.proto

Co-authored-by: Robert Zaremba <robert@zaremba.ch>

* Update proto/regen/ecocredit/v1alpha1/events.proto

Co-authored-by: Cory <cjlevinson@gmail.com>

* Update proto/regen/ecocredit/v1alpha1/tx.proto

Co-authored-by: Robert Zaremba <robert@zaremba.ch>

* docs

Co-authored-by: Marie Gauthier <marie.gauthier63@gmail.com>
Co-authored-by: Robert Zaremba <robert@zaremba.ch>
Co-authored-by: Cory <cjlevinson@gmail.com>

proto/regen/ecocredit/v1alpha1/events.proto

@@ -0,0 +1,75 @@
+syntax = "proto3";
+
+package regen.ecocredit.v1alpha1;
+
+option go_package = "github.com/regen-network/regen-ledger/x/ecocredit";
+
+// EventCreateClass is an event emitted when a credit class is created.
+message EventCreateClass {
+
+    // class_id is the unique ID of credit class.
+    string class_id = 1;
+
+    // designer is the designer of the credit class.
+    string designer = 2;
+}
+
+// EventCreateBatch is an event emitted when a credit batch is created.
+message EventCreateBatch {
+
+    // class_id is the unique ID of credit class.
+    string class_id = 1;
+
+    // batch_denom is the unique ID of credit batch.
+    string batch_denom = 2;
+
+    // issuer_address is the account address of the issuer of the credit batch.
+    string issuer_address = 3;
+
+    // total_units is the total number of units in the credit batch.
+    string total_units = 4;
+}
+
+// EventReceive is an event emitted when credits are received either upon
+// creation of a new batch or upon transfer. Each batch_denom created or
+// transferred will result in a separate EventReceive for easy indexing.
+message EventReceive {
+
+    // from indicates the originator of the credits - either an issuer (in the case of Msg/CreateBatch) or a
+    // sender (in the case of Msg/Send).
+    oneof from {
+        // issuer is the issuer of the credit batch in the case that this event is the result of a new batch being created.
+        // It will not be set if credits were transferred.
+        string issuer = 1;
+
+        // sender is the sender of the credits in the case that this event is the result of a transfer.
+        // It will not be set if credits were issued.
+        string sender = 2;
+    }
+
+    // recipient is the recipient of the credits
+    string recipient = 3;
+
+    // batch_denom is the unique ID of credit batch.
+    string batch_denom = 4;
+
+    // units is the decimal number of both tradable and retired credits received.
+    string units = 5;
+}
+
+// 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.
+message EventRetire {
+
+    // retirer is the account which has done the "retiring". This will be the account receiving credits in
+    // the case that credits were retired upon issuance using Msg/CreateBatch or retired upon transfer
+    // using Msg/Send.
+    string retirer = 1;
+
+    // batch_denom is the unique ID of credit batch.
+    string batch_denom = 2;
+
+    // units is the decimal number of credits that have been retired.
+    string units = 3;
+}

proto/regen/ecocredit/v1alpha1/query.proto

@@ -0,0 +1,107 @@
+syntax = "proto3";
+
+package regen.ecocredit.v1alpha1;
+
+import "regen/ecocredit/v1alpha1/types.proto";
+
+option go_package = "github.com/regen-network/regen-ledger/x/ecocredit";
+
+// Msg is the regen.ecocredit.v1alpha1 Query service.
+service Query {
+    // ClassInfo queries for information on a credit class.
+    rpc ClassInfo(QueryClassInfoRequest) returns (QueryClassInfoResponse);
+
+    // BatchInfo queries for information on a credit batch.
+    rpc BatchInfo(QueryBatchInfoRequest) returns (QueryBatchInfoResponse);
+
+    // Balance queries the balance (both tradable and retired) of a given credit batch for a given account.
+    rpc Balance(QueryBalanceRequest) returns (QueryBalanceResponse);
+
+    // Supply queries the tradable and retired supply of a credit batch.
+    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.
+    rpc Precision(QueryPrecisionRequest) returns (QueryPrecisionResponse);
+}
+
+// QueryClassInfoRequest is the Query/ClassInfo request type.
+message QueryClassInfoRequest {
+
+    // class_id is the unique ID of credit class to query.
+    string class_id = 1;
+}
+
+// QueryClassInfoResponse is the Query/ClassInfo request type.
+message QueryClassInfoResponse {
+
+    // info is the ClassInfo for the credit class.
+    ClassInfo info = 1;
+}
+
+// QueryBatchInfoRequest is the Query/BatchInfo request type.
+message QueryBatchInfoRequest {
+
+    // batch_denom is the unique ID of credit batch to query.
+    string batch_denom = 1;
+}
+
+// QueryBatchInfoResponse is the Query/BatchInfo response type.
+message QueryBatchInfoResponse {
+
+    // info is the BatchInfo for the credit batch.
+    BatchInfo info = 1;
+}
+
+// QueryBalanceRequest is the Query/Balance request type.
+message QueryBalanceRequest {
+
+    // account is the address of the account whose balance is being queried.
+    string account = 1;
+
+    // batch_denom is the unique ID of credit batch balance to query.
+    string batch_denom = 2;
+}
+
+// QueryBalanceResponse is the Query/Balance response type.
+message QueryBalanceResponse {
+
+    // tradable_units is the decimal number of tradable units.
+    string tradable_units = 1;
+
+    // retired_units is the decimal number of retired units.
+    string retired_units = 2;
+}
+
+// QuerySupplyRequest is the Query/Supply request type.
+message QuerySupplyRequest {
+
+    // batch_denom is the unique ID of credit batch to query.
+    string batch_denom = 1;
+}
+
+// QuerySupplyResponse is the Query/Supply response type.
+message QuerySupplyResponse {
+
+    // tradable_units is the decimal number of tradable units in the batch supply.
+    string tradable_supply = 1;
+
+    // retired_supply is the decimal number of retired units in the batch supply.
+    string retired_supply = 2;
+}
+
+
+// QueryPrecisionRequest is the Query/Precision request type.
+message QueryPrecisionRequest {
+
+    // batch_denom is the unique ID of credit batch to query.
+    string batch_denom = 1;
+}
+
+// QueryPrecisionResponse is the Query/Precision response type.
+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 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

@@ -0,0 +1,167 @@
+syntax = "proto3";
+
+package regen.ecocredit.v1alpha1;
+
+option go_package = "github.com/regen-network/regen-ledger/x/ecocredit";
+
+// Msg is the regen.ecocredit.v1alpha1 Msg service.
+service Msg {
+
+    // CreateClass creates a new credit class with an approved list of issuers and optional metadata.
+    rpc CreateClass(MsgCreateClassRequest) returns (MsgCreateClassResponse);
+
+    // CreateBatch creates a new batch of credits for an existing credit class. This will create a new batch denom
+    // with a fixed supply. Issued credits can be distributed to recipients in either tradable or retired form.
+    rpc CreateBatch(MsgCreateBatchRequest) returns (MsgCreateBatchResponse);
+
+    // Send sends tradeable credits from one account to another account. Sent credits can either be tradable or retired on receipt.
+    rpc Send(MsgSendRequest) returns (MsgSendResponse);
+
+    // Retire retires a specified number of credits in the holder's account.
+    rpc Retire(MsgRetireRequest) returns (MsgRetireResponse);
+
+    // 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
+    // places allowed for a credit batch is determined by the original number of decimal places used with calling CreatBatch.
+    // SetPrecision allows the number of allowed decimal places to be increased, effectively making the supply more
+    // granular without actually changing any balances. It allows asset issuers to be able to issue an asset without needing
+    // to think about how many subdivisions are needed upfront. While it may not be relevant for credits which likely have
+    // a fairly stable market value, I wanted to experiment a bit and this serves as a proof of concept for a broader
+    // bank redesign where say for instance a coin like the ATOM or XRN could be issued in its own units rather than
+    // micro or nano-units. Instead an operation like SetPrecision would allow trading in micro, nano or pico in the future
+    // based on market demand. Arbitrary, unbounded precision is not desirable because this can lead to spam attacks (like
+    // sending 0.000000000000000000000000000001 coins). This is effectively fixed precision so under the hood it is still
+    // basically an integer, but the fixed precision can be increased so its more adaptable long term than just an integer.
+    rpc SetPrecision(MsgSetPrecisionRequest) returns (MsgSetPrecisionResponse);
+}
+
+// MsgCreateClassRequest is the Msg/CreateClass request type.
+message MsgCreateClassRequest {
+
+    // designer is the address of the account which designed the credit class. The designer has special permissions
+    // to change the list of issuers and perform other administrative operations.
+    string designer = 1;
+
+    // issuers are the account addresses of the approved issuers.
+    repeated string issuers = 2;
+
+    // metadata is any arbitrary metadata to attached to the credit class.
+    bytes metadata = 3;
+}
+
+// MsgCreateClassResponse is the Msg/CreateClass response type.
+message MsgCreateClassResponse {
+
+    // class_id is the unique ID of the newly created credit class.
+    string class_id = 1;
+}
+
+// MsgCreateBatchRequest is the Msg/CreateBatch request type.
+message MsgCreateBatchRequest {
+
+    // issuer is the address of the batch issuer.
+    string issuer = 1;
+
+    // class_id is the unique ID of the class.
+    string class_id = 2;
+
+    // issuance are the credits issued in the batch.
+    repeated BatchIssuance issuance = 3;
+
+    // metadata is any arbitrary metadata to attached to the credit batch.
+    bytes metadata = 4;
+
+    // BatchIssuance represents the issuance of some credits in a batch to a single recipient.
+    message BatchIssuance {
+
+        // recipient is the account of the recipient.
+        string recipient = 1;
+
+        // tradable_units are the units of credits in this issuance that can be traded by this recipient.
+        // Decimal values are acceptable.
+        string tradable_units = 2;
+
+        // retired_units are the units of credits in this issuance that are effectively retired by the issuer on receipt.
+        // Decimal values are acceptable.
+        string retired_units = 3;
+    }
+}
+
+// MsgCreateBatchResponse is the Msg/CreateBatch response type.
+message MsgCreateBatchResponse {
+
+    // batch_denom is the unique denomination ID of the newly created batch.
+    string batch_denom = 1;
+}
+
+// MsgSendRequest is the Msg/Send request type.
+message MsgSendRequest {
+
+    // sender is the address of the account sending credits.
+    string sender = 1;
+
+    // sender is the address of the account receiving credits.
+    string recipient = 2;
+
+    // credits are the credits being sent.
+    repeated SendUnits credits = 3;
+
+    // SendUnits are the tradable and retired units of a credit batch to send.
+    message SendUnits {
+
+        // batch_denom is the unique ID of the credit batch.
+        string batch_denom = 1;
+
+        // tradable_units are the units of credits in this issuance that can be traded by this recipient.
+        // Decimal values are acceptable within the precision returned by Query/Precision.
+        string tradeable_units = 2;
+
+        // retired_units are the units of credits in this issuance that are effectively retired by the issuer on receipt.
+        // Decimal values are acceptable within the precision returned by Query/Precision.
+        string retired_units = 3;
+    }
+}
+
+// MsgSendResponse is the Msg/Send response type.
+message MsgSendResponse { }
+
+// MsgRetireRequest is the Msg/Retire request type.
+message MsgRetireRequest {
+
+    // holder is the credit holder address.
+    string holder = 1;
+
+    // credits are the credits being retired.
+    repeated RetireUnits credits = 2;
+
+    // RetireUnits are the units of the batch being retired.
+    message RetireUnits {
+
+        // batch_denom is the unique ID of the credit batch.
+        string batch_denom = 1;
+
+        // retired_units are the units of credits being retired.
+        // Decimal values are acceptable within the precision returned by Query/Precision.
+        string units = 2;
+    }
+}
+
+// MsgRetireRequest is the Msg/Retire response type.
+message MsgRetireResponse { }
+
+// MsgRetireRequest is the Msg/SetPrecision request type.
+message MsgSetPrecisionRequest {
+
+    // issuer is the address of the batch issuer.
+    string issuer = 1;
+
+    // batch_denom is the unique ID of the credit batch.
+    string batch_denom = 2;
+
+    // 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 feature to concretely explore an idea proposed in https://github.com/cosmos/cosmos-sdk/issues/7113.
+    uint32 max_decimal_places = 3;
+}
+
+// MsgRetireRequest is the Msg/SetPrecision response type.
+message MsgSetPrecisionResponse { }

proto/regen/ecocredit/v1alpha1/types.proto

@@ -0,0 +1,40 @@
+syntax = "proto3";
+
+package regen.ecocredit.v1alpha1;
+
+option go_package = "github.com/regen-network/regen-ledger/x/ecocredit";
+
+// ClassInfo represents the high-level on-chain information for a credit class.
+message ClassInfo {
+
+    // class_id is the unique ID of credit class.
+    string class_id = 1;
+
+    // designer is the designer of the credit class.
+    string designer = 2;
+
+    // issuers are the approved issuers of the credit class.
+    repeated string issuers = 3;
+
+    // metadata is any arbitrary metadata to attached to the credit class.
+    bytes metadata = 4;
+}
+
+// BatchInfo represents the high-level on-chain information for a credit batch.
+message BatchInfo {
+
+    // class_id is the unique ID of credit class.
+    string class_id = 1;
+
+    // batch_denom is the unique ID of credit batch.
+    string batch_denom = 2;
+
+    // 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;
+
+    // metadata is any arbitrary metadata to attached to the credit batch.
+    bytes metadata = 5;
+}