feat(x/ecocredit): forward contract proof-of-concept

proto/regen/ecocredit/contract/v1alpha1/doc.proto

@@ -0,0 +1,10 @@
+syntax = "proto3";
+
+// regen.contract.v1alpha1 describes the API for the contract submodule.
+//
+// The following outlines revisions and tagged versions of the compiled code in
+// relation to tagged releases in regen-network/regen-ledger:
+//
+// - Revision 0: (in progress)
+//
+package regen.ecocredit.contract.v1alpha1;

proto/regen/ecocredit/contract/v1alpha1/state.proto

@@ -0,0 +1,83 @@
+syntax = "proto3";
+
+package regen.ecocredit.contract.v1alpha1;
+
+import "cosmos/base/v1beta1/coin.proto";
+import "cosmos/orm/v1/orm.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+import "regen/ecocredit/contract/v1alpha1/types.proto";
+
+// Contract defines a forward contract and the forward contract table.
+message Contract {
+  option (cosmos.orm.v1.table) = {
+    id : 1,
+    primary_key : {fields : "id", auto_increment : true}
+  };
+
+  // id is the table row identifier of the contract.
+  uint64 id = 1;
+
+  // project_id is the unique identifier of the project.
+  string project_id = 2;
+
+  // status is the status of the contract (e.g. "proposed", "approved").
+  Status status = 3;
+
+  // metadata is any arbitrary string that includes or references additional
+  // information about the contract such as calculations made to determine
+  // the volume of credits and the price per credit.
+  string metadata = 4;
+
+  // price is the token denomination and amount the project is asking for
+  // per credit.
+  cosmos.base.v1beta1.Coin price = 5;
+
+  // amount is the amount of future credits issued that are available to
+  // purchase. The amount will decrease with each investment, therefore
+  // representing the remaining amount of credits available.
+  string amount = 6;
+
+  // volume_percentage is the percentage of future credits issued that was
+  // made available to purchase. The volume percentage is used to determine
+  // the percentage of future credits issued in each credit issuance based
+  // on the amount of credits purchased by an investor.
+  string volume_percentage = 7;
+
+  // start_date is the contract start date.
+  google.protobuf.Timestamp start_date = 8;
+
+  // end_date is the contract end date.
+  google.protobuf.Timestamp end_date = 9;
+
+  // buffer_window is the duration after the end date in which credits may
+  // still be issued with a monitoring period that falls within the start
+  // and end date of the contract. The credits held in the reserve pool are
+  // not distributed or returned until end date + buffer window.
+  google.protobuf.Duration buffer_window = 10;
+}
+
+// ContractReserve defines a forward contract reserve (aka "buffer pool")
+// and the table within which forward contract reserves are stored.
+message ContractReserve {
+  option (cosmos.orm.v1.table) = {
+    id : 2,
+    primary_key : {fields : "contract_id"}
+  };
+
+  // contract_id is the table row identifier of the contract.
+  uint64 contract_id = 1;
+
+  // balances is the list of credit batch balances held in the reserve.
+  repeated Balance balances = 2;
+
+  // Balance defines a balance of credits held in the reserve.
+  message Balance {
+
+    // batch_denom is the denom of the credits in the reserve.
+    string batch_denom = 1;
+
+    // tradable_amount is the amount of the credits in the reserve.
+    string tradable_amount = 2;
+  }
+}

proto/regen/ecocredit/contract/v1alpha1/tx.proto

