github.com/inklabsfoundation/inkchain@v0.17.1-0.20181025012015-c3cef8062f19/docs/chaincode_interfaces.md (about)

     1  INKchain Chaincode API for Development
     2  ---------------------
     3  As a helpful tool in chaincode, INKchain has extended the original interfaces of Fabric, and provided a serious of APIs to help chaincode developers to work more efficiently. These APIs are divided into four categories: APIs for Interacting with Ledger Status, APIs about Transaction Information, APIs for Reading Parameters and other APIs, which are introduced in detail as follows.
     4  
     5  ### 1. APIs for Interacting with Ledger Status
     6  Chaincodes intend to record data in a distributed ledger. The data to be recorded is called “state,” stored in a key-value form. Based on Fabric, INKchain has modified the structure of block, adding new types of transaction and structure of data storage. New interfaces about accounts are proposed. Meanwhile, as a supplement for Read-Write Set in Fabric, Transfer Set is created to realize the functionality of recording account transfers. Details of APIs for Interacting with Ledger Status are listed as follows.
     7  
     8  Transfer(to string, balanceType string, amount *big.Int) error
     9  > Tranfer implements atomic balance changes. It allows an transaction of a specific tpye of token (e.g., INK) from invoker's account to another one. Transfer puts the specified “key” and “value” into the transaction's transferset as a data-write proposal. Transfer doesn't effect the ledger until the transaction is validated and successfully committed.
    10  
    11  GetAccount(address string) (*wallet.Account, error)
    12  > GetAccount returns the account information of the given address. Account information includes its address, balances of different kinds of tokens, and a counter.
    13  
    14  GetState(key string) ([]byte, error)
    15  > GetState return the value of the specified “key” from the ledger.
    16  
    17  PutState(key string, value []byte) error
    18  > PutState puts the specified “key” and “value” into the transaction's writeset as a data-write proposal. PutState doesn't effect the ledger until the transaction is validated and successfully committed.
    19  
    20  DelState(key string) error
    21  > DelState records the specified key to be deleted in the writeset of the transaction proposal. The key and its value will be deleted from the ledger when the transaction is validated and successfully committed.
    22  
    23  GetStateByRange (startKey, endKey string) (StateQueryIteratorInterface, error)
    24  > GetStateByRange returns a range iterator over a set of keys in the ledger. The iterator can be used to iterate over all keys between the startKey (inclusive) and endKey (exclusive). The keys are returned by the iterator in lexical order. Note that startKey and endKey can be empty string, which implies unbounded range query on start or end. Call Close() on StateQueryIteratorInterface object when done.
    25  
    26  GetStateByPartialCompositeKey(obje ctType string, keys []string) (StateQueryIteratorInterface, error)
    27  > GetStateByPartialCompositeKey queries the state in the ledger based on a given partial composite key. This function returns an iterator which can be used to iterate over all composite keys whose prefix matches the given partial composite key. Call Close() on the returned StateQueryIteratorInterface object when done.
    28  
    29  GetHistoryForKey(key string) (HistoryQueryIteratorInterface, error)
    30  > GetHistoryForKey returns a history of key values across time. GetHistoryForKey requires peer configuration core.ledger.history.enableHistoryDatabase to be true.
    31  
    32  GetQueryResult(query string) (StateQueryIteratorInterface, error)
    33  > GetQueryResult performs a “rich” query against a state database. An iterator is returned which can be used to iterate (next) over the query result set. The query is NOT re-executed during validation phase, phantom reads are not detected. That is, other committed transactions may have added, updated, or removed keys that impact the result set, and this would not be detected at validation/commit time. It is only supported for state databases that support rich query, e.g.CouchDB.
    34  
    35  ### 2. APIs about Transaction Information
    36  With the help of these APIs, information about transactions could be achieved. Proposals are created when users make invocations of chaincodes (Init() when initializing and upgrading, or Invoke() when operating). It is convenient to obtain properties of the current proposal’s structure with these APIs, whose details are listed as follows.
    37  
    38  GetSender() (string, error)
    39  > GetSender returns the sender's address. The address is revealed from his/her signature.
    40  
    41  GetTxID() string
    42  > GetTxID returns the tx_id of the transaction proposal (see ChannelHeader in protos/common/common.proto). Generally, TxID is the digital digest created when making proposals in clients, generated by SHA256 with Nonce and the identity information of the signer.
    43  
    44  GetTxTimestamp() (*timestamp.Timestamp, error)
    45  > GetTxTimestamp returns the timestamp when the transaction was created. This is taken from the transaction ChannelHeader, therefore it will indicate the client's timestamp, and will have the same value across all endorsers.
    46  
    47  GetBinding () ([]byte, error)
    48  > GetBinding returns the transaction binding. Note that binding is the digital digest generated by hashing the information of nonce, creator and epoch in proposals.
    49  
    50  GetSignedProposal() (*pb.SignedProposal, error)
    51  > GetSignedProposal returns the SignedProposal object, which contains all data elements part of a transaction proposal.
    52  
    53  GetCreator() ([]byte, error)
    54  > GetCreator returns SignatureHeader.Creator (e.g. an identity) of the SignedProposal. This is the identity of the agent (or user) submitting the transaction.
    55  
    56  GetTransient() (map[string][]byte, error)
    57  > GetTransient returns ChaincodeProposalPayload.Transient field. It is a map that contains data (e.g. cryptographic material) that might be used to implement some form of application-level confidentiality. The contents of this field, as prescribed by ChaincodeProposalPayload, are supposed to always be omitted from the transaction and excluded from the ledger.
    58  
    59  ### 3. APIs for Parameter Reading
    60  It is able to input several parameters when invoking chaincodes, which can be obtained through APIs. Detail information is listed as follows.
    61  
    62  GetArgs() [][]byte
    63  > GetArgs returns the arguments intended for the chaincode Init and Invoke as an array of byte arrays.
    64  
    65  GetArgsSlice() ([]byte, error)
    66  > GetArgsSlice returns the arguments intended for the chaincode Init and Invoke as a byte array.
    67  
    68  GetFunctionAndParameters() (string, []string)
    69  > GetFunctionAndParameters returns the first argument as the function name and the rest of the arguments as parameters in a string array. Only use GetFunctionAndParameters if the client passes arguments intended to be used as strings.
    70  
    71  GetStringArgs() []string
    72  > GetStringArgs returns the arguments intended for the chaincode Init and Invoke as a string array. Only use GetStringArgs if the client passes arguments intended to be used as strings.
    73  
    74  ### 4. Other APIs
    75  INKchain also provides several assistant interfaces listed as follows.
    76  
    77  CreateCompositeKey(objectType string, attributes []string) (string, error)
    78  > CreateCompositeKey combines the given attributes to form a composite key. The objectType and attributes are expected to have only valid utf8 strings and should not contain U+0000 (nil byte) and U+10FFFF (biggest and unallocated code point). The resulting composite key can be used as the key in PutState().
    79  
    80  SplitCompositeKey(compositeKey string) (string, []string, error)
    81  > SplitCompositeKey splits the specified key into attributes on which the composite key was formed.
    82  
    83  InvokeChaincode(chaincodeName string, args [][]byte, channel string) pb.Response
    84  > InvokeChaincode locally calls the specified chaincode Invoke using the same transaction context; that is, chaincode calling chaincode doesn't create a new transaction message. If the called chaincode is on the same channel, it simply adds the called chaincode read set and write set to the calling transaction. If the called chaincode is on a different channel, only the Response is returned to the calling chaincode; any PutState calls from the called chaincode will not have any effect on the ledger; that is, the called chaincode on a different channel will not have its read set and write set applied to the transaction. Only the calling chaincode's read set and write set will be applied to the transaction.
    85  
    86  SetEvent(name string, payload []byte) error
    87  > SetEvent allows the chaincode to propose an event on the transaction proposal. If the transaction is validated and successfully committed, the event will be delivered to the current event listeners.