Warning, Work in progress, use at your own caution. 

Introduction to Subscriptions

Subscriptions allow two picos to communicate with each other on a secure channel. Subscriptions characteristics and uses:

• Subscriptions can occur between any two picos, augmenting the parent-child hierarchy to create peer-to-peer structures.
• Subscriptions allow picos to establish communication channels with relationships. 

From each pico's perspective there is an receiving channel , Rx , and an transmitting channel, Tx. The pico receives events and queries from the other pico in the subscriptions over the Rx channel and makes queries and sends events to the other pico using the Tx channel. 

Subscriptions can exist between any two picos. They do not have to have the same parent. In the Forever application, for example, the picos belonged to different people and represented their personal contact information. 

Well Known Rx

When subscription ruleset is installed a well known Rx channel is created. The well known channel name is wellKnown_Rx with Tx_Rx channel type. This channel is used for subscription requests, and is meant to be publicly shared with potential subscribers. In the future this channel will use Policies to restrict events to only subscription request, making your engine more secure.

Simple Subscription

A simple subscription only contains what is needed for basic secure communication. 

Directional Subscription

Directional subscritpion are subscription that store roles, providing a way to identifie direction of a subscription.

Cross Engine Subscription

Cross engine subscription are subscriptions that store a host, providing subscritpions to be used across engines or possibly with 3rd party services.

Auto Accepting Subscription Request

Subscription rulest is configurable to auto accept specfied subscriptions requests. ...

At the time of writting this single use configuration is a planned feature.

Subscription Event Flow

To establish a basic subscription between pico A and pico B:

1. Pico A receives a wrangler:subscription event which includes a wellKnown_Tx attribute. wellKnown_Tx is Pico B's wellKnown_Rx .  Pico A creates a channel for the subscription which is store as Rx.
2. Pico A then sends pico B wrangler:pending_subscription with attribute status set to inbound. Pico A sends with that event the following attributes.
   
   1. Tx - Pico A Rx.
   2. Tx_verify_key - Pico A's Rx channel verifyKey.
   3. Tx_public_key - Pico A's Rx channel encryptionPublicKey.
3. Pico B creates a Rx channel for the subscription which is stored as Rx along with Tx , Tx_verify_key, Tx_public_key in inbound subscription entity variable.
   Pico A also raises an internal  wrangler:pending_subscription event with status set to outbound, with the corresponding attributes above which is stored in outbound subscription entity variable. 
4. After storeing pending subscriptions, Pico B and Pico A raises corisponding wrangler:inbound_pending_subscription_added event and wrangler:outbound_pending_subscription_added event.
   The state of each Picos subscription is static at this point. Pico A has an outgoing pending subscription and Pico B has an incoming pending subscription.
5. If Pico B wants to approve the subscription request, it raises the wrangler:pending_subscription_approval event with an attribute Rx containing the Rx channel identifier of the subscription to approve.  Upon successfully storing the subscription in established enity variable. Pico B: 
   1. sends the wrangler:pending_subscription_approved event with attribute status set to outbound to Pico A on Pico B's subscriptions Tx. 
   2. raises an API internal event wrangler:subscription_added.
6. Upon receiving the wrangler:pending_subscription_approved event, Pico A adds an Tx eci to the subscription and stores the subscription in established entity variable.  And raises the wrangler:subscription_added event.
7. If Pico B wants to reject the subscription, it raises the wrangler:subscription_cancellation event (internally) with an attribute named Rx - which is the Rx of the subscription to reject. Pico B:
   1. sends the wrangler:established_removal event to Pico A on Picos B Tx eci, which then raises an internal API wrangler:subscription_removed event to itself.
   2. raises the wrangler:established_removal event, which then raises an internal API wrangler:subscription_removed event.

Upon receiving a wrangler:established_removal event, the pico deletes the specified subscription from the established entity variable.

Initial Subscription Flow

Subscription Approval Flow

Subscription Rejection Flow

Subscription Events

Overview

Events Users Might Raise

• wrangler:subscription
• wrangler:pending_subscription_approval
• wrangler:outbound_cancellation
• wrangler:inbound_rejection
• wrangler:subscription_cancellation

Events Users Might React To

• wrangler:subscription_added
• wrangler:subscription_removed
• wrangler:subscription_added

Event Attributes

wrangler:subscription (pico A)

wrangler:outbound_cancellation,
wrangler:inbound_rejection,
wrangler:subscription_cancellation

wrangler:pending_subscription_approval (pico B)

wrangler:outbound_pending_subscription_added (pico A)

example value of established():

[
  {
    "Rx": "5sk3bNLv1aZC1w4Gz9tg7i",
    "Tx": "BQMnQkRhpwRBspcnz4LdX8",
    "Tx_verify_key": "6frM5S1t6i2SJh1Rp4AXDpsmwQsCqMjLagsyEKrv6HEN",
    "Tx_public_key": "DCVx2iExZb6gnumBoHz5GA2rdrt3BbsU41YUJjcF7Peq"
  }
]

wrangler:inbound_pending_subscription_added (pico B)

wrangler:subscription_removed

wrangler:subscription_added

Subscription Functions

wellKnown_Rx()

wellKnown_Rx() returns the well known channel, e.g.

{
  "id": "4H2tXa1NkexgyfEbzCFsPE",
  "pico_id": "cjc78fh4s000b9iry4u2j2len",
  "name": "wellKnown_Rx",
  "type": "Tx_Rx",
  "sovrin": {
    "did": "4H2tXa1NkexgyfEbzCFsPE",
    "verifyKey": "2naJczreMuFRiDJcc3SWpP4CkXVSuViKMNq4gRmh3Tzq",
    "encryptionPublicKey": "G3Xq6daaUndzwjiP8H1WFt9fKKb2NCbZtEVwGqXLuGMC"
  }
}

established()

established() returns all established subscription in an array, e.g.

[
  {
    "Rx": "5sk3bNLv1aZC1w4Gz9tg7i",
    "Tx": "BQMnQkRhpwRBspcnz4LdX8",
    "Tx_verify_key": "6frM5S1t6i2SJh1Rp4AXDpsmwQsCqMjLagsyEKrv6HEN",
    "Tx_public_key": "DCVx2iExZb6gnumBoHz5GA2rdrt3BbsU41YUJjcF7Peq"
  }
]

outbound()

outbound() returns all outbound subscriptions in an array, e.g.

[
  {
    "wellKnown_Tx": "B5JMLRzZnz7NQcDJuBAPSr",
    "Rx": "Q4aosn4DiPdEEpqwZZGEbh"
  }
]

inbound()

inbound() returns all inbound subscriptions in an array, e.g.

[
  {
    "Tx": "Q4aosn4DiPdEEpqwZZGEbh",
    "Rx": "MvgUk1pHSFHqtzpUKkJErC",
    "Tx_verify_key": "Da2dgGAEFPLJV4bTP6kYTdphUXcJaQ5Zrnq5rnMXS5UZ",
    "Tx_public_key": "39V93tWrxWBK2Anez4Mz6J6ec8eX3v7ZcTEdsEMSL42a"
  }
]

autoAcceptConfig()