net_srv

Network services management — find, dump, create, update, and delete service orders; query usage limits and reports.

Verified against public RPC http://rpc.cellframe.net/ (networks: Backbone, KelVPN).

JSON-RPC request

Method name: net_srv. Response type is 2 (TYPE_RESPONSE_JSON).

Two request formats are supported. The response version echoes the request version and affects JSON field names in order and get_limits responses (see v1 vs v2 field names).

Version 1 — legacy `params` string

{
  "method": "net_srv",
  "params": ["net_srv;-net;KelVPN;order;find"],
  "id": 1,
  "version": 1
}

params is an array with one string. Every token is separated by ; — not spaces.

Version 2 — `subcommand` + `arguments`

{
  "method": "net_srv",
  "subcommand": "order;find",
  "arguments": {"net": "Backbone"},
  "id": 1,
  "version": 2
}

subcommand may also be a JSON array:

{
  "method": "net_srv",
  "subcommand": ["order", "find"],
  "arguments": {"net": "KelVPN", "direction": "sell"},
  "id": 2,
  "version": 2
}

Both forms produce the same internal command: net_srv;order;find;-net;KelVPN;-direction;sell.

Spaces in subcommand do not work. Use "order;find" or ["order","find"], not "order find".

To use version 2 fields, omit params entirely.

Version 2 `arguments` mapping

`arguments` key	CLI flag	Used by
`net`	`-net`	All subcommands except `report`
`H`	`-H`	Hash output format (`hex` or `base58`)
`direction`	`-direction`	`order find`, `order create` (`sell` or `buy`)
`srv_uid`	`-srv_uid`	`order find`, `order create`, `get_limits`
`srv_class`	`-srv_class`	`order find`
`hash`	`-hash`	`order dump`, `order update`, `order delete`
`price_unit`, `price_token`	`-price_unit`, `-price_token`	`order find`, `order create`
`price_min`, `price_max`	`-price_min`, `-price_max`	`order find`
`price`, `units`, `cert`	`-price`, `-units`, `-cert`	`order create`
`node_addr`, `tx_cond`, `expires`	`-node_addr`, `-tx_cond`, `-expires`	`order create`
`ext`, `region`, `continent`	`-ext`, `-region`, `-continent`	`order create`, `order update`
`tx_to_json`	`-tx_to_json`	`order dump` (bare flag: `""`)
`provider_pkey_hash`, `client_pkey_hash`	`-provider_pkey_hash`, `-client_pkey_hash`	`get_limits`

Argument values must be strings (or null/empty string for bare flags). JSON numbers and booleans are rejected.

Global options

Option	Description
`-H hex\|base58`	Hash output format (default: `hex`).
`-net <net_name>`	Network selector (required except for `report`).

Subcommands

Subcommand	Description	Public RPC
`order find`	Search orders with optional filters.	tested
`order dump -hash`	Dump one order by hash.	tested
`report`	Service usage report (no `-net` required).	tested
`get_limits`	Remaining service limits for provider/client pair.	tested (returns error when no data)
`order create`	Create a signed order (`-cert` required since v5.2).	requires local certificate and master role — not testable on public node
`order update -hash`	Update order extension or location.	requires existing order write access — not testable on public node
`order delete -hash`	Delete an order.	write operation — not tested on public node

Subcommand syntax (CLI / v1 params)

net_srv;report

net_srv;-net;<net_name>;order;find
net_srv;-net;<net_name>;order;find;-direction;sell
net_srv;-net;<net_name>;order;find;-direction;buy
net_srv;-net;<net_name>;order;find;-srv_uid;0x0000000000000014
net_srv;-net;<net_name>;order;find;-price_unit;DAY;-price_token;KEL
net_srv;-net;<net_name>;order;find;-price_min;10;-price_max;100

net_srv;-net;<net_name>;order;dump;-hash;0xORDER_HASH
net_srv;-net;<net_name>;order;dump;-hash;0xORDER_HASH;-tx_to_json

net_srv;-net;<net_name>;order;delete;-hash;0xORDER_HASH

net_srv;-net;<net_name>;order;create;-direction;sell;-srv_uid;0x1;-price;100
  ;-price_unit;DAY;-price_token;KEL;-units;30;-cert;node.dcert
  ;[-node_addr;<addr>][;-tx_cond;<hash>][;-expires;<unix_ts>]
  ;[-ext;<extension>|-region;<region>;-continent;<continent>]

net_srv;-net;<net_name>;order;update;-hash;0xORDER_HASH
  ;[-ext;<extension>|-region;<region>;-continent;<continent>]

net_srv;get_limits;-net;<net_name>;-srv_uid;0x1
  ;-provider_pkey_hash;0xPROVIDER;-client_pkey_hash;0xCLIENT

-direction: sell or buy (maps to SERV_DIR_SELL / SERV_DIR_BUY in responses).

-price_unit for create: B, KB, MB, SEC, DAY, PCS.

Example requests

Version 1

{"method":"net_srv","params":["net_srv;-net;KelVPN;order;find;-direction;sell;-srv_uid;0x0000000000000014"],"id":1,"version":1}

