Categorygithub.com/payprotocol/kiesnet-cc-token
modulepackage
1.4.1
Repository: https://github.com/payprotocol/kiesnet-cc-token.git
Documentation: pkg.go.dev
Overview
Versions
2
Dependencies
19
Dependents
0
Files
5.7k SLOC

# README

Kiesnet Token Chaincode

An account/balance based token

requirement

  • kiesnet-id chaincode (devmode: kiesnet-cc-id)
  • kiesnet-contract chaincode (devmode: kiesnet-cc-contract)
  • knt-{token_code} chaincodes (devmode: knt-cc-{token_code})

Terms

  • PAOT : personal(main) account of the token
  • EOA : Externally Owned Accounts

API

method func [arg1, arg2, ... ] {trs1, trs2, ... }

  • method : query or invoke
  • func : function name
  • [arg] : mandatory argument
  • [arg] : optional argument
  • {trs} : mandatory transient
  • {trs} : optional transient

invoke account/create [token_code, co-holders...] {"kiesnet-id/pin"}

  • Create an account
  • [token_code] : issued token code
  • [co-holders...] : PAOTs (exclude invoker, max 127)
  • If holders(include invoker) are more then 1, it creates a joint account. If not, it creates the PAOT.

query account/get [token_code|address]

  • Get the account
  • If the parameter is token code, it returns the PAOT.
  • account types
    • 0x00 : unknown
    • 0x01 : personal
    • 0x02 : joint

invoke account/holder/add [account, holder] {"kiesnet-id/pin"}

  • Create a contract to add the holder
  • [account] : the joint account address
  • [holder] : PAOT of the holder to be added

invoke account/holder/remove [account, holder] {"kiesnet-id/pin"}

  • Create a contract to remove the holder
  • [account] : the joint account address
  • [holder] : PAOT of the holder to be removed

query account/list [token_code, bookmark, fetch_size]

  • Get account list
  • If token_code is empty, it returns all account regardless of tokens.
  • [fetch_size] : max 200, if it is less than 1, default size will be used (20)

invoke account/suspend [token_code] {"kiesnet-id/pin"}

  • Suspend the PAOT

invoke account/unsuspend [token_code] {"kiesnet-id/pin"}

  • Unsuspend the PAOT

query balance/logs [token_code|address, log_type, bookmark, fetch_size, starttime, endtime]

  • Get balance logs
  • If the parameter is token code, it returns logs of the PAOT.
  • [fetch_size] : max 200, if it is less than 1, default size will be used (20)
  • [starttime] : time(seconds) represented by int64
  • [endtime] : time(seconds) represented by int64
  • log types
    • 0x00 : mint
    • 0x01 : burn
    • 0x02 : send
    • 0x03 : receive
    • 0x04 : deposit (create a pending balance)
    • 0x05 : withdraw (from the pending balance)
    • 0x06 : pay
    • 0x07 : refund
    • 0x08 : prune pay
    • 0x09 : prune fee
    • 0x0a : wrap
    • 0x0b : unwrap
    • 0x0c : wrap complete
    • 0x0d : unwrap complete

query balance/pending/get [pending_balance_id]

  • Get the pending balance
  • pending types
    • 0x00 : account
    • 0x01 : contract

query balance/pending/list [token_code|address, sort, bookmark, fetch_size]

  • Get pending balances list
  • If the parameter is token code, it returns logs of the PAOT.
  • [sort] : 'created_time' or 'pending_time'(default)
  • [fetch_size] : max 200, if it is less than 1, default size will be used (20)
  • pending types
    • 0x00 : account
    • 0x01 : contract

invoke balance/pending/withdraw [pending_balance_id] {"kiesnet-id/pin"}

  • Withdraw the balance

query fee/list [token_code, bookmark, fetch_size, starttime, endtime]

  • Get fee list of token
  • [fetch_size] : max 200, if it is less than 1, default size will be used (20)
  • [starttime] : time(seconds) represented by int64
  • [endtime] : time(seconds) represented by int64

invoke fee/prune [token_code, ten_minutes_flag, endtime] {"kiesnet-id/pin"}

  • prune the fees from last fee time to end_time. if end_time is not provided, prune to 10 mins lesser than current time(if ten_minutes_flag is set to true).
  • Only holder of FeePolicy.TargetAddress is able to prune.
  • [ten_minutes_flag] : Boolean if set to true, the end_time can't be greater than current time minus 10 minutes.
  • [end_time]: to time for pruning
  • has_more field is true in the response json string, it means there are more fees to prune given time period.

invoke token/burn [token_code, amount] {"kiesnet-id/pin"}

  • Get the burnable amount and burn the amount.
  • [amount] : big int
  • If genesis account holders are more than 1, it creates a contract.

invoke token/create [token_code, co-holders...] {"kiesnet-id/pin"}

  • Create(Issue) the token
  • [token_code] : 3~6 alphanum
  • [co-holders...] : PAOTs (exclude invoker, max 127)
  • It queries meta-data of the token from the knt-{token_code} chaincode.