@@ -0,0 +1,211 @@
+syntax = "proto3";
+
+package regen.ecocredit.contract.v1alpha1;
+
+import "cosmos/base/v1beta1/coin.proto";
+import "cosmos/msg/v1/msg.proto";
+import "gogoproto/gogo.proto";
+import "google/protobuf/duration.proto";
+import "google/protobuf/timestamp.proto";
+
+// Msg is the regen.ecocredit.contract.v1alpha1 Msg service.
+service Msg {
+
+  // Create creates a new forward contract. A new contract starts with status
+  // "proposed" and only the class admin can approve the contract.
+  rpc Create(MsgCreate) returns (MsgCreateResponse);
+
+  // Update updates a proposed forward contract. A contract can only be updated
+  // by the project admin before the contract is approved.
+  rpc Update(MsgUpdate) returns (MsgUpdateResponse);
+
+  // Cancel cancels a forward contract. A contract can only be cancelled by the
+  // project admin before the contract is approved.
+  rpc Cancel(MsgCancel) returns (MsgCancelResponse);
+
+  // Approve approves a proposed forward contract, changing the status of the
+  // contract to "approved" and preventing any further changes. Only an approved
+  // credit class issuer can approve the contract.
+  rpc Approve(MsgApprove) returns (MsgApproveResponse);
+
+  // Reserve sends credits to the contract reserve. Only credits from the same
+  // credit class can be sent to the reserve and once the credits are sent to
+  // the reserve, the credits are held in escrow until the end of the contract.
+  rpc Reserve(MsgReserve) returns (MsgReserveResponse);
+
+  // Invest sends funds to a project in return for a share of the contract
+  // and therefore ownership of future credits issued from the project.
+  rpc Invest(MsgInvest) returns (MsgInvestResponse);
+}
+
+// MsgCreate is the Msg/Create request type.
+message MsgCreate {
+  option (cosmos.msg.v1.signer) = "project_admin";
+
+  // project_id is the unique identifier of the project.
+  string project_id = 1;
+
+  // project_admin is the admin of the project.
+  string project_admin = 2;
+
+  // metadata is any arbitrary string that includes or references additional
+  // information about the contract such as calculations made to determine
+  // the volume of credits and the price per credit.
+  string metadata = 3;
+
+  // price is the token denomination and amount the project is asking for
+  // per credit.
+  cosmos.base.v1beta1.Coin price = 4;
+
+  // amount is the amount of future credits issued that will be available to
+  // purchase. The amount is a decimal value with a precision determined by
+  // the credit type of the credit class.
+  string amount = 5;
+
+  // volume_percentage is the percentage of future credits issued that will be
+  // available to purchase. The percentage is used to determine the amount of
+  // credits issued to investors with each credit issuance.
+  string volume_percentage = 6;
+
+  // start_date is the contract start date.
+  google.protobuf.Timestamp start_date = 7 [ (gogoproto.stdtime) = true ];
+
+  // end_date is the contract end date.
+  google.protobuf.Timestamp end_date = 8 [ (gogoproto.stdtime) = true ];
+
+  // buffer_window is the duration after the end date in which credits may
+  // still be issued with a monitoring period that falls within the start
+  // and end date of the contract. The credits held in the reserve pool are
+  // not distributed or returned until end date + buffer window.
+  google.protobuf.Duration buffer_window = 9;
+}
+
+// MsgCreateResponse is the Msg/Create response type.
+message MsgCreateResponse {
+
+  // id is the unique identifier of the created contract.
+  uint64 id = 1;
+}
+
+// MsgUpdate is the Msg/Update request type.
+message MsgUpdate {
+  option (cosmos.msg.v1.signer) = "project_admin";
+
+  // id is the unique identifier of the contract.
+  uint64 id = 1;
+
+  // project_admin is the admin of the project.
+  string project_admin = 2;
+
+  // metadata is any arbitrary string that includes or references additional
+  // information about the contract such as calculations made to determine
+  // the volume of credits and the price per credit.
+  string metadata = 3;
+
+  // price is the token denomination and amount the project is asking for
+  // per credit.
+  cosmos.base.v1beta1.Coin price = 4;
+
+  // amount is the amount of future credits issued that will be available to
+  // purchase. The amount is a decimal value with a precision determined by
+  // the credit type of the credit class.
+  string amount = 5;
+
+  // volume_percentage is the percentage of future credits issued that will be
+  // available to purchase. The percentage is used to determine the amount of
+  // credits to be issued to investors with each credit issuance.
+  string volume_percentage = 6;
+
+  // start_date is the contract start date.
+  google.protobuf.Timestamp start_date = 7 [ (gogoproto.stdtime) = true ];
+
+  // end_date is the contract end date.
+  google.protobuf.Timestamp end_date = 8 [ (gogoproto.stdtime) = true ];
+
+  // buffer_window is the duration after the end date in which credits may
+  // still be issued with a monitoring period that falls within the start
+  // and end date of the contract. The credits held in the reserve pool are
+  // not distributed or returned until end date + buffer window.
+  google.protobuf.Duration buffer_window = 9;
+}
+
+// MsgUpdateResponse is the Msg/Update response type.
+message MsgUpdateResponse {}
+
+// MsgCancel is the Msg/Cancel request type.
+message MsgCancel {
+  option (cosmos.msg.v1.signer) = "project_admin";
+
+  // id is the unique identifier of the contract.
+  uint64 id = 1;
+
+  // project_admin is the admin of the project.
+  string project_admin = 2;
+}
+
+// MsgCancelResponse is the Msg/Cancel response type.
+message MsgCancelResponse {}
+
+// MsgApprove is the Msg/Approve request type.
+message MsgApprove {
+  option (cosmos.msg.v1.signer) = "class_issuer";
+
+  // id is the unique identifier of the contract.
+  uint64 id = 1;
+
+  // class_issuer is the address of the credit class issuer that is approving
+  // the contract on behalf of the credit class.
+  string class_issuer = 2;
+}
+
+// MsgApproveResponse is the Msg/Approve response type.
+message MsgApproveResponse {}
+
+// MsgReserve is the Msg/Reserve request type.
+message MsgReserve {
+  option (cosmos.msg.v1.signer) = "issuer";
+
+  // contract_id is the unique identifier of the contract.
+  uint64 contract_id = 1;
+
+  // issuer is the address of the issuer that approved the contract. Only the
+  // issuer in the contract can send credits to the contract reserve.
+  string issuer = 2;
+
+  // batch_denom is the batch denom of the credits being sent.
+  string batch_denom = 3;
+
+  // tradable_amount is the amount of tradable credits being sent.
+  string tradable_amount = 4;
+}
+
+// MsgReserveResponse is the Msg/Reserve response type.
+message MsgReserveResponse {}
+
+// MsgInvest is the Msg/Invest request type.
+message MsgInvest {
+  option (cosmos.msg.v1.signer) = "investor";
+
+  // id is the unique identifier of the contract.
+  uint64 id = 1;
+
+  // investor is the address of the account funding the project and receiving a
+  // percentage of future credits issued from the project.
+  string investor = 2;
+
+  // amount is the total amount of future credits issued that the investor is
+  // purchasing and will receive over time with each credit issuance based on
+  // the volume percentage defined within the contract.
+  string amount = 3;
+
+  // auto_retire determines whether the credits will be automatically retied
+  // upon issuance (i.e. the issuance policy will be set to auto-retire).
+  bool auto_retire = 4;
+
+  // retirement_jurisdiction is the jurisdiction of the investor. A jurisdiction
+  // is only required if auto-retire is enabled.
+  string retirement_jurisdiction = 5;
+}
+
+// MsgInvestResponse is the Msg/Invest response type.
+message MsgInvestResponse {}

proto/regen/ecocredit/contract/v1alpha1/types.proto

@@ -0,0 +1,20 @@
+syntax = "proto3";
+
+package regen.ecocredit.contract.v1alpha1;
+
+// Status is the status of a forward contract.
+enum Status {
+
+  // STATUS_UNSPECIFIED
+  STATUS_UNSPECIFIED = 0;
+
+  // STATUS_PROPOSED is the initial state of a contract after the contract
+  // has been created. When the contract status is "proposed", the contract
+  // can be updated or cancelled by the project admin.
+  STATUS_PROPOSED = 1;
+
+  // STATUS_APPROVED is the state of the contract after the contract has
+  // been approved by a credit class issuer. When the contract status is
+  // "approved", the contract cannot be updated or cancelled.
+  STATUS_APPROVED = 2;
+}