masa-oracle

README

Masa Oracle: Decentralized Data and LLM Network 🌐

Contents

• Getting Started
  • Hardware Requirements
  • Network Requirements
  • Prerequisites
  • Installation
    • Quick Start Docker Setup
    • Compile and Run Setup
  • Staking Tokens
  • Running the Node
• Updates & Additional Information

Getting Started

Hardware Requirements

Nodes can run on any hardware for which you can build a golang application.

Our smallest nodes are running GCP on e2-standard-2 instances, with 2 vCPUs, 8GB RAM, and 10GB SCSI drives. This works well for running a node to test out the protocol.

While a Masa Protocol node itself requires few resources to run on testnet, if you wish to create a worker node that performs a useful task, such as running an LLM model, your hardware choices should be dictated by the requirements of that task.

Network Requirements

If your node will participate in the network as a "Worker," doing data scraping, or providing LLM, etc., you will need to open the following ports to inbound traffic:

• 4001 (TCP; UDP as well if behind NAT)
• 8080 (TCP)

• port 8080 is only required to provide access to the API, and can be changed with environment configuration.
• Only 4001 is required to be open publicly for participation in the p2p Masa Protocol network as a Worker node.
• A basic node will still find the bootnodes and register itself as part of the network without any specific inbound ports open.

Installation

Quick Start Docker Setup

The quickest and simplest way to set up a Masa Protocol node is with docker. For complete instructions on building, staking, and running a node with Docker, please see here

Compile and Run Setup

This local setup guide is for those who wish to compile the code and run directly on your machine, which will give you a more in depth understanding of the Masa Protocol node.

Prerequisites

Ensure these prerequisites are installed for a local setup:

• Go: Grab it from Go's official site.

• Yarn: Install it via Yarn's official site.

• Git: Required for cloning the repository.

1. Clone the repository

git clone https://github.com/masa-finance/masa-oracle.git

2. Build the go code into the masa-node binary

go build -v -o masa-node ./cmd/masa-node

3. Go into the contracts directory and build the contract npm modules that the go binary uses

cd contracts/ 
yarn install
cd ../

4. Set env vars using the following template

# Node Configuration

BOOTNODES=/ip4/35.223.224.220/udp/4001/quic-v1/p2p/16Uiu2HAmPxXXjR1XJEwckh6q1UStheMmGaGe8fyXdeRs3SejadSa

API_KEY=
ENV=test
FILE_PATH=.
PORT=8080
RPC_URL=https://ethereum-sepolia.publicnode.com
VALIDATOR=false

# AI LLM
CLAUDE_API_KEY=
CLAUDE_API_URL=https://api.anthropic.com/v1/messages
CLAUDE_API_VERSION=2023-06-01
ELAB_URL=https://api.elevenlabs.io/v1/text-to-speech/ErXwobaYiN019PkySvjV/stream
ELAB_KEY=
OPENAI_API_KEY=
PROMPT="You are a helpful assistant."

# Bring your own Twitter credentials
TWITTER_USER="yourusername"
TWITTER_PASS="yourpassword"
TWITTER_2FA_CODE="your2fa"

# Worker participation
TWITTER_SCRAPER=true
DISCORD_SCRAPER=true
WEB_SCRAPER=true

5. Start up masa-node. Be sure to include your bootnodes list with the --bootnodes flag

/ip4/35.223.224.220/udp/4001/quic-v1/p2p/16Uiu2HAmPxXXjR1XJEwckh6q1UStheMmGaGe8fyXdeRs3SejadSa

./masa-node --bootnodes=/ip4/35.223.224.220/udp/4001/quic-v1/p2p/16Uiu2HAmPxXXjR1XJEwckh6q1UStheMmGaGe8fyXdeRs3SejadSa

Makefile Commands

The Makefile provides several commands to build, install, run, test, and clean the Masa Node project. Here's a description of each command:

make build

The build command compiles the Masa Node binary and places it in the ./bin directory. It uses the go build command with the following flags:

-v: Enables verbose output to show the packages being compiled. -o ./bin/masa-node: Specifies the output binary name and location. ./cmd/masa-node: Specifies the package to build (the main package). make install The install command runs the node_install.sh script to install any necessary dependencies or perform additional setup steps required by the Masa Node.

make run

The run command first builds the Masa Node binary using the build command and then executes the binary located at ./bin/masa-node. This command allows you to compile and run the Masa Node in a single step.

make test

The test command runs all the tests in the project using the go test command. It recursively searches for test files in all subdirectories and runs them.

make clean

The clean command performs cleanup tasks for the project. It removes the bin directory, which contains the compiled binary, and deletes the masa_node.log file, which may contain log output from previous runs.

To execute any of these commands, simply run make in your terminal from the project's root directory. For example, make build will compile the Masa Node binary, make test will run the tests, and make clean will remove the binary and log file.

Funding the Node (in order to Stake)

  ./bin/masa-node --faucet

OR

Find the public key of your node in the logs.

Send 1000 MASA and .01 sepoliaETH to the node's public key / wallet address.

When the transactions have settled, you can stake

Staking Tokens

• For local setup, stake tokens with:

  ./bin/masa-node --stake 1000
  

• For Docker setup, stake tokens with:

  docker-compose run --rm masa-node /usr/bin/masa-node --stake 1000
  

Running the Node

• Local Setup: Connect your node to the Masa network:

  ./masa-node --bootnodes=/ip4/35.223.224.220/udp/4001/quic-v1/p2p/16Uiu2HAmPxXXjR1XJEwckh6q1UStheMmGaGe8fyXdeRs3SejadSa --port=4001 --udp=true --tcp=false --start=true --env=test
  

• Docker Setup: Your node will start automatically with docker-compose up -d. Verify it's running correctly:

  docker-compose logs -f masa-node
  

After setting up your node, its address will be displayed, indicating it's ready to connect with other Masa nodes. Follow any additional configuration steps and best practices as per your use case or network requirements.

Updates & Additional Information

Stay tuned to the Masa Oracle repository for updates and additional details on effectively using the protocol. For Docker users, update your node by pulling the latest changes from the Git repository, then rebuild and restart your Docker containers.

Masa Node CLI

For more detailed documentation, please refer to the CLI.md file.

Masa Node Twitter Sentiment Analysis

For more detailed documentation, please refer to the LLM.md file.

API Swagger Docs

http://<masa-node-ip>:8080/swagger/index.html

LLM Endpoint examples

ollama

curl http://localhost:8080/api/chat -d '{"model": "llama2","messages": [{"role": "user", "content": "why is the sky blue?" }], "stream": false}'