# Msg Service

# MsgCreateClass

MsgCreateClass creates a new credit class with a credit class admin, an approved list of issuers, optional metadata, and a credit type. The party signing this transaction is the credit admin.

// 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.
  bytes metadata = 3;

  // credit_type_name describes the type of credit (e.g. "carbon", "biodiversity").
  string credit_type_name = 4;
}

# Validation:

  • admin must ba a valid address, and their signature must be present in the transaction
  • if the allowlist_enabled paramater is set to true, admin must be on the list of approved credit class creators (the allowed_class_creators parameter)
  • issuers must not be empty and all addresses must be valid addresses
  • credit_type (the name of the credit type) must not be empty and on the list of approved credit types (the credit_types parameter)
  • metadata must be less than or equal to 256 bytes

# MsgCreateBatch

MsgCreateBatch 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. The message must be signed by an approved issuer of the desired credit class.

The message must specify the receiver of the batch of credits as well as the number of units to issue in this batch and metadata.

In order to support use cases when credits are to be immediately retired upon issuance, for each account to be issued credits, both an amount of tradeable and retired credit units can be specified.

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

  // 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 attached to the credit batch.
  bytes 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 ];

  // project_location is the location of the project backing the credits in this
  // batch. It is a string of the form
  // [-[ ]], 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 can be added for increasing precision.
  string project_location = 7;

  // 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_location is the location 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
    // [-[ ]], with the first two
    // fields conforming to ISO 3166-2, and postal-code being up to 64
    // alphanumeric characters.
    string retirement_location = 4;
  }
}

# Validation:

  • issuer must ba a valid address, and their signature must be present in the transaction
  • issuer must be on the list of approved issuers for the given credit class
  • class_id must be a valid credit class ID
  • recipient must ba a valid address
  • tradable_amount must not be negative
  • retired_amount must not be negative
  • if retired_amount is positive, retirement_location must be a valid location
  • metadata must be less than or equal to 256 bytes
  • start_date must be a valid date
  • end_date must be a valid date
  • project_location must be a valid location

# MsgSend

Send sends tradable credits from one account to another account. Sent credits can either be tradable or retired on receipt.

// 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 ID 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_location is the location 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
    // [-[ ]], with the first two
    // fields conforming to ISO 3166-2, and postal-code being up to 64
    // alphanumeric characters.
    string retirement_location = 4;
  }
}

# Validation:

  • sender must ba a valid address, and their signature must be present in the transaction
  • recipient must ba a valid address
  • credits must not be empty
  • batch_denom must be a valid batch denomination
  • tradable_amount must not be negative
  • retired_amount must not be negative
  • if retired_amount is positive, retirement_location must be a valid location

# MsgRetire

Retire retires a specified number of credits in the holder's account.

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

  // holder is the credit holder address.
  string holder = 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 ID 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;
  }

  // location is the location of the beneficiary or buyer of the retired
  // credits. It is a string of the form
  // [-[ ]], with the first two
  // fields conforming to ISO 3166-2, and postal-code being up to 64
  // alphanumeric characters.
  string location = 3;
}

# Validation:

  • holder must ba a valid address, and their signature must be present in the transaction
  • credits must not be empty
  • batch_denom must be a valid batch denomination
  • amount must be positive
  • location must be a valid location

# MsgCancel

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.

message MsgCancel {

  // 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;

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

# Validation:

  • holder must ba a valid address, and their signature must be present in the transaction
  • credits must not be empty
  • batch_denom must be a valid batch denomination
  • amount must be positive