From 73124f52398808b944bb3b25f36b9a716443b10d Mon Sep 17 00:00:00 2001 From: Bartosz Nowak Date: Sat, 1 Jun 2024 14:54:23 +0200 Subject: [PATCH] init docs --- docs/.gitignore | 1 + docs/book.toml | 6 ++++++ docs/src/SUMMARY.md | 18 ++++++++++++++++++ docs/src/architecture/architecture.md | 17 +++++++++++++++++ docs/src/architecture/delegator.md | 5 +++++ docs/src/architecture/executor.md | 9 +++++++++ docs/src/architecture/registry.md | 13 +++++++++++++ docs/src/installation.md | 1 + docs/src/misc/contributors.md | 1 + 9 files changed, 71 insertions(+) create mode 100644 docs/.gitignore create mode 100644 docs/book.toml create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/architecture/architecture.md create mode 100644 docs/src/architecture/delegator.md create mode 100644 docs/src/architecture/executor.md create mode 100644 docs/src/architecture/registry.md create mode 100644 docs/src/installation.md create mode 100644 docs/src/misc/contributors.md diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 0000000..8a0bd0b --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,6 @@ +[book] +authors = ["Okm165"] +language = "en" +multilingual = false +src = "src" +title = "SHARP-P2P documentation" diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 0000000..ecf2f1a --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,18 @@ +# Summary + +[Introduction](../../README.md) + +# Reference Guide + +- [Architecture](architecture/architecture.md) + - [Delegator Peer](architecture/delegator.md) + - [Executor Peer](architecture/executor.md) + - [Registry Contract](architecture/registry.md) + +# User Guide + +- [Installation](installation.md) + +----------- + +[Contributors](misc/contributors.md) diff --git a/docs/src/architecture/architecture.md b/docs/src/architecture/architecture.md new file mode 100644 index 0000000..9ce1c21 --- /dev/null +++ b/docs/src/architecture/architecture.md @@ -0,0 +1,17 @@ +## Architecture and Workflow + +We will explore the job pathway as it goes from Delegator to Executor via the peer-to-peer network to better understand the workings of this service: + +1. **Delegator Initiates Job**: The Delegator, who has funds deposited into the Registry and is part of the SHARP-P2P network, initiates a job. They define the job, which consists of a Job Header and a Job Body. The Job Header contains basic information about the task, such as its reward and its hash, while the Job Body contains the Cairo program to be executed. + +2. **Storage in Peer-to-Peer Network**: The Delegator signs and stores the Job Body in a Distributed Hash Table (DHT) within the peer-to-peer network. Simultaneously, they sign the Job Header and send it to the peer-to-peer network using a gossip-sub message. + +3. **Executor's Perspective**: An Executor within the network receives the Job Header from the Delegator. The Executor first verifies the validity of the message by checking if the Job Header was correctly signed by the Delegator. If valid, the Executor retrieves the Job Body from the DHT and performs similar checks. + +4. **Account Solvency Check**: The Executor also checks if the Delegator's account has a safe amount of funds remaining for the job reward. If everything checks out, the Executor proceeds to execute the job. + +5. **Job Execution**: The execution process consumes time and resources on the host machine. Once completed, the Executor produces a Job Witness containing the results of the Cairo program and proof of its correct execution. + +6. **Submission to Registry and Receiving Reward**: The Executor promptly submits the job to the Registry. The Registry verifies the signature of the Delegator, the hash of the job, and the job proof of correctness. If all criteria are met, the Registry sends the funds as a reward. The Delegator subscribes to the Registry contract events and, when a job is successfully registered, the output of the job is emitted. + +To sum up, the Delegator pays the Executor for doing their job in a way that is safe and sound for both parties of the SHARP-P2P network. \ No newline at end of file diff --git a/docs/src/architecture/delegator.md b/docs/src/architecture/delegator.md new file mode 100644 index 0000000..dbac329 --- /dev/null +++ b/docs/src/architecture/delegator.md @@ -0,0 +1,5 @@ +## Details on Delegator Working Process + +1. The Delegator comes up with the Cairo Program and creates the Job Header and Job Body, sending them to the peer-to-peer network. +2. If they have enough funds in the Registry and they place an attractive offer, the task will be picked up. +3. After broadcasting the Job Header, they listen for the events from the Registry to receive the verified Job Witness they pay for. diff --git a/docs/src/architecture/executor.md b/docs/src/architecture/executor.md new file mode 100644 index 0000000..de052dd --- /dev/null +++ b/docs/src/architecture/executor.md @@ -0,0 +1,9 @@ +## Details on Executor Working Process + +1. **Job Record**: This is a crucial component for the Executor. It provides information about available jobs. The Executor's goal is to identify the most profitable job opportunities from the Job Record. Since multiple Executors might start the same job simultaneously, there's a competition aspect involved. The first Executor to submit a job gets the reward for completing it. + +2. **Job Header**: Once the Executor selects a job from the Job Record, they obtain the Job Header. This contains essential metadata about the job. It acts as a pointer to the actual task details, which are stored off-chain in the peer-to-peer network. + +3. **Job Body**: The Job Body comprises all the necessary information required for executing the task, including the Cairo program and public inputs. This information is fetched from the peer-to-peer network. The Executor transforms the Job Body into the Job Witness by executing the task locally. + +4. **Job Witness**: This is the output generated by executing the task locally. It serves as proof of correct execution of the program. The Executor's main objective is to submit this Job Witness to the StarkNet Registry promptly, so they can claim the reward for completing the job before another Executor does. It's a race against time to submit the Job Witness and secure the reward. diff --git a/docs/src/architecture/registry.md b/docs/src/architecture/registry.md new file mode 100644 index 0000000..be06f07 --- /dev/null +++ b/docs/src/architecture/registry.md @@ -0,0 +1,13 @@ +## Registry Contract + +The Registry contract is a critical component of the SHARP-P2P network, responsible for the following tasks: + +1. **Fund Management**: Delegators deposit funds into the Registry to offer rewards for job execution. The Registry securely holds these funds until they are distributed to Executors. + +2. **Verification and Reward Distribution**: The Registry verifies the submitted Job Witnesses from Executors. This involves checking the Delegator's signature, the job's hash, and the proof of correct execution. If the job is verified successfully, the Registry distributes the corresponding reward to the Executor. + +3. **Event Emission**: The Registry emits events upon successful job verification and reward distribution. Delegators can subscribe to these events to receive notifications about the status of their jobs. + +4. **Security**: The Registry ensures that only valid and correctly executed jobs are rewarded. This provides a layer of trust and security for both Delegators and Executors in the network. + +By managing the financial and verification aspects, the Registry contract plays a pivotal role in maintaining the integrity and efficiency of the Sharp p2p network. \ No newline at end of file diff --git a/docs/src/installation.md b/docs/src/installation.md new file mode 100644 index 0000000..25267fe --- /dev/null +++ b/docs/src/installation.md @@ -0,0 +1 @@ +# Installation diff --git a/docs/src/misc/contributors.md b/docs/src/misc/contributors.md new file mode 100644 index 0000000..77e8114 --- /dev/null +++ b/docs/src/misc/contributors.md @@ -0,0 +1 @@ +# Contributors