Skip to content

API

Jump to bottom
Egor Lysenko edited this page Aug 7, 2020 · 7 revisions

Lachesis API

Lachesis fully supports web3.js API. There are some subtle differences due to the graph structure of the ledger. The current doc describes only the differences from web3 API.

For support of web3.js, please refer to web3 for details.

Differences from web3.js API

Pending blocks

Retrieval of pending blocks isn't supported, because Lachesis doesn't have this entity.

Block Header fields

  • "nonce" is always 0
  • "mixHash" is always 0
  • "sha3Uncles" is always 0
  • "logsBloom" is always 0 (Lachesis uses the DB index for efficient logs search, instead of Bloom filters)
  • "mixHash" is always 0
  • "miner" field is an undefined address
  • "difficulty" is always 0
  • "extraData" is always empty
  • "gasLimit" is always 0xFFFFFFFFFFFF , i.e. infinite (Lachesis has a different transaction authorization mechanism)
  • "transactionsRoot" is always 0
  • "receiptsRoot" is always 0
  • "timestampNano" additional field, returns block's consensus time in UnixNano

Transactions Receipt fields

  • "logsBloom" is always 0 (Lachesis uses the DB index for efficient logs search, instead of Bloom filters)

Not supported namespaces

  • shh
  • db
  • bzz

Ftm API calls

ftm_getEvent

returns Lachesis event by hash or short ID

Parameters:

  • String, - full event ID (hex-encoded 32 bytes) or short event ID.
  • Boolean, - If true it returns the full transaction objects, if false only the hashes of the transactions.

Returns:

  • Object - An event object, or null when no event was found:
  • version: QUANTITY - the event version.
  • epoch: QUANTITY - the event epoch number.
  • seq: QUANTITY - the event sequence number.
  • hash: DATA, 32 Bytes - full event ID.
  • frame: QUANTITY - event's frame number.
  • isRoot: Boolean - true if event is root.
  • creator: DATA, 20 Bytes - the address of the event creator (validator).
  • prevEpochHash: DATA, 32 Bytes - the hash of the state of previous epoch
  • parents: Array, - array of event IDs
  • gasPowerLeft: QUANTITY - event's not spent gas power.
  • gasPowerUsed: QUANTITY - event's spent gas power.
  • lamport: QUANTITY - event's Lamport index.
  • claimedTime: QUANTITY - the UnixNano timestamp of creator's local creation time.
  • medianTime: QUANTITY - the UnixNano timestamp of the secure median time.
  • extraData: DATA - the "extra data" field of this event.
  • transactionsRoot: DATA, 32 Bytes - the root of the transaction trie of the event.
  • transactions: Array - Array of transaction objects, or 32 Bytes transaction hashes depending on the last given parameter.
Example with short ID

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getEvent","params":["1:3:a2395846", true],"id":1}' localhost:18545

Example with full ID

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getEvent","params":["0x00000001000000039bcda184cc9e2b20386dcee5f39fe3c4f36f7b47c297ff2b", true],"id":1}' localhost:18545

ftm_getEventHeader

returns the Lachesis event header by hash or short ID.

Parameters:

  • String - full event ID (hex-encoded 32 bytes) or short event ID.

Returns:

  • Object - An event object, or null when no event was found:
  • version: QUANTITY - the event version.
  • epoch: QUANTITY - the event epoch number.
  • seq: QUANTITY - the event sequence number.
  • hash: DATA, 32 Bytes - full event ID.
  • seq: QUANTITY - the event sequence number.
  • frame: QUANTITY - event's frame number.
  • isRoot: Boolean - true if event is root.
  • creator: QUANTITY, - the ID of the event creator (validator).
  • prevEpochHash: DATA, 32 Bytes - the hash of the state of previous epoch
  • parents: Array, - array of event IDs
  • gasPowerLeft.shortTerm: QUANTITY - event's not spent gas power in short-term gas power window.
  • gasPowerLeft.longTerm: QUANTITY - event's not spent gas power in long-term gas power window.
  • gasPowerUsed: QUANTITY - event's spent gas power.
  • lamport: QUANTITY - event's Lamport index.
  • claimedTime: QUANTITY - the UnixNano timestamp of creator's local creation time.
  • medianTime: QUANTITY - the UnixNano timestamp of the secure median time.
  • extraData: DATA - the "extra data" field of this event.
  • transactionsRoot: DATA, 32 Bytes - the hash of transactions of the event.
