Merge pull request #31 from SammyOina/sm

NOISSUE - Enhanced Agent State Management and Documentation Updates

docs/agent.md

@@ -6,18 +6,39 @@ The picture below shows where the Agent runs in the Cocos system, helping us bet
 
 ![Agent](./img/agent.png){ align=center }
 
+## StateMachine
+- Orchestrates the overall flow of the computation.
+- Transitions between states based on received events.
+- Defines valid state transitions and associated functions.
+
+### States
+- `idle`: Initial state, waiting for the computation to start.
+- `receivingManifest`: Receives the initial computation manifest.
+- `receivingAlgorithm`: Receives the algorithm for the computation.
+- `receivingData`: Receives dataset data for the computation.
+- `running`: Executes the computation using received algorithms and data.
+- `resultsReady`: Computation has finished, results are available.
+- `complete`: All results have been consumed, computation lifecycle ends.
+
+### Events
+- `start`: Triggers the computation startup process.
+- `manifestReceived`: Indicates computation manifest has been received.
+- `algorithmReceived`: Indicates the algorithm has been received.
+- `dataReceived`: Indicates all dataset data has been received.
+- `runComplete`: Signals the completion of the computation execution.
+- `resultsConsumed`: Indicates all consumers have retrieved the results.
+
 ## Agent Events
 
-As the computation in the agent undergoes different operations, it sends events to the manager so that the user can monitor the computation from either the UI or other client. Events sent to the manager include computation running, computation finished, computation failed, and computation stopped.
+As the computation in the agent undergoes different operations, it sends events to the manager so that the user can monitor the computation from either the UI or other client. Events sent to the manager based on the agent state as defined by the statemachine.
 
 ## Vsock Connection Between Agent & Manager
 
-Agent sends agent events to the manager via vsock. The manager listens to the vsock and forwards the events via gRPC. The agent events are used to show the status of the computation inside the TEE so that a user can be aware of what is happening inside the TEE.
-
-## Security
-
-To run a computation in the agent, a signed certificate is required. The certificate is used to verify the user who is running the computation. The certificate is sent to the agent by the manager, and the agent verifies the certificate before running the computation.
+Agent sends agent events and logs to the manager via vsock. The manager listens to the vsock and forwards the events via gRPC. The agent events and logs are used to show the status of the computation inside the TEE so that a user can be aware of what is happening inside the TEE.
 
 ## Attestation
 
-The Agent can fetch the [attestation](./attestation.md) report from the host using the AMD SEV guest driver. The attestation report proves that the Agent is running inside the secure virtual machine (SVM) and that the SVM is running the expected code on the expected hardware and is configured correctly.
+The Agent can fetch the [attestation](./attestation.md) report from the host using the AMD SEV guest driver. The attestation report proves that the Agent is running inside the secure virtual machine (SVM) and that the SVM is running the expected code on the expected hardware and is configured correctly.
+
+## Algorithm and dataset validation
+Before execution, algorithms and datasets are validated against the computation manifest to ensure integrity and compatibility. This includes the sha3 256 hash of the dataset and algorithm, which are validated against the value set in the manifest. The algorithm and dataset provider ID are also validated against the manifest during the uploading of the dataset and algorithm.

docs/getting-started.md

@@ -19,7 +19,7 @@ Copy the downloaded files to `cocos/cmd/manager/img`.
 ## Starting Manager Server
 Manager is a gRPC client and needs gRPC sever to connect to. We have an example server for testing purposes in `test/manager-server`. Run the server as follows:
 
-`go run ./test/manager-server/main.go`
+`go run ./test/computations/main.go`
 
 the output should be simillar to this:
 `{"time":"2024-03-19T12:27:46.542638146+03:00","level":"INFO","msg":"manager_test_server service gRPC server listening at :7001 without TLS"}`
@@ -58,7 +58,7 @@ the output will be simillar to this
 ```
 
 ### Run
-When manager connects to the server, it sends a whoAmI request after which the server sends a computation manifest. In response manager will sends logs and events from the computation both from manager and agent. To start run:
+When manager connects to the computations server, the server then sends a computation manifest. In response manager will sends logs and events from the computation both from manager and agent. To start run:
 
 ```shell
 cd cmd/manager

docs/manager.md

@@ -141,7 +141,7 @@ NB: we set environment variables that we will use in the shell process where we
 
 ## Deployment
 
-To start the service, execute the following shell script (note a server needs to be running see  [here](../test/manager-server/README.md)):
+To start the service, execute the following shell script (note a server needs to be running see  [here](../test/computations/README.md)):
 
 ```bash
 # download the latest version of the service
@@ -176,18 +176,18 @@ MANAGER_QEMU_SEV_CBITPOS=51 \
 
 ### Verifying VM Launch
 
-NB: To verify that the manager successfully launched the VM, you need to open three terminals on the same machine. In one terminal, you need to launch the Manager test server by executing (with the environment variables of choice):
+NB: To verify that the manager successfully launched the VM, you need to open three terminals on the same machine. In one terminal, you need to launch the computations server by executing (with the environment variables of choice):
 
 ```bash
-go run ./test/manager-server/main.go
+go run ./test/computations/main.go <path to dataset> <path to algorithm>
 ```
 and in the second the manager by executing (with the environment variables of choice):
 
 ```bash
 go run ./cmd/manager/main.go
 ```
 
-Ensure that the Manager can connect to the Manager test server by setting the MANAGER_GRPC_PORT with the port value of the Manager test server. The Manager test server is listening on the default value of the MANAGER_GRPC_PORT. In the last one, you can run the verification commands.
+Ensure that the Manager can connect to the computations server by setting the MANAGER_GRPC_PORT with the port value of the computations server. In the last terminal window, you can run the verification commands.
 
 To verify that the manager launched the VM successfully, run the following command: