tx.proto

syntax = "proto3";

package regen.ecocredit.v1;

import "gogoproto/gogo.proto";
import "google/protobuf/timestamp.proto";
import "cosmos/base/v1beta1/coin.proto";
import "regen/ecocredit/v1/types.proto";

option go_package = "github.com/regen-network/regen-ledger/x/ecocredit/core";

// Msg is the regen.ecocredit.v1 Msg service.
service Msg {

  // CreateClass creates a new credit class with an approved list of issuers and
  // optional metadata.
  rpc CreateClass(MsgCreateClass) returns (MsgCreateClassResponse);

  // CreateProject creates a new project within a credit class.
  rpc CreateProject(MsgCreateProject) returns (MsgCreateProjectResponse);

  // CreateBatch creates a new batch of credits for an existing project.
  // 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(MsgCreateBatch) returns (MsgCreateBatchResponse);

  // MintBatchCredits issues new token in a given batch.
  // The issuer must be the account who created (or delegated using x/authz),
  // the batch.
  // The request will fail if the batch is not open (is sealed).
  // NOTE: this method is only for bridge purpose. It must not be used
  // for issuing native credits on Regen. More specifically, we
  // enable minting more credits in an existing batch, when the batch
  // represents a vintage originally registered in another chain.
  rpc MintBatchCredits(MsgMintBatchCredits)
      returns (MsgMintBatchCreditsResponse);

  // MsgSealBatch sets the `batch.open` attribute to false. Sealed batch
  // can't issue more credits. Once batch is sealed it can't be toggled any
  // more. Only batch creator can seal a batch.
  rpc SealBatch(MsgSealBatch) returns (MsgSealBatchResponse);

  // Send sends tradable credits from one account to another account. Sent
  // credits can either be tradable or retired on receipt.
  rpc Send(MsgSend) returns (MsgSendResponse);

  // Retire retires a specified number of credits in the holder's account.
  rpc Retire(MsgRetire) 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(MsgCancel) returns (MsgCancelResponse);

  // UpdateClassAdmin updates the credit class admin
  rpc UpdateClassAdmin(MsgUpdateClassAdmin)
      returns (MsgUpdateClassAdminResponse);

  // UpdateClassIssuers updates the credit class issuer list
  rpc UpdateClassIssuers(MsgUpdateClassIssuers)
      returns (MsgUpdateClassIssuersResponse);

  // UpdateClassMetadata updates the credit class metadata
  rpc UpdateClassMetadata(MsgUpdateClassMetadata)
      returns (MsgUpdateClassMetadataResponse);

  // UpdateProjectAdmin updates the project admin address
  rpc UpdateProjectAdmin(MsgUpdateProjectAdmin)
      returns (MsgUpdateProjectAdminResponse);

  // UpdateProjectMetadata updates the project metadata
  rpc UpdateProjectMetadata(MsgUpdateProjectMetadata)
      returns (MsgUpdateProjectMetadataResponse);

  // Bridge cancels credits and emits a bridge event.
  rpc Bridge(MsgBridge) returns (MsgBridgeResponse);
}

// MsgCreateClass is the Msg/CreateClass request type.
message MsgCreateClass {
  // admin is the address of the account that created the credit class.
  string admin = 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.
  string metadata = 3;

  // credit_type_abbrev is the abbreviation of a credit type (e.g. "C", "BIO").
  string credit_type_abbrev = 4;

  // fee specifies the fee to pay for the creation of the credit class.
  // acceptable fees for creating a credit class can be found in the governance
  // parameters for the ecocredit module.
  cosmos.base.v1beta1.Coin fee = 5;
}

// MsgCreateClassResponse is the Msg/CreateClass response type.
message MsgCreateClassResponse {

  // class_id is the unique identifier of the credit class.
  string class_id = 1;
}

// MsgCreateProjectResponse is the Msg/CreateProject request type.
message MsgCreateProject {
  // issuer is the address of an approved issuer for the credit class through
  // which batches will be issued. It is not required, however, that this same
  // issuer issue all batches for a project.
  string issuer = 1;

  // class_id is the unique identifier of the credit class within which the
  // project will be created.
  string class_id = 2;

  // metadata is any arbitrary metadata attached to the project.
  string metadata = 3;

  // jurisdiction is the jurisdiction of the project backing the credits
  // in this batch. 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
  // alphanumeric characters. country-code is required, while sub-national-code
  // and postal-code are optional and can be added for increased precision.
  string jurisdiction = 4;

  // reference_id is any arbitrary string used to reference the project.
  string reference_id = 5;
}

// MsgCreateProjectResponse is the Msg/CreateProject response type.
message MsgCreateProjectResponse {

  // project_id is the unique identifier of the newly created project.
  string project_id = 1;
}

// MsgCreateBatch is the Msg/CreateBatch request type.
message MsgCreateBatch {

  // issuer is the address of the batch issuer.
  string issuer = 1;

  // project_id is the unique identifier of the project within which the credit
  // batch will be created.
  string project_id = 2;

  // issuance are the credits issued in the batch.
  repeated BatchIssuance issuance = 3;

  // metadata is any arbitrary metadata attached to the credit batch.
  string metadata = 4;

  // start_date is the beginning of the period during which this credit batch
  // was quantified and verified.
  google.protobuf.Timestamp start_date = 5 [ (gogoproto.stdtime) = true ];

  // end_date is the end of the period during which this credit batch was
  // quantified and verified.
  google.protobuf.Timestamp end_date = 6 [ (gogoproto.stdtime) = true ];

  // If open is true we will enable future minting.
  // Otherwise we will seal the batch and disable the future minting.
  bool open = 7;

  // A reference to a transaction or an event referencing the transaction
  // which caused the transfer from other chain or registry.
  // If not set (null), it means that the batch originate in Regen Ledger
  // (doesn't come from external registry).
  OriginTx origin_tx = 8;

  // reference note for accounting, will be passed to an event
  string note = 9;
}

// 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_amount is the number of credits in this issuance that can be
  // traded by this recipient. Decimal values are acceptable.
  string tradable_amount = 2;

  // 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_amount = 3;

  // retirement_jurisdiction is the jurisdiction of the beneficiary or buyer of
  // the 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 alphanumeric characters.
  string retirement_jurisdiction = 4;
}

// MsgCreateBatchResponse is the Msg/CreateBatch response type.
message MsgCreateBatchResponse {

  // batch_denom is the unique identifier of the newly created batch.
  string batch_denom = 1;
}

// MsgMintBatchCredits is a request type for MintBatchCredits Msg RPC.
message MsgMintBatchCredits {
  // Issuer must equal to the batch.issuer address.
  // Signer of the msg.
  string issuer = 1;

  // batch_denom is the unique identifier of the credit batch.
  string batch_denom = 2;

  // issuance are the credits issued in the batch.
  repeated BatchIssuance issuance = 3;

  // A reference to a transaction or an event referencing the transaction
  // which caused the transfer from other chain or registry.
  OriginTx origin_tx = 4;

  // reference note for accounting, will be passed to an event
  string note = 5;
}

// MsgSealBatch request type for MsgSealBatch RPC.
message MsgSealBatch {
  // Issuer must equal to the batch.issuer address.
  // Signer of the msg.
  string issuer = 1;

  // batch_denom is the unique identifier of the credit batch.
  string batch_denom = 2;
}

// MsgMintBatchCreditsResponse is the Msg/MintBatchCredits response type.
message MsgMintBatchCreditsResponse {}

// MsgSealBatchResponse is the Msg/SealBatch response type.
message MsgSealBatchResponse {}

// MsgSend is the Msg/Send request type.
message MsgSend {

  // 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 SendCredits credits = 3;

  // 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 identifier of the credit batch.
    string batch_denom = 1;

    // 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_amount = 2;

    // 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_amount = 3;

    // retirement_jurisdiction is the jurisdiction of the beneficiary or buyer
    // of the 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 alphanumeric characters.
    string retirement_jurisdiction = 4;
  }
}

// MsgSendResponse is the Msg/Send response type.
message MsgSendResponse {}

// MsgRetire is the Msg/Retire request type.
message MsgRetire {

  // owner is the address of the account that owns the credits being retired.
  string owner = 1;

  // credits are the credits being retired.
  repeated RetireCredits credits = 2;

  // RetireCredits specifies a batch and the number of credits being retired.
  message RetireCredits {

    // batch_denom is the unique identifier of the credit batch.
    string batch_denom = 1;

    // amount is the number of credits being retired.
    // Decimal values are acceptable within the precision returned by
    // Query/Precision.
    string amount = 2;
  }

  // jurisdiction is the jurisdiction of the beneficiary or buyer of the retired
  // credits. 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
  // alphanumeric characters.
  string jurisdiction = 3;
}

// MsgRetire is the Msg/Retire response type.
message MsgRetireResponse {}

// MsgCancel is the Msg/Cancel request type.
message MsgCancel {

  // owner is the address of the account that owns the credits being cancelled.
  string owner = 1;

  // credits are the credits being cancelled.
  repeated Credits credits = 2;

  // reason is any arbitrary string that specifies the reason for cancelling
  // credits.
  string reason = 3;
}

// MsgCancelResponse is the Msg/Cancel response type.
message MsgCancelResponse {}

// MsgUpdateClassAdmin is the Msg/UpdateClassAdmin request type.
message MsgUpdateClassAdmin {

  // admin is the address of the account that is the admin of the credit class.
  string admin = 1;

  // class_id is the unique identifier of the credit class.
  string class_id = 2;

  // new_admin is the address of the new admin of the credit class.
  string new_admin = 3;
}

// MsgUpdateClassAdminResponse is the MsgUpdateClassAdmin response type.
message MsgUpdateClassAdminResponse {}

// MsgUpdateClassIssuers is the Msg/UpdateClassIssuers request type.
message MsgUpdateClassIssuers {

  // admin is the address of the account that is the admin of the credit class.
  string admin = 1;

  // class_id is the unique identifier of the credit class.
  string class_id = 2;

  // add_issuers are the issuers to add to the class issuers list.
  repeated string add_issuers = 3;

  // remove_issuers are the issuers to remove from the class issuers list.
  repeated string remove_issuers = 4;
}

// MsgUpdateClassIssuersResponse is the MsgUpdateClassIssuers response type.
message MsgUpdateClassIssuersResponse {}

// MsgUpdateClassMetadata is the Msg/UpdateClassMetadata request type.
message MsgUpdateClassMetadata {

  // admin is the address of the account that is the admin of the credit class.
  string admin = 1;

  // class_id is the unique identifier of the credit class.
  string class_id = 2;

  // metadata is the updated arbitrary metadata to be attached to the credit
  // class.
  string metadata = 3;
}

// MsgUpdateClassMetadataResponse is the Msg/UpdateClassMetadata response type.
message MsgUpdateClassMetadataResponse {}

// MsgUpdateProjectAdmin is the Msg/UpdateProjectAdmin request type.
message MsgUpdateProjectAdmin {

  // admin is the project's current admin address.
  string admin = 1;

  // new_admin is the address of the new admin of the project.
  string new_admin = 2;

  // project_id is the unique identifier of the project (e.g. VERRA1).
  string project_id = 3;
}

// MsgUpdateProjectAdmin is the Msg/UpdateProjectAdmin response type.
message MsgUpdateProjectAdminResponse {}

// MsgUpdateProjectMetadata is the Msg/UpdateProjectMetadata request type.
message MsgUpdateProjectMetadata {

  // admin is project admin address.
  string admin = 1;

  // new_metadata is the metadata to update the project with.
  string new_metadata = 2;

  // project_id is the unique identifier of the project (e.g. VERRA1).
  string project_id = 3;
}

// MsgUpdateProjectMetadataResponse is the Msg/UpdateProjectMetadataResponse
// response type.
message MsgUpdateProjectMetadataResponse {}

// MsgBridge is the Msg/Bridge request type.
message MsgBridge {
  // target is the target chain.
  string target = 1;

  // recipient is the recipient address.
  string recipient = 2;

  // contract is the contract address.
  string contract = 3;

  // owner is the address of the account that owns the credits being bridged.
  string owner = 4;

  // credits are the credits being cancelled.
  repeated Credits credits = 5;
}

// MsgBridgeResponse is the Msg/MsgBridge response type.
message MsgBridgeResponse {}