Chainlink Node Setup

  1. Home
  2. Docs
  3. Chainlink Node Setup
  4. Service Agreements

Service Agreements

Protocol Information

protocol

Setup

  • Oracle calls Deposit on the Oracle Contract and enter LINK amount.

CreateServiceAgreement – Request sends a proposed service agreement over to each of the oracles selected to provide data.


  • Requester calls CreateServiceAgreement on each Oracles’ API:
    • Full ServiceAgreement
    • Signature. Hash of the SA parameters

Each oracle accepts a service agreement proposal. Oracle signs the hash of the encoded service agreement and returns a signature to the requester.


  • Oracle responds to the Requester with:
    • Signature covering the SAID

Requester submits service agreement with all oracle signatures.

  • Requester calls the Oracle Contracts’ InitiateServiceAgreement with:
    • ABI encoded service agreement
    • List of oracle signatures, ordered as they are listed in service agreement.

Requester directs the oracle to create a Run of the Job Specifications. Requests can be sent directly to the Oracle contract, or be routed through the Consuming Contract. (Example below uses Consuming Contract method)


  • Requester calls ExecuteServiceAgreement on the Consuming Contract with:
    • SAID
    • This Run Requests parameters

  • Consumer Contracts calls RequestRun on the oracle contract with:
    • SAID
    • Run Requests parameters
    • Callback address
    • Callback function selector

  • Oracle Contract issues Run Log containing:
    • Request ID
    • SAID
    • Request Parameters

Oracles’ report their answers and aggregate them together.  The Oracle Contract sends the final reported answer to the Consuming Contract.

  • Each oracle calls Fulfill on the Oracle Contract with:
    • Request ID
    • Reported response

  • Oracle passes all responses on to its specified aggregation function.
    • Answer Aggregator reports the final answer to the consuming contract.
    • Answer Aggregator report cooperative/uncooperative oracles.


Service Agreement

Specifies all of the details requested work. This is broken into two parts, the off-chain Job Spec and the on-chain Encumbrance. The SA is the subset of the Job Spec’s parameters that can be enforced on-chain; e.g. payment amount, oracle deposit amount, oracle list, etc.

In order to be referred to reliably, the SA can be sent in with any JSON but it is always normalized by the Oracle Node in order to create a deterministic JSON string to work with. Using a deterministic function allows the Oracle Nodes to agree to work with each other without communicating directly. Normalization handles JSON key ordering, character encoding, float representation, etc.

In order for the SA to be enforced, and for all of the Oracle Nodes to have the guarantee that they are operating on the same data the Oracles commit to the SA by ABI encoding it and signing a hash of the ABI encoding. The hash of the ABI encoded SA is known as the SAID.


Job Spec

The Job Spec is a series of steps for each Oracle Node to perform and report the result of; e.g. httpGet, jsonParse, ethTx. The Job Spec is a template for specific invocations of work, aka Job Runs, which can have unique parameters; e.g. URL, jsonPath, format.


Encumbrance

Request Payment Amount

Oracle Staked Amount

Minimum Responses: number of nodes that must respond in order for answer to return

Submitted By: deadline for the SA to be confirmed on-chain

Request Expiration Time: amount of time an Oracle Node has to respond after a RUN Request is submitted

Aggregating Function: specifies the type of data expected back

End At: the deadline to submit a Run Request

Oracle Addresses: list of all Oracle Nodes participating in Job Spec

Requester: verified by signing the SAID, checked by the oracle before signing on-chain.

Hash of Service Agreement Body: Hash of normalized Service Agreement JSON. Provides the Oracle Nodes a guarantee that they are all operating on the same data.


S.A.I.D.

hash(abi.encode(encumbranceParams... requester, hash(normalized(JobSpecJSON))))

The full encoding is submitted to the Oracle Contract. The Oracle Contract checks the validity of all of the parameters(see the Encumbrance definition for validity definitions for each parameter), then hashes them to get the Spec ID. It then checks all of the signatures of the Oracle Nodes to make sure that all of the oracles listed in the SA have actually agreed to the SA.


Deposit Contract

The Deposit Contract has a corresponding managing contract, in our case it’s the Oracle Contract. The Deposit Contract keeps track of the Withdrawable Balance for any account. Any account can call Deposit() with LINK, and that amount of LINK is credited to the account’s withdrawable balance. When that account calls Withdraw(n) they can withdraw any amount up to their Withdrawable Balance. The managing contract can increment and decrement the withdrawable balance.

In the simplest case, when a request is accepted by an oracle its withdrawable balance is decremented. When the request is fulfilled it is incremented. Further rewards and punishments can be added on in the future.

For simplicity’s sake, the diagram above shows a locking up of deposits per request. Additionally, to incentivize Oracles to stick around for the entire lifetime of a Job Spec, we will likely add an additional deposit locking round for the opening and closing of a Job Spec.


Penalty Deposits

From the white paper:

Amount of penalty payments: If penalty payments were locked in to assure a node operator’s performance, the result would be a financial metric of an oracle provider’s commitment not to engage in an “exit scam” attack, where the provider takes users’ money and doesn’t provide services. This metric would involve both a temporal and a financial dimension.

Basic functions:

  • Deposit: The node deposits an amount of LINK to the Coordinator contract
  • Lock: When a service agreement which requires a penalty fee is accepted, that amount is locked, which makes it unavailable for withdraw
  • Unlock: When the service agreement that required a penalty fee ends, that amount is unlocked, which makes it available for withdraw
  • Withdraw: The node withdraws any unlocked amount of LINK from the oracle contract

Depositing

Depositing LINK requires a small amount of gas to pay for the transaction. Your Ethereum address on the node will need to be funded for the deposit transaction to succeed.


Withdrawing

You may withdraw your LINK which is not currently locked in a service agreement as a penalty fee at any time. Once again, your Ethereum address on the node will pay for the transaction fee.


Example Scenarios

Additional actions used in the scenarios:

  • Require: The requester may require a specified amount of LINK be locked as a penalty fee for a request
  • Ends: The service agreement ends when it has expired, unlocking the LINK on deposit that was previously required

Scenario A: Node meets deposit requirement

  1. NodeA deposits 100 LINK to the Coordinator contract
    NodeA -(Deposit 100 LINK)> Coordinator
    Balances: 100 Total, 0 Penalty, 100 Withdrawable
  2. SA1 created that requires each node to lock 10 LINK as a penalty fee
    SA1 -(Require 10 LINK)> Coordinator
  3. NodeA accepts
    NodeA -(Lock 10 LINK)> Coordinator
    Balances: 100 Total, 10 Penalty, 90 Withdrawable
  4. SA1 ends
    Coordinator -(Unlock 10 LINK)> NodeA
    Balances: 100 Total, 0 Penalty, 100 Withdrawable

Scenario B: Node does not deposit

  1. NodeA never deposits LINK to the Coordinator contract
  2. SA1 created that requires each node to lock 10 LINK as a penalty fee
    SA1 -(Require 10 LINK)> Coordinator
  3. NodeA is unable to accept

Scenario C: Node cannot meet deposit requirement part 1

  1. NodeA deposits 100 LINK to the Coordinator contract
    NodeA -(Deposit 100 LINK)> Coordinator
    Balances: 100 Total, 0 Penalty, 100 Withdrawable
  2. SA1 created that requires each node to lock 110 LINK as a penalty fee
    SA1 -(Require 110 LINK)> Coordinator
  3. NodeA is unable to accept

Scenario D: Node cannot meet deposit requirement part 2

  • NodeA deposits 100 LINK to the Coordinator contract
    NodeA -(Deposit 100 LINK)> Coordinator
    Balances: 100 Total, 0 Penalty, 100 Withdrawable
  • SA1 created that requires each node to lock 100 LINK as a penalty fee
    SA1 -(Require 100 LINK)> Coordinator
  • NodeA accepts
    NodeA -(Lock 100 LINK)> Coordinator
    Balances: 100 Total, 100 Penalty, 0 Withdrawable
  • SA2 created that requires each node to lock 10 LINK as a penalty fee
    SA2 -(Require 10 LINK)> Coordinator
  • NodeA is unable to accept SA2
  • SA1 ends
    Coordinator -(Unlock 100 LINK)> NodeA
    Balances: 100 Total, 0 Penalty, 100 Withdrawable

Scenario E: Node meets multiple deposit requirements

  • NodeA deposits 100 LINK to the Coordinator contract
    NodeA -(Deposit 100 LINK)> Coordinator
    Balances: 100 Total, 0 Penalty, 100 Withdrawable
  • SA1 created that requires each node to lock 50 LINK as a penalty fee
    SA1 -(Require 50 LINK)> Coordinator
  • NodeA accepts SA1
    NodeA -(Lock 50 LINK)> Coordinator
    Balances: 100 Total, 50 Penalty, 50 Withdrawable
  • SA2 created that requires each node to lock 40 LINK as a penalty fee
    SA2 -(Require 40 LINK)> Coordinator
  • NodeA accepts SA2
    NodeA -(Lock 40 LINK)> Coordinator
    Balances: 100 Total, 90 Penalty, 10 Withdrawable
  • SA1 ends
    Coordinator -(Unlock 50 LINK)> NodeA
    Balances: 100 Total, 40 Penalty, 50 Withdrawable
  • SA2 ends
    Coordinator -(Unlock 40 LINK)> NodeA
    Balances: 100 Total, 0 Penalty, 100 Withdrawable
Was this article helpful to you? Yes No

How can we help?