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.
-
Golem is protocol for selling and using resources in Golem Network
-
Protocol is open for being extended by it's users (community)
- It provides basic specification how Nodes should communicate within Golem Network
- Protocol allows for creating sub-protocols on top of Golem, meaning that developers can define specifications that add specific bahaviors to Nodes, Provider/Requestor agents, SDKs etc.
-
Golem Factory creates specification that are guiding reference implementation of yagna daemon and Agents applications
-
This doesn't close the option to reimplement those components in complately different way
-
Example: mid-agreement payments
- On the lowest protocol level Golem defines market exchange of Offers/Demands artifacts, property constraint langauge and Payment artifacts (DebitNotes, Invoices)
- Golem Factory creates specification of protocol defining what should be included in Offer/Demand to use mid-agreement payments and how should Agent application bahave in relation to sending DebitNotes and when payments should happen
- Bahavior is implemented in reference implementation
- Other developers are allowed not to use this protocol when implementic their own Nodes
- They can prepare their own alternative specification of mid-agreement payments as well
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.
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.
This word is used to describe Offer/Demand put on market, so we should mention it.
Bottom-up description of different layers of Golem that impose structure on how we split components and facilitate communication between them. Golem is not monolithic and division of responsibility is not arbitrary.
The goal of this chapter is to sketch general idea, rather than describe specifics.
RPC-like communication layer providing a way to call other modules or other nodes in unified way.
Offers/Demands property and constraint language is used to build subprotocols for negotiating certain aspects of Agreements.
There are a few ways to implement an execution environment. We have a few APIs here:
- Bind and handle GSB messages directly
- Implement RuntimeSDK and use ExeUnit binary for common functionalities
- Command specification which can be executed by ExeUnit is flexible enough that higher level protocols could be created here.
Each specialized module exposes some APIs to users. It is either REST API, yagna cli or set of GSB endpoints for communication between modules and nodes.
This section dives into aspects of Golem network architecture to explain how they work under the hood. The level of detail does not include code structure, interfaces nor data structures but names key components and interaction between them.
- 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 sepcification (?)
- Link to design decision
- Algorithm overview
- 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
- Identification
- Relay
- Discovering Nodes
- P2P communication
- Relayed communication
- Cryptography
- Node identity verification (challenges)
- Communication encryption
- Communication is independent from net implementation
- GSB addressing
- 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
- 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
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