Service Creation (~ 5 min)

Services

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

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:

Create service

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

Example for Beta TestNet (assuming you have an account named USER and its address via pocketd keys show USER -a):

Example

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:

Show service

pocketd query service show-service ${SERVICE_ID}

Example:

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:

Example:

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:

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

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.

Update compute units

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

Example:

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:

Attach metadata from 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

Example:

Example

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:

Attach metadata base64

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:

Update 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

Important notes about experimental metadata

• 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).