Skip to main content

Service Creation (~ 5 min)

Services FAQ

Visit the Service FAQ for more information about interacting with Services.

Table of Contents

Introduction

This page will walk you through creating an onchain Service.

To learn more about what a Service is, or how it works, see the Protocol Documentation.

Prerequisites

  1. Install the pocketd CLI.
  2. Create and fund a new account before you begin.

How do I create a new service?

Service Limitations

Service IDs are limited to 42 chars and descriptions are limited to 169 chars.

1. Add a Service

Grove Employees Service Creation

If you are a Grove Employee, you ABSOLUTELY MUST create all Mainnet Services using the Grove Master Gateway: pokt1lf0kekv9zcv9v3wy4v6jx2wh7v4665s8e0sl9s

Use the add-service command to create a new service like so:

pocketd tx service add-service \
${SERVICE_ID} "${SERVICE_DESCRIPTION}" ${COMPUTE_UNITS_PER_RELAY} \
--fees 300upokt --from ${SERVICE_OWNER} --network=beta

For example, assuming you have an account with the name USER(pocketdkeysshowUSER (`pocketd keys show USER -a`), you can run the following for Beta TestNet:

pocketd tx service add-service \
"svc-$USER" "service description for $USER" 13 \
--fees 300upokt --from $USER \
--network=beta

2. Query for the Service

Query for your service on the next block:

pocketd query service show-service ${SERVICE_ID}

For example:

pocketd query service show-service "svc-$USER" \
--network=beta --output json | jq

Query without metadata (dehydrated)

If you want to query a service without its metadata (API specifications) to reduce payload size:

pocketd query service show-service ${SERVICE_ID} --dehydrated

For example:

pocketd query service show-service "svc-$USER" \
--dehydrated --network=beta --output json | jq

This is useful when you only need basic service information (ID, name, compute units, owner) without the full API specification.

Query all services

To list all services:

pocketd query service all-services

By default, this excludes metadata to reduce payload size. To include metadata for all services:

pocketd query service all-services --dehydrated=false

3. What do I do next?

TODO(@olshansk): Coming soon...

How do I update an existing service's compute_units_per_relay?

Use the add-service command to modify the compute_units_per_relay for an existing service.

Provide the SERVICE_ID of the Service you want to update, but with a new value for COMPUTE_UNITS_PER_RELAY.

pocketd tx service add-service \
${SERVICE_ID} "${SERVICE_DESCRIPTION}" ${NEW_COMPUTE_UNITS_PER_RELAY} \
--fees 300upokt --from ${SERVICE_OWNER} --network=beta

For example:

pocketd tx service add-service \
"svc-$USER" "service description for $USER" 20 \
--fees 300upokt --from $USER \
--network=beta

Experimental: How do I add API specifications to a service?

Experimental Feature

The onchain service metadata feature is experimental and subject to change. The metadata payload is limited to 256 KiB when decoded as of #1825.

You can attach an API specification (OpenAPI, OpenRPC, etc.) to a service when creating or updating it.

The API specification is stored on-chain and can be used by applications, gateways, and suppliers to understand the service's interface.

Using a File

To attach an API specification from a file:

pocketd tx service add-service \
${SERVICE_ID} "${SERVICE_DESCRIPTION}" ${COMPUTE_UNITS_PER_RELAY} \
--experimental-metadata-file ./openapi.json \
--fees 300upokt --from ${SERVICE_OWNER} --network=beta

For example, to create a service for the Pocket network with its OpenAPI specification:

pocketd tx service add-service \
"pocket" "Pocket Network RPC" 1 \
--experimental-metadata-file ./docs/static/openapi.json \
--fees 300upokt --from $USER \
--network=beta

Using Base64-Encoded Data

Alternatively, you can provide the API specification as base64-encoded data:

pocketd tx service add-service \
${SERVICE_ID} "${SERVICE_DESCRIPTION}" ${COMPUTE_UNITS_PER_RELAY} \
--experimental-metadata-base64 $(base64 -w0 ./openapi.json) \
--fees 300upokt --from ${SERVICE_OWNER} --network=beta

Updating Service Metadata

To update the metadata of an existing service, use the same add-service command with new metadata:

pocketd tx service add-service \
"pocket" "Pocket Network RPC" 1 \
--experimental-metadata-file ./docs/static/openapi-v2.json \
--fees 300upokt --from $USER \
--network=beta

Important Notes

  • The --experimental-metadata-file and --experimental-metadata-base64 flags are mutually exclusive.
  • The decoded payload must be 256 KiB or less.
  • The metadata is stored on-chain as raw bytes and base64-encoded in JSON representations.
  • Only the service owner can update the service metadata.
  • To remove metadata from a service, update it without providing any metadata flags.
  • Updating metadata replaces the entire previous metadata (not a partial update).