6529-Prenode

6529 Prenode

Overview
AWS Setup
Manual Configuration
Updates

1. Overview

The 6529 Prenode decentralizes access to TDH data for 6529 Identities and 6529 NFTs.

1.1 Purpose

As a web service running a RESTful API, it uses the same calculation logic as the 6529 websites. Standardized setup through a provided CloudFormation script means anyone can run on their AWS account.

What is the purpose of the Prenode? There are three purposes for the Prenode:

Most important: The immediate use of the Prenode is to enable multiple parties to independently serve as TDH providers to the on-chain TDH oracle contract that will be launching soon™. This will allow for on-chain composable TDH that is not dependent on any single party.
To allow anyone to serve as an API provider of TDH information in general, in any context, onchain or offchain.
To serve as the first step towards 6529 Nodes that can run on any computing environment.

Some further points:

You should assume that there will be further updates to the Prenodes and, later, to Nodes. The Prenode name will remain until the code is restructured to run in any computer environment.
There are no current economic incentives to run a Prenode, but it is something that will be considered later if necessary. Our current view is that there are sufficient people with the capacity and motivation to run a Prenode that it is better not to yet commit to a crypto-economic model that may be immature or not necessary.
We estimate the cost of running a Prenode on AWS to be less than 0.015 ETH per month ($50 or so).
For now, we request that people and organizations with the economic capacity to do so to run Prenodes for the health of the network.

1.2 The technical details

To run the Prenode, you’ll need a domain name, a database, a server configured with SSL, the open-source TDH code, and some configuration.

Since the setup of all these things can be a little tricky, we’ve provided a CloudFormation script that will automate much of the setup process for you, directly in your own AWS account. This script will create the required EC2 instance, RDS instance, and a Route 53 domain, and configure them all to work together in a standalone VPC environment (and no, you don’t need to know what all that means to get it going). All told, this configuration should run for less than $50/month (likely less if you have free tier resources available).

Experienced cloud computing users who want to run Prenode in a different context can use the automated scripts provided here to work out how to proceed.

The Prenode endpoints are documented with OpenAPI Definitions, and published from the repo: https://6529-collections.github.io/6529-Prenode/docs.

2. AWS setup

You’ll need just a few things in place before starting the automated setup process.

Prerequisites:

You need an AWS account, of course! If you don’t have one, you can create one for free (but will be required to register a payment method). You’ll also need just a little familiarity with using the AWS console (Sign in now) and the AWS CLI (command line interface) tool (installation guide).
Since the node is required to run securely over HTTPS, you’ll need a domain name for an SSL certificate. The automated setup process will then get a free cert for you.
The Prenode is querying data directly from the blockchain, so you’ll need an Alchemy API key. You can get one for free by visiting the Alchemy quick-start guide.

2.1 Configure AWS CLI

After some initial setup through the AWS web console, the rest of the process can be done from your computer’s local CLI. You’ll need to install the AWS CLI tool (see link above) and configure it to use your AWS account.

Select (or create) the IAM user you want to use, initially with no access policies attached. Note the ARN of this user.
Add a new IAM policy along the lines of the provided IAM policy example, making sure you scope it your new user’s ARN properly.
‘Add permission’ to attach this policy to the user.

NOTE: This policy grants the user full access to a number of resources. Be SURE to remove the policy when done, so the user account can’t be exploited.
Now view the user’s Security Credentials and generate a new Access Key for CLI usage.

Now, configure your local computer terminal (NOT CloudShell) with a profile that uses this access key, secret access key, and your default region:

aws configure --profile 6529Prenode

You can run this again if you ever need to update any of these settings.

2.2 Generate a key pair

To connect to the EC2 instance, you’ll need to generate a key pair. As you will use this later, you can store the name of the key in an environment variable.

You can do this by running the following commands:

export PRENODE_EC2_KEY_PAIR_NAME=PrenodeEC2KeyPairName;
aws ec2 create-key-pair --key-name $PRENODE_EC2_KEY_PAIR_NAME \
  --output text > ~/.ssh/$PRENODE_EC2_KEY_PAIR_NAME.pem \
  --query 'KeyMaterial' \
  --profile 6529Prenode;
chmod 400 ~/.ssh/$PRENODE_EC2_KEY_PAIR_NAME.pem;

2.3 Get a domain name

Your node will require SSL, and therefore a domain name. You will need to provide this domain name in the next step.

The automated CloudFormation setup process will configure the domain name for you, if you have a domain registered in Route 53.

So, before you proceed to the next step, go get a new domain name, or transfer an existing one to Route 53. You can do this by visiting the Route 53 console.

In addition to the domain name, you will need the Hosted Zone ID for the domain. You can find this by selecting the domain and copying the Hosted Zone ID from the right-hand side of the page.

2.4 Create the CloudFormation stack

Find an Ubuntu AMI ID for the region you will deploy in. You can find the AMI ID for your region by visiting the Ubuntu Cloud Image Locator. Use the filters at the bottom of the table to select your preferred region, and the latest version of Ubuntu, and be sure it is amd64 (to work with the instance type the script uses). That should narrow it down to a single option.

If you are familiar with the AWS web-based tools, you can build the stack by visiting the CloudFormation console, and uploading the template from ./aws/prenode-deployment.yaml.

Or, you can run the commands below in your local terminal to create the stack and verify it from your own machine’s CLI environment.

Set these values in your local environment (in addition to PRENODE_EC2_KEY_PAIR_NAME, which was done above) to make calling the CloudFormation script easier. You’ll only need them once, to fire off the CloudFormation script from your command line. Copy the below into your CLI one at a time (with updated values) to save the values temporarily in your environment (until you close the CLI).

Replace the your-* values with what your stack should use:

export PRENODE_DOMAIN=your-domain-name # What FQDN do you want to use for accessing your Prenode?

export PRENODE_HOSTED_ZONE_ID=your-route53_hosted_zone_id # Copy this directly from the Route 53 console

export PRENODE_EMAIL=your-email # Used for administrative contact and SSL certificate registration

export PRENODE_AMI_ID=your-ami-id # The AMI ID for the Ubuntu image you found

export PRENODE_DB_PASSWORD=your-long-db-password-less-than-40-chars # Pick a new password for the database that will be created

export ALCHEMY_API_KEY=your-alchemy-api-key # Copy this from the Alchemy API console

To keep any of these around for future terminal sessions, you can add them to your shell profile (e.g. ~/.bashrc).

Run the following command to create the CloudFormation stack:

aws cloudformation create-stack \
  --stack-name Prenode6529 \
  --template-body "$(curl -L https://raw.githubusercontent.com/6529-Collections/6529-Prenode/HEAD/aws/prenode-deployment.yaml)" \
  --parameters ParameterKey=DomainName,ParameterValue=$PRENODE_DOMAIN \
               ParameterKey=AdminEmail,ParameterValue=$PRENODE_EMAIL \
               ParameterKey=AMIId,ParameterValue=$PRENODE_AMI_ID \
               ParameterKey=MasterUserPassword,ParameterValue=$PRENODE_DB_PASSWORD \
               ParameterKey=KeyName,ParameterValue=$PRENODE_EC2_KEY_PAIR_NAME \
               ParameterKey=HostedZoneId,ParameterValue=$PRENODE_HOSTED_ZONE_ID \
               ParameterKey=AlchemyAPIKey,ParameterValue=$ALCHEMY_API_KEY \
  --profile 6529Prenode

Note: this command expects that you have properly set the environment variables in the previous step.

And you are basically done!

Give it a few moments (it might take 10 minutes or more) to create the stack. The next steps here are just to verify that everything is working as expected.

You can check the status of the stack from the AWS console, or by running:

aws cloudformation describe-stacks --stack-name Prenode6529 --profile 6529Prenode

2.5 Get the public IP address

Once the stack is created, you can hold the public IP address of your EC2 instance in an env var by running:

export PRENODE_IP=`aws cloudformation describe-stacks --stack-name Prenode6529 --query "Stacks[0].Outputs[?OutputKey=='ElasticIPAddress'].OutputValue" --output text --profile 6529Prenode`; echo $PRENODE_IP;

Now you can SSH into your EC2 instance, if you want to check the configuration:

ssh -i ~/.ssh/$PRENODE_EC2_KEY_PAIR_NAME.pem ubuntu@$PRENODE_IP

The source code can be found in ~/6529-Prenode. You can find logs in ~/.pm2/logs.

2.6 Verify

Once the CloudFormation stack has completed building out all resources, verify it is working by navigating to the domain name you provided in the CloudFormation script:

https://YOUR.DOMAIN.NAME/oracle/address/0xADDRESS

Compare the response with

https://api.seize.io/oracle/address/0xADDRESS

If you registered a new domain name, be sure to verify your email address within 15 days, as required by ICANN. Look for the subject “Verify your email address for…” in your inbox.

Your Prenode should now be up and running, and ready for any TDH requests.

Thank you for supporting decentralization!

2.7 Clean up

Be sure you have removed the permissive IAM policy from any user accounts you created for this process.

If you want to fully remove the Prenode resources from your AWS account, you can simply delete the CloudFormation stack to remove all resources created by the script. The easiest way to do so is from the CloudFormation console, by selecting the stack and choosing “Delete Stack”. Be sure to Re-attach the Prenode IAM policy to your user account, to provide adequate access to complete the cleanup.

3. Manual configuration

If you’d like to run the 6529 Prenode in any other context (Advanced), you can manually configure it using the following steps.

DO NOT PROCEED if your AWS setup is complete.

3.1 Get the code

Clone repository “6529-Prenode” at branch main

git clone --branch main https://github.com/6529-Collections/6529-Prenode.git

then change directory to the repository

cd 6529-Prenode/

scripts/setup.sh # Install dependencies, configure pm2, turn on log rotations

To run the project you need a file to hold environment variables. The following script will run you through the process of creating this file.

Note:

you will be asked to provide database credentials
- host
- port
- admin user and password (used to create database and new users for the services but not saved in .env file)
- new database user/password
you will be asked to provide an Alchemy API key (get one here)
at the end of this process:
- new database created
- new read and write users created
- database tables created (empty)
- a new file will be created .env.prenode

npm run set_env

Sample .env file

3.2 Initialize DB

The database expects some initial data. Choose to load EITHER from the latest snapshot or directly.

3.2.1 Restore snapshot

The best option is usually to restore a recent seize.io snapshot.

Populate your Prenode database from the latest snapshot using the following

npm run restore

3.2.2 Direct load

DO NOT PROCEED if you have already restored from a snapshot. No need, you’ve got the data.

If you’d like to load data directly from the chain, you can do so by following the steps below.

Two main components need to be loaded directly: NFTDelegation data and Transaction data.

Run the following to restore data from the NFTDelegation contract

npm run direct_load_nftd

Run the following to restore transaction data

npm run direct_load_trx

3.3 Run services

To ensure your application starts on system boot, you can use PM2’s startup script generator. Run the following command and follow the instructions provided:

pm2 startup

3.4 Set up log rotation

PM2 can also manage log rotation, which is critical for ensuring that logs do not consume all available disk space.

3.5 Manual start

3.5.1 Run Prenode

PM2 process name: 6529Prenode

pm2 start npm --name=6529Prenode -- run prenode

CRON: When starting the service, several scheduled cron jobs are running at specific intervals which will consume onchain data, process it, and save the result to the database. e.g. discovering Transactions - there is a scheduled cron job to run every 2 minutes which detects new transactions on the chain and saves them in the database
Note: On start, this service will always run the TDH calculation on start and schedule it to run at 00:00 UTC

3.5.2 Run API

PM2 process name: 6529Prenode-api
PORT: 3000

pm2 start npm --name=6529Prenode-api -- run api

Note: To ensure PM2 knows which processes to restart at boot, you need to save the list after starting the services

pm2 save

3.6 Scripted start

scripts/start.sh

3.7 Verify

3.7.1 Local

To test your API locally, navigate in your browser to:

http://localhost:3000/oracle/address/0xADDRESS

3.7.2 Production

Once you have completed the above steps on your production server, you’ll also need to ensure that your domain is pointing to the server’s IP address, and is correctly configured for SSL.

SSL traffic on port 443 needs be routed to port 3000 to reach the API server. Use the approach appropriate for your server to configure this.

Config for nginx might look like:

server {
    listen 443 ssl;
    server_name YOUR-DOMAIN-NAME;

   #... SSL configuration

   location / {
      proxy_pass http://localhost:3000;
   }
}

When this is all working, you can finally navigate to

https://YOUR-DOMAIN-NAME/oracle/address/0xADDRESS