Registry Subscription
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.
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.
wss://dev2.siasky.dev/skynet/registry/subscription
You do not need to use an API Key at this point in time.
Expected Behavior: Upgrade Connection and Handshake occur.
Send a message with this information to subscribe to a registry entry.
{
"action": "subscribe",
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889999"
}
The portal will immediately respond with the highest revision values for the entry that it has, in the following format:
{
"responsetype": "notification",
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889999",
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
"signature": "13b550940f18d22a7d4ec012479cb90a8c8e82d00be4710cbaeae3aadc710961decee957af947892f11f5ab6ecc679fb79103257337af961350437a0b8aeb30e",
"data": "0800153ab78a56202090455d8ec06cc5cc14e6e531e47daf7f56062c31d6f5f20ac1",
"revision": 11,
"type": 1
}
If an entry is not yet written, the response will be missing the
data
and signature
fields and look like this:{
"responsetypejson": "notification",
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889998",
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
"revision": 0
}
- 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.
Send a message with information to unsubscribe to a registry entry.
{
"action": "unsubscribe",
"pubkey": "ed25519:23fd7ee9e44085e4830925d59369ebccb0af8978f963b34cfb91c919c960a459",
"datakey": "4096a333c23c3f80c9011d2e0aa359eee53224781cac2d210e13722a56889999"
}
None if successful. If the input is malformed, it will return an error.
Send this message to see all active subscriptions.
{
"action": "subscriptions"
}
The response contains a list of all currently active subscribed registry entries.
{
"responsetype": "activesubscriptions",
"subscriptions": [
"f4b95286a7f7db5f8ecc254ccbc1b4ae279df6f9704ecc4b49420e766118b501"
]
}
- 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.
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
.