Skip to content

Commit dd9d1cd

Browse files
vlasonfavlasonfa
committed
2 parents 0ac1b37 + 7b9efad commit dd9d1cd

20 files changed

+2420
-0
lines changed

‎.prettierignore renamed to ‎.prettierignore

File renamed without changes.

‎lib/allora/.gitignore

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
*.js
2+
!jest.config.js
3+
*.d.ts
4+
node_modules
5+
6+
# CDK asset staging directory
7+
.cdk.staging
8+
cdk.out

‎lib/allora/.npmignore

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,6 @@
1+
*.ts
2+
!*.d.ts
3+
4+
# CDK asset staging directory
5+
.cdk.staging
6+
cdk.out

‎lib/allora/README.md

Lines changed: 233 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,233 @@
1+
# Sample AWS Blockchain Node Runner app for Allora Worker Nodes
2+
3+
| Contributed by |
4+
|:--------------------:|
5+
| [@clementupshot](https://github.com/clementupshot), [@allora-rc](https://github.com/allora-rc), [@Madisonw](https://github.com/Madisonw)|
6+
7+
[Allora](https://www.allora.network/) is a self-improving decentralized Artificial Intelligence (AI) network. The primary goal of the network is to be the marketplace for intelligence. In other words, Allora aims to incentivize data scientists (workers) to provide high-quality inferences as requested by consumers. Inferences include predictions of arbitrary future events or difficult computations requiring specialized knowledge.
8+
9+
The Allora Network brings together:
10+
11+
- [Consumers](https://docs.allora.network/devs) who pay for and acquire inferences or expertise to be revealed
12+
- [Workers](https://v2.docs.allora.network/datasci) who reveal inferences
13+
- [Reputers](https://docs.allora.network/nops) who determine how accurate workers are after a ground truth is revealed
14+
- [Validators](https://docs.allora.network/nops) who secure protocol state, history, and reward distributions
15+
16+
With these ingredients, the Allora Network is able to continuously learn and improve itself over time producing inferences that are more accurate than the most accurate participant.
17+
18+
Allora Worker nodes are the interfaces between data scientists' models and the Allora Network. A worker node is a machine-intelligent application registered on the Allora chain that provides inference/prediction on a particular topic it's subscribed to and gets rewarded based on the inference quality.
19+
20+
This blueprint is designed to assist in deploying a single Allora [Worker Node](https://v2.docs.allora.network/datasci) on AWS. It is intended for use in development, testing, or Proof of Concept (PoC) environments.
21+
22+
## Overview of Deployment Architecture
23+
24+
### Single Worker Node Setup
25+
![Single Worker Node Deployment](./doc/assets/Architecture-Single-Allora-Worker-Node.png)
26+
27+
The AWS Cloud Development Kit (CDK) is used to deploy a single Allora Worker Node. The CDK application deploys the following infrastructure:
28+
29+
- Virtual Private Cloud (VPC)
30+
- Internet Gateway (IGW) to allow inbound requests for inferences from consumers and outbound responses from the worker node revealing inferences
31+
- Public subnet that has a direct route to the IGW
32+
- Security Group (SG) with TCP Port 9010 open inbound allowing requests for inferences to be routed to the Allora Worker Node
33+
- Single Amazon Elastic Compute Cloud (EC2) instance (the Allora Worker Node) assigned to the public subnet
34+
35+
The Allora Worker Node is accessed by the user internally and is not exposed to the Internet to protect the node from unauthorized access. A user can gain access to the EC2 Instance using AWS Session Manager.
36+
37+
Multiple processes run on the Allora Worker Node (EC2 instance):
38+
39+
- Docker container with the worker node logic that handles communication between the worker and the public head nodes
40+
- Docker container running the model server that reveals inferences to consumers
41+
42+
Allora Public Head Nodes publish the Allora chain requests (requests for inferences from consumers) to Allora worker nodes. When a worker node is initialized, it starts with an environment variable called BOOT_NODES, which helps handle the connection and communications between worker nodes and the head nodes.
43+
44+
The worker node (docker container) will call the function that invokes custom logic that handles the actual inference. The request-response is a bidirectional flow from the Allora chain (inference requests from consumers) to the public head nodes to the worker node and finally to the model server that reveals inferences.
45+
46+
## Additional materials
47+
48+
<details>
49+
50+
<summary>Well-Architected Checklist</summary>
51+
52+
This is the Well-Architected checklist for the Allora worker nodes implementation of the AWS Blockchain Node Runner app. This checklist takes into account questions from the [AWS Well-Architected Framework](https://aws.amazon.com/architecture/well-architected/) which are relevant to this workload. Please feel free to add more checks from the framework if required for your workload.
53+
54+
| Pillar | Control | Question/Check | Remarks |
55+
|:------------------------|:----------------------------------|:---------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
56+
| Security | Network protection | Are there unnecessary open ports in security groups? | Please note that port 9010 (TCP) is open inbound to support requests for inferences from the Allora Network public head nodes. |
57+
| | | Traffic inspection | Traffic protection is not used in the solution. [AWS Web Applications Firewall (WAF)](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) could be implemented for traffic over HTTP(S), [AWS Shield](https://docs.aws.amazon.com/waf/latest/developerguide/shield-chapter.html) provides Distributed Denial of Service (DDoS) protection. Additional charges will apply. |
58+
| | Compute protection | Reduce attack surface | This solution uses Amazon Linux AMI. You may choose to run hardening scripts on it. |
59+
| | | Enable people to perform actions at a distance | This solution uses [AWS Systems Manager for terminal session](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager-working-with-sessions-start.html#start-sys-console). SSH Port 22 is not open inbound. |
60+
| | Data protection at rest | Use encrypted Amazon Elastic Block Store (Amazon EBS) volumes | This solution uses encrypted Amazon EBS volumes. |
61+
| | Authorization and access control | Use instance profile with Amazon Elastic Compute Cloud (Amazon EC2) instances | This solution uses AWS Identity and Access Management (AWS IAM) role instead of IAM user. |
62+
| | | Following principle of least privilege access | Root user is not used (using special user "ec2-user" instead). |
63+
| | Application security | Security focused development practices | cdk-nag is being used with appropriate suppressions. |
64+
| Cost optimization | Service selection | Use cost effective resources | We use a T3 instance as T3 instances are a low cost burstable general purpose instance type that provide a baseline level of CPU performance with the ability to burst CPU usage at any time for as long as required. T3 instances are designed for applications with moderate CPU usage that experience temporary spikes in use. This profile aligns closely with the load profile of Allora Network worker nodes. |
65+
| Reliability | Resiliency implementation | Withstand component failures | This solution does not use an [AWS EC2 Auto Scaling Group](https://aws.amazon.com/ec2/autoscaling/) but one can be implemented. |
66+
| | Data backup | How is data backed up? | Considering blockchain data is replicated by Allora Cosmos AppChain Validator nodes, we don't use additional mechanisms to backup the data. |
67+
| | Resource monitoring | How are workload resources monitored? | Resources are not being monitored using Amazon CloudWatch dashboards. Amazon CloudWatch custom metrics are being pushed via CloudWatch Agent. |
68+
| Performance efficiency | Compute selection | How is compute solution selected? | Compute solution is selected based on best price-performance, i.e. AWS EC2 T3 Medium instance suitable for bursty workloads. |
69+
| | Storage selection | How is storage solution selected? | Storage solution is selected based on best price-performance, i.e. Amazon EBS volumes with optimal IOPS and throughput. |
70+
| | Architecture selection | How is the best performance architecture selected? | A combination of recommendations from the Allora Network community and Allora Labs testing. |
71+
| Sustainability | Hardware & services | Select most efficient hardware for your workload | The solution uses AMD-powered instances. There is a potential to use AWS Graviton-based Amazon EC2 instances which offer the best performance per watt of energy use in Amazon EC2.
72+
</details>
73+
74+
## Worker Node System Requirements
75+
76+
- Operating System: Any modern Linux operating system
77+
- CPU: Minimum of 2 cores
78+
- Memory: Minimum of 4GB
79+
- Storage: SSD or NVMe with minimum of 20GB of space
80+
81+
## Setup Instructions
82+
83+
### Setup Cloud9
84+
85+
We will use AWS Cloud9 to execute the subsequent commands. Follow the instructions in [Cloud9 Setup](../../docs/setup-cloud9.md).
86+
87+
### Clone this repository and install dependencies
88+
89+
```bash
90+
git clone https://github.com/aws-samples/aws-blockchain-node-runners.git
91+
cd aws-blockchain-node-runners
92+
npm install
93+
```
94+
95+
### Deploy single worker node
96+
97+
1. Make sure you are in the root directory of the cloned repository
98+
99+
2. Configure your setup
100+
101+
Create your own copy of `.env` file and edit it to update with your AWS Account ID and Region:
102+
```bash
103+
# Make sure you are in aws-blockchain-node-runners/lib/allora
104+
cd lib/allora
105+
npm install
106+
pwd
107+
cp ./sample-configs/.env-sample-full .env
108+
nano .env
109+
```
110+
> NOTE:
111+
> Example configuration parameters are set in the local `.env-sample` file. You can find more examples inside `sample-configs` directory.
112+
113+
> IMPORTANT:
114+
> All AWS CDK v2 deployments use dedicated AWS resources to hold data during deployment. Therefore, your AWS account and Region must be [bootstrapped](https://docs.aws.amazon.com/cdk/v2/guide/bootstrapping.html) to create these resources before you can deploy. If you haven't already bootstrapped, issue the following command:
115+
> ```bash
116+
> cdk bootstrap aws://ACCOUNT-NUMBER/REGION
117+
> ```
118+
119+
3. Deploy Common Stack
120+
121+
```bash
122+
pwd
123+
# Make sure you are in aws-blockchain-node-runners/lib/allora
124+
npx cdk deploy allora-edge-common --json --outputs-file allora-edge-common-deploy.json
125+
```
126+
127+
5. Deploy Allora Worker Node
128+
129+
```bash
130+
pwd
131+
# Make sure you are in aws-blockchain-node-runners/lib/allora
132+
npx cdk deploy allora-single-node --json --outputs-file single-node-deploy.json
133+
```
134+
135+
## Clear up and undeploy everything
136+
137+
1. Undeploy worker node and common components
138+
139+
```bash
140+
# Setting the AWS account id and region in case local .env file is lost
141+
export AWS_ACCOUNT_ID=<your_target_AWS_account_id>
142+
export AWS_REGION=<your_target_AWS_region>
143+
144+
pwd
145+
# Make sure you are in aws-blockchain-node-runners/lib/allora
146+
147+
# Undeploy Single Node
148+
npx cdk destroy allora-single-node
149+
150+
# Undeploy Common Stack
151+
npx cdk destroy allora-edge-nodes-common
152+
```
153+
154+
2. Follow these steps to delete the Cloud9 instance in [Cloud9 Setup](../../docs/setup-cloud9.md)
155+
156+
Navigate to the AWS Cloud9 service in your Management Console, then select the environment you have created. On the top right, click **Delete** button and follow the instructions.
157+
158+
3. Delete the instance profile and IAM role
159+
160+
```bash
161+
aws iam delete-instance-profile --instance-profile-name Cloud9-Developer-Access
162+
aws iam delete-role --role-name Cloud9-Developer-Access
163+
```
164+
165+
### FAQ
166+
167+
1. How to check the logs from the EC2 user-data script?
168+
169+
Please enter the [AWS Management Console - EC2 Instances](https://us-east-2.console.aws.amazon.com/ec2/home?region=us-east-2#Instances:instanceState=running), choose the correct region, copy the instance ID you need to query.
170+
171+
```bash
172+
pwd
173+
# Make sure you are in aws-blockchain-node-runners/lib/allora
174+
175+
export INSTANCE_ID="i-**************"
176+
echo "INSTANCE_ID=" $INSTANCE_ID
177+
aws ssm start-session --target $INSTANCE_ID --region $AWS_REGION
178+
sudo cat /var/log/cloud-init-output.log
179+
```
180+
2. How to check the worker node connectivity to the Allora Network?
181+
182+
Please enter the [AWS Management Console - EC2 Instances](https://us-east-2.console.aws.amazon.com/ec2/home?region=us-east-2#Instances:instanceState=running), choose the correct region, copy the instance ID you need to query.
183+
184+
```bash
185+
pwd
186+
# Make sure you are in aws-blockchain-node-runners/lib/allora
187+
188+
export INSTANCE_ID="i-**************"
189+
echo "INSTANCE_ID=" $INSTANCE_ID
190+
aws ssm start-session --target $INSTANCE_ID --region $AWS_REGION
191+
```
192+
193+
You should be able to query Topic 1 on the Allora Network and see similar output below
194+
```bash
195+
$ allorad q emissions topic 1 --node https://allora-rpc.testnet-1.testnet.allora.network
196+
effective_revenue: "0"
197+
topic:
198+
allow_negative: true
199+
alpha_regret: "0.1"
200+
creator: allo1lzf3xp0zqg4239mrswd0cclsgt3y8fl7l84hxu
201+
default_arg: ETH
202+
epoch_last_ended: "183177"
203+
epoch_length: "120"
204+
ground_truth_lag: "120"
205+
id: "1"
206+
inference_logic: bafybeifqs2c7ghellof657rygvrh6ht73scto3oznw4i747sqk3ihy7s5m
207+
inference_method: allora-inference-function.wasm
208+
loss_logic: bafybeid7mmrv5qr4w5un6c64a6kt2y4vce2vylsmfvnjt7z2wodngknway
209+
loss_method: loss-calculation-eth.wasm
210+
metadata: ETH 10min Prediction
211+
p_norm: "3"
212+
tolerance: "0.001"
213+
weight: "0"
214+
```
215+
3. How to check the Allora worker containers are running?
216+
217+
Please enter the [AWS Management Console - EC2 Instances](https://us-east-2.console.aws.amazon.com/ec2/home?region=us-east-2#Instances:instanceState=running), choose the correct region, copy the instance ID you need to query.
218+
219+
```bash
220+
pwd
221+
# Make sure you are in aws-blockchain-node-runners/lib/allora
222+
223+
export INSTANCE_ID="i-**************"
224+
echo "INSTANCE_ID=" $INSTANCE_ID
225+
aws ssm start-session --target $INSTANCE_ID --region $AWS_REGION
226+
```
227+
228+
```bash
229+
[ec2-user@ip-192-168-0-224 ~]$ docker ps -a
230+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
231+
b10c12c51f32 worker-worker "allora-node allora-…" 18 hours ago Exited (2) 18 hours ago worker
232+
05273577ce7a alloranetwork/allora-inference-base-head:latest "allora-node allora-…" 18 hours ago Exited (2) 18 hours ago head
233+
```

0 commit comments

Comments
 (0)