Registry Subscription

Introduction

The Registry allows for fast reads and writes of mutable data on Skynet. Using the regular HTTP endpoints allows a user to read an entry or see if it exists, but requires an application to "poll" to see if the entry has been updated or created.
Registry Subscription utilizes websockets to allow an application to subscribe to a number of registry entries and be notified by the portal if any updates occur. This is helpful in near-realtime applications where a client needs to respond to registry updates made by other applications, either to refresh the client application's UI or take an action in response.
Registry Subscriptions work by using Web Sockets to connect to the portal and then deliver messages back and forth while the connection stays open.
As of April 2022, Registry Subscription is still experimental.
The feature may be unstable and specs may change as we gather developer feedback.

Using Registry Subscription

Registry Subscription is not yet integrated into any Skynet SDK. Instead, you’ll want to use a tool or lib that can handle establishing websocket connections and transferring messages in JSON format. For example, this React Hook.

Connect to End-point

1
wss://dev2.siasky.dev/skynet/registry/subscription
Copied!
You do not need to use an API Key at this point in time.
Expected Behavior: Upgrade Connection and Handshake occur.

Subscribe to an Entry

Send a message with this information to subscribe to a registry entry.
1
{
2
"action": "subscribe",
3
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
4
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889999"
5
}
Copied!

Response

The portal will immediately respond with the highest revision values for the entry that it has, in the following format:
1
{
2
"responsetype": "notification",
3
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889999",
4
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
5
"signature": "13b550940f18d22a7d4ec012479cb90a8c8e82d00be4710cbaeae3aadc710961decee957af947892f11f5ab6ecc679fb79103257337af961350437a0b8aeb30e",
6
"data": "0800153ab78a56202090455d8ec06cc5cc14e6e531e47daf7f56062c31d6f5f20ac1",
7
"revision": 11,
8
"type": 1
9
}
Copied!
If an entry is not yet written, the response will be missing the data and signature fields and look like this:
1
{
2
"responsetypejson": "notification",
3
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889998",
4
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
5
"revision": 0
6
}
Copied!

Notes

  • The portal will relay registry entries as it receives them from hosts. On subscription, you may receive multiple messages in a short time-period, but the last entry should have the highest revision number.
  • If no entry is found, the portal will return after a timeout period that matches the registry entry GET endpoint. (GET waits for 80% of the fastest 50% of workers to return with a minimum of 10.)
  • If you are already subscribed to an entry, you can send this message to poll for the latest value. You will still only be subscribed once.
  • If the input is malformed, it will return an error.

Unsubscribe to an Entry

Send a message with information to unsubscribe to a registry entry.
1
{
2
"action": "unsubscribe",
3
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
4
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889999"
5
}
Copied!

Response

None if successful. If the input is malformed, it will return an error.

View Active Subscriptions

Send this message to see all active subscriptions.
1
{
2
"action": "subscriptions"
3
}
Copied!

Response

The response contains a list of all currently active subscribed registry entries.
1
{
2
"responsetype": "activesubscriptions",
3
"subscriptions": [
4
"f4b95286a7f7db5f8ecc254ccbc1b4ae279df6f9704ecc4b49420e766118b501"
5
]
6
}
Copied!

Notes

  • The data type of subscriptions is ‘registry entry ids’ which is related to Resolver Skylinks, but we don’t currently have a convenient way of handling conversion of PubKey+DataKey -> Id.

Limitations

Right now, there are no subscription quantity limitations in place. Limits will be determined as we do more testing with real-world applications. Ratelimit are determined by portal values for bandwidthlimit and notificationdelay.