Authors: Witold Dzięcioł, Przemysław Rekucki, Marek Dopiera,
<YOUR NAME GOES HERE>
Reviewers: Maciej Maciejowski, Paweł Burgchardt
Status: WIP
The goal of this document is to describe present Golem architecture in enough detail for an outside person to understand how it works under the hood. The intended audience is assumed to be technical but not necessarily have deep expertise in the crypto world. The level of detail stops short of describing code and its organization but describes key technologies used in order to implement the needed functionalities.
The aim is not to dive deep into every integration, but to capture architectural decisions and their consequences.
This section describes what comprises Golem network, namely the actors, technical artifacts and activities they actors may perform on those activities. The objective of this paragraph is to tie together all the terms and provide a very high level description of what they are.
This section describes the actors using Golem Network and their role in the system.
Note: We use term Requestor not Requester.
Consumer of resources can be different person than Requestor. For example we can have web service which forwards computationally expensive jobs to Golem Network. Example: Deposits
This section describes what actors can do to the system. The descriptions are only as detailed as to explain how the actors control the artifacts. The goal is to give the reader an overview of the terms introduced by Golem without any details and establish a glossary to ensure consistency within the document.
decomposition into layers. responsibility of the layers.
decomposition into functional areas and scopes of responsibility of these layers.
a brief overview of sample applications.
This section describes the artifacts, i.e. the terms introduced in Golem Network on which actors can act. They are organized by respective aspects of Golem Network. The descriptions describe their function rather than their implementation.
Section should serve as dictionary to be linked by other chapters.
aka Golem Node. The Golem network client component. It provides a "low-level" API for Golem network participants. It delivers services for peer discovery, contract agreements,and the settlement and payment for services.
A resource-selling application. It uses the Golem API to broadcast an offer on the market and negotiate a contract. It is responsible for price negotiations and issuing an invoice for the used resources.
A resource buying application. It uses the Golem API to find an offer on the market and negotiate a contract. It is responsible for price negotiations and verifying costs during service agreement.
This word is used to describe Offer/Demand put on market, so we should mention it.
This section describes key components of Golem Network, i.e. their responsibilities, interfaces and which other components they utilize.
- how it works that two separate Yagnas can talk to each other
- Identification
- Relay
- Discovering Nodes
- P2P communication
- Relayed communication
- Cryptography
- Node identity verification (challenges)
- Communication encryption
- what it is, how it works and how it imposes a code structure and how addressing works
A description of the component responsible for making offers, counter-offers, negotiations, etc.
- Offer/Demand properties and constraint langauge
- Yagna is property agnostic - doesn't understand semantic of properties, only agent do
- Some examples of properties and costraints and how it works
- Links to more detailed docs for properties langauge and properties specification (?)
- Initial Proposal
- Countering Proposal
- What can change in counter proposal (protocols based on property langauge)?
- Provider Agent possible Proposal responses (counter, reject)
- Requestor Agent possible Proposal responses (counter, reject, propose Agreement)
- Provider Agent possible Agreement responses (accept, reject)
- Requestor possbility of Agreement Proposal cancallation
- Restarting negotiations (who can, who can't and how?)
- Who is allowed to terminate? In what situation?
- What is specified by protocol and what is left to future specifications?
- Termination reason concept
- a description of how it happens that offers are visible to reqestors
- Link to design decision
- Algorithm overview
- a description of current payment driver, its modes of operations and how it can be extended
- Describe generic model which is open for new implementations
- Payment model specification in Offer/Demand language
- Linear Payment model as an example
- Negotiating payment platform and other payment details
- Testnet(s) vs. mainnet(s)
- Tokens
- Partial payments vs. payments after Agreement finish
- DebitNotes/Invoices interactions (acceptance, rejection, cancellation)
- How DebitNote/Invoice acceptance relates to payment on blockchain?
- Payment settlement and payment confirmation for Provider
- Abstract concept (independance from underlying payment mechanisms)
- How payment platform relates to payment driver?
- Examples: erc20 driver, zksync (?)
- Overview of the concept
- Link to external documentation describing details
- How the actions on behalf of the requestor are performed
- We should dive into each important and general implementation, i.e. WASM and VM
- ExeUnit concept is generic enough to sell any kind of computation resources
- Generic ExeUnits (for example VM, WASM etc.) vs. specialized ExeUnits for specific tasks like:
- GamerHash
- outbound gateway
- http authentication
- SGX variant of ExeUnit
- These points are not meant to document those ExeUnits, rather show possible variaty based on these examples
- Interaction with yagna through GSB
- Control flow between Requestor and ExeUnit
- Extensible commands list (ExeUnit implementation dependent)
- Spawning ExeUnit (contract between Provider Agent and ExeUnit)
- Self-test
- Offer template
- Binding to GSB (addressing based on activity id)
- Requestor state control
- Commands and batches:
- Deploy, Start, Transfer, Run, Terminate
- Querying command/batch state, receiving results
- Transfer methods (GFTP, http)
- Why splitting Supervisor and Runtime?
- Common functionalities provided by Supervisor
- Virtual machine desciption (so the reader knows what is there, but not details)
- Functionalities (outbound, VPN, process output capturing)
- VM images, gvmkit-build etc
- WASM supported execution engines
- WASM images
- The component responsible for creating a VPN between VMs
- a description of how it is evaluated, distributed and used
- which of the logic useful to the user ends up in the SDK
How the components are reflected in processes, where the processes are run, what is their relation ship, etc.
This section documents how control and responsibility flows through the listed components to achieve Golem's functionalities. Any non-trivial algorithms spanning more than one component are also described here.
PR: this is part of the business logic layer. you would need to think about how to add objects from this layer and SDK implementations in different versions to this document. and the concept of building various reputation methods.
PR: ya-provider is also from this layer and you could write down what configurations it supports. e.g. node attestation, authorization certificates, etc.
This section contains known shortcomings of the implemented architecture — irrespective of whether they were intentional or unintentional.
The preexisting categories of actors (providers and requesters) and their asymmetric roles are limiting in certain scenarios. FIXME FIXME FIME