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 differences
• wc_notifyWatchSubscriptions response and wc_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
• 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

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.