Skip to main content

Services

Services are decentralized agreements between a Publisher and a group of Subscribers registered on-chain. They are accessible through the developer portal, which provides an official front-end implementation of a decentralized data market, but there can be other implementations.

A decentralized data market is part of the Synternet Data Layer protocol, which allows parties to find each other in terms of data being offered and data being requested.

Types

There are two types of services:

  • Public, where any new Subscriber is always allowed to subscribe to the service. Data stream is unencrypted.
  • Private, where only an authorized group of Subscribers can subscribe to the service. Data stream is encrypted.

In the initial release of the Synternet Data Layer protocol, only the Public types of services are implemented.

Service module

The service on-chain module enables interactions with the Service data structure and executes the logic necessary to reach an agreement between Publishers and Subscribers. In order to be valid and in the Active state, each service must be properly backed by collateral.

The design uses two sources of collateral:

  • Credit provided by the Publisher (also referred to as Stake in the specification). Credit is returned back to the Publisher when service expires. It can also be slashed when the Publisher misbehaves. However, in tokenomics v1, Publisher misbehavior is not monitored.
  • Credit provided by the Subscriber. Credit is deducted as a result of data streams being consumed by Subscriber or its Clients. There can also be credit deductions, if the Subscriber misbehaves. Unused credit can be claimed back by the Subscriber when service expires or when Subscriber decides to exit.
note

Note that Synternet tokens are used for staking on Validator network and for crediting on Data Layer. In both cases they are temporarily locked within the service contract. The naming differs because of fundamentally different concepts: stake delegation refers to security, credit locking refers to usage.

Registration

Creation flows

We are allowing Publishers and Subscribers to register a service. Therefore we are defining the following two equivalent flows that lead to a correct service registration.

  1. Offer-Subscribe is led by Publishers, who send service Offers to the market. Publishers define the subject, the format of the data they provide, and the price they charge.
  2. Request-Publish is led by Subscribers, who send service Requests to the market. Subscribers specify the subject, its format, and the price they are willing to pay.

In the initial release of the Synternet Data Layer protocol, only the first creation flow led by a Publisher is supported.

Offer-Subscribe

When a Publisher registers a Service, it sends the Offer message to the chain. An Offer message must include:

  1. PublisherId: a public key obtained through NATS account generation
  2. SubjectName: NATS subject name
  3. Stake: the amount of tokens that are locked by the Publisher as a collateral for the Service. In the Offer-Subscribe case, this credited amount of tokens also becomes a StakeThreshold for the service, which means that the Publisher cannot reduce its credit when the service becomes active.
  4. ServiceFeeRate: the amount of tokens that is going to be paid for each Client to the Publisher per standard unit of data. To put it simply, this is the price of data.
  5. CreditThreshold: the amount of tokens, which will be required from Subscriber in order to make the service Active. A common case is that the CreditThreshold is equal to the Stake. Since the Stake is equal to the StakeThreshold, we get the parity: Credit = CreditThreshold = StakeThreshold.

In order to activate a service offer, a certain number of Subscribers must register their interest in the service by sending a Subscribe message. A Subscribe message must include only a handful of fields:

  1. SubscriberId: a public key obtained through NATS account generation.
  2. ServiceId: this is discovered by reading the chain. In practice, the developer portal UI will prefill it when Subscriber is clicking.
  3. Credit: the allocation of the tokens owned by Subscriber as a collateral for creation of the Service. This is how many tokens the Subscriber is reserving to pay for the service. Each subscribe message adds its credit to the total credit available in Service.

When the total Credit accumulated exceeds the CreditThreshold, the Service is marked as Active.

It is possible that a Publisher wants to give the data away for free. In such a case, a Publisher will have to set both the ServiceFeeRate and CreditThreshold to zero when sending the Offer message. Whereas, Subscribers will only be charged network fee for consuming the data stream published under that subject.

Request-Publish

When a Subscriber registers a Service, it sends a Request message to the chain. A Request message must include:

  1. SubscriberId: a public key obtained through NATS account generation.
  2. SubjectName: a NATS subject name.
  3. ServiceFeeRate: the amount of tokens that is going to be paid for each Client to the Publisher per standard unit of data. To put it simply, this is the price of data.
  4. StakeThreshold: the amount of tokens required to be credited by the Publisher who will be responding to this request.
  5. Credit: the allocation of the tokens owned by Subscriber as a collateral for creation of the Service. This is how many tokens the Subscriber is reserving to pay for the service. Each subscribe message adds its credit to the total credit available in Service. In the Offer-Subscribe case, it is common that the credited amount of tokens is equal to the StakeThreshold.

While the service is inactive, subsequent Subscribe messages sent by other Subscribers increase the credit available in the service and the value of both thresholds due to the Credit = CreditThreshold = StakeThreshold parity. After service activation, additional subscriptions are only increasing the value of the credit. An increasing credit threshold signals that the demand for such service is strong and would guarantee income for the potential Publisher.

In order to activate a request, a Publisher must register his interest in providing the Service by sending a Publish message. A Publish message must include only a handful of fields:

  1. PublisherId: a public key obtained through NATS account generation.
  2. ServiceId: this is discovered by reading the chain. In practice, the developer portal UI will prefill it when Subscriber is clicking.
  3. Stake: the amount of tokens that are locked by the Publisher as a collateral for the Service. Stake must be at least equal to the StakeThreshold, which is already set within the service by Subscribers.

When the Publisher responds to the request by sending the Stake that is larger or equal to the StakeThreshold, the service changes its status to Active.

Service lifetime

Inactive

A service is registered with an Inactive state by the Offer or Request message. A service is inactive until one of the activating conditions are met, or in other words, until it is matched.

Figure: Service lifetime

Active

Mutually exclusive service activation conditions:

  • Both ServiceFeeRate and CreditThreshold are zero: this will instantly activate the service, since the Publisher does not need any payment for this service.
  • Credit exceeds CreditThreshold: this shows a sufficient interest in the service from the Subscriber side. Publisher has indicated the CreditThreshold when creating the service, hence, it now has enough financial motivation to deliver data.

An Active service state is a contract whose terms are accepted by a proper set of transactions executed by Publisher and Subscribers. Consequently, such a contract is used for delivering data and accounting for it.

In case a service is not activated for a prolonged period of time, called activation period, it immediately transitions to the Terminated state.

Usage during Active state

A service can be used only when it is in the Active state. The usage of the service from tokenomics perspective is straightforward.

  • Data delivered to Subscribers is accounted for by Brokers.
  • Brokers are generating proofs of delivery (PoDs) and sending them to Observers for validation.
  • Brokers submit PoDs to the chain.
  • If proofs are valid, Observers send their attestations to the chain.
  • The proofs and attestations are checked on-chain and, if correct, the rewards are calculated and scheduled.
  • After a challenging period passes and no valid challenges have been submitted, the rewards are paid out to Brokers, Observers, and Publishers.

Expiring

A service enters the Expiring state when Publisher sends the message Expire and one of the following conditions are met:

  • ServiceFee is zero: this means that Publisher is providing a service for free and, therefore, has more freedom when choosing its expiration.
  • Credit is at or below CreditThreshold: which means the interest in a service has dwindled from the Subscriber side. Normally, a service will not satisfy this condition as long as there’s continued interest from Subscribers, which means they are regularly topping up their subscriptions.

After a service enters the Expiring state, an event is generated, which signals Subscribers and Brokers to close the connections and finalize the accounting.

In this state, there’s an expiration time, which does not allow any parties, Subscribers as well as the Publisher, to move their credit. This is required for the accounting to be fully finished. After the expiration time passes, a service changes its state to Expired, but the tokens remain bonded for longer.

Expired

An Expired service state indicates that the service expiration time passed, i.e. a certain block height was reached. After reaching this state, a service enters into a termination phase and waits until the end of bonding time. This time is dedicated for challenging the PoDs and their attestations on-chain. When the bonding period finishes, these procedures are no longer possible, and a service changes its state to Terminated.

Terminated

A service becomes Terminated after the timeout meant for challenging the accounting information has passed. Termination of the service means that all payments have been registered, all challenges resolved.

After entering a Terminated state and during the grace period, the Subscribers are allowed to transfer back their unspent credit by sending the Retrieve message.

Removable and Removed

When the grace period ends, a service enters the Removable state. Since the grace period ended, Subscribers can no longer retrieve their funds.

In the Removable state the service can be removed from the chain by the Publisher sending a Refund message. It is the only way for the Publisher to get its credit back. If there is some trailing credit left on the service, it is burned during Refund execution due to the service entry being removed from the on-chain registry.

Following the execution of this message, service enters the final state – Removed, which is no longer reflected on-chain, because the entry of the service is removed altogether.