Example with short ID

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getEventHeader","params":["1:3:a2395846"],"id":1}' localhost:18545

Example with full ID

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getEventHeader","params":["0x00000001000000039bcda184cc9e2b20386dcee5f39fe3c4f36f7b47c297ff2b"],"id":1}' localhost:18545

ftm_getHeads

returns IDs of all the epoch events with no descendants in a given epoch

Parameters:

  • String, - epoch number (HEX-encoded) for a specific epoch (pass “latest” to uselatest latest epoch; pass “pending” to use latest sealed epoch).

Returns:

  • Array - Array of event IDs

Example:

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getHeads","params":["latest"],"id":1}' localhost:18545

ftm_getConsensusTime

returns event's consensus time, if event is confirmed (more accurate than MedianTime)

Parameters

  • String, - full event ID (hex-encoded 32 bytes) or short event ID.

Returns

  • QUANTITY - the UnixNano timestamp of the secure and accurate consensus time.
Example with short ID

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getConsensusTime","params":["1:3:a2395846"],"id":1}' localhost:18545

Example with full ID

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getConsensusTime","params":["0x00000001000000039bcda184cc9e2b20386dcee5f39fe3c4f36f7b47c297ff2b"],"id":1}' localhost:18545

ftm_currentEpoch

returns current epoch number

Returns:

  • String - epoch number (HEX-encoded)

Example:

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_currentEpoch","id":1}' localhost:18545

ftm_getEpochStats

returns epoch statistics

Parameters:

  • String, - epoch number (HEX-encoded) for a specific epoch (pass “latest” to use latest epoch; pass “pending” to use latest sealed epoch).

Returns:

  • Object - An status object, or null when no epoch was found:
  • epoch: QUANTITY - the epoch number.
  • start: QUANTITY - the UnixNano timestamp of epoch's start time.
  • end: QUANTITY - the UnixNano timestamp of epoch's end time.
  • totalFee: QUANTITY - the total epoch's fee.
  • totalBaseRewardWeight: QUANTITY - the total epoch's base reward weight.
  • totalTxRewardWeight: QUANTITY - the total epoch's tx reward weight.

Example:

curl -X POST -H "Content-Type: application/json" --data '{"jsonrpc":"2.0","method":"ftm_getEpochStats","params":["latest"],"id":1}' localhost:18545

Sfc API calls

sfc_getValidationScore

return score of validators.

Parameters:

  • Int - stakerID

Returns:

  • Int - score of staker as decimal int

sfc_getOriginationScore

return origination score of staker.

Parameters:

  • Int - stakerID

Returns

  • Int - origination score of staker as decimal int

sfc_getStakerPoI

return staker POI.

Parameters:

  • Int - stakerID

Returns

  • Int - POI of staker as decimal int

sfc_getRewardWeights

return reward weights information for staker.

Parameters:

  • Int - stakerID

Returns:

  • Object - reward waights information:
    • baseRewardWeight: Int
    • txRewardWeight: Int

sfc_getDowntime

return information about staker downtime.

Parameters:

  • Int - stakerID

Returns:

  • Object - downtime information:
    • downtime: Int
    • missedBlocks: Int

sfc_getStaker

return staker information.

Parameters:

  • Int - stakerID
  • Int - verbosity level (1-2)

Returns:

Object - staker information for verbosity level 1:

  • address: HexStr
  • createdEpoch: Int
  • createdTime: Int UnixTime
  • deactivatedEpoch: Int
  • deactivatedTime: Int UnixTime
  • delegatedMe: Int
  • id:Int
  • isActive: boolean
  • isCheater: boolean
  • isOffline: boolean
  • isValidator: boolean
  • stake: Int
  • totalStake: Int

Addition fields for verbosity level 2:

  • baseRewardWeight: Int
  • claimedRewards: Int
  • delegationsClaimedRewards: Int
  • downtime: Int
  • missedBlocks: Int
  • originationScore: Int
  • poi: Int
  • txRewardWeight: Int
  • validationScore: Int

sfc_getStakerByAddress

return staker information.

