Skip to content

Latest commit

 

History

History
715 lines (454 loc) · 18.4 KB

Help.md

File metadata and controls

715 lines (454 loc) · 18.4 KB

casper-swift-sdk manual on classes and methods, serialization

This is the documentation for the method call for Casper RPC and the serialization for Casper Domain Specific Objects

The RPC methods are listed as below:

  1. chain_get_state_root_hash

  2. info_get_peers

  3. info_get_deploy

  4. info_get_status

  5. chain_get_block_transfers

  6. chain_get_block

  7. chain_get_era_info_by_switch_block

  8. state_get_item

  9. state_get_dictionary_item

  10. state_get_balance

  11. state_get_auction_info

The serialization work is done with the following work:

  • Build CLType primitives structure

  • Build CLValue structure

  • Build Casper Domain Specific Objects

  • Serialization of Casper Domain Specific Objects

Classes and methods in detail

RPC Calls

I. Get State Root Hash

1. Method declaration

        public func getStateRootHash(getStateRootHashParam:GetStateRootHashParam)

2. Input & Output:

Input: GetStateRootHashParam object, which consist of a BlockIdentifier enum object, with value of either .Hash(String) or Height(UInt64) or None (if send method without any parameter to get the latest state_root_hash)

Base on the input, the folowing output is possible:

  • Input: Hash(block_hash) with correct block_hash of a block, Output: the state root hash of the block with the specific hash of the input

  • Input: Hash(block_hash) with wrong block_hash or non-exist block_hash, Output: the state root hash of the latest block

  • Input: Height(block_height) with correct block_height, Output: the state root hash of the block with the specific height of the input

  • Input: Height(block_height) with wrong block_height, such as the value is too big, Output: A block not found Error is thrown.

3. Method flow detail:

  • input getStateRootHashParam of type GetStateRootHashParam will be used to make json data for post method
let data = JsonConversion.fromBlockIdentifierToJsonData(input: getStateRootHashParam.block_identifier, method: .chainGetStateRootHash)
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the state root hash is retrieved by running this code line

let stateRootHash = try GetStateRootHash.getStateRootHash(from: responseJSON);

II. Get network peers list

1. Method declaration

public func getPeers()

2. Input & Output:

  • Input: None

  • Output: List of peer defined in class GetPeersResult, which contain a list of PeerEntry - a class contain of nodeId and address.

3. Method flow detail:

  • Call to httpHandler object of HttpHandler class.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the peer list is retrieved by running this code line

let getPeer:GetPeersResult = try GetPeers.getPeers(from: responseJSON)

You can then retrieve all the peer through the getPeer object (of class GetPeersResult), for example this following code log out all retrieved peers:

let peerEntries:[PeerEntry] = getPeer.getPeerMap().getPeerEntryList()
for peerEntry in peerEntries {
    NSLog("Peer address:\(peerEntry.address)")
    NSLog("Peer id:\(peerEntry.nodeID)")
}

III. Get Deploy

1. Method declaration

public func getDeploy(getDeployParam:GetDeployParams)

2. Input & Output:

  • Input: GetDeployParams object, which consist of a deploy_hash string

  • Output: The GetDeployResult class object, which represent all information the deploy should contain.

3. Method flow detail:

  • input getDeployParam of type GetDeployParams will be used to make json data for post method
let params = getDeployParam.toJsonData()
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the GetDeployResult is retrieved by running this code line

let getDeployResult : GetDeployResult = try GetDeploy.getDeploy(from: responseJSON)

You can then retrieve information such as:

  • getDeployResult.api_version

  • getDeployResult.deploy

  • getDeployResult.execution_results

In which from getDeployResult.deploy you can retrieve information such as:

  • getDeployResult.deploy.hash

  • getDeployResult.deploy.header

  • getDeployResult.deploy.payment

  • getDeployResult.deploy.session

  • getDeployResult.deploy.approvals

From getDeployResult.execution_results you can retrieve information such as:

  • getDeployResult.execution_results.first.block_hash

  • getDeployResult.execution_results.first.result

IV. Get Node Status

1. Method declaration

public func getStatus()

2. Input & Output

  • Input: None

  • Output: GetStatusResult object, which contain all information of a node status

3. Method flow detail:

  • Call to httpHandler object of HttpHandler class.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the GetStatusResult is retrieved by running this code line

let getStatusResult:GetStatusResult = try GetStatus.getStatus(from:responseJSON)

You can then get the state root hash or peer entry list by taking the following attribute of the returning object:

  • getStatusResult.starting_state_root_hash for the state root hash

  • getStatusResult.peers.getPeerEntryList() for the peer entry list

V. Get BlockTransfers

1. Method declaration

public func getBlockTransfers(input:BlockIdentifier)

2. Input & Output:

  • Input: BlockIdentifier enum object, with value of either .Hash(String) or Height(UInt64)

  • Output: GetBlockTransfersResult object, which contain all information of block transfer

3. Method flow detail:

  • input of type BlockIdentifier will be used to make json data for post method
let jsonData = JsonConversion.fromBlockIdentifierToJsonData(input:input,method: .chainGetBlockTransfer)
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the GetBlockTransfersResult is retrieved by running this code line

let getBlockTransferResult:GetBlockTransfersResult = try GetBlockTransfers.getResult(from: responseJSON)

You can then get the information of the GetBlockTransfersResult by using the following properties:

  • getBlockTransferResult.api_version

  • getBlockTransferResult.block_hash

  • getBlockTransferResult.transfers

VI. Get Block

1. Method declaration

public func getBlock(input:BlockIdentifier)

2. Input & Output:

  • Input: BlockIdentifier enum object, with value of either .Hash(String) or Height(UInt64)

  • Output: GetBlockResult object, which contain all information of a block

3. Method flow detail:

  • input of type BlockIdentifier will be used to make json data for post method
let jsonData = JsonConversion.fromBlockIdentifierToJsonData(input: input, method: .chainGetBlock)
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the GetBlockResult is retrieved by running this code line

let getBlockResult:GetBlockResult = try GetBlock.getBlock(from: responseJSON)

From this you can get the block information by using the following properties:

  • getBlockResult.apiVersion

  • getBlockResult.block.hash

  • getBlockResult.block.header

  • getBlockResult.block.body

  • getBlockResult.block.proofs

VII. Get EraInfo By Switch Block

1. Method declaration

public func getEraBySwitchBlock(input:BlockIdentifier)

2. Input & Output:

  • Input: BlockIdentifier enum object, with value of either .Hash(String) or Height(UInt64)

  • Output: GetEraInfoResult object

3. Method flow detail:

  • input of type BlockIdentifier will be used to make json data for post method
let params = JsonConversion.fromBlockIdentifierToJsonData(input: input, method: .chainGetEraInfoBySwitchBlock)
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the GetEraInfoResult is retrieved by running this code line

let eraResult:GetEraInfoResult = try GetEraInfoBySwitchBlock.getResult(from: responseJSON)

You can then retrieve information such as:

  • eraResult.api_version

  • eraResult.era_summary.block_hash

  • eraResult.era_summary.era_id

  • eraResult.era_summary.stored_value

  • eraResult.era_summary.state_root_hash

  • eraResult.era_summary.merkle_proof

VIII. Get StateItem

1. Method declaration

    public func getItem(input:GetItemParams)

2. Input & Output: GetItemParams which is defined as

  • Input:
 public class GetItemParams {
    public var state_root_hash:String?
    public var key:String?
    public var path:[String]?
}

Output: GetItemResult object

3. Method flow detail:

  • input of type GetItemParams will be used to make json data for post method
let params = JsonConversion.fromGetStateItemToJsonData(input:input)
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the GetItemResult is retrieved by running this code line

let getStateItemResult: GetItemResult =  GetItem.getItem(from:responseJSON)

You can then retrieve information such as:

  • getStateItemResult.api_version

  • getStateItemResult.stored_value

  • getStateItemResult.merkle_proof

IX. Get DictionaryItem

1. Method declaration

public func getDictionaryItem(from:GetDictionaryItemParams)

2. Input & Output: GetDictionaryItemParams which is defined as

  • Input:
public class GetDictionaryItemParams : Codable {
    var state_root_hash:String!;
    var dictionary_identifier: DictionaryIdentifier!;
}

in which DictionaryIdentifier is an enum defined as

public enum DictionaryIdentifier : Codable {
    case AccountNamedKey(key:String,dictionary_name:String,dictionary_item_key:String)
    case ContractNamedKey(key:String,dictionary_name:String,dictionary_item_key:String)
    case URef(seed_uref:String,dictionary_item_key:String)
    case Dictionary(String)
}
  • Output: GetDictionaryItemResult object

3. Method flow detail:

  • input of type GetDictionaryItemParams will be used to make json data for post method
let jsonData = try from.toJsonData() // from is the GetDictionaryItemParams object
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: data)

In the handleRequest function the GetDictionaryItemResult is retrieved by running this code line

let getDictionaryItemResult : GetDictionaryItemResult = try GetDictionaryItemResult.getResult(from: responseJSON)

You can then retrieve information such as:

  • getDictionaryItemResult.api_version

  • getDictionaryItemResult.dictionary_key

  • getDictionaryItemResult.stored_value

  • getDictionaryItemResult.merkle_proof

X. Get Balance

1. Method declaration

public func getStateBalance(input:GetBalanceParams)

2. Input & Output :

  • Input: GetBalanceParams which is defined as
 public class GetBalanceParams {
    public var state_root_hash:String = ""
    public var purse_uref:String = ""
}
  • Output: GetBalanceResult object

3. Method flow detail:

  • input of type GetBalanceParams will be used to make json data for post method
let jsonData = JsonConversion.fromGetBalanceParamsToJsonData(input: input)
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: jsonData)

In the handleRequest function the GetBalanceResult is retrieved by running this code line

let getBalanceResult:GetBalanceResult = try GetBalance.getStateBalanceFromJson(from: responseJSON)

You can then retrieve information such as:

  • getBalanceResult.api_version

  • getBalanceResult.balance_value

  • getBalanceResult.merkle_proof

XI. Get current auction state

1. Method declaration

public func getAuctionInfo(input:BlockIdentifier)

2. Input & Output:

  • Input: BlockIdentifier enum object, with value of either .Hash(String) or Height(UInt64)

  • Output: GetAuctionInfoResult object

3. Method flow detail:

  • input of type BlockIdentifier will be used to make json data for post method
let paramJsonData = JsonConversion.fromBlockIdentifierToJsonData(input: input, method: .stateGetAuctionInfo)
  • Then json data will be sent to the httpHandler object of HttpHandler class with the method call and json data just generated.
httpHandler.handleRequest(method: methodCall, params: jsonData)

In the handleRequest function the GetBalanceResult is retrieved by running this code line

let getAuctionInfo:GetAuctionInfoResult = try GetAuctionInfo.getAuctionInfo(from: responseJSON)

You can then retrieve information such as:

  • getAuctionInfo.api_version

  • getAuctionInfo.auction_state.state_root_hash

  • getAuctionInfo.auction_state.block_height

  • getAuctionInfo.auction_state.era_validators

CLType, CLValue, Casper Domain Specific Objects and Serialization

CLType

Implemented in enumeration type, declared as below code:

public enum CLType {
    case Bool
    case I32
    case I64
    case U8
    case U32
    case U64
    case U128
    case U256
    case U512
    case Unit
    case String
    case Key
    case URef
    case PublicKey
    case BytesArray(UInt32);
    indirect case Result(CLType,CLType)
    indirect case Option(CLType)
    indirect case List(CLType)
    indirect case FixedList(CLType)
    indirect case Map(CLType,CLType)
    indirect case Tuple1(CLType)
    indirect case Tuple2(CLType,CLType)
    indirect case Tuple3(CLType,CLType,CLType)
    case CLAny
    case NONE
}

CLValue

Implemented in enumeration type with name CLValueWrapper, declared as below code:

public enum CLValueWrapper {
    case Bool(Bool)
    case I32(Int32)
    case I64(Int64)
    case U8(UInt8)
    case U32(UInt32)
    case U64(UInt64)
    case U128(U128Class)
    case U256(U256Class)
    case U512(U512Class)
    case Unit(String)
    case String(String)
    case Key(String)
    case URef(String)
    case PublicKey(String)
    case BytesArray(String)
    indirect case OptionWrapper(CLValueWrapper)
    indirect case ListWrapper([CLValueWrapper])
    indirect case FixedListWrapper([CLValueWrapper])
    indirect case ResultWrapper(String,CLValueWrapper)
    indirect case MapWrapper([CLValueWrapper],[CLValueWrapper])
    indirect case Tuple1Wrapper(CLValueWrapper)
    indirect case Tuple2Wrapper(CLValueWrapper,CLValueWrapper)
    indirect case Tuple3Wrapper(CLValueWrapper,CLValueWrapper,CLValueWrapper)
    case AnyCLValue(AnyObject)
    case NULL
    case NONE
}

This CLValue enumeration data structure contain both the type of CLType and the corresponding value for CLType. For example if CLValueWrapper has the value of .String("Hello, World!") then the CLType is String and the value is "Hello, World!"

If CLValueWrapper has the value of .ListWrapper([UInt32(1),UInt32(2),UInt32(3)]) then the CLType is List and the value is a list of 3 UInt32 elements with value [1,2,3]

Casper Domain Specific Objects:

Are built with corresponding Swift classes, and in Entity folder

For example Deploy class is declared as:

public class Deploy {
    public var hash:String = "";
    public var approvals:[DeployApprovalItem] = [DeployApprovalItem]();
    public var header:DeployHeader = DeployHeader();
    public var payment:ExecutableDeployItem?;
    public var session:ExecutableDeployItem?;
}

The DeployHeader is declared as:

public class DeployHeader {
    public var account:String = "";
    public var body_hash:String = "";
    public var chain_name:String = "";
    public var gas_price:UInt64 = 0;
    public var timestamp:String = "";
    public var ttl:String = "";
    public var dependencies:[String] = [String]();
}

payment and session in Deploy are of type ExecutableDeployItem, which an enumeration type, declared as:

public enum ExecutableDeployItem {
    case ModuleBytes (module_bytes:Bytes, args: RuntimeArgs)
    case StoredContractByHash(hash:String,entry_point:String,args:RuntimeArgs)
    case StoredContractByName(name:String,entry_point:String,args:RuntimeArgs)
    case StoredVersionedContractByHash (hash:String,version:UInt32?,entry_point:String,args:RuntimeArgs)
    case StoredVersionedContractByName(name:String,version:UInt32?,entry_point:String,args:RuntimeArgs)
    case Transfer(args:RuntimeArgs)
    case NONE
}

DeployApprovalItem class is declared as:

public class DeployApprovalItem {
    public var signature:String = "";
    public var signer:String = "";
}

Serialization

The serialization for CLType, CLValue and Deploy (which consists of Deploy Header, Deploy Session, Deploy Payment, Approvals) is implemented based on the document at this address: https://casper.network/docs/design/serialization-standard#serialization-standard-state-keys

For CLType and CLValue, the serialization is done within class CLTypeSerializeHelper, which consists of two main methods:

  • CLTypeSerialize is for CLType serialization

  • CLValueSerialize is for CLValue serialization

For Deploy and Deploy related objects (Deploy Header, Deploy Session, Deploy Payment, Approvals) is done within file DeploySerialization.swift, in which there are classes for the serialization work

  • DeploySerialization class is for Deploy Serialization

  • DeployHeaderSerialization class is for Deploy Header Serialization

  • ExecutableDeployItemSerializaton class is for Session and Payment Serialization

  • DeployApprovalSerialization class is for Approval Serialization