-
Notifications
You must be signed in to change notification settings - Fork 712
api
AurelienFT edited this page Apr 12, 2022
·
16 revisions
This crate exposes Rust methods (through the Endpoints trait) as
JSON-RPC API endpoints (thanks to the ParityJSON-RPC crate).
E.g. this curl command will call endpoint stop_node (and stop the
locally running massa-node):
curl -X POST -H "Content-Type: application/json" -d '{"jsonrpc": "2.0", "method": "stop_node", "id": 123 }' 127.0.0.1:33034Endpoints are organized in 2 authorizations levels:
a.k.a. "user mode" endpoints (running by default on [::]:33035)
Summary of the current state: time, last final blocks (hash, thread, slot, timestamp), clique count, connected nodes count.
-
No parameters.
-
Return:
{
"config": {
"block_reward": String, // represent an Amount in coins
"delta_f0": Number, // Used to compute finality threshold
"end_timestamp": null or Number, // millis since 1970-01-01 (only in tesnets)
"genesis_timestamp": Number, // millis since 1970-01-01
"operation_validity_periods": Number,
"periods_per_cycle": Number,
"pos_lock_cycles": Number,
"pos_lookback_cycles": Number,
"roll_price": String, // represent an Amount in coins
"t0": Number, // millis between to slots in the same thread
"thread_count": Number
},
"connected_nodes": {
"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx": String // Node id -> ip address
},
"consensus_stats": {
"clique_count": Number,
"end_timespan": Number,// stats time interval, millis since 1970-01-01
"final_block_count": Number,
"final_operation_count": Number,
"staker_count": Number,
"stale_block_count": Number,
"start_timespan": // stats time interval, millis since 1970-01-01
},
"current_cycle": Number,
"current_time": Number, // millis since 1970-01-01
"last_slot": {
"period": Number,
"thread": Number
},
"network_stats": {
"active_node_count": Number,
"banned_peer_count": Number,
"in_connection_count": Number,
"known_peer_count": Number,
"out_connection_count": Number
},
"next_slot": {
"period": Number,
"thread": Number
},
"node_id": String,
"node_ip": null or String, // ip address if provided
"pool_stats": {
"endorsement_count": Number,
"operation_count": Number
},
}Get cliques.
-
No parameters.
-
Return:
[
{
"block_ids": [String],
"fitness": Number,
"is_blockclique": Boolean,
},
];Returns the active stakers and their roll counts for the current cycle.
-
No parameters.
-
Return:
{
"xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx": Number
} // Dictionnary associating staker addresses to their active roll countsReturns operations information associated to a given list of operations' IDs.
- Parameters:
[String]. // String must be an operation Id- Return:
[
{
"id": String, // Operation id
"in_blocks": [String], // Block ids
"in_pool": Boolean,
"is_final": Boolean,
"operation": {
"content": {
"expire_period": Number,// after that period, the operation become invalid forever
"fee": String, // represent an Amount in coins
"op": {
"Transaction": {
"amount": String, // represent an Amount in coins
"recipient_address": String
}
OR
"RollBuy": {
"roll_count": Number
}
OR
"RollSell": {
"roll_count": Number
}
OR
"ExecuteSC": {
"data": [Number], // vec of bytes to execute
"max_gas": Number, // maximum amount of gas that the execution of the contract is allowed to cost.
"coins": String, // represent an Amount in coins that are spent by consensus and are available in the execution context of the contract.
"gas_price": String, // represent an Amount in coins, price per unit of gas that the caller is willing to pay for the execution.
}
OR
"CallSC": {
"target_addr": String, // Address
"target_func": String, // Function name
"param": String, // Parameter to pass to the function
"max_gas": Number,
"sequential_coins": Number, // Amount
"parallel_coins": Number, // Amount
"gas_price": Number, // Amount
}
},
"sender_public_key": String
},
"signature": String
}
}
]Get endorsements
- Parameters:
[String]; // string must be an endorsement id- Return:
[{
"id": String, // EndorsementId,
"in_pool": Boolean,
"in_blocks": [String], // BlockId,
"is_final": Boolean,
"endorsement": {
"content":{
"sender_public_key": String,
"slot": {
"period": Number,
"thread": Number
},
"index": Number,
"endorsed_block": String // BlockId,
}
"signature": String
}
}]Get information on a block given its hash.
- Parameters:
[String]; // Block IDs- Return:
{
"id": String // BlockId,
"content": Null or {
"is_final": bool,
"is_stale": bool,
"is_in_blockclique": bool,
"block": {
"header": {
"content": {
"endorsed_block": String, // Block id
"index": Number,
"sender_public_key": String,
"slot": { // endorsed block slot: deifferent from block's slot
"period": Number,
"thread": Number
}
},
"signature": String
}
],
"operation_merkle_root": String, // Hash of all operations
"parents": [String], // Block ids, as many as thread count
"slot": {
"period": Number,
"thread": Number
}
},
"signature": String
},
"operations": [
{
"content": {
"expire_period": Number,
"fee": String, // represent an Amount in coins
"op": {
"Transaction": {
"amount": String, // represent an Amount in coins
"recipient_address": String
}
OR
"RollBuy": {
"roll_count": Number
}
OR
"RollSell": {
"roll_count": Number
}
OR
ExecuteSC {
"data": [Number], // vec of bytes to execute
"max_gas": Number, // maximum amount of gas that the execution of the contract is allowed to cost.
"coins": String, // represent an Amount in coins that are spent by consensus and are available in the execution context of the contract.
"gas_price": String, // represent an Amount in coins, price per unit of gas that the caller is willing to pay for the execution.
}
},
"sender_public_key": String
},
"signature": String
}
]
},
"is_final": Boolean,
"is_in_blockclique": Boolean,
"is_stale": Boolean
},
}Get the block graph within the specified time interval.
- Parameters:
{
"start": null or Number, // in millis since 1970-01-01, field may be omitted
"end": null or Number,// in millis since 1970-01-01, field may be omitted
}- Return:
[
{
"creator": String, // public key
"id": String, // Block Id
"is_final": Boolean,
"is_in_blockclique": Boolean,
"is_stale": Boolean,
"parents": [String], // as many block Ids as there are threads
"slot": {
"period": Number,
"thread": Number,
},
},
];Get addresses.
- Parameters:
[
[String], // Addresses
];- Return:
[
{
"address": String,
"balance": {
"candidate_balance": String, // represent an Amount in coins
"final_balance": String, // represent an Amount in coins
"locked_balance": String, // represent an Amount in coins
},
"block_draws": [
{
"period": Number,
"thread": Number,
},
],
"blocks_created": [String], // Block ids
"endorsement_draws": [
{
"slot": {
"period": Number,
"thread": Number,
},
"index": Number,
},
],
"involved_in_endorsements": [String], // Endorsement Id
"involved_in_operations": [String], // Operation id
"production_stats": [
// as many items as cached cycles
{
"cycle": Number,
"is_final": Boolean,
"nok_count": Number,
"ok_count": Number,
},
],
"rolls": {
"active_rolls": Number,
"candidate_rolls": Number,
"final_rolls": Number,
},
"thread": Number,
"final_sce_ledger_info": {
"balance": String // reprensents an amount
"module": [Number] // stored bytecode
"datastore": {
xxxxxxxxxxxxxxxxxxxxxx: [Number] // bytes
}
},
"candidate_sce_ledger_info": {
"balance": String // reprensents an amount
"module": [Number] // stored bytecode
"datastore": {
xxxxxxxxxxxxxxxxxxxxxx: [Number] // bytes
}
}
},
];Adds operations to pool. Returns operations that were ok and sent to pool.
- Parameters:
[[
{
"content": {
"expire_period": Number,
"fee": String, // represent an Amount in coins
"op": {
"Transaction": {
"amount": String, // represent an Amount in coins
"recipient_address": String
}
OR
"RollBuy": {
"roll_count": Number
}
OR
"RollSell": {
"roll_count": Number
}
OR
"ExecuteSC": {
"data": [Number], // vec of bytes to execute
"max_gas": Number, // maximum amount of gas that the execution of the contract is allowed to cost.
"coins": String, // represent an Amount in coins that are spent by consensus and are available in the execution context of the contract.
"gas_price": String, // represent an Amount in coins, price per unit of gas that the caller is willing to pay for the execution.
}
OR
"CallSC": {
"target_addr": String, // Address
"target_func": String, // Function name
"param": String, // Parameter to pass to the function
"max_gas": Number,
"sequential_coins": Number, // Amount
"parallel_coins": Number, // Amount
"gas_price": Number, // Amount
}
},
"sender_public_key": String
},
"signature": String
}
]]- Return:
[String], // Operation idsReturns events optionally filtered by: start slot, end slot, emitter address, original caller address, operation id
It will take the interval start slot..=end slot
- Parameters:
{
"start": null OR {
"period": Number, // will use by default Slot(0,0)
"thread": Number // will use by default Slot(0,0)
},
"end": null OR {
"period": Number, // will use by default Slot(0,0)
"thread": Number // will use by default Slot(0,0)
},
"emitter_address": null OR String, // Address
"original_caller_address": null OR String, // Address
"original_operation_id": null OR String, // operation id
}- Return:
[
{
"data": String, // Arbitrary json string generated by the smart contract
"id": String // event id
"context":{
"slot": {
"period": Number,
"thread": Number
},
"block": null OR String // block id,
"read_only": Boolean // wether the event was generated during read only call
"call_stack": [String], //Addresses
"index_in_slot": Number,
"origin_operation_id": null OR String // operation id
}
}
]Call a function of a contract in a read only context. The changes on the ledger will not be applied and directly drop after the context of the execution. All the events generated will be returned :
- Parameters:
[
{
"max_gas": Number,
"simulated_gas_price": Number,
"target_address": String,
"target_function": String,
"parameter": String,
"caller_address": String OR null,
}
]- Returns:
[
{
"executed_at": {
"period": Number,
"thread": Number
},
"result": String, //"ok" or error message
"output_events": [
// Each id is a event id. The size of this array is dynamic over the number of events pop in the execution.
"id1": {
"id": String, //id of the event
"context": {
"slot": {
"period": Number,
"thread": Number
},
"block": null OR String // block id,
"read_only": Boolean // wether the event was generated during read only call
"call_stack": [String], //Addresses
"index_in_slot": Number,
"origin_operation_id": null OR String // operation id
}
"data": String // String of the event you sended
}
]
}
]Execute a smart contract in a read only context. The changes on the ledger will not be applied and directly drop after the context of the execution. All the events generated will be returned :
- Parameters:
[
{
"max_gas": Number,
"simulated_gas_price": Number,
"bytecode": [Number],
"address": String OR null,
}
]- Returns:
[
{
"executed_at": {
"period": Number,
"thread": Number
},
"result": String, //"ok" or error message
"output_events": [
// Each id is a event id. The size of this array is dynamic over the number of events pop in the execution.
"id1": {
"id": String, //id of the event
"context": {
"slot": {
"period": Number,
"thread": Number
},
"block": null OR String // block id,
"read_only": Boolean // wether the event was generated during read only call
"call_stack": [String], //Addresses
"index_in_slot": Number,
"origin_operation_id": null OR String // operation id
}
"data": String // String of the event you sended
}
]
}
]a.k.a. "manager mode" endpoints (running by default on 127.0.0.1:33034)
Gracefully stop the node.
-
No parameters.
-
No return.
Sign message with node's key.
- Parameter:
[u8];- Return:
{"public_key": String, "signature": String}Where public_key is the public key used to sign the input and signature, the resulting signature.
Add a vec of new private keys for the node to use to stake.
- Parameter:
[String];The strings must be private keys.
- No return.
Remove a vec of addresses used to stake.
- Parameter:
[String];The strings must be addresses.
- No return.
Return hashset of staking addresses.
-
No parameters.
-
Return:
[String];The strings are addresses.
Bans given IP addresses.
- Parameter:
[String];The strings must be ip addresses.
- No return.
Unbans given IP addresses.
- Parameter:
[String];The strings must be ip addresses.
- No return.