# 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](https://shade-agent-template-woad.vercel.app/) and view the full documentation [here](https://docs.near.org/ai/shade-agents/getting-started/quickstart/deploying).

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](https://github.com/NearDeFi/shade-agent-cli):

  ```bash
  npm i -g @neardefi/shade-agent-cli
  ```
* Set up **Docker** if you have not already:
  * **Install** Docker for [Mac](https://docs.docker.com/desktop/setup/install/mac-install/) or [Linux](https://docs.docker.com/desktop/setup/install/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:

  ```bash
  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.

```env
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:

  ```bash
  sudo systemctl start docker
  ```

  Mac:

  Simply open the Docker Desktop application or run:

  ```bash
  open -a Docker
  ```
* Install dependencies:

  ```bash
  npm i
  ```

***

## Local Development

* Make sure `environment` is set to `local` in the `deployment.yaml` file.
* In one terminal, run the Shade Agent CLI:

  ```bash
  shade deploy
  ```

  On Linux, the CLI may prompt you to enter your **sudo password**.
* Then, start your app:

  ```bash
  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:

  ```bash
  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

  ```bash
  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 the[dashboard](https://cloud.phala.network/dashboard).

***

## 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:

```bash
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](https://github.com/NearDeFi/shade-agent-template/blob/main/frontend/src/config.js) file.

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://civictech-ou.gitbook.io/nova-docs/shade-agent.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.