Transactions

Karma Coin has 3 kinds of blockchain transactions: New User Transaction, Update User Transaction and Payment Transaction. Transaction data is included in a generic higher-level SignedTransaction data object which includes fields common to all transactions and is signed by the user.

In addition to the core transactions described above, Karma Coin supports transactions for Staking Karma Coins with validators, nominating validators, and voting on governance proposals.

enum TransactionType {
  TRANSACTION_TYPE_PAYMENT_V1 = 0;
  TRANSACTION_TYPE_NEW_USER_V1 = 1;
  TRANSACTION_TYPE_UPDATE_USER_V1 = 2;
}

/// The transaction data is serialized payment, new user or update user transaction data.
message SignedTransaction {
  AccountId signer = 1; // account this tx is signed by
  uint64 timestamp = 2; // time transaction was signed
  uint64 nonce = 3; // tx nonce
  uint64 fee = 4; // network fee provided by sender
  TransactionData transaction_Data = 5; // binary transaction data
  uint32 net_id = 6; // network id to avoid confusion with testnets
  Signature signature = 7; // signer signature on all of the above data
}

---

New User Transaction

This transaction is submitted by new Karma Coin users to create an on-chain account. It includes a signed message from a trusted verifier that attests the user's requested unique user-name, verified phone number and account id.

// Created and signed by a verifier to attest that an account owns a mobile number
message UserVerificationData {
  AccountId verifier_account_id = 1;
  uint64 timestamp = 2;
  VerificationResult verification_result = 3;
  AccountId account_id = 4;
  MobileNumber mobile_number = 5;
  // only used in referral onboarding flow to indicate referral transaction id
  bytes referral_transaciton_id = 6;
  string requested_user_name = 7;
  Signature signature = 8;
}

enum VerificationResult {
  VERIFICATION_RESULT_UNSPECIFIED = 0;
  VERIFICATION_RESULT_USER_NAME_TAKEN = 1; // there's already a user with the requested user name
  VERIFICATION_RESULT_VERIFIED = 2; // user is verified using provided token
  VERIFICATION_RESULT_UNVERIFIED = 3; // user is not verifier using provided token
  VERIFICATION_RESULT_MISSING_DATA = 4; // request is missing required data
  VERIFICATION_RESULT_INVALID_SIGNATURE = 5; // bad client signature
  VERIFICATION_RESULT_ACCOUNT_MISMATCH = 6; // different account associated with phone number
}

// new user transactions submitted by users
message NewUserTransactionV1 {
  // Evidence from a valid verifier about the new user
  UserVerificationData verify_number_response = 1;
}

---

Payment Transaction

A payment transaction specifies transfer of KCents from one user account to another user account. It optionally includes an appreciation for a character trait.

Payment transactions are used for several Karma Coin use cases: appreciation, tipping w/o an appreciation and a simple coin transfer operation.

Transaction receiver is always a mobile phone number. This is designed so existing users can tip, appreciate or send coins to any other person even before that person created an on-chain user account via a NewUser transaction. See the onboarding flow for additional info regarding how these transactions are processed.

// Basic payment transaction with optional character appreciation
message PaymentTransactionV1 {
  MobileNumber to = 1; // dest is always a mobile number (of a user or a non-user) no accountId needed.
  uint64 amount = 2; // amount in tokens to transfer
  uint32 char_trait_id = 3; // char trait id set by sender. e.g. smart
}

Update User Transaction

This transaction is used by users who have an on-chain account in several use cases:

1. Update nickname.
2. Update mobile phone number.

Update Nickname

This is a request by an existing user to change his unique Karma Coin user-name. This operation doesn't requrie signed verification data from a verifier. Block producers check that the requested name is available and reject the transaction if it is taken.

Update Mobile Number

This is used when user has changed his mobile phone number. It updates the user's phone number in the on-chain user account. This operation requires the user to attach a signed verification from a verifier regarding ownership of the number.

// Update user info
message UpdateUserTransactionV1 {

    // new requested nickname
    string nickname = 1;

    // Updated verified number
    MobileNumber mobile_number = 2;

    // verifier attestation regarding the number and the account
    UserVerificationData user_verification_data = 3;
}