query token/get [token_code]

  • Get the current state of the token

invoke token/mint [token_code, amount] {"kiesnet-id/pin"}

  • Get the mintable amount and mint the amount.
  • [amount] : big int
  • If genesis account holders are more than 1, it creates a contract.

invoke token/update [token_code] {"kiesnet-id/pin"}

  • // Get updated information from the token meta chaincode(e.g. knt-cc-pci) and save it to the ledger.
  • [token_code] : issued token code. If the token is not issued, this function does nothing and returns success.

invoke transfer [sender, receiver, amount, memo, order_id, pending_time, expiry, extra-signers...] {"kiesnet-id/pin"}

  • Transfer the amount of the token or create a contract
  • [sender] : an account address, empty = PAOT
  • [receiver] : an account address
  • [amount] : big int
  • [memo] : max 1024 charactors
  • [order_id] : order ID (vendor specific)
  • [pending_time] : time(seconds) represented by int64
  • [expiry] : duration(seconds) represented by int64, multi-sig only
  • [extra-signers...] : PAOTs (exclude invoker, max 127)

query transfer/get [order_id]

  • Get the balance log by order id
  • [order_id] : order ID (vender specific)

invoke pay [sender, receiver, amount, order_id, memo, expiry] {"kiesnet-id/pin"}

  • pay the amount of positive token to the receiver or creaete a pay contract
  • [sender]: an account address, TOKENCODE = PAOT
  • [receiver] : an account address
  • [amount] : big int
  • [order_id] : order ID (vendor specific)
  • [memo] : max 1024 charactors
  • [expiry] : duration(seconds) represented by int64, multi-sig only

query pay/get [pay_id, order_id]

  • Get the pay (unspent token)
  • [pay_id] : pay ID
  • [order_id] : order ID (vendor specific)

invoke pay/refund [original_pay_id, amount, memo, order_id ] {"kiesnet-id/pin"}

  • refund the amount of token the based on original_pay_id
  • [original_pay_id] : original_pay_id
  • [amount]: the amount of token to refund. This value cannot be acculumated more than the original pay amount.
  • [memo]: max 1024 charactors
  • [order_id] : order ID (vendor specific)

invoke pay/prune [token_code|address, ten_minutes_flag, end_time] {"kiesnet-id/pin"}

  • prune the pays from last pay time to end_time. if end_time is not provided, prune to 10 mins lesser than current time(if ten_minutes_flag is set to true).
  • [ten_minutes_flag] : Boolean if set to true, the end_time can't be greater than current time minus 10 minutes.
  • [end_time]: to time for pruning
  • has_more field is true in the response json string, it means there are more pays to prune given time period.

query pay/list [token_code|address, sort_order, bookmark, fetchsize, start_time, end_time ]

  • Get pay list
  • If the 1st parameter is token code, it returns list of the PAOT.
  • [sort_order] : "asc" ascending order. "desc" decending order. if not set, decending order is the default value.
  • [fetch_size] : max 200, if it is less than 1, default size will be used (20)
  • [starttime] : time(seconds) represented by int64
  • [endtime] : time(seconds) represented by int64

invoke wrap [token_code|sender, ext_token_code, ext_address, amount, memo, order_id, expiry, extra-signers...]

  • Wrap the amount of the token or create a contract
  • [sender]: an account address, TOKENCODE = PAOT
  • [ext_token_code] : external token code (eg. wpci)
  • [ext_address] : external address(EOA)
  • [amount] : big int
  • [memo]: max 1024 charactors
  • [order_id] : order ID (vendor specific)
  • [expiry] : duration(seconds) represented by int64, multi-sig only
  • [extra-signers...] : PAOTs (exclude invoker, max 127)

invoke wrap/complete [wrap_key, fee, ext_tx_id]

  • When bridge receive wrap event, handling fee
  • [wrap_key] : wrap tx hash (without '0x' prefix)
  • [fee] : big int
  • [ext_tx_id] : external tx hash (with '0x' prefix)

invoke unwrap [token_code|receiver, ext_token_code, ext_address, ext_tx_id, amount]

  • Unwrap the amount of the token
  • If the 1st parameter is token code, send amount to wrap address.
  • [ext_token_code] : external token code (eg. wpci)
  • [ext_address] : external address(EOA)
  • [ext_tx_id] : external transaction id, for handling duplicate check
  • [amount] : big int

query ver

  • Get version

# Functions

