| Contract | Address |
|---|---|
| Token | 0x95E7e7Ed5463Ff482f61585605a0ff278e0E1FFb |
| Node | 0xB0E9A451Ce0CC181EA9888C7B42BB8Ad90b73C78 |
| Task | 0xba2489a25A5f542877D3825Ab802651f28878C4a |
The Crynux Network Architecture
Nonce: a random number
Task ID Commmitment: hash(Task GUID, Nonce) A ->> B: Create task activate B Note over A,B: Task ID Commitment
Nonce deactivate A B ->> B: Generate sampling seed Note over B,B: Sampling Seed: a random number activate A B -->> A: Return sampling seed Note over A,B: Sampling Seed par Upload task parameters B ->> B: Select node or enqueue until a node is selected B ->> A: Event: TaskStarted activate A Note over A,B: Task ID Commitment
Selected Node deactivate B A ->> R: Upload task parameters activate R note over A,R: Encrypted Task Parameters deactivate A R ->> B: Update Merkle root note over B,R: Merkle Root R -->> A: Return hash and Merkle proof activate A note over A,R: Hash of Encrypted Task Parameters
Merkle Proof deactivate R A ->> B: Notify task parameters uploaded activate B note over A,B: Task ID Commitment
Hash of Encrypted Task Parameters
Merkle Proof deactivate A B ->> N: Event: TaskParametersUploaded note over B,N: Task ID Commitment
Hash of Encrypted Task Parameters
Selected Node deactivate B and Send validation tasks activate A A ->> A: Generate Sampling Number
Using VRF note over A,A: Sampling Number: VRF(Sampling Seed, Private Key) opt Last digit of the Sampling Number is 0 loop Repeat 2 times A ->> B: Create validation task and upload the task parameters deactivate A end end end " %} ``` ### Task GUID and Task ID Commitment To initiate a task, the application creates a unique `Task GUID`. The `Task GUID` for each task is obscured by generating a `Task ID Commitment`. This commitment is a hash of the real `Task GUID` combined with a random number `Nonce`. For three tasks within the same validation group, each `Task ID Commitment` is derived from the same `Task GUID` but uses different random numbers, making them appear unrelated in public data. Only the `Task ID Commitment` is sent to the blockchain, and is used to identify the task during the whole task lifecycle. This prevents the nodes from knowing whether the task will be validated or not. After execution, the application will reveal the real `Task GUID` on the blockchain. This allows the blockchain to validate task relationships, preventing the application from fraudulently grouping unrelated tasks. This ensures honest nodes are not penalized. ### Secret Selection of Validation Tasks The sampling process begins when the application sends the transaction to create a task on the blockchain. Upon receiving the task, the blockchain generates a random number to be used as the `Sampling Seed` for the VRF and return it to the application. The application uses VRF locally to generate the `Sampling Number`, using the `Sampling Seed` and its own private key as the VRF inputs. With a 10% sampling ratio, the task will be selected for validation if the `Sampling Number` ends in 0. The `Sampling Number` is only known to the application, since no one else knows its private key. The application cannot cheat on the `Sampling Number` either, as the `Sampling Seed` is fixed on the blockchain. Additionally, the public key of the application is set before the task and is known to the blockchain. ### Sending the Validation Tasks If the task is not selected for validation, the application will simply stop and await for the notification to upload the `Task Parameters`. However, if the task is selected, the application must send two additional tasks with the same `Task Parameters` for validation purposes. {% hint style="info" %} The application will not get the computing result if the validation tasks are not submitted or if they are submitted with inconsistent parameters. The blockchain will verify the correctness of the validation tasks before allowing the application to get the computation result. More details are provided in the next section. {% endhint %} The fees charged for the validation tasks will be refunded once the task is completed. This extra charge ensures that the validation tasks appear identical to regular tasks, preventing nodes from distinguishing them based on the fees. If an application sends tasks infrequently, such as a human sending tasks to the blockchain via a browser-based DApp and Metamask, the node can monitor the user's address for new tasks. If no additional tasks are sent from the same address in a short period, the task is likely non-validation. However, if tasks are sent frequently, it becomes impossible for the node to determine if a task is for validation. The higher probability of guessing correctly increases the chance of a node performing a successful [statistical attack](/system-design/consensus-protocol#expectation-of-the-income). Increasing the required amount of staking could solve this issue. A task mixer can also be designed to combine tasks from all applications before dispatching them to the nodes, thereby concealing the origin of the tasks from the nodes. ### Uploading Task Parameters to the DA/Relay When a task is created on the blockchain, the blockchain will try to select a node based on the task's criteria. If no node is available, the task is added to a queue. Once a new node becomes available, the task is retrieved from the queue and executed. Details of this process are outlined in the following document: {% content-ref url="/pages/Y7oaQ7V3uKJTimOkHrhD" %} [Task Dispatching](/system-design/task-dispatching) {% endcontent-ref %} When a node is selected for the task, the blockchain will emit `TaskStarted` event to notify the application to upload `Task Parameters`. Knowing which node will execute the task, the application encrypts the `Task Parameters`, such as the prompt and image size, using the node's public key. It then sends the `Encrypted Task Parameters` to the DA/Relay service and gets the `Merkle Proof` in return. {% hint style="info" %} The DA/Relay will save the data and make it publicly available. A [Merkle Tree](https://en.wikipedia.org/wiki/Merkle_tree) is generated for a collection of recently submitted data, and the Merkle Root is sent to the smart contract on the blockchain. The application receives the Merkle Proof for the data. Using the correct Merkle Proof, the blockchain can verify data availability under a specific hash, confirming its existence and public accessibility. {% endhint %} The `Encrypted Task Parameters` can only be decrypted by the assigned node. Nodes cannot decrypt the parameters of other tasks, making it impossible to determine if a task will be validated by comparing task parameters. After sending the `Encrypted Task Parameters` to the DA/Relay and obtaining the `Merkle Proof`, the application notifies the blockchain by sending the `Merkle Proof` to the blockchain. The blockchain verifies the `Merkle Proof`, and emits `TaskParametersUploaded` event to notify the node to start the execution. The verification of the `Merkle Proof` only makes sure **some** **data** is uploaded to the DA/Relay and is claimed to be the encrypted `Task Parameters` for the given `Task ID Commitment`, it doesn't guarantee the correctness of the `Task Parameters`. The task parameters may still be inconsistent across tasks in a validation group, may be in an invalid format, or may be undecryptable by the node at all. If the `Task Parameters` are invalid, the node will report error to the blockchain, and the task will be aborted. The task fee is returned to the application, but the transaction fee is still charged, which will stop the application from sending the invalid `Task Parameters` intentionally. The consistency of the `Task Parameters` across the validation group will be verified later using Zero-Knowledge Proof (ZKP). ## Task Execution Upon receiving the `TaskParametersUploaded` event from the blockchain, the node retrieves the `Encrypted Task Parameters` from the DA/Relay service, decrypts them, and executes the task on the local GPU. After the computation is finished, the node will calculate the `Sim Hash` of the result, and send the `Sim Hash` to the blockchain. Then the node should wait for a future notification from the blockchain. If the wait exceeds the timeout period, the node may abort the task. The task fee will then be refunded to the application. The node cannot send the task result to the DA/Relay service at this stage. If the result is transmitted, the application could retrieve it prematurely and disrupt subsequent processes. The blockchain lacks mechanisms to identify and penalize the application in such scenarios. When the `Sim Hash` is sent, the blockchain emits `TaskResultReady` event to notify the application. If the `Task Parameters` are invalid, the node will report error to the blockchain, and the blockchain will emit `TaskErrorReported`. In both cases, the task enters the **Result Validation** stage. ## Result Validation When the `TaskResultReady` or `TaskErrorReported` event is received, the application should proceed with one of two different strategies based on the previously generated `Sampling Number`. ### Tasks Require Validation {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain Participant N as Node ``` activate B loop Until events from all three tasks are received alt B ->> A: Event: TaskResultReady activate A Note over A,B: Task ID Commitment
Sim Hash else B ->> A: Event: TaskErrorReported activate A Note over A,B: Task ID Commitment deactivate B end A ->> A: Wait for other validation tasks end A ->> B: Finish task activate B Note over A,B: Task ID Commitment
Task GUID
Sampling Number
VRF Proof
Hash of Task Parameters
ZK Proof deactivate A B ->> B: Validate task break Task error reported B ->> A: Event: TaskAborted end alt Sim Hash identical B ->> N: Event: TaskValidated Note over B,N: Task ID Commitment else One Sim Hash different B ->> N: Event: NodeSlashed else All Sim Hash different B ->> A: Event: TaskAborted end deactivate B " %} ``` If the `Sampling Number` ends with 0, the task requires validation. The application will wait for the submission of all the 3 `Sim Hash` (or error reporting) on the blockchain, and then disclose the relationship of the tasks, and other relevant proofs for the blockchain to validate: #### Sampling Number Validation The application sends the `VRF Proof` and the `Sampling Number` to the blockchain, and the blockchain validates the `Sampling Number` using the `VRF Proof` and the `Application Public Key`. This ensures that the `Sampling Number` is generated from the on-chain `Sampling Seed` and the application's private key. {% @mermaid/diagram content="graph LR sn\[Sampling Number] --> |VRF Proof| ss\[Sampling Seed] ss --> bc\[Blockchain] sn --> |VRF Proof| pk\[Application Public Key] pk --> bc" %} If the `VRF Proof` is valid, the blockchain will verify whether the `Sampling Number` ends in 0. If valid, the blockchain confirms that the task was genuinely selected during the secret task selection. #### Task Relationship Validation The application sends the `Task ID Commitment` of all three tasks along with the actual `Task GUID` to the blockchain. The blockchain validates the `Task ID Commitment` with the previously uploaded `Nonce`, ensuring they are generated from the same `Task GUID`. The task relationship validation ensures the application does not send misleading information to the blockchain, such as the combination of three irrelevant tasks, which could cause honest nodes to be penalized. #### Task Parameters Validation This validation ensures the `Task Parameters` provided by the application are consistent across all three nodes. Inconsistent parameters given to different nodes result in different `SimHash` being submitted to the blockchain, causing honest nodes to be penalized. The validation is implemented using Zero-Knowledge Proofs. The application sends the hash of the `Task Parameters`, along with a `ZK Proof` to the blockchain. {% @mermaid/diagram content="graph TD tp\[Task Parameters] --> |ZK Proof| hash\[Hash of Task Parameters] hash --> |Compare| ot\[Other Tasks] tp --> |ZK Proof| etp\[Encrypted Task Parameters] pk\[Node Public Key] --> |ZK Proof| etp etp --> |ZK Proof| hetp\[Hash of Encrypted Task Parameters] hetp --> |Merkle Proof| bc\[Blockchain]" %} The `ZK Proof` is constructed to use the plain text `Task Parameters` as the private input, the `Public Key` of the node as the public input, and publicly outputs the hash of the `Task Parameters` and the hash of the `Encrypted Task Parameters`. A valid `ZK Proof` ensures that: 1. The `Task Parameters` has the given hash value `Hash of Task Parameters`. 2. The `Task Parameters` are encrypted using the `Node Public Key`, and the cipher text has the given hash value `Hash of Encrypted Task Parameters`. If the `ZK Proof` is valid, the blockchain verifies that the three `Hash of Encrypted Task Parameters` match those provided by the application in the **Task Creation** stage, which are previous verified using the `Merkle Proof`. This ensures that the `Task Parameters` referenced in the `ZK Proof` are identical to those actually executed by the nodes. The blockchain then compares the three `Hash of Task Parameters` to ensure they are identical. This prevents the application from submitting inconsistent `Task Parameters` to different nodes, which could lead to the penalization of the honest nodes. There is no way to penalize the application for submitting inconsistent `Task Parameters` for different tasks in a validation group. The application could always escape from the penalization by not sending the validation transaction, and simply waiting for the timeout of the tasks. The application will not send inconsistent tasks intentionally though, since there is a small cost of the transaction fee, and there is no benefit at all. #### Task Result Validation The blockchain uses three `Sim Hash` values to verify task results. If one node submits a `Sim Hash` significantly different from the other two, it will be penalized. If all the three `Sim Hash` are different, the task will be aborted. ### Tasks Do Not Require Validation {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain Participant N as Node ``` alt B ->> A: Event: TaskResultReady activate A Note over A,B: Task ID Commitment
Sim Hash else B ->> A: Event: TaskErrorReported Note over A,B: Task ID Commitment end A ->> B: Finish task activate B Note over A,B: Task ID Commitment
Sampling Number
VRF Proof deactivate A B ->> B: Validate Sampling Number break Task error reported B ->> A: Event: TaskAborted end B ->> N: Event: TaskValidated Note over B,N: Task ID Commitment deactivate B" %} ``` If the `Sampling Number` does not end in 0, which means the task does not require validation, the validation will be much simpler. The [Relationship Validation](#task-relationship-validation) and the [Parameters Validation](#task-parameters-validation) are both skipped. Only the `Sampling Number` needs validation to ensure the task doesn't require result validation. The [Sampling Number Validation](#sampling-number-validation) remains unchanged, with the exception that the blockchain must ensure the `Sampling Number` does not end in 0. ## Result Retrieval {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain Participant N as Node Participant D as DA/Relay ``` B ->> N: Event: TaskValidated activate N Note over B,N: Task ID Commitment N ->> D: Send task result activate D Note over N,D: Encrypted Task Result deactivate N D ->> B: Update Merkle root Note over B,D: Merkle Root D -->> N: Return Merkle proof activate N Note over N,D: Hash of Encrypted Task Result
Merkle Proof deactivate D N ->> B: Report result uploaded deactivate N activate B Note over B,N: Task ID Commitment
Hash of Encrypted Task Result
Merkle Proof
ZK Proof B ->> B: Validate proofs B ->> B: Settle task fee B ->> A: Event: TaskSuccess activate A Note over A,B: Task ID Commitment deactivate B A ->> D: Get task result deactivate A activate D D -->> A: Return task result note over A,D: Encrypted Task Result deactivate D ``` " %} After the node receives the `TaskValidated` event, it encrypts the task result using the public key of the application, and sends the cipher text to the DA/Relay service. After receiving the `Merkle Proof`, the node generates a `ZK Proof` and submits it to the blockchain. {% @mermaid/diagram content="graph TD tr\[Task Result] --> |ZK Proof| sh\[Sim Hash] tr --> |ZK Proof| etr\[Encrypted Task Result] pk\[Application Public Key] --> |ZK Proof| etr etr --> |ZK Proof| hetr\[Hash of Encrypted Task Result] sh --> bc\[Blockchain] hetr --> |Merkle Proof| bc " %} The `ZK Proof` uses the `Task Result` as the private input, the `Application Public Key` as the public input, and publicly outputs the `Sim Hash`, and the `Hash of Encrypted Task Result`. A valid `ZK Proof` makes sure: 1. The `Task Result` has the given `Sim Hash`. 2. The `Task Result` is encrypted using the `Application Public Key`, and the cipher text has the given hash `Hash of Encrypted Task Result`. The blockchain verifies the `Sim Hash` against the previously submitted one from the node to pass the result validation. This ensures that the `Task Result` produces the correct `Sim Hash`. The blockchain verifies the `Hash of Encrypted Task Result` using the `Merkle Proof` against the `Merkle Root` submitted by the DA/Relay. This ensures that the correct cipher texts have been uploaded to the DA/Relay service and are accessible to the application. If all the validation passes, the blockchain distributes the task fee to all participating nodes based on their [QoS scores](/system-design/quality-of-service-qos) and notifies the application to retrieve the task result. Once the application retrieves the result, the task is marked as completed. # Task Lifecycle From the task creation to the task success ## Overview Tasks are central to the Crynux Network. Each application use case is represented as a different task. Applications interact with the network by sending various tasks, and nodes are responsible solely for executing these tasks. A task consists of a group of `Task Parameters`. For instance, in a Stable Diffusion image generation task, the `Task Parameters` might include: * **Text Prompt:** The description or scene you want to generate. * **Image Size:** Dimensions of the generated image. * **Guidance Scale:** Controls the strength of the prompt on the image generation. * **Controlnet Image:** An image used as the reference in the Controlnet. Here is a concrete example of the `Task Parameters` of an SD image generation task: ```json { "version": "2.0.0", "base_model": { "name": "stabilityai/sdxl-turbo" }, "prompt": "best quality, ultra high res, photorealistic++++, 1girl, desert, full shot, dark stillsuit, " "stillsuit mask up, gloves, solo, highly detailed eyes," "hyper-detailed, high quality visuals, dim Lighting, ultra-realistic, sharply focused, octane render," "8k UHD", "negative_prompt": "no moon++, buried in sand, bare hands, figerless gloves, " "blue stillsuit, barefoot, weapon, vegetation, clouds, glowing eyes++, helmet, " "bare handed, no gloves, double mask, simplified, abstract, unrealistic, impressionistic, " "low resolution,", "task_config": { "num_images": 9, "steps": 1, "cfg": 0 }, "lora": { "model": "https://civitai.com/api/download/models/178048" }, "controlnet": { "model": "diffusers/controlnet-canny-sdxl-1.0", "image_dataurl": "data:image/png;base64,12FE1373...", "preprocess": { "method": "canny" }, "weight": 70 }, "scheduler": { "method": "EulerAncestralDiscreteScheduler", "args": { "timestep_spacing": "trailing" } } } ``` The lifecycle of a task consists of four stages: **Task Creation**, **Task Execution**, **Result Validation**, and **Result Retrieval**. In the **Task Creation** stage, the application initiates a task by sending a transaction to the blockchain. The `Task Parameters` are not sent to the blockchain due to size constraints. Instead, the application sends the task's consensus-related metadata to the blockchain to create the task. Once the task is dispatched to a node, the application encrypts the `Task Parameters` using the node's public key and sends them to the DA/Relay. To ensure successful cross-validation for the nodes, the blockchain may require the application to send two additional tasks with identical `Task Parameters`. The application will be unable to obtain the computation results if the additional tasks are not sent. In the **Task Execution** stage, the node is notified about the task by the blockchain. It then receives the task metadata from the blockchain, fetches the `Task Parameters` from the DA/Relay, and executes the task locally. Upon a successful run, the node computes the similarity hash of the result and submits it to the blockchain for validation. In the **Result Validation** stage, the application either completes the task directly or waits for other validation tasks to complete, based on the VSS selection result. In both scenarios, it must submit the relevant proofs to the blockchain to initiate validation. The application will not be able to get the computation result if the proofs are not submitted. The blockchain will perform the validation. Once validation is complete, the task proceeds to the **Result Retrieval** stage. The node will upload the actual computation result to the DA/Relay, and claim the task fee from the blockchain by proving the availability of the computation result to the application. The node will get the task fee immediately when the validation completes on-chain. No interaction from the application is required. After the validation, the application is notified to download the result from the DA/Relay, and the task is completed. The subsequent sections detail all the stages. This document focuses on listing the interaction steps between components, the parameters required for each step, and the possible status and return values. Explanations on why a parameter is required are given in other documents. For the validation related parameters, refer to the following document: {% content-ref url="/pages/pxDilxJ3o0ya0wNKpnTu" %} [Verifiable Secret Sampling](/system-design/verifiable-secret-sampling) {% endcontent-ref %} For the node criteria related parameters, refer to the following document: {% content-ref url="/pages/Y7oaQ7V3uKJTimOkHrhD" %} [Task Dispatching](/system-design/task-dispatching) {% endcontent-ref %} And the pricing related parameters: {% content-ref url="/pages/QAZOlU2eJGyB4PPBPOXI" %} [Task Pricing](/system-design/task-pricing) {% endcontent-ref %} The task lifecycle is modeled and implemented as the [Finite State Machine (FSM)](https://en.wikipedia.org/wiki/Finite-state_machine) in the smart contract. All the states and possible transitions are given in the document below: {% content-ref url="/pages/OQilzRJn2d1IYfRJPv3u" %} [Task State Transitions](/system-design/task-lifecycle/task-state-transitions) {% endcontent-ref %} ## Task Creation ### Create Task On-Chain {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain ``` A ->> B: Create Task activate B Note over A,B: Task ID Commitment
Nonce
Model ID
Minimum VRAM
Required GPU
Task Fee
Task Version break Task Fee == 0 or Nonce is not unique B -->> A: Tx reverted end B ->> A: Event: TaskCreated activate A Note over A,B: Sampling Seed deactivate B A ->> A: Generate Sampling Number
Using VRF opt Last digit of the Sampling Number is 0 loop Repeat 2 times A ->> B: Create the validation task and upload Task Parameters end end deactivate A activate B alt Node available B ->> A: Event: TaskStarted Note over A,B: Task ID Commitment
Selected Node else No node available B ->> A: Event: TaskQueued Note over A,B: Task ID Commitment loop New node available break Node available for task B ->> B: Select node B ->> A: Event: TaskStarted Note over A,B: Task ID Commitment
Selected Node deactivate B end end end" fullWidth="false" %} ``` The application starts a task by signing a transaction, invoking the smart contract to create the task on the Blockchain. The application must set the task fee it is willing to pay in the `value` field of the transaction. The transaction might be reverted, due to several reasons: * The transaction value is not set (task fee is not paid). * The Nonce has already been used before. If the transaction is confirmed, the application receives a `Sampling Seed`. The application then uses the VRF algorithm with this `Sampling Seed` to generate a `Sampling Number`. If the last digit of the `Sampling Number` is 0, the application should create two additional tasks to form a task validation group. The details of the task validation are described in the following document: {% content-ref url="/pages/pxDilxJ3o0ya0wNKpnTu" %} [Verifiable Secret Sampling](/system-design/verifiable-secret-sampling) {% endcontent-ref %} For each of the tasks, the blockchain will attempt to locate a suitable node that is available to execute the task. If such a node is found, the task starts immediately. Otherwise, the task is added to the queue and `TaskQueued` event is emitted. When a new node becomes available, it will retrieve the task from the queue and begin execution. In both cases, the blockchain emits a `TaskStarted` event when the task begins, including the node's address. Details of this process are outlined in the following document: {% content-ref url="/pages/Y7oaQ7V3uKJTimOkHrhD" %} [Task Dispatching](/system-design/task-dispatching) {% endcontent-ref %} ### Upload Task Parameters {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain Participant R as DA/Relay Participant N as Node ``` activate B B ->> A: Event: TaskStarted activate A Note over A,B: Task ID Commitment
Selected Node deactivate B A ->> R: Upload task parameters activate R note over A,R: Encrypted Task Parameters deactivate A R ->> B: Update Merkle root note over B,R: Merkle Root R -->> A: Return hash and Merkle proof activate A note over A,R: Hash of Encrypted Task Parameters
Merkle Proof deactivate R A ->> B: Notify task parameters uploaded activate B note over A,B: Task ID Commitment
Hash of Encrypted Task Parameters
Merkle Proof deactivate A break Validation failed B -->> A: Validation failed end B ->> N: Event: TaskParametersUploaded note over B,N: Task ID Commitment
Hash of Encrypted Task Parameters
Selected Node deactivate B" fullWidth="false" %} ``` Upon receiving the `TaskStarted` event, the application should encrypt the `Task Parameters` using the node's public key and send them to the DA/Relay. The DA/Relay will update the `Merkle Root` to the blockchain for validation, and return the `Merkle Proof` to the application. The application sends the hash and `Merkle Proof` to the blockchain. The blockchain verifies the proof against the `Merkle Root` submitted by the DA/Relay, ensuring the `Task Parameters` are uploaded. It then emits the `TaskParametersUploaded` event to notify the node to start execution. ## Task Execution {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain Participant N as Node Participant R as DA/Relay ``` B ->> N: Event: TaskParametersUploaded Note over B,N: Task ID Commitment
Hash of Encrypted Task Parameters
Selected Node activate N N ->> R: Get task parameters activate R Note over N,R: Hash of Encrypted Task Parameters deactivate N R -->> N: Return the encrypted task parameters activate N Note over N,R: Encrypted Task Parameters deactivate R N ->> N: Execute the task locally break Task not executable N ->> B: Report task error activate B B ->> A: Event: TaskErrorReported deactivate B end N ->> N: Calculate the task score N ->> B: Submit the score activate B Note over N,B: Task ID Commitment
Task Score B ->> A: Event: TaskScoreReady Note over A,B: Task ID Commitment
Task Score deactivate B break Waiting exceeds timeout N ->> B: Abort task deactivate N activate B B ->> A: Event: TaskAborted deactivate B end ``` " fullWidth="false" %} When the node receives the `TaskStarted` event, it will start to execute the task locally. The execution starts by fetching the `Encrypted Task Parameters` from the DA/Relay. After the parameters are received, the node decrypts them using its own private key, and starts the execution. The first step is to download the models. The node will check the local existence of the models specified in the `Task Parameters`. If the models are not cached locally, they will be downloaded from the network. If there are network issues during the download, the node will retry the download several times until the timeout period is reached. The task will be cancelled by the node if the timeout is reached. If the model download link is confirmed to be invalid, such as a 404 response from Civitai, the node will report error to the blockchain. The task is then sent to the execution engine of the node. If the execution engine finds out that the task is misconfigured, such as an SDXL LoRA model combined with an SD1.5 base model, it will report the error to the blockchain. When the task has finished execution successfully, the node has the final computation result such as the images. It will calculate the score of the result, and then submit it to the blockchain. The blockchain will emit `TaskScoreReady` event to the application, and wait for the application to perform the validation process. The node will also wait for the task validation. If validation isn't completed within the timeout period, the node might abort the task to accept new ones instead of waiting indefinitely. ## Result Validation {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain Participant N as Node ``` alt B ->> A: Event: TaskScoreReady activate A Note over A,B: Task ID Commitment
Task Score else B ->> A: Event: TaskErrorReported Note over A,B: Task ID Commitment else B ->> A: Event: TaskAborted Note over A,B: Task ID Commitment end alt Validation not required A ->> B: Validate single task activate B Note over A,B: Task ID Commitment
Sampling Number
VRF Proof deactivate A B ->> B: Validate Sampling Number break Validation failed B -->> A: Validation error end break Task error reported B ->> A: Event: TaskAborted end B ->> N: Event: TaskValidated Note over B,N: Task ID Commitment deactivate B else Validation required activate A activate B loop Until events from all three tasks are received A ->> A: Wait for other validation tasks alt B ->> A: Event: TaskScoreReady Note over A,B: Task ID Commitment
Task Score else B ->> A: Event: TaskErrorReported Note over A,B: Task ID Commitment else B ->> A: Event: TaskAborted Note over A,B: Task ID Commitment end end deactivate B A ->> B: Validate task group activate B Note over A,B: Task ID Commitments
Task GUID
Sampling Number
VRF Proof
Hash of Task Parameters
ZK Proof deactivate A B ->> B: Validate task break Invalid proofs B -->> A: Validation error end break Task error reported B ->> A: Event: TaskAborted end alt Task Score identical B ->> N: Event: TaskValidated Note over B,N: Task ID Commitment else One Task Score different B ->> N: Event: NodeSlashed else All Task Score different B ->> A: Event: TaskAborted end deactivate B end " fullWidth="false" %} ``` Upon receiving the `TaskResultReady` event, the application's response varies based on the need for task validation: ### Task does not Require Validation If the task does not require validation, the application should send the "Complete Task" transaction directly to the blockchain, including proofs of the `Sampling Number`. The blockchain will then validate the proofs. If the validation passes, the blockchain will emit `TaskValidated` event to the node to notify it to disclose the actual computation result. The transaction will fail if the validation does not pass. For more information on the validation process, please see the following document: {% content-ref url="/pages/pxDilxJ3o0ya0wNKpnTu" %} [Verifiable Secret Sampling](/system-design/verifiable-secret-sampling) {% endcontent-ref %} ### Task Requires Validation If validation is required, the application should wait for the `TaskResultReady` event from the other two tasks in the validation group. Once all three tasks have submitted their similarity hashes, the application will disclose their relationship for blockchain validation. There are more validations to be performed by the blockchain, comparing to the validation of tasks that do not require validation. For more information on the validation process, please see the following document: {% content-ref url="/pages/pxDilxJ3o0ya0wNKpnTu" %} [Verifiable Secret Sampling](/system-design/verifiable-secret-sampling) {% endcontent-ref %} If the validation passes, the blockchain will emit `TaskValidated` event to all the three nodes. The transaction will fail if the proofs provided by the application are invalid. If the `Sim Hash` are different across the nodes, if two of them are identical, the other node will be slashed. If all three `Sim Hash`are different, the task will be aborted. ## Result Retrieval {% @mermaid/diagram content="sequenceDiagram Participant A as Application Participant B as Blockchain Participant N as Node Participant D as DA/Relay ``` B ->> N: Event: TaskValidated activate N Note over B,N: Task ID Commitment N ->> D: Send task result activate D Note over N,D: Encrypted Task Result deactivate N D -->> B: Update Merkle root note over B,D: Merkle Root D -->> N: Return Merkle proof activate N Note over N,D: Hash of Encrypted Task Result
Merkle Proof deactivate D N ->> B: Report result uploaded activate B Note over B,N: Task ID Commitment
Hash of Encrypted Task Result
Merkle Proof
ZK Proof deactivate N B ->> B: Validate proofs break Validation failed B -->> N: Validation failed end B ->> B: Settle task fee B ->> A: Event: TaskSuccess activate A Note over A,B: Task ID Commitment deactivate B A ->> D: Get task result deactivate A activate D D -->> A: Return task result note over A,D: Encrypted Task Result deactivate D ``` " fullWidth="false" %} Upon receiving the `TaskValidated` event, the node can upload the computation result to the DA/Relay service and obtain the task fee by proving to the blockchain that the upload was correct. The proving is implemented using ZKP, the details are described in the following section of the documentation: {% content-ref url="/pages/pxDilxJ3o0ya0wNKpnTu" %} [Verifiable Secret Sampling](/system-design/verifiable-secret-sampling) {% endcontent-ref %} The computation result is encrypted with the application's public key before being sent to the DA/Relay, ensuring that only the application can decrypt and access the actual result. Once the node submits the proofs to the blockchain, and they are verified, the blockchain will transfer the task fee to the node and emit a `TaskSuccess` event to the application. The application can then retrieve the computation result from the DA/Relay service, completing the task. # Task State Transitions Task as Finite State Machine (FSM) ## State Transition Graph Relay owns task deadlines. A task can be aborted only by the deadline rule for its current state, or by its creator while it is still `Queued`. A selected node cannot abort a task. The task state transition graph is given below. Deadline transitions to `EndAborted` are listed separately after the graph: ```mermaid stateDiagram-v2 state "Queued" as q state "Started" as s state "Parameters Uploaded" as pu state "Error Reported" as er state "Score Ready" as sr state "Validated" as v state "Group Validated" as gv state "End Group Refund" as egr state "End Success" as es state "End Group Success" as egs state "End Invalidated" as ei state "End Aborted" as ea [*] --> q: App - create task [*] --> s: App - create task q --> s: Blockchain - start task s --> pu: Relay - report parameters uploaded pu --> sr: Node - submit task score pu --> er: Node - report task error sr --> ei: App - validate task group sr --> v: App - validate single task sr --> gv: App - validate task group gv --> egs: Relay - report result uploaded sr --> egr: App - validate task group er --> ea: App - validate single task
App - validate task group er --> ei: App - validate task group v --> es: Relay - report result uploaded ea --> ea: App - validate task group es --> [*] egr --> [*] egs --> [*] ei --> [*] ea --> [*] ``` ## Deadline Transitions Only the row matching the current state applies. A state transition invalidates the preceding deadline. | Current state | Deadline | Transition | Fee handling | Node handling | | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | ------------------------------------------------------------------------- | -------------------------------------------------- | | `Queued` | Ordinary GPT and Stable Diffusion: `CreateTime + queue_timeout_seconds`. Stable Diffusion fine-tuning: `CreateTime + 3 minutes + Timeout`. | `Queued → EndAborted`, reason `TaskAbortTimeout` | Full refund | No selected node and no penalty | | `Started` or `ParametersUploaded` | `StartTime + Timeout` | Current state `→ EndAborted`, reason `TaskAbortTimeout` | Full refund | Execution-timeout health penalty, then release | | `ScoreReady` or `ErrorReported` | `ScoreReadyTime + app_validation_timeout_seconds` | Current state `→ EndAborted`, reason `TaskAbortCreatorValidationTimeout` | No refund; distribute this task's fee using the successful-task fee split | No penalty, then release | | `Validated` or `GroupValidated` | `ValidatedTime + result_upload_timeout_seconds` | Current state `→ EndAborted`, reason `TaskAbortResultUploadTimeout` | Full refund | Result-upload-timeout health penalty, then release | For ordinary GPT and Stable Diffusion tasks, Relay calculates execution `Timeout` after selecting the exact GPU variant. The execution parameters are estimates only; they do not determine validation, consensus, payment, or slashing. `TaskAbortCreatorValidationTimeout` means the creator did not complete validation by the deadline. Its fee distribution compensates the node operator and eligible delegators for node time already occupied. The task remains `EndAborted`, and the distribution does not mean the result was correct. This applies to both `ScoreReady` and `ErrorReported`. If any validation-group member reaches `EndAborted` for `TaskAbortCreatorValidationTimeout`, Relay permanently rejects validation of the whole group. The group cannot be validated by excluding that member. Other members retain their own deadlines and current states until they independently reach terminal states. The creator can cancel only a task whose current state is `Queued`. This transition uses the creator-cancellation reason, gives a full refund, and does not penalize a node. ## Group Validation Results When a task is validated in a validation group, its result state is determined according to the table below: Rows containing `EndAborted` apply only when no member has ended with `TaskAbortCreatorValidationTimeout`. That reason permanently makes the group ineligible for validation.
| Task 1 Before | Task 2 Before | Task 3 Before | Task 1 After | Task 2 After | Task 3 After |
|---|---|---|---|---|---|
| ScoreReady (A) | ScoreReady (A) | ScoreReady (A) | GroupValidated | EndGroupRefund | EndGroupRefund |
| ScoreReady (A) | ScoreReady (A) | ScoreReady (B) | GroupValidated | EndGroupRefund | EndInvalidated |
| ScoreReady (A) | ScoreReady (B) | ScoreReady (C) | EndAborted | EndAborted | EndAborted |
| ScoreReady (A) | ScoreReady (A) | ErrorReported | GroupValidated | EndGroupRefund | EndInvalidated |
| ScoreReady (A) | ScoreReady (B) | ErrorReported | EndAborted | EndAborted | EndAborted |
| ScoreReady (A) | ScoreReady (A) | EndAborted | GroupValidated | EndGroupRefund | EndAborted |
| ScoreReady (A) | ScoreReady (B) | EndAborted | EndAborted | EndAborted | EndAborted |
| ScoreReady | ErrorReported | ErrorReported | EndInvalidated | EndAborted | EndAborted |
| ScoreReady | ErrorReported | EndAborted | EndAborted | EndAborted | EndAborted |
| ScoreReady | EndAborted | EndAborted | EndAborted | EndAborted | EndAborted |
| ErrorReported | ErrorReported | ErrorReported | EndAborted | EndAborted | EndAborted |
| ErrorReported | ErrorReported | EndAborted | EndAborted | EndAborted | EndAborted |
| ErrorReported | EndAborted | EndAborted | EndAborted | EndAborted | EndAborted |
| EndAborted | EndAborted | EndAborted | EndAborted | EndAborted | EndAborted |
| State | Action |
|---|---|
| Group Validated | Record the address of all the 3 nodes in the validation group. |
| End Success | Settle the payment. Release the node. |
| End Group Refund | Refund the payment. Release the node. |
| End Group Success | Distribute payment to 3 nodes. Release the node. |
| End Invalidated | Refund the payment. Slash the node. |
| End Aborted: CreatorValidationTimeout | Distribute this task's fee using the successful-task fee split as compensation for occupied node time. Do not mark the result correct. Do not penalize the node. Release the node. |
| End Aborted: all other reasons | Refund the payment. Apply a node health penalty only when the specific reason assigns the timeout to the node. Release a selected node. |
The task score of a node by its submission order and status
| Blockchain | Platform | Requirements | Download Link |
|---|---|---|---|
| Base | Windows | Nvidia GPU with 8GB VRAM | https://drive.google.com/uc?id=11xaq4TYq9N4cYP70o8OEjH4MaP1I3GhN&export=download |
| Base | Mac | M1/M2/M3 and later | https://github.com/crynux-network/crynux-node/releases/download/v3.5.1/crynux-node-lithium-v3.5.1-base-mac-arm64-unsigned.dmg |
| Near | Windows | Nvidia GPU with 8GB VRAM | |
| Near | Mac | M1/M2/M3 and later |
| Hardware | Requirements |
|---|---|
| GPU | NVIDIA GPU with 8GB VRAM |
| Memory | 16GB |
| Disk Space | 60GB |
| Network | Public network access to Huggingface and Civitai |
| Hardware | Requirements |
|---|---|
| Model | Mac M1, M2, M3 or newer |
| Memory | 16GB |
| Disk Space | 60GB |
| Network | Public network access to Huggingface and Civitai |
| Hardware | Requirements |
|---|---|
| GPU | NVIDIA GPU with 8GB VRAM |
| Memory | 16GB |
| Disk Space | 60GB |
| Network | Public network access to Huggingface and Civitai |
If you have 16GB of memory and use Docker with WSL2 on Windows
The memory limit for WSL is default to 8GB, which is not enough to run the Node. You will have to change the default settings using a [`.wslconfig`](https://learn.microsoft.com/en-us/answers/questions/1296124/how-to-increase-memory-and-cpu-limits-for-wsl2-win) file to allow WSL to use 16GB memory.If you are running on Linux (Ubuntu/Fedora/CentOS/...)
Install the latest version of NVIDIA Container Toolkit:$ sudo docker run --rm --gpus all ubuntu nvidia-smi
| Hardware | Requirements |
|---|---|
| GPU | NVIDIA GPU with 8GB VRAM |
| Memory | 16GB |
| Disk Space | 60GB |
| Network | Public network access to Huggingface and Civitai |
deploy:
resources:
reservations:
devices:
- driver: nvidia
capabilities: [gpu]
device_ids: ["0"]
deploy:
resources:
reservations:
devices:
- driver: nvidia
capabilities: [gpu]
device_ids: ["0"]
Task Fee B -->> A: Transaction confirmed deactivate B activate A A ->> R: Send task parameters activate R note over A,R: Task Parameters deactivate A R -->> A: Task parameters saved deactivate R B ->> A: Event: TaskSuccess activate A A ->> R: Get task result deactivate A activate R R -->> A: Task result deactivate R ``` The application initiates the workflow by calling the `CreateTask` method of the smart contract. This method receives task parameters related to the task criteria, such as the task type and VRAM requirements, which the network uses to select suitable nodes. The application transfers the task fee to the contract address by specifying it in the transaction's `value` field. Upon task completion, tokens are sent to the nodes. If the task fails, the fee is refunded to the application's wallet. After the transaction is confirmed on-chain, the application should then send the task parameters to the Relay. > Selected nodes will retrieve task parameters from the Relay and then execute the tasks locally. > > When images or texts are generated, nodes will create proofs and send them to the blockchain. The blockchain will verify the correctness of these proofs and transfer tokens to the nodes upon successful verification. > > The nodes will upload the result images/texts to the Relay, which will compare the results with the on-chain proofs to verify their accuracy. After sending the task parameters to the Relay, the application should wait for the `TaskSuccess` event from the blockchain. Once the event is received, the application can retrieve the images or texts from the Relay, marking the completion of the task workflow. The results have already been verified by the Relay, so no further verification by the application is necessary. For a detailed workflow involving all network participants, please refer to the task lifecycle document: {% content-ref url="/pages/iPukPMh2AXLB0TPkE1Wt" %} [Task Lifecycle](/system-design/task-lifecycle) {% endcontent-ref %} ## The Reference Applications The workflow has been fully implemented in the showcase applications: the Image Generator and the AI Chatbot. Which can be accessed at: The Image Generator:
| Method | Arguments |
|---|---|
| canny | high_threshold, low_threshold |
| scribble_hed | |
| scribble_hedsafe | |
| softedge_hed | |
| softedge_hedsafe | |
| depth_midas | |
| mlsd | thr_v, thr_d |
| openpose | |
| openpose_face | |
| openpose_faceonly | |
| openpose_full | |
| openpose_hand | |
| dwpose | |
| scribble_pidinet | apply_filter |
| softedge_pidinet | apply_filter |
| scribble_pidisafe | apply_filter |
| softedge_pidisafe | apply_filter |
| normal_bae | |
| lineart_coarse | |
| lineart_realistic | |
| lineart_anime | |
| depth_zoe | gamma_corrected |
| depth_leres | thr_a, thr_b |
| depth_leres++ | thr_a, thr_b |
| shuffle | h, w, f |
| mediapipe_face | max_faces, min_confidence |
(Arbitrum Orbit Chain)
Native Token"] <-- Standard Arbitrum Token Bridge --> BASE["Base (L1)
OptimismMintableERC20"] CRYNUX_NEAR["Crynux on Near (L2)
(Virtual Chain by Aurora)
Native Token"] <-- Token Bridge --> NEAR["Near (L1)
NEP-141"] BASE <-- Standard Optimism Token Bridge --> ETH["Ethereum (L0)
ERC20 + Emission"] NEAR <-- Rainbow Bridge --> ETH ``` You can use the Crynux Portal at [portal.crynux.io](https://portal.crynux.io) to add networks easily: open the site, connect your wallet, choose the network you want, and the portal will automatically add the corresponding network to MetaMask. ## Ethereum (L0) Ethereum is the top layer of the architecture. It hosts the canonical CNX ERC20 token, which defines the total CNX supply across all networks, and the Emission contract, which releases new CNX to the network participants according to the emission schedule. CNX on every other network is a bridged representation of the canonical token on Ethereum.
| Contract | Address |
|---|---|
| Crynux Token | 0xa97998Bf97f5A6A96393b85B4e02A0440AE220F2 |
| Emission Contract | 0x72666bA4dE68bB46b4dE59641af99346318016DD |
| Wallet | Purpose |
|---|---|
| Relay Deposit Address | Pooled user deposits. This is where users send CNX to top up their Relay accounts. Its balance is simply the aggregate deposits of all Relay users. |
| Relay Hot Wallet | Pays out Relay withdrawals. Its key lives on a server, and since any online key is a potential attack target, the hot wallet only keeps a small working balance. |
| Relay Cold Wallet | The Relay's cold-storage reserve. The key is kept fully offline. When the hot wallet runs low, it is manually refilled from cold storage. Even if the withdrawal server were fully compromised, only the small hot-wallet float would be at risk — never the main reserve. |
| Item | Address |
|---|---|
| Crynux Token CA | 0x9557DD9E241bc9636732623B672B4090AF519396 |
| Relay Deposit Address | 0x95dAd4af9aCaDEaf1704d3C980e7f571A9c5C5a0 |
| Relay Hot Wallet | 0x2Dc0538727d569cD40f7a2FcfD2749A3D62f44d9 |
| Relay Cold Wallet | 0x552A7D01C9e854244cC04Fd3e6C47f9036132f74 |
| Item | Value |
|---|---|
| JSON RPC | https://json-rpc.base.crynux.io |
| Chain ID | 18896214 |
| Token Symbol | CNX |
| Decimal | 18 |
| Block Explorer | https://cnxscan.base.crynux.io |
| Wallet | Address |
|---|---|
| Relay Deposit Address | 0x95dAd4af9aCaDEaf1704d3C980e7f571A9c5C5a0 |
| Relay Hot Wallet | 0x2Dc0538727d569cD40f7a2FcfD2749A3D62f44d9 |
| Relay Cold Wallet | 0x552A7D01C9e854244cC04Fd3e6C47f9036132f74 |