> For the complete documentation index, see [llms.txt](https://neutrinoliu.gitbook.io/fiesta/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://neutrinoliu.gitbook.io/fiesta/api-reference/miner-api.md).

# Miner API

API reference for miner nodes

#### APIs for Edge Nodes

## Upload a trained local model to miner

<mark style="color:green;">`POST`</mark> `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"<mark style="color:red;">\*</mark>     | String | unique id of the uploader                                                                         |
| "content"<mark style="color:red;">\*</mark>    | json   | json of model information, check source code for reference.                                       |
| "type"<mark style="color:red;">\*</mark>       | String | fixed as: "localModelWeight"                                                                      |
| "timestamp"<mark style="color:red;">\*</mark>  | long   | timestamp                                                                                         |
| "plz\_spread"                                  | int    | whether want the miner to share this local model with other miners, having this field means true. |
| "seed\_name"<mark style="color:red;">\*</mark> | String | seed name of this model                                                                           |

{% tabs %}
{% tab title="201: Created local model received" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request local model invalid" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

## Get the latest global model from the miner

<mark style="color:blue;">`GET`</mark> `http://miner_addr:port/global_model`

{% tabs %}
{% tab title="200: OK the global weight\&bias together with all kinds of parameters" %}

```javascript
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,
}
```

{% endtab %}
{% endtabs %}

#### APIs for Blockchain

## Get the full chain from a miner

<mark style="color:blue;">`GET`</mark> `http://miner_addr:port/chain`

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}

## Get the length of current chain together with the latest block

<mark style="color:blue;">`GET`</mark> `http://miner_addr:port/chain_simple`

Mainly used for faster consensus.

{% tabs %}
{% tab title="200: OK " %}

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

{% endtab %}
{% endtabs %}

## One miner shares his newly mined block with another miner

<mark style="color:green;">`POST`</mark> `http://miner_addr:port/add_block`

#### Request Body

| Name                                             | Type   | Description                                 |
| ------------------------------------------------ | ------ | ------------------------------------------- |
| "local\_list"<mark style="color:red;">\*</mark>  | json   | list of local models, might be empty        |
| "prev\_hash"<mark style="color:red;">\*</mark>   | String | previous block hash                         |
| "time\_stamp"<mark style="color:red;">\*</mark>  | long   | timestamp                                   |
| "index"<mark style="color:red;">\*</mark>        | int    | index of this block                         |
| "miner"<mark style="color:red;">\*</mark>        | String | unique id of the miner of this block        |
| "base\_global"<mark style="color:red;">\*</mark> | json   | base global model of this block             |
| "hash"<mark style="color:red;">\*</mark>         | String | this block's hash                           |
| "nonce"<mark style="color:red;">\*</mark>        | long   | nonce of this block                         |
| "difficulty"<mark style="color:red;">\*</mark>   | int    | difficulty of this blockchain               |
| "seed\_name"<mark style="color:red;">\*</mark>   | String | seed name of the model                      |
| "local\_hash"<mark style="color:red;">\*</mark>  | String | hash of the local list (to reduce the size) |
| "new\_global"<mark style="color:red;">\*</mark>  | json   | new global model of this block              |

{% tabs %}
{% tab title="200: OK this block is accepted successfully" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request this block is inconsistent with local chain" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:blue;">`GET`</mark> `http://miner_addr:port/pending_tx`

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}

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

<mark style="color:green;">`POST`</mark> `http://miner_addr:port/seed_update`

#### Request Body

| Name                                           | Type   | Description                       |
| ---------------------------------------------- | ------ | --------------------------------- |
| "name"<mark style="color:red;">\*</mark>       | String | name of the new seed              |
| "from"<mark style="color:red;">\*</mark>       | String | name of the seed node             |
| "seedWeight"<mark style="color:red;">\*</mark> | json   | new global modal of this new seed |
| "para"<mark style="color:red;">\*</mark>       | json   | all kinds of para                 |
| "peers"<mark style="color:red;">\*</mark>      | json   | list of peer miners               |

{% tabs %}
{% tab title="201: Created Seed accepted" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="400: Bad Request Seed invalid" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}