CreateQueryBalanceLogByOrderID _.
CreateQueryBalanceLogsByID _.
CreateQueryBalanceLogsByIDAndTimes _.
CreateQueryDocumentByID _.
CreateQueryFeesByCode _.
CreateQueryFeesByCodeAndTimes _.
CreateQueryHoldersByID _.
CreateQueryHoldersByIDAndTokenCode _.
CreateQueryPayByOrderID _.
CreateQueryPaysByID _.
CreateQueryPaysByIDAndTime _.
CreateQueryPendingBalancesByAddress _.
CreateQueryPruneFee generates query string to fetch fee list of tokenCode from stime to etime.
CreateQueryPrunePays _.
NewAccountStub _.
NewAddress _.
NewAmount _.
NewAmountWithBigInt _.
NewBalanceDepositLog _.
NewBalancePayLog _.
NewBalancePruneFeeLog creates new BalanceLog of type BalanceLogTypePruneFee.
NewBalancePrunePayLog No need RID.
NewBalanceRefundLog _.
NewBalanceStub _.
NewBalanceSupplyLog _.
NewBalanceTransferLog _.
No description provided by the author
No description provided by the author
NewBalanceWithdrawLog _.
No description provided by the author
No description provided by the author
NewFeeStub _.
NewHolder _.
NewLastPrunedFeeIDStub _.
NewPay _.
NewPayResult _.
NewPayStub _.
NewPendingBalance _.
NewQueryResult _.
NewTokenStub _.
NewWrapBridge _.
NewWrapStub _.
NormalizeExtAddress _.
NormalizeExtTxID _.
ParseAddress parses address string and validates it.
ParseCode parses the token code.
ParseFeePolicy parses fee policy format string to FeePolicy struct.
ValidateTokenCode validates a code and returns an uppercased code.
ZeroAmount _.

# Constants

AccountsFetchSize _.
AccountTypeJoint _.
AccountTypePersonal _.
AccountTypeUnknown _.
BalanceLogsFetchSize _.
BalanceLogTypeBurn _.
BalanceLogTypeDeposit deposit balance to contract.
BalanceLogTypeMint _.
BalanceLogTypePay pay amount of balance.
BalanceLogTypePruneFee is created when fee utxos are pruned to genesis account.
BalanceLogTypePrunePay the amount of pruned payments.
BalanceLogTypeReceive _.
BalanceLogTypeRefund refund amount of balance.
BalanceLogTypeSend _.
BalanceLogTypeUnwrap is created when unwrap from bridge.
BalanceLogTypeUnwrapComplete unwrap balance from bridge account.
BalanceLogTypeWithdraw withdraw balance from contract.
BalanceLogTypeWrap is created when wrap to bridge.
BalanceLogTypeWrapComplete is created when wrap bridge handle fee.
FeeFetchSize _.
FeePruneSize is number of fee utxo that one prune request can handle.
MemoMaxLength is used to limit memo field length (BalanceLog, PendingBalance, Pay).
PaysFetchSize _.
PaysPruneSize _ XXX *** StateDB fetch limit MUST be greater than PaysPruneSize.
PendingBalancesFetchSize _.
PendingBalanceTypeAccount _.
PendingBalanceTypeContract _.
QueryBalanceLogByOrderID _.
QueryBalanceLogsByID _.
QueryBalanceLogsByIDAndTimes _.
CreateQueryDocumentByID _.
QueryFeesByCode _.
QueryFeesByCodeAndTime _.
QueryHoldersByID _.
QueryHoldersByIDAndTokenCode _.
QueryPayByOrderID _.
QueryPaysByID _.
QueryPaysByIDAndTime _.
QueryPendingBalancesByAddress _.
QueryPruneFee _TODO check sort, use_index.
QueryPrunePays _.

# Structs

Account _.
AccountStub _.
Address _.
Amount _.
Balance _.
BalanceLog _.
BalanceStub _.
Chaincode _.
DuplicateUnwrapCompleteError occurs when unwrap is already completed.
DuplicateWrapCompleteError occurs when wrap is already completed.
ExistedAccountError _.
Fee is a transfer/pay fee utxo which will be pruned to genesis account.
FeePolicy _.
FeeRate _.
FeeStub _.
FeeSum stands for amount&state of accumulated fee from Start to End.
Holder represents an account-holder relationship (many-to-many).
InvalidAccessError _.
InvalidAccountAddrError _.
JointAccount _.
LastPrunedFeeID is a last pruned fee id of the token.
LastPrunedFeeIDStub _.
NotExistedAccountError _.
NotExistedFeeError occurs when GetFeeState() got invalid fee id.
NotExistedPayError _.
NotInitLastPrunedFeeIDError is an error there is no LastPrunedFeeID state in the world state.
NotIssuedTokenError _.
Pay _.
PayResult _.
PayStub _.
PaySum _.
PendingBalance _.
QueryResult _.
ResponsibleErrorImpl _.
SupplyError _.
Token _.
TokenResult is response payload of token/burn and token/mint.
TokenStub _.
Unwrap _.
Wrap _.
WrapPolicy _.
WrapStub _.

# Interfaces

AccountInterface _.
Identifiable _.
ResponsibleError is the interface used to distinguish responsible errors.

# Type aliases

AccountType _.
BalanceLogType _.
CtrFunc _.
PendingBalanceType _.
TxFunc _.