Miner API

API reference for miner nodes

APIs for Edge Nodes

Upload a trained local model to miner

POST http://miner_addr:port/new_transaction

Not only model with weight and bias, but also some other info are upload together. We call them as a transaction, which is a concept borrow from blockchain.

Request Body

Name	Type	Description
"author"*	String	unique id of the uploader
"content"*	json	json of model information, check source code for reference.
"type"*	String	fixed as: "localModelWeight"
"timestamp"*	long	timestamp
"plz_spread"	int	whether want the miner to share this local model with other miners, having this field means true.
"seed_name"*	String	seed name of this model

201: Created local model received

{
    // Response
}

400: Bad Request local model invalid

{
    // Response
}

Get the latest global model from the miner

GET http://miner_addr:port/global_model

200: OK the global weight&bias together with all kinds of parameters

GET_resp = {
    "weight": state_dict_of_global_weight,
    "preprocPara": {
	"avg": list_of_avg_double,
	"std": list_of_std_double
	},
    "trainPara": {
        "batch": local_training_batch_size,
	"lr": learning_rate,
	"opt": optimization_algorithm,
	"epoch": local_training_epoch_num,
	"loss": local_training_loss_func,
	},
    "samplePara": {
	"center_freq": center_frequency_int,
	"bandwidth": bandwidth_int,
	},
    "layerStructure": a_list_describe_layer_structure,
    "seed_name": seed_name,
    "generation": generation_number_of_the_seed,
}

APIs for Blockchain

Get the full chain from a miner

GET http://miner_addr:port/chain

200: OK

{
    "length" : length_of_chain_int,
    "chain" : detailed_list_of_blocks
}

Get the length of current chain together with the latest block

GET http://miner_addr:port/chain_simple

Mainly used for faster consensus.

200: OK

{
    "length" : length_of_chain_int,
    "latest_block" : details_of_the_last_block
}

One miner shares his newly mined block with another miner

POST http://miner_addr:port/add_block

Request Body

Name	Type	Description
"local_list"*	json	list of local models, might be empty
"prev_hash"*	String	previous block hash
"time_stamp"*	long	timestamp
"index"*	int	index of this block
"miner"*	String	unique id of the miner of this block
"base_global"*	json	base global model of this block
"hash"*	String	this block's hash
"nonce"*	long	nonce of this block
"difficulty"*	int	difficulty of this blockchain
"seed_name"*	String	seed name of the model
"local_hash"*	String	hash of the local list (to reduce the size)
"new_global"*	json	new global model of this block

200: OK this block is accepted successfully

{
    // Response
}

400: Bad Request this block is inconsistent with local chain

{
    // Response
}

return the list of those local transactions who haven't be included into the block

GET http://miner_addr:port/pending_tx

200: OK

{
    // Response
}

Seed node inject a new seed into miner network through this api

POST http://miner_addr:port/seed_update

Request Body

Name	Type	Description
"name"*	String	name of the new seed
"from"*	String	name of the seed node
"seedWeight"*	json	new global modal of this new seed
"para"*	json	all kinds of para
"peers"*	json	list of peer miners

201: Created Seed accepted

{
    // Response
}

400: Bad Request Seed invalid

{
    // Response
}