{"method":"net_srv","params":["net_srv;-net;Backbone;order;dump;-hash;0x17C692FA7DD35E66C07F51C1D49595B5F588FFB6C2C728B84A5A58964C9F4CE8"],"id":2,"version":1}

{"method":"net_srv","params":["net_srv;report"],"id":3,"version":1}

{"method":"net_srv","params":["net_srv;get_limits;-net;KelVPN;-srv_uid;0x0000000000000014;-provider_pkey_hash;0xPROVIDER;-client_pkey_hash;0xCLIENT"],"id":4,"version":1}

Version 2 (verified on rpc.cellframe.net)

{"method":"net_srv","subcommand":"order;find","arguments":{"net":"Backbone","direction":"sell","srv_uid":"0x0000000000000014"},"id":1,"version":2}

{"method":"net_srv","subcommand":["order","find"],"arguments":{"net":"KelVPN","direction":"sell"},"id":2,"version":2}

{"method":"net_srv","subcommand":"order;dump","arguments":{"net":"Backbone","hash":"0x17C692FA7DD35E66C07F51C1D49595B5F588FFB6C2C728B84A5A58964C9F4CE8"},"id":3,"version":2}

{"method":"net_srv","subcommand":"report","id":4,"version":2}

{"method":"net_srv","subcommand":"get_limits","arguments":{"net":"KelVPN","srv_uid":"0x0000000000000014","provider_pkey_hash":"0xPROVIDER","client_pkey_hash":"0xCLIENT"},"id":5,"version":2}

Response envelope

Same JSON-response format as other CLI modules:

{
  "type": 2,
  "result": [ { ... } ],
  "id": 1,
  "version": 2
}

type — 2 (TYPE_RESPONSE_JSON)
result — JSON array of result objects (or error objects)
id — echoes the request id
version — RPC protocol version (1 or 2)

Errors appear inside result[].errors[]:

{
  "type": 2,
  "result": [
    {
      "errors": [
        { "code": 10, "message": "Can't find order with hash 0x...\n" }
      ]
    }
  ],
  "id": 1,
  "version": 2
}

v1 vs v2 response field names

Version 1	Version 2	Context
`price coins`	`price_coins`	`order find` / `order dump` order objects
`price datoshi`	`price_datoshi`	order objects
`price token`	`price_token`	order objects
`price unit`	`price_unit`	order objects
`provider`	`sig_inf_provider`	`get_limits` success response
`client`	`sig_inf_client`	`get_limits` success response

All other order fields (order, direction, srv_uid, node_addr, etc.) use the same names on both versions. Buy orders may include tx_cond_hash.

Response fields (verified on rpc.cellframe.net)

net_srv order find

// version 2
{
  "result": [
    {
      "count": 203,
      "orders": [
        {
          "order": "0x17C692FA7DD35E66C07F51C1D49595B5F588FFB6C2C728B84A5A58964C9F4CE8",
          "version": 3,
          "direction": "SERV_DIR_SELL",
          "created": "Wed, 21 Aug 2024 12:00:19 +0000",
          "timestamp": 1724241619,
          "srv_uid": "0x0000000000000014",
          "price_coins": "46.5",
          "price_datoshi": "46500000000000000000",
          "price_token": "mCELL",
          "units": "1",
          "price_unit": "pieces",
          "node_addr": "B400::E107::817F::B2A4",
          "node_location": "None - None",
          "ext_size": 64,
          "pkey": "0x0465C436A7C5B5AD984FAA02FFA04F38C43BD875D51E697B4A3E364812B27FBB"
        }
      ]
    }
  ]
}

// version 1 — same order, spaced price fields
{
  "price coins": "46.5",
  "price datoshi": "46500000000000000000",
  "price token": "mCELL",
  "price unit": "pieces"
}

net_srv order dump

Same fields as a single order object from order find. With -tx_to_json, returns data_hash, data_type, data_size, and base58-encoded data instead.

net_srv order create (not tested on public node)

{
  "result": [
    { "order_hash": "0xNEW_ORDER_HASH..." }
  ]
}

Requires -cert with a private key and node role ≥ master. Without a certificate, returns error code 13 ("The certificate name was not specified...").

net_srv order delete (not tested on public node)

{
  "result": [
    { "order_hash": "0xABCDEF0123456789" }
  ]
}

net_srv order update (not tested on public node)

{
  "result": [
    { "status": "updated" }
  ]
}

net_srv get_limits

// success (field names depend on version)
{
  "result": [
    {
      "sig_inf_provider": "0xPROVIDER_HASH...",
      "sig_inf_client": "0xCLIENT_HASH...",
      "sec": 86400,
      "bytes": 1073741824
    }
  ]
}

Version 1 uses provider / client instead of sig_inf_provider / sig_inf_client. Returns error code 28 when no remain-limits data exists for the given keys (verified on rpc.cellframe.net with dummy hashes).

net_srv report

{
  "result": [
    { "report": "Service report:\n" }
  ]
}

Common error codes

Code	When
10	Order not found (`dump`, `delete`, `update`).
12	`order delete` missing `-hash`.
13	`order create` — node role too low, or certificate not specified.
28	`get_limits` — no remain service data for the given provider/client.
102	Missing required `-net` parameter.