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