RPC Methods
Methods can be called after the client registers an Identity Key.
All methods contain an "auth" field in the params
(for request) or result
(for response) which is a signed JWT. JWTs are specified in the authentication document.
All methods follow the JSON-RPC 2.0 spec.
Getting & watching subscriptions
Notes:
- Each client will call
wc_notifyWatchSubscriptions
to receive subscription updates for a blockchain account subs
contains the full subscription state, not delta or transactional differenceswc_notifyWatchSubscriptions
response andwc_notifySubscriptionsChanged
request messages expires after 5 minutes to reduce mailbox load and these updates are ephemeral anyway- If client goes offline for 5 minutes it must call
wc_notifyWatchSubscriptions
again to continue receiving updates
- If client goes offline for 5 minutes it must call
- Notify server has an "watcher" timeout and will no longer send updates after 1 day of not calling
wc_notifyWatchSubscriptions
- Client must call
wc_notifyWatchSubscriptions
at least once a day to continue receiving updates
- Client must call
wc_notifyWatchSubscriptions
Watches for updates to subscriptions for an account. Each update will result in a wc_notifySubscriptionsChanged
request to the client. Calling this will also immediately trigger a wc_notifySubscriptionsChanged
with the current subscription state.
Calling this method will create a "watcher" on the Notify Server for the given account and iss
. A symkey and topic is derived from kY
(which is specified under Response below) and saved for future updates. This derived topic is used to send the method response, and future updates to an account's subscriptions are also sent. Updates will stop and the watcher removed after the watcher timeout, which is 1 day.
If this method is called again with the same iss
, it will update the watcher with the new account and app
, reset the watcher timeout, and re-derive the symkey/topic from the current kY
and Notify Keys. Clients should re-use the same iss
and kY
for the same account on the same device to avoid abandoned topics and improve performance. To watch multiple accounts at the same time, separate iss
and kY
must be used for each account otherwise it will either update the account and app
being watched (if iss
is the same), or result in receiving updates for multiple accounts on the same topic (if kY
is the same).
Watchers will only be notified of changes from other clients. I.e. if a subscription change is made by iss
, then as a response to that iss
's request the latest subscriptions will be provided. But it will not receive a wc_notifySubscriptionsChanged
request.
Request
{
"watchSubscriptionsAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 300 |
| Tag | 4010 |
Topic: hash of key agreement public key from Notify Server Authentication.
Message uses type 1 envelope with the client's persistant private key.
Response
{
"responseAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 300 |
| Tag | 4011 |
Topic: hash of symmetric key derivation of client's persistant private key and key agreement public key from Notify Server Authentication.
wc_notifySubscriptionsChanged
Used to indicate a change to subscriptions has occurred.
Request
{
"subscriptionsChangedAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 300 |
| Tag | 4012 |
Topic: same as wc_notifyWatchSubscriptions response.
Response
{
"responseAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 300 |
| Tag | 4013 |
Topic: same as wc_notifyWatchSubscriptions response.
wc_notifySubscribe
Used to subscribe notify subscription to a peer through subscribe topic. Response is expected on the response topic.
Request
{
"subscriptionAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 300 |
| Tag | 4000 |
Topic: hash of key agreement public key from Notify Server Authentication.
Message uses type 1 envelope with the client's persistant private key.
Response
{
"responseAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 2592000 |
| Tag | 4001 |
Topic: hash of symmetric key derivation of client's persistant private key and key agreement public key from Notify Server Authentication.
Detailed request & response pattern
This is used by wc_notifyWatchSubscriptions
and wc_notifySubscribe
wc_notifyMessage
Used to publish a notification message to a peer through notify topic. Response is expected on the same topic.
Request
{
"messageAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 2592000 |
| Tag | 4002 |
Topic: notify topic.
Response
{
"responseAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 2592000 |
| Tag | 4003 |
Topic: notify topic.
wc_notifyUpdate
Used to update a notify subscription with a new notify subscription, replacing an existing notify subscription through notify topic.
Note: this method is atomically performing two methods (wc_notifyDelete + wc_notifySubscribe)
Request
{
"updateAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 300 |
| Tag | 4008 |
Topic: notify topic.
Response
{
"responseAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 2592000 |
| Tag | 4009 |
Topic: notify topic.
wc_notifyDelete
Used to inform the peer to close and delete a notify subscription through notify topic. The reason field should be a human-readable message defined by the SDK consumer to be shown on the peer's side.
Request
{
"deleteAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 2592000 |
| Tag | 4004 |
Topic: notify topic.
Response
{
"responseAuth": string
}
| IRN | |
| ------- | -------- |
| TTL | 2592000 |
| Tag | 4005 |
Topic: notify topic.