Service Creation (~ 5 min)
Visit the Service FAQ for more information about interacting with Services.
Table of Contents
- Introduction
- Prerequisites
- How do I create a new service?
- How do I update an existing service's
compute_units_per_relay
? - Experimental: How do I add API specifications to a service?
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
- Install the pocketd CLI.
- Create and fund a new account before you begin.
How do I create a new service?
Service IDs are limited to 42
chars and descriptions are limited to 169
chars.
1. Add a Service
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 -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?
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).