---

Transactions Events Model

Events are generated by runtime transaction processing and include non-chain data that provides useful information for users, validators and verifiers that doesn't need to be kept on-chain.

Karma Coin Archive nodes keep all events since genesis and make them accessible via the Karma Coin blockchain node API.

Full nodes retain only recent events and make them available via the same API. There are two types of events: Transaction Events and Block Events.

A blockchain event is generated for each block produced by a block producer.

A transaction event is generated for each processed transaction and includes transactions that were rejected by a block producer for inclusion in a block as well as transactions that were added to a block.

enum FeeType {
  FEE_TYPE_MINT = 0; // fee provided by the protocol
  FEE_TYPE_USER = 1; // fee provided by the transaction signer
}

enum ExecutionResult {
  EXECUTION_RESULT_EXECUTED = 0;
  EXECUTION_RESULT_INVALID = 1; // invalid syntax
}

enum ExecutionInfo {
  EXECUTION_INFO_UNKNOWN = 0;
  EXECUTION_INFO_NICKNAME_UPDATED = 1;
  EXECUTION_INFO_NICKNAME_NOT_AVAILABLE = 2;
  EXECUTION_INFO_NICKNAME_INVALID = 3;
  EXECUTION_INFO_NUMBER_UPDATED = 4;
  EXECUTION_INFO_ACCOUNT_CREATED = 5;
  EXECUTION_INFO_PAYMENT_CONFIRMED = 6;
  EXECUTION_INFO_INVALID_DATA = 7;
  EXECUTION_INFO_ACCOUNT_ALREADY_EXISTS = 8;
  EXECUTION_INFO_TX_FEE_TOO_LOW = 9;
  EXECUTION_INFO_INTERNAL_NODE_ERROR = 10;
}


// Transaction event
message TransactionEvent {
  uint64 timestamp = 1;
  uint64 height = 2; // ledger height of execution
  SignedTransaction transaction = 3;
  bytes transaction_hash = 4;
  ExecutionResult result = 5;
  ExecutionInfo info = 6;
  string error_message = 7;
  FeeType fee_type = 8;
  uint64 signup_reward = 9;
  uint64 referral_reward = 10;
  uint64 fee = 11;
}

// Block event
message BlockEvent {
    uint64 timestamp = 1;
    uint64 height = 2;
    bytes block_hash = 3;
    repeated TransactionEvent transactions_events = 4;
    uint64 signups_count = 5;
    uint64 payments_count = 6;
    uint64 user_updates_count = 7;
    uint64 fees_amount = 8;
    uint64 signup_rewards_amount = 9;
    uint64 referral_rewards_amount = 10;
    uint64 referral_rewards_count = 11;
    uint64 reward = 12;
}

---

Transactions Pool Model

The Transactions Pool is a temporary storage for transactions that are received by a node but not yet included in a block. The pool is used to store transactions that are received before a block producer is elected and to store transactions that were rejected by a block producer for inclusion in a block. The following describes the transactions pool model. Some special care is needed to implement Karma Coin correctly which involves how transactions are processed and how the pool is managed.

Payment Translations Handling

As one of the top project goals is to make it easy for users to sign up and appreciate. Clients do not block users from submitting payment/appreciation transactions as soon as they've signe-up in the app and before a new user's new user transcation is processed there's no online account for the user. The following rules should be applied:

1. The pool management logic should not reject payment transactions where the sender's account is not found on chain. These transactions should be stored in the pool for a period of 14 days.
2. Block producers should not process payment transactions where the sender's account is not found on chain. Only payment transactions where the sender's account is found on chain should be processed and included in new blocks.

New User Transactions Handling

Some checks should be performed by the pool logic before accepting a new user transaction to the pool. The following validation rules should be applied:

1. A valid validators' attestation - signed by an active validator.
2. User requested nickname is available. e.g. was not already taken.
3. Valid reference to a payment transaction when the transaction includes a referral transaction id. The payment transaction identified by the id should be in the pool.

In case that a transaction does not meet these validation criteria, it should not be added to the pool and rejected upon submission.

---

License

Copyright (c) 2022 by the Karma Coin Authors. This work is licensed under the Karma Coin License.