remote testing and readme

simulation/Makefile

@@ -32,4 +32,17 @@ push-to-ecr:
 ## build-client: Build Docker image only without pushing to ECR
 build-client:
 	@echo "Building Docker image without pushing to ECR..."
-	./script/build_and_push.sh -a $(AWS_ACCOUNT_ID) -r $(AWS_REGION) -e $(ECR_REPOSITORY_NAME) -i $(IMAGE_NAME) -d $(DOCKERFILE_PATH) -c $(BUILD_CONTEXT) --no-push
+	./script/build_and_push.sh -a $(AWS_ACCOUNT_ID) -r $(AWS_REGION) -e $(ECR_REPOSITORY_NAME) -i $(IMAGE_NAME) -d $(DOCKERFILE_PATH) -c $(BUILD_CONTEXT) --no-push
+
+## run-remote: Run simulation on remote server
+run-remote:
+	@echo "Running simulation on remote server..."
+	@if [ -z "$(SUBNET_IDS)" ]; then \
+		echo "Error: SUBNET_IDS is not set. You can find this in CloudFormation outputs."; \
+		exit 1; \
+	fi
+	@if [ -z "$(SECURITY_GROUP_IDS)" ]; then \
+		echo "Error: SECURITY_GROUP_IDS is not set. You can find this in CloudFormation outputs."; \
+		exit 1; \
+	fi
+	go run ./remote/orchestrator/main.go

simulation/README.md

@@ -1,26 +1,102 @@
-# Simulation Framework for Server Testing
+# Simulation Framework for Ark Server Testing
 
-This simulation framework is designed to test the **Ark Server** by simulating multiple clients performing 
-various actions over several rounds. It reads simulation configurations from YAML files, validates them against a predefined schema, 
-and executes the simulation accordingly.
+This simulation framework tests the **Ark Server** by simulating multiple clients performing various actions over several rounds. It utilizes YAML configuration files and validates them against a predefined schema.
+
+## Architecture
+
+The simulation framework is structured as follows:
+
+1. **Configuration Files**:
+    - `schema.yaml`: Defines the structure and rules for configuration files used in simulations.
+    - `Simulation.yaml`: The main configuration file, following `schema.yaml`, specifies the parameters for each simulation.
+
+2. **Orchestrator**:
+    - Acts as the main controller, reading configurations from `schema.yaml` and `Simulation.yaml`.
+    - Start ASP and Ark Clients and orchestrates the interactions between them based on the defined simulation scenarios.
+    - Supports both single-process and multi-process simulations for flexible testing.
+
+3. **Ark Clients**:
+    - Represent individual Ark Client that interact with the **Ark Server** based on orchestrated instructions.
+    - Multiple Ark Clients can run in parallel, enabling the simulation of a network of users with varying behaviors.
+
+4. **External Dependencies**:
+    - **Nigiri**: Provides a local Bitcoin Regtest environment, necessary for simulating blockchain-related actions.
+    - **Ark Server**: The server under test, which receives requests from Ark Clients and processes them accordingly.
+
+<p align="center">
+  <img src="./arch.png" alt="Architecture Diagram" width="55%">
+</p>
 
 ## Usage
 
-### 1. Start Nigiri
+The simulation can be run either locally or on AWS.
+
+### Local Deployment
+
+For smaller tests, local deployment allows for a quick setup:
+
+- **Single process**: The orchestrator and Ark Clients run in the same process.
+- **Multi-process**: The orchestrator and clients run as separate processes, mimicking a more realistic client-server interaction.
+
+#### Prerequisites
+
+1. **Start Nigiri (Bitcoin Regtest environment)**:
+   ```bash
+   nigiri start
+   ```
+
+2. **Configure Testing Scenario**:
+    - Create a simulation YAML file based on the `schema.yaml` format.
+    - Check out the example configuration for guidance.
+
+3. **Run Simulation**:
+   ```bash
+   # Single-process mode:
+   make run-single
+
+   # Multi-process mode:
+   make run-multi
+   ```
+
+### AWS Deployment
+As more users join the round, VTXO tree grows and there will be more transactions to sign by each user.
+Considering signing is expensive operation, it quickly becomes a bottleneck in the simulation, as it drains the CPU resources.
+To overcome this and to provide a more realistic simulation, this framework supports running the simulation in AWS.
+
+#### Prerequisites
 
-Ensure that Nigiri (a Bitcoin Regtest environment) is running:
+1. **Create AWS SSH Keys**:
+    - Go to AWS EC2 Console > Key Pairs
+    - Create a new key pair and save the private key file (`.pem`)
 
-```sh
-nigiri start
-```
+#### Setup Process
 
-#### 2. Configure the Testing Scenario
-Create a simulation YAML file based on the [schema.yaml](./schema.yaml). You can refer to the [this](./simulation1.yaml) example for guidance.
+1. **Deploy CloudFormation Stack**:
+    - Upload the CloudFormation template file to AWS CloudFormation
+    - Fill in the mandatory parameters:
+        - Stack name
+        - SSH key pair (select the one created in prerequisites)
+        - Ark GitHub URL
+        - Branch name (defaults to master)
 
-#### 3. Run simulation
+2. **Get Infrastructure Details**:
+    - Once CloudFormation stack creation is complete, go to the Outputs tab
+    - Note down the following values:
+        - `SUBNET_IDS`
+        - `SECURITY_GROUP_IDS`
 
-```sh
-make run SIMULATION=your_simulation.yaml
-```
+3. **Verify Installation**:
+    - SSH into the EC2 instance
+    - Check installation progress:
+      ```bash
+      less /var/log/cloud-init-output.log
+      ```
+    - Verify that the Ark Client Docker image has been successfully pushed to ECR
 
-Replace your_simulation.yaml with the path to your simulation configuration file.
+4. **Run Remote Simulation**:
+   ```bash
+   cd ./ark/simulation/remote/orchestrator
+   export SUBNET_IDS={SUBNET_IDS}
+   export SECURITY_GROUP_IDS={SECURITY_GROUP_IDS}
+   make run-remote
+   ```

simulation/remote/infra/cloudformation.yaml

@@ -327,8 +327,8 @@ Resources:
       NetworkMode: awsvpc
       RequiresCompatibilities:
         - FARGATE
-      Cpu: '512'
-      Memory: '1024'
+      Cpu: '1024'
+      Memory: '2048'
       ExecutionRoleArn: !GetAtt ECSTaskExecutionRole.Arn
       TaskRoleArn: !GetAtt ECSTaskExecutionRole.Arn
       ContainerDefinitions: