shade-agent-template

Warning

The Shade Agent Framework has not yet undergone a formal audit.

No representations or warranties are made regarding security, correctness, or fitness for any purpose. Use of this software is entirely at your own risk.

This repo contains a simple Shade Agent built with Hono and written in TypeScript that acts as a verifiable ETH price oracle. It fetches the price of Eth from two different APIs, takes the average, and then pushes the price to an Ethereum contract.

You can try the live demo here and view the full documentation here.

There are two deployment scenarios:

1. Local Development: Running the agent locally for rapid testing and development.
2. TEE Deployment: Running the agent in a real Trusted Execution Environment (TEE).

Prerequisites

• Install the Shade Agent CLI:

  npm i -g @neardefi/shade-agent-cli

• Set up Docker if you have not already:

  • Install Docker for Mac or Linux and create an account.

  • Log in to Docker, using docker login for Mac or sudo docker login for Linux.

• Set up a free Phala Cloud account at https://cloud.phala.network/register, then get an API key from https://cloud.phala.network/dashboard/tokens.

What is a Phala Cloud?

Phala Cloud is a cloud service that supports hosting applications in TEEs. It makes it easy to run an agent in TEE.

---

Set Up

• First set up NEAR and Phala credentials in the CLI:

  shade auth set all testnet create-new

• Set a unique agent_contract.contract_id (e.g. example-contract-123.testnet) and fill in your build_docker_image.tag (e.g. pivortex/my-first-agent) in the deployment.yaml file.

• Create a .env file and configure your environment variables.

AGENT_CONTRACT_ID= Set this to the agent contract ID you set in the deployment.yaml file
SPONSOR_ACCOUNT_ID= Set this to the NEAR account ID generated by the CLI
SPONSOR_PRIVATE_KEY= Set this to the private key generated by the CLI

• Start up Docker:

  Linux:

  sudo systemctl start docker

  Mac:

  Simply open the Docker Desktop application or run:

  open -a Docker

• Install dependencies:

  npm i

---

Local Development

• Make sure environment is set to local in the deployment.yaml file.

• In one terminal, run the Shade Agent CLI:

  shade deploy

  On Linux, the CLI may prompt you to enter your sudo password.

• Then, start your app:

  npm run dev

  Your app will start on http://localhost:3000

• Lastly, you need to whitelist the agent in the agent contract (only needed for local development). In another terminal, run:

  shade whitelist 

  Enter the agent account ID displayed when starting the app.

---

TEE Deployment

• Change the environment to TEE in the deployment.yaml file.

• Run the Shade Agent CLI

  shade deploy

  The CLI on Linux may prompt you to enter your sudo password.

The CLI will output the URL of your app.

After deploying to Phala Cloud, monitor your deployments and delete unused ones to avoid unnecessary costs. You can manage your deployments from thedashboard.

---

Interacting with the Agent

You can interact with your agent via the APIs directly or via the frontend contained in this repo.

Direct

For Phala deployments, swap localhost:3000 for your deployment URL.

• Get information about the agent:

  http://localhost:3000/api/agent-info
  

• Get the derived Ethereum Sepolia price pusher account ID and its balance (you will need to fund this account):

  http://localhost:3000/api/eth-info
  

• Request the agent to update the price of Eth:

  http://localhost:3000/api/transaction
  

Frontend

To start the frontend, run:

cd frontend
npm i
npm run dev

To use the frontend with your Phala deployment, change the API_URL to the Phala URL in your config.js file.

In the frontend, you can review the approved measurements and PPID in the contract and details of the registered agents.