Parameters:

  • String - staker address (hex)
  • Int - verbosity level (1-2)

Returns

  • Object - staker information (see sfc_getStaker return data)

sfc_getStakers

return list of stakers data.

Parameters:

  • String - staker address (hex)
  • Int - verbosity level (1-2)

Returns:

List of stakers information (see sfc_getStaker return data) by stakers Id.

For verbosity 0 - list of stakers id:

  • [<staker id 1:Int>, <staker id 2:Int>, ...]

For verbosity 1 and 2 - list of stakers objects like sfc_getStaker return data:

  • [{<staker 1 data>}, {<staker 2 data>}, ...]

sfc_getDelegationsOf

return list of delegations of a staker.

Parameters:

  • Int - staker id
  • Int - verbosity level (1-2)

Returns:

List of delegations information. If verbosity level is 0, then include only addresses. If >= 1, then include base fields. If >= 2, then include metrics.

Base fields:

  • address: Hex
  • toStakerID: Int
  • amount: Int
  • createdEpoch: Int
  • createdTime: Int UnixTime
  • deactivatedEpoch: Int
  • deactivatedTime: Int UnixTime

Metrics fields:

  • claimedRewards: Int

sfc_getDelegation

returns SFC delegation info.

Parameters:

  • String - delegation address (hex)
  • Int - staker ID
  • Int - verbosity level (1-2)

Returns:

If verbosity level is 1, then include base fields. If >= 2, then include metrics.

sfc_getDelegationsByAddress

returns SFC delegations of a delegator

Parameters:

  • String - delegation address (hex)
  • Int - verbosity level (1-2)

Returns:

If verbosity level is 1, then include base fields. If >= 2, then include metrics.

sfc_getDelegationClaimedRewards

returns sum of claimed rewards in past, by this delegation.

Parameters:

  • String - delegation address (hex)
  • Int - staker ID

Returns:

  • Int - delagator claimed rewards.

sfc_getStakerClaimedRewards

returns sum of claimed rewards in past, by this staker.

Parameters:

  • Int - staker ID

Returns:

  • Int - staker claimed rewards.

sfc_getStakerDelegationsClaimedRewards

returns sum of claimed rewards in past, by all delegations of this staker.

Parameters:

  • Int - staker ID

Returns:

  • Int - staker delagators claimed rewards.

Debug API

debug_blocksTTF

TtfReport for a range of blocks.

Parameters:

  • Int - until block (pass “latest” to use latest block)
  • Int - max blocks
  • String - mode ("arrival_time", "claimed_time")
  • Int - verbosity (If 0, then include only avg, min, max. If >= 1, then include histogram with 6 bins. If >= 2, then include histogram with 16 bins. If >= 3, then include raw data.)

Returns:

Object - ttf report

For verbosity 0:

  • stats:
    • avg: string - time (for example: “1s”)
    • max: string - time
    • min: string - time
    • samples: Int

Addition data for verbosity 1, 2:

  • histogram: list of data for histogram
    • count: Int
    • mean: String - time

Addition data for verbosity 3:

  • raw: Object - raw data

debug_validatorTimeDrifts

Return validator time drifts for an epoch.

Parameters:

  • Int - epoch number (HEX-encoded) for a specific epoch (pass “latest” to use latest epoch; pass “pending” to use latest sealed epoch).
  • Int - max events
  • Int - verbosity (If 0, then include only avg, min, max. If >= 1, then include histogram with 6 bins. If >= 2, then include histogram with 16 bins. If >= 3, then include raw data.)

Returns:

Object - data by validators (validator id like key):

For verbosity 0:

  • stats:
    • avg: string - time (for example: “1s”)
    • max: string - time
    • min: string - time
    • samples: Int

Addition data for verbosity 1, 2:

  • histogram: list of data for histogram
    • count: Int
    • mean: String - time

Addition data for verbosity 3:

  • raw: Object - raw data

debug_validatorVersions

Return validators versions data for epoch.

Parameters:

  • Int - epoch number (HEX-encoded) for a specific epoch (pass “latest” to use latest epoch; pass “pending” to use latest sealed epoch).
  • Int - max events

Returns:

Object - versions by validators (validator id like key):

  • <Int: validator ID>: <String: validator version>
Clone this wiki locally