diff --git a/docs/ai/shade-agents/custom-contracts/agent-guard-rails.md b/docs/ai/shade-agents/custom-contracts/agent-guard-rails.md new file mode 100644 index 00000000000..e0694db0b55 --- /dev/null +++ b/docs/ai/shade-agents/custom-contracts/agent-guard-rails.md @@ -0,0 +1,6 @@ +--- +id: agent-guard-rails +title: Agents Guard Rails +sidebar_label: Agent Guard Rails +description: "TODO" +--- \ No newline at end of file diff --git a/docs/ai/shade-agents/custom-contracts/near-agents.md b/docs/ai/shade-agents/custom-contracts/near-agents.md new file mode 100644 index 00000000000..9f4e8b50dd4 --- /dev/null +++ b/docs/ai/shade-agents/custom-contracts/near-agents.md @@ -0,0 +1,6 @@ +--- +id: near-agents +title: NEAR Agents +sidebar_label: NEAR Agents +description: "TODO" +--- \ No newline at end of file diff --git a/docs/ai/shade-agents/custom-contract.md b/docs/ai/shade-agents/custom-contracts/overview.md similarity index 73% rename from docs/ai/shade-agents/custom-contract.md rename to docs/ai/shade-agents/custom-contracts/overview.md index 3aee5d39b48..f2ef412d919 100644 --- a/docs/ai/shade-agents/custom-contract.md +++ b/docs/ai/shade-agents/custom-contracts/overview.md @@ -1,11 +1,10 @@ --- -id: custom-agent-contract -title: Custom Agent Contract -sidebar_label: Custom Agent Contract -description: This document explains how to create and deploy a custom Shade Agent contract on NEAR, including compiling, deploying, and interacting with the contract. +id: overview +title: Overview +sidebar_label: Overview +description: "This document explains how to create and deploy a custom Shade Agent contract on NEAR, including compiling, deploying, and interacting with the contract." --- -import { SigsSupport } from '@site/src/components/sigsSupport'; import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; @@ -17,11 +16,11 @@ In some cases, you may want to deploy a custom agent contract. This allows for m To create a custom agent contract, we recommend you fork the [sandbox contract](https://github.com/NearDeFi/shade-agent-js/tree/main/contracts/sandbox). This is the agent contract that's deployed under the hood when using the `shade-agent-cli`. For testing locally, you will need to maintain a separate similar contract that does not implement the agent registration flow; for this, you can follow the structure of the [proxy contract](https://github.com/NearDeFi/shade-agent-js/tree/main/contracts/proxy). -Inside this contract, you will create your own functions. For building contracts on NEAR, see our [smart contract docs](../../smart-contracts/quickstart.md). You can only develop agent contracts in Rust. +Inside this contract, you will create your own functions. For building contracts on NEAR, see our [smart contract docs](../../../smart-contracts/quickstart.md). You can only develop agent contracts in Rust. With the quickstart template, an agent can sign any transaction. You may want to limit your agent to only be able to sign transactions for a limited set of functions or actions. For this, we recommend building your transactions inside your agent contract with the [omni-transaction-rs](https://github.com/near/omni-transaction-rs) library. In such case, you should make the `request_signature` function private. -For developing Shade Agents that just interact with NEAR, you can remove the `request_signature` function. The agent will make function calls to the contract directly. Make sure that you restrict relevant functions to only be allowed to be called by the agent. If you want to interact with existing contracts on NEAR that do not implement agent registration, you can leverage [cross contract calls](../../smart-contracts/anatomy/crosscontract.md). +For developing Shade Agents that just interact with NEAR, you can remove the `request_signature` function. The agent will make function calls to the contract directly. Make sure that you restrict relevant functions to only be allowed to be called by the agent. If you want to interact with existing contracts on NEAR that do not implement agent registration, you can leverage [cross contract calls](../../../smart-contracts/anatomy/crosscontract.md). How you compile the contract depends on your operating system. @@ -54,7 +53,7 @@ How you compile the contract depends on your operating system. ## Deploying the Custom Contract -To deploy your agent with the custom contract, add the `--wasm` flag when using the `shade-agent-cli`, specifying the path to your wasm file. Depending on the size of the wasm, you may require more NEAR to deploy the contract. This can be done using the `--funding` flag, followed by the amount of NEAR (100KB = 1 NEAR). +To deploy your agent with the custom contract, add the `--wasm` flag when using the Shade Agent CLI, specifying the path to your wasm file. Depending on the size of the wasm, you may require more NEAR to deploy the contract. This can be done using the `--funding` flag, followed by the amount of NEAR (100KB = 1 NEAR). Here is an example: @@ -66,16 +65,4 @@ shade-agent-cli --wasm contract/target/near/contract.wasm --funding 5 ## Interacting with Custom Contract -To call a function on your custom agent contract, use the `agentCall` function provided by `shade-agent-js`. Supply the `methodName` and the `args` to the function call. - -```js -const res = await agentCall({ - methodName: 'example_function', - args: { - arg1, - arg2, - }, -}); -``` - - +To call a function on your custom agent contract, use the `agentCall` function provided by the Shade Agent API. Please refer to the [relevant docs](../framework/api.md#agent-call) for calling the contract in your desired language. \ No newline at end of file diff --git a/docs/ai/shade-agents/custom-contracts/yield-for-agent.md b/docs/ai/shade-agents/custom-contracts/yield-for-agent.md new file mode 100644 index 00000000000..d0f1be47751 --- /dev/null +++ b/docs/ai/shade-agents/custom-contracts/yield-for-agent.md @@ -0,0 +1,6 @@ +--- +id: yield-for-agent +title: Yield for Agent +sidebar_label: Yield for Agent +description: "TODO" +--- \ No newline at end of file diff --git a/docs/ai/shade-agents/examples.md b/docs/ai/shade-agents/examples.md index 3ed93be956f..3e99c343367 100644 --- a/docs/ai/shade-agents/examples.md +++ b/docs/ai/shade-agents/examples.md @@ -10,29 +10,42 @@ With their extensive list of features, Shade Agents unlock a wide range of new u ## Shade Agent Features Shade Agents are: -- **AI Powered** - Verifiably access LLMs. - -- **Multichain** - Can hold any crypto asset and sign transactions on any chain. - - **Non-custodial** - No one entity controls the private keys of the agent (MPC signing). - **Verifiable** - Agent code is known and executes as expected; no one can tamper with the agent. +- **Multichain** - Can hold any crypto asset and sign transactions on any chain. + +- **AI Powered** - Can verifiably access LLMs. + - **Confidential** - Inputs and state of the agent can be private. - **Flexible** - Interact with off-chain data and APIs beyond blockchain VM limits. - **Low cost** - Run intensive computation cheaply without gas limits (~20% TEE overhead compared to standard servers). +--- ## Agentic Protocols -Shade Agents enable a new paradigm of decentralized applications where a major component of the logic for a protocol is run in a verifiable off-chain environment. This allows for more flexibility in terms of computation, cost, privacy, and the data you have access to. Agentic Protocols are designed to be autonomous, proactive, and intelligent. +Shade Agents enable a new paradigm of decentralized applications where a component of the logic for a protocol is run in a verifiable off-chain environment. This allows for more flexibility in terms of computation, cost, privacy, and the data you have access to. Agentic Protocols are designed to be autonomous, proactive, and intelligent. -- A Yield Optimizer that earns optimal yield on assets across various DeFi protocols on different chains and autonomously rebalances according to a verifiable algorithm. -- A private DAO agent on Ethereum Mainnet that takes votes confidentially and publishes the end result in a single transaction. +- A Yield Optimizer that earns optimal yield on assets across various DeFi protocols on different chains and autonomously rebalances according to a verifiable algorithm to get users the best rate, always. - A staking protocol that can implement complex reward mechanics. +- A private DAO agent on Ethereum Mainnet that takes votes confidentially and publishes the end result in a single transaction. +- A smart contract that can verifiably book users plane tickets by calling the contract with funds and passing secrets (passport information and email address) to the agent directly. + +--- + +## Flexible Oracles + +Since Shade Agents can access off-chain data and APIs, they make great cheap, flexible, quick-to-spin-up oracles. +- A custom data oracle where app developers list a number of different sources, a consensus mechanism (4 of 5 sources state the same data), and the frequency with which data is pushed (or on demand), which allows smart contracts to access any data verifiably. +- A prediction market resolver agent that uses an LLM to interpret multiple webpages and APIs to resolve markets quickly and accurately. +- Verifiable randomness oracle. + +--- ## Smart Contracts using LLMs @@ -40,14 +53,15 @@ Shade Agents allow you to access LLMs from a smart contract that lives on any ch There are two main flows: -- The smart contract emits an event during a function call, the agent indexes this, uses the LLM to make a decision, and the agent calls a function on the contract with the result that is restricted to the agent's address. -- Users interact with the agent which makes decisions via the LLM and carries out certain on-chain actions based upon the decision (transfers, function calls, swaps, etc.). +1) The smart contract emits an event during a function call, the agent indexes this, uses the LLM to make a decision, and the agent calls a function on the contract with the result that is restricted to the agent's address. +2) Users interact with the agent which makes decisions via the LLM and carries out certain on-chain actions based upon the decision (transfers, function calls, swaps, etc.). With this, you could create: - A DAO with an AI President that makes decisions based on aggregate user opinions, historical context, and user reputation formulated from on-chain and off-chain data. - A decentralized social platform that uses an LLM to moderate content. - A treasury that trades assets according to news, sentiment, and historical price. +--- ## Custom Authentication @@ -55,13 +69,4 @@ Shade agents allow users to control accounts through ways other than a private k - A prediction market that lets you create new markets and place bets all from Twitter (X). - A more secure social onboarding experience where you can log in via Google, Email, etc. -- A Telegram bot for trading within a group chat. - - -## Flexible Oracles - -Since Shade Agents can access off-chain data and APIs, they make great cheap, flexible, quick-to-spin-up oracles. - -- A custom data oracle where app developers list a number of different sources, a consensus mechanism (4 of 5 sources state the same data), and the frequency with which data is pushed (or on demand), which allows smart contracts to access any data verifiably. -- A prediction market resolver agent that uses an LLM to interpret multiple webpages and APIs to resolve markets quickly and accurately. -- Verifiable randomness oracle. +- A Telegram bot for trading within a group chat. \ No newline at end of file diff --git a/docs/ai/shade-agents/framework/api.md b/docs/ai/shade-agents/framework/api.md new file mode 100644 index 00000000000..7c285c08cb1 --- /dev/null +++ b/docs/ai/shade-agents/framework/api.md @@ -0,0 +1,518 @@ +--- +id: api +title: Shade Agent API +sidebar_label: Shade Agent API +description: "TODO" +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import {Github, Language} from "@site/src/components/codetabs" + +The Shade Agent API abstracts away the complexity of the TEE and interacting with the agent contract. The API is packaged as a Docker image and included in your agent when uploaded to Phala Cloud. The API is accessible internally by default on port 3140, it is not accessible from outside the TEE. + +When the API image boots up it will automatically create the agents account, fund it with the NEAR_ACCOUNT_ID from the environment variables and register the agent in the agent contract. + +The API can be used in any language but we maintain API wrappers in TypeScript and Python. We recommend your develop in TypeScript as it has great synergies with [chainsig.js](../../../chain-abstraction/chain-signatures/implementation.md) for building multichain transactions. + +--- + +## Setup + + + + + + ```bash + npm install @neardefi/shade-agent-js + ``` + + + + + + ```bash + pip install shade-agent-py + ``` + + + + + + You can use the Shade Agent API directly with any language that supports HTTP requests. The base API endpoints change depending on your deployment: + + **Local Development:** + ``` + http://localhost:3140/api/agent + ``` + + **Production (TEE):** + ``` + http://shade-agent-api:3140/api/agent + ``` + + All endpoints expect POST requests with JSON payloads and return JSON responses. + + If you are running your API on a port other than 3140 you should ammend the base URL accordingly. + + + + + +--- + +## Agent Account ID + +Fetches the NEAR account ID of the agent. + + + + + + ```ts + import { agentAccountId } from '@neardefi/shade-agent-js'; + + const res = await agentAccountId(); + const accountId = res.accountId + ``` + + + + + + + ```py + from shade_agent import agent_account_id + + res = await agent_account_id() + account_id = res["account_id"] + ``` + + + + + + **POST /getAccountId** + + Request body + ```json + {} + ``` + + Response + ```json + { + "accountId": "14bc8ee18f2d1ef51e7d581bdd96797804c56247733defdae67ad41314686fd7" + } + ``` + + + + + +--- + +## Agent Info + +Fetches the code hash and checksum for the agent. +- The `code hash` is the code hash of the app image running inside the agent. +- The `checksum` is produced by the TEEs attestation and represents that the agent is registered. + +This function will only return the details once the agent has successfully registered in the agent contract. For running the API locally it will only return the code hash not the checksum. + + + + + + ```ts + import { agentInfo } from '@neardefi/shade-agent-js'; + + const res = await agentInfo(); + const codehash = res.codehash + const checksum = res.checksum + ``` + + + + + + + ```py + from shade_agent import agent_info + + res = await agent_info() + codehash = res["codehash"] + checksum = res["checksum"] + ``` + + + + + + **POST /view** + + Request body + ```json + { + "methodName": "get_agent", + "args": { + "account_id": "14bc8ee18f2d1ef51e7d581bdd96797804c56247733defdae67ad41314686fd7" + } + } + ``` + + Response + ```json + { + "codehash": "03bcd36d3ffb5346c9e1e0166a4c2734a9e7cceedee6f7d992499aeb7fa54ead", + "checksum": "0c32c5c598bc8a3bfec47f3d7d9a9d600c8a60e5b97d90a4c2856a7c829eb6d4" + } + ``` + + + + + +--- + +## Agent Balance + +Fetches the NEAR balance of the agent's account in yoctoNEAR (1 NEAR = 10^24 yoctoNEAR). + + + + + + ```ts + import { agent } from '@neardefi/shade-agent-js'; + + const res = await agent("getBalance"); + const balance = res.balance + ``` + + + + + + + ```py + from shade_agent import agent + + res = await agent("getBalance") + balance = res["balance"] + ``` + + + + + + **POST /getBalance** + + Request body + ```json + {} + ``` + + Response + ```json + { + "balance": "203436730084671139765003" + } + ``` + + + + + +--- + +## Request Signature + +Requests a signature from the Shade Agent system for a multichain account. It has three arguments: +- **path** - An string that maps the signature to a specific account, the path can be set to anything and by changing the path you will be signing for a different account. +- **payload** - The hash of the transaction to be signed, given as a hex string. +- **keyType** - The signature scheme being used to sign the payload `Ecdsa` (secp256k1) or `Eddsa` (ed25519). + +It returns the signature for the transaction. + + + + + + ```ts + import { requestSignature } from '@neardefi/shade-agent-js'; + + const res = await requestSignature({ + path: "ethereum-1", + payload: "cf80cd8a...", + keyType: "Ecdsa", // Or "Eddsa" + }); + ``` + +
+ Response + + For `Ecdsa` the function returns the components of the signature as hex strings. Note that to get r remove the first two hex characters from big_r. + + ```typescript + { + scheme: 'Secp256k1', + big_r: { + affine_point: '03D537AFFD52BE9AF0DA6CF41B573F4BE065434AEE2D25A500BC730C06E7EB2AF1' + }, + s: { + scalar: '3470037EB46DC6D1921900B635785290184EC980CFEC7109EB103B5698D4F725' + }, + recovery_id: 0 + } + ``` + + For `Eddsa` the function returns the whole signature as a 64-byte array. + + ```typescript + { + scheme: 'Ed25519', + signature: [ + 5, 105, 30, 208, 192, 39, 154, 105, 252, 20, 132, + 64, 247, 207, 223, 127, 197, 43, 30, 145, 164, 224, + 1, 45, 240, 28, 155, 218, 204, 5, 136, 111, 238, + 40, 120, 122, 249, 166, 193, 174, 120, 94, 177, 39, + 179, 193, 170, 117, 37, 36, 155, 38, 72, 24, 118, + 235, 187, 110, 129, 26, 186, 7, 0, 8 + ] + } + ``` + + If your using the chainsig.js library you don't need to worry about the format of these responses since the library handles it. + +
+ + + + + + ```py + from shade_agent import request_signature + + res = await request_signature( + path="ethereum-1", + payload="cf80cd8a...", + key_type="Ecdsa", # Or "Eddsa" + ) + ``` + +
+ Response + + For `Ecdsa` the function returns the components of the signature as hex strings. Note that to get r remove the first two hex characters from big_r. + + ```python + { + 'scheme': 'Secp256k1', + 'big_r': { + 'affine_point': '03D537AFFD52BE9AF0DA6CF41B573F4BE065434AEE2D25A500BC730C06E7EB2AF1' + }, + 's': { + 'scalar': '3470037EB46DC6D1921900B635785290184EC980CFEC7109EB103B5698D4F725' + }, + 'recovery_id': 0 + } + ``` + + For `Eddsa` the function returns the whole signature as a 64-byte array. + + ```python + { + 'scheme': 'Ed25519', + 'signature': [ + 5, 105, 30, 208, 192, 39, 154, 105, 252, 20, 132, + 64, 247, 207, 223, 127, 197, 43, 30, 145, 164, 224, + 1, 45, 240, 28, 155, 218, 204, 5, 136, 111, 238, + 40, 120, 122, 249, 166, 193, 174, 120, 94, 177, 39, + 179, 193, 170, 117, 37, 36, 155, 38, 72, 24, 118, + 235, 187, 110, 129, 26, 186, 7, 0, 8 + ] + } + ``` + +
+ + + + + + **POST /call** + + Request body + ```json + { + "methodName": "request_signature", + "args": { + "path": "ethereum-1", + "payload": "cf80cd8a...", + "key_type": "Ecdsa" + } + } + ``` + +
+ Response + + For `Ecdsa` the function returns the components of the signature as hex strings. Note that to get r remove the first two hex characters from big_r. + + ```json + { + "scheme": "Secp256k1", + "big_r": { + "affine_point": "03D537AFFD52BE9AF0DA6CF41B573F4BE065434AEE2D25A500BC730C06E7EB2AF1" + }, + "s": { + "scalar": "3470037EB46DC6D1921900B635785290184EC980CFEC7109EB103B5698D4F725" + }, + "recovery_id": 0 + } + ``` + + For `Eddsa` the function returns the whole signature as a 64-byte array. + + ```json + { + "scheme": "Ed25519", + "signature": [ + 5, 105, 30, 208, 192, 39, 154, 105, 252, 20, 132, + 64, 247, 207, 223, 127, 197, 43, 30, 145, 164, 224, + 1, 45, 240, 28, 155, 218, 204, 5, 136, 111, 238, + 40, 120, 122, 249, 166, 193, 174, 120, 94, 177, 39, + 179, 193, 170, 117, 37, 36, 155, 38, 72, 24, 118, + 235, 187, 110, 129, 26, 186, 7, 0, 8 + ] + } + ``` + +
+ + + + + +--- + +## Agent Call + +Makes a function call to the agent contract from the agent. This is used for custom contracts when you want to call a function other than request_signature. It returns the result of the function call. + + + + + + ```ts + import { agentCall } from '@neardefi/shade-agent-js'; + + const res = await agentCall({ + methodName: "example_call_method", + args: { + arg1: "Value1", + arg2: "Value2", + }, + gas: "30000000000000", // Optional + }) + ``` + + + + + + ```py + from shade_agent import agent_call + + res = await agent_call({ + "methodName": "example_call_method", + "args": { + "arg1": "Value1", + "arg2": "Value2, + }, + "gas": "30000000000000", # Optional + }) + ``` + + + + + + **POST /call** + + Request body + ```json + { + "methodName": "example_call_method", + "args": { + "arg1": "value1", + "arg2": "value2" + }, + "gas": "30000000000000" // Optional + } + ``` + + + + + + +--- + +## Agent View + +Makes a function call to a view method (a method that does not require gas) on the agent contract. It returns the result of the function call. + + + + + + ```ts + import { agentView } from '@neardefi/shade-agent-js'; + + const res = await agentView({ + methodName: "example_view_method", + args: { + arg1: "value1", + arg2: "value2", + }, + }) + ``` + + + + + + ```py + from shade_agent import agent_view + + res = await agent_view({ + "methodName": "example_view_method", + "args": { + "arg1": "value1", + "arg2": "value2", + }, + }) + ``` + + + + + + **POST /view** + + Request body + ```json + { + "methodName": "example_view_method", + "args": { + "arg1": "value1", + "arg2": "value2" + } + } + ``` + + + + \ No newline at end of file diff --git a/docs/ai/shade-agents/framework/cli.md b/docs/ai/shade-agents/framework/cli.md new file mode 100644 index 00000000000..7d2d1ec6147 --- /dev/null +++ b/docs/ai/shade-agents/framework/cli.md @@ -0,0 +1,127 @@ +--- +id: cli +title: Shade Agent CLI +sidebar_label: Shade Agent CLI +description: "TODO" +--- + +The [Shade Agent CLI](https://github.com/NearDeFi/shade-agent-cli/tree/main) abstracts away the complexity of deploying a Shade Agent. + +Under the hood the CLI: +- Builds and publishes the Docker Image for your agent app and modifies your environment variables and docker-compose.yaml to match your new image +- Creates the agent contract account, deploys the agent contract to it and initializes it with the ACCOUNT_ID as the owner +- Approves the image code hashes for your agent (app and API image) +- Deploys the agent to a TEE on Phala Cloud + +--- + +## Local vs Production + +The `NEXT_PUBLIC_contractId` in your environment variables prefix should be set to `ac-proxy.` for local development and `ac-sandbox.` for TEE deployment. + +For local deployment the CLI works a little differently: +- No Docker Image is built or published for your agent app +- An agent contract that doesn't require agent registration is deployed instead (since locally you cannot produce a valid TEE attestation) +- The API image is hosted locally instead of deploying anything to a TEE + +--- + +## Installation + +```bash +npm i -g @neardefi/shade-agent-cli +``` + +--- + +## Usage + +The Shade Agent CLI is a single command with standard configurations. Run the command within the root of your project. + +```bash +shade-agent-cli +``` + +Your project root must contain your `.env.development.local`, `Dockerfile` and `docker-compose.yaml` files. + +--- + +## Flags + +The CLI comes with a list of flags to configure the CLI and switch part off. If you need further customizability when deploying your agent we suggest you switch off the relevant part via a flag and complete that step manually using native tools - [Docker CLI](https://docs.docker.com/reference/cli/docker/), [NEAR CLI](https://docs.near.org/tools/near-cli) and [Phala CLI](https://docs.phala.network/phala-cloud/phala-cloud-cli/overview) + + +- **--wasm ``** + + Path to a custom agent contract WASM file (e.g. `contract/near/contract.wasm`) to deploy instead of the default contract. Use this when using [custom contracts](../custom-contracts/overview.md). + +- **--funding ``** + + Amount of NEAR tokens to fund the contract deployment (e.g. `5` for 5 NEAR). Use this when deploying a custom contract. + +- **--image** + + Build and push the Docker image only. Use this when you want customizability over the deployment of the agent contract. + +- **--contract** + + Build and push the Docker image, and deploy the contract only. Use this when you want customizability over the approving of image code hashes. + +- **--phala-only** + + Deploy the agent, specified by the currentΒ `docker-compose.yaml`, to Phala Cloud. Use this when you want to redeploy the same agent as you last deployed. + +- **--no-redeploy** + + Skip redeploying the contract. Use when you want to deploy a new agent quicker and you don't need the agent contract redeploying. + +- **--no-build** + + Skip building and pushing the Docker image. Use this when you want to redeploy the same agent or want more control over the image build process. + +- **--no-phala** + + Skip deploying the agent to Phala Cloud. Use this when you want more control over hosting the agent (e.g. deploying to a TEE with higher specs). + +- **--no-cache** + + Run docker build with --no-cache. Use this when you need clean builds or want to update cached layers (e.g. cached layers may use older packages). + +:::note +Some options are mutually exclusive. See error messages for details if you use conflicting flags. +::: + +--- + +## Custom RPC + +To use the non default RPC with the CLI and the API create a filed named `near-rpc.json` with your projects root and configure the RPCs you would like to use, for example: + +```json +{ + "nearRpcProviders": [ + { + "connectionInfo": { + "url": "https://neart.lava.build:443" + }, + "options": { + "retries": 3, + "backoff": 2, + "wait": 1000 + } + }, + { + "connectionInfo": { + "url": "https://test.rpc.fastnear.com" + }, + "options": { + "retries": 3, + "backoff": 2, + "wait": 1000 + } + } + ] +} +``` + +If required, you can specify headers under connectionInfo. diff --git a/docs/ai/shade-agents/framework/environment-variables.md b/docs/ai/shade-agents/framework/environment-variables.md new file mode 100644 index 00000000000..ede32f475d3 --- /dev/null +++ b/docs/ai/shade-agents/framework/environment-variables.md @@ -0,0 +1,94 @@ +--- +id: environment-variables +title: Environment Variables +sidebar_label: Environment Variables +description: "TODO" +--- + +Environment variables are a crucial component of the Shade Agent Framework. They configure your Shade Agent and are passed encrypted into your agent when it goes live. Note that the same agent code (same Docker Compose file) can use different environment variables in different deployments. + +The environment variables file must be named `.env.development.local`. + +## Required Variables + +Below, we'll walk through each environment variable required by the Shade Agent Framework: + +- **NEAR_ACCOUNT_ID** + + :::info Example + NEAR_ACCOUNT_ID=example-account.testnet + ::: + + This is the NEAR account ID that is used to create the agent contract's account when running the Shade Agent CLI and to automatically fund the agent account during startup. You should ensure this account remains funded as you continue to deploy additional agents. + + You can create a NEAR account by using the NEAR CLI. + + Install the CLI: + + ```bash + curl --proto '=https' --tlsv1.2 -LsSf https://github.com/near/near-cli-rs/releases/latest/download/near-cli-rs-installer.sh | sh + ``` + + Create an account: + + ```bash + export ACCOUNT_ID=example-name.testnet + near account create-account sponsor-by-faucet-service $ACCOUNT_ID autogenerate-new-keypair save-to-keychain network-config testnet create + ``` + + Replace `example-name.testnet` with a unique account ID. + +- **NEAR_SEED_PHRASE** + + :::info Example + NEAR_SEED_PHRASE="book chapter unknown knife strange inherit amazing artist mixture loan rotate lyrics" + ::: + + This is the seed phrase for the NEAR_ACCOUNT_ID. When creating an account with the above command the seed phrase will be printed to the terminal + +- **NEXT_PUBLIC_contractId** + + :::info Examples + NEXT_PUBLIC_contractId=ac-proxy.example-account.testnet + NEXT_PUBLIC_contractId=ac-sandbox.example-account.testnet + ::: + + This is the NEAR account ID where the agent contract will be deployed when running the Shade Agent CLI. The account is automatically created when you run the Shade Agent CLI. This account must be your NEAR_ACCOUNT_ID prefixed with either `ac-proxy.` or `ac-sandbox.`, which determines whether the deployment is local or to a TEE, respectively. For `ac-proxy.` deployments, the agent contract doesn't require agent registration since local environments cannot provide valid TEE attestation. + +- **API_CODEHASH** + + The API_CODEHASH defines the code hash of the Shade Agent API. You only need to update this when a new API version is released. The [Quickstart Template](https://github.com/NearDeFi/shade-agent-template/blob/main/.env.development.local.example#L9) always includes the most up-to-date API code hash. + +- **APP_CODEHASH** + + The APP_CODEHASH defines the code hash of your agent. You don't need to edit this as it will be automatically updated when running the Shade Agent CLI in production. + +- **DOCKER_TAG** + + :::info Example + DOCKER_TAG=username/my-app + ::: + + The `Docker_TAG` specifies how to find your app image on Docker hub. You need to edit the Docker tag so that the first part matches your Docker username. You can set the second part to whatever you want your image to be called. When the CLI is ran the docker tag for your apps image in the docker-compose.yaml will be automatically updated. + +- **PHALA_API_KEY** + + :::info Example + PHALA_API_KEY=phak_tIhrDY0mXJMgmLLMEMoM6yBxOsjfVM-sTmXmjOF4Fks + ::: + + The PHALA_API_KEY is used to upload your agent to Phala Cloud when running the Shade Agent CLI. You can get a key [here](https://cloud.phala.network/dashboard/tokens). + +## Optional Environment Variables + +- **API_PORT** + + :::info Example + API_PORT=4000 + ::: + + The API_PORT defines which port number the Shade Agent API port is exposed on. The API by default is hosted on port 3140. + +## Your Own Variables + +You should also set any additional environment variables your agent may need in the `.env.development.local` file. Remember to update your [Docker Compose](https://github.com/NearDeFi/shade-agent-template/blob/main/docker-compose.yaml#L21) file to pass these additional variables to your agent. \ No newline at end of file diff --git a/docs/ai/shade-agents/framework/overview.md b/docs/ai/shade-agents/framework/overview.md new file mode 100644 index 00000000000..77b2cce36e3 --- /dev/null +++ b/docs/ai/shade-agents/framework/overview.md @@ -0,0 +1,128 @@ +--- +id: overview +title: Framework Overview +sidebar_label: Framework Overview +description: "TODO" +--- + +import { SigsSupport } from '@site/src/components/sigsSupport'; + +The Shade Agent Framework provides a suite of tools designed to simplify the development and deployment of Shade Agents. This framework abstracts away the complexities of the underlying infrastructure, allowing developers to focus on building their agent logic. In this section, we'll explore the tooling provided by the framework and examine the key components you need when building an agent. + +--- + +## Languages, Templates and Architecture + +When starting to build with the Shade Agent Framework, we recommend forking the quickstart [Shade Agent Template](https://github.com/NearDeFi/shade-agent-template). This template contains all the necessary files to build a Shade Agent (which we'll explore later on this page). + +Since the agent is written in TypeScript and uses `shade-agent-js`, it integrates seamlessly with [chainsig.js](../../../chain-abstraction/chain-signatures/implementation.md) for building multichain transactions and deriving multichain accounts. + +We also maintain a [Python example](https://github.com/NearDeFi/shade-python-example/tree/main) that uses `shade-agent-py`, allowing you to develop agents in Python. However, note that we don't currently maintain tooling for building multichain transactions and deriving multichain accounts in Python, so additional development work will be required. + +Agents can be written in any language as long as you can create a Docker image for it by using the API directly. You can learn more about this approach on the [API page](./api.md). + +An Agent is essentially a backend service (or server) that uses the Shade Agent API and runs inside a Trusted Execution Environment (TEE) instead of on a centralized server. You can develop using any backend framework you prefer, expose API routes, run cron jobs, or index events and respond to them with actions. If you're planning to develop Shade Agents seriously, we recommend having prior experience with creating backend services. + +--- + +## Shade Agent API + +The Shade Agent API abstracts away the complexity of the TEE and interacting with the agent contract. To learn more about how the API works and how to use it in different languages, please refer to the [API page](./api.md). + +--- + +## Shade Agent CLI + +The Shade Agent CLI abstracts away the complexity of deploying a Shade Agent. To learn more about how the CLI works and how to use it, please refer to the [CLI page](./cli.md). + +--- + +## Environment Variables + +Environment variables are a crucial component of the Shade Agent Framework. They configure your Shade Agent and are passed encrypted into your agent when it goes live. To learn more about configuring environment variables in your project, please refer to the [Environment Variables page](./environment-variables.md). + +--- + +## Agent Contract + +By default the Shade Agent CLI will deploy a generic agent contract that implements the three methods, approve_codehash, register_agent, and request_signature, talked about in the introduction. This generic agent contract works for many use cases since you can register any arbitrary agent and have it request signatures for any chain - it's very flexible. + +There are also cases when you should develop your own custom agent contract. These include, but are not limited to: +1) You want to implement strict guardrails that prevent malicious actions, even if the TEE is somehow compromised +2) You want to implement a custom agent registration or code hash upgradability mechanism +3) You want to build an agent that just interacts with the NEAR blockchain + +Further documentation can be found in the [custom contract section](../custom-contracts/overview.md). + +--- + + +## Phala Cloud + +Phala Cloud is a cloud solution that simplifies hosting applications and agents inside Trusted Execution Environments. The Shade Agent Framework uses Phala Cloud for agent deployment. You can deploy any standard Docker application to Phala. To learn more about Phala, visit their [documentation](https://docs.phala.network/phala-cloud/what-is/what-is-phala-cloud). + +Once your agent is deployed, you can manage the deployment from the [dashboard](https://cloud.phala.network/dashboard). + +To deploy an agent to production, you'll need a Phala Cloud account. You can create one [here](https://cloud.phala.network/register). + +--- + +## Docker + +Docker is a platform that allows you to package an application into a self-contained environment. By creating a Docker image, you can run your agent in the TEE. An agent typically consists of two Docker images (the application and the Shade Agent API), but it can include more. When building Shade Agents, it's helpful to understand how Docker works. If you're interested in learning more about Docker, please visit the [documentation](https://docs.docker.com/get-started/docker-overview/). + +You'll need to set up docker on your machine if you do not have it already and create an account: +- 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. + +There are two Docker-related files included in our project: the `Dockerfile` and the `Docker Compose` file. + +### Dockerfile + +The Dockerfile tells Docker how to build and run your image. The Shade Agent CLI automatically builds your Docker image using the Dockerfile and pushes it to Docker Hub, making it accessible over the internet. + +A standard Dockerfile will: +1. Start with a `base image`, which serves as the starting point for your application (e.g., Ubuntu, Alpine, Node.js, Python pre-installed) +2. Set the working directory +3. Install system dependencies +4. Add relevant files from the project to the image (in our examples, everything within the `source folder` is included, along with the `manifest file` that lists your dependencies like package.json or pyproject.toml) +5. Install project dependencies +6. Build the project +7. Set the environment (production, development) +8. Tell Docker how to start the application + +In most cases, you can use the Dockerfile already supplied in the template without modification. + +Here are example Dockerfiles for a [Typescript](https://github.com/NearDeFi/shade-agent-template/blob/main/Dockerfile) and [Python](https://github.com/NearDeFi/shade-python-example/blob/main/Dockerfile) agent. + +You can learn more about the Dockerfile [here](https://docs.docker.com/reference/dockerfile/) + +### Docker Compose + +The Docker Compose file (docker-compose.yaml) defines which Docker images will be included within your agent. This file is what is actually uploaded to Phala Cloud to run your agent, which then pulls the specified images. The compose file also specifies which environment variables are passed to the images, whether images are exposed on ports, and other configuration details. + +The images used are automatically configured when you run the Shade Agent CLI. In most cases, you can use the Docker Compose file already supplied [in the template](https://github.com/NearDeFi/shade-agent-template/blob/main/docker-compose.yaml). However, if you want to include additional Docker images in your agent or use additional environment variables for your application, you'll need to edit the Docker Compose file. + +You can learn more about the Docker Compose file [here](https://docs.docker.com/reference/compose-file/) + +--- + +## Next Steps + +Now that you have an overview of the framework, we recommend exploring these sections next: +1. Framework components: [API](./api.md), [CLI](./cli.md), and [Environment Variables](./environment-variables.md) +2. [Custom Contracts](../custom-contracts/overview.md) - build specialized agent contracts +3. [Plugins](../plugins.md) - extend your agent's capabilities +4. [Security Considerations](../security.md) - check your agent abides by best practices + + + + + + \ No newline at end of file diff --git a/docs/ai/shade-agents/introduction.md b/docs/ai/shade-agents/introduction.md index 1a969500d01..dffb35c5640 100644 --- a/docs/ai/shade-agents/introduction.md +++ b/docs/ai/shade-agents/introduction.md @@ -13,7 +13,7 @@ Previous Web3 agents fall into one of two categories: 1. They are trustless and verifiable by using a trusted execution environment (TEE), but if the TEE goes down, the private keys and funds of the agent are lost. 2. The agent’s accounts are persistent, but the agents are centralized. -Shade Agents provide verifiability and non-custody by operating in TEEs, but also persistent control of accounts by using NEAR's decentralized key management. Any instance of an agent running the same code inside a TEE has access to the same accounts. You don't need to worry about private keys being lost or exposed. +Shade Agents provide verifiability and non-custody by operating in TEEs, but also persistent control of accounts by using NEAR's decentralized key management. Any instance of an agent running the same code inside a TEE can access the same accounts meaning you don't need to worry about private keys being lost or exposed. Thanks to combining TEEs with the NEAR tech stack, Shade Agents can autonomously sign transactions across any chain, interact with AI models and external data sources, manage assets, and perform privacy-preserving, verifiable computations, offering the flexibility and performance of Web2 with the verifiability of Web3. @@ -59,17 +59,17 @@ The Agent Contract has three main functions: After the contract is deployed, a `code hash` is set to ensure that only agents running the correct code (i.e. it has the same code hash) can be registered in the agent contract. -Developers or protocols may need to modify the code running inside agents over time. Because of this, when the contract is initialized an `owner` account Id is set. Only the owner can approve a new `code hash`. +Developers or protocols may need to modify the code running inside agents over time. Because of this, when the contract is initialized an `owner` account ID is set. Only the owner can approve a new `code hash`. The `shade-agent-cli` handles the deployment of the agent contract and automatically approves the code hash of your agent. :::tip -Upgradeability can be designed for the specific use case. Common upgrade methods include approving a new code hash through DAO voting or implementing a grace period or cooldown, allowing users to withdraw funds if they're uncomfortable with the incoming code hash for the new agent. +Upgradeability can be designed for the specific use case. Common upgrade methods include approving a new code hash through DAO voting or implementing a grace period or cool down, allowing users to withdraw funds if they're uncomfortable with the incoming code hash for the new agent. ::: #### Register Agent -The `register_agent` function verifies that the agent is running in a TEE and executing the expected code (as defined by the approved code hash). Upon successful verification, the agent's account Id becomes registered and gains access to transaction signing (request_signature). +The `register_agent` function verifies that the agent is running in a TEE and executing the expected code (as defined by the approved code hash). Upon successful verification, the agent's account ID becomes registered and gains access to transaction signing (request_signature). The `shade-agent-api` automatically registers the agent when booting up in the TEE. @@ -89,25 +89,23 @@ The request signature function accepts three arguments: The `shade-agent-api` exposes the `requestSignature` function to sign transactions on behalf of the Shade Agent within your agent. :::tip -Within agent gated functions, we can implement an additional layer of security to strictly limit the Shade Agent's actions. For example, it could be restricted to only create transactions on Solana, perform swaps but not transfers, or transfer a maximum of 1 ETH per day. +Within agent gated functions, we can implement an additional layer of security to strictly limit the Shade Agent's actions. For example, it could be restricted to only create transactions for Solana, perform swaps but not transfers, or transfer a maximum of 1 ETH per day. ::: --- -## Development flows +## Languages and Frameworks -In most cases you will develop your agent using the [quickstart template](./quickstart/deploying.md). This template is designed to enable you to sign transactions from your agent on any blockchain. In some cases, you may want to deploy a [custom agent contract](./custom-contract.md), which allows for more customizability inside of the agent contract, allows you to restrict your agent to certain actions, and is used for building Shade Agents that just interact with NEAR. +The agent is just a backend service that runs inside a TEE instead of a centralized server. You can run the agent on an internal cron job, respond to actions, or it can expose API routes that can be called. -In very rare cases, you may want to implement niche features that cannot be done with the `shade-agent-cli` or `shade-agent-api`. In such cases, you can develop a Shade Agent without these tools. Here is an [example repository](https://github.com/NearDeFi/shade-agent-no-api). +Agents can be written in virtually any programming language and use any framework, as long as you can build a `Docker image` for your program. ---- +If you require a custom agent contract (which not all use cases do) then these are written in Rust. -## Languages and Frameworks - -The agent is just a backend service that runs inside a TEE instead of a centralized server. You can run the agent on an internal cron job to perform an action every set time period, or in response to actions, or it can expose API routes that can be called. +--- -Agents can be written in virtually any programming language and use any framework, as long as you can build a `Docker image` for your program. +## Next Steps -For most use cases you do not need to write your own agent contract. If you require a custom contract then these are written in Rust. +Now that you've learned what Shade Agents are and why they're powerful, head to the [quickstart](./quickstart/deploying.md) to deploy your first agent and see how to build them. \ No newline at end of file diff --git a/docs/ai/shade-agents/quickstart/components.md b/docs/ai/shade-agents/quickstart/components.md index 62591c61336..a362c7d2360 100644 --- a/docs/ai/shade-agents/quickstart/components.md +++ b/docs/ai/shade-agents/quickstart/components.md @@ -8,7 +8,7 @@ description: "Learn about the core components of production Shade Agents, includ import {Github} from "@site/src/components/codetabs" import { SigsSupport } from '@site/src/components/sigsSupport'; -In this section, we'll explore the main components of the [quickstart template](https://github.com/NearDeFi/shade-agent-template) and how you can modify it to build your own agent. +In this section, we'll explore the main components of the [quickstart template](https://github.com/NearDeFi/shade-agent-template) to understand how to develop a Shade Agent. We'll also look at how to modify the template to build an agent for your use case. --- @@ -17,7 +17,7 @@ In this section, we'll explore the main components of the [quickstart template]( The template we're using is a simple Shade Agent built with Hono and written in TypeScript that acts as a verifiable ETH price oracle. It takes prices from two different APIs, takes the average, and then pushes the price to an Ethereum contract. The template also comes with a frontend to make it easier to interact with the Shade Agent. The project has three different APIs: -1) [**agentAccount**](https://github.com/NearDeFi/shade-agent-template/blob/main/src/routes/agentAccount.ts) - This API simply fetches the agent's NEAR account Id and its balance by using the `agentAccountId` and `agent("getBalance")` functions from the `shade-agent-js` library. +1) [**agentAccount**](https://github.com/NearDeFi/shade-agent-template/blob/main/src/routes/agentAccount.ts) - This API simply fetches the agent's NEAR account ID and its balance by using the `agentAccountId` and `agent("getBalance")` functions from the `shade-agent-js` library. 2) [**ethAccount**](https://github.com/NearDeFi/shade-agent-template/blob/main/src/routes/ethAccount.ts) - This API returns the `Ethereum Sepolia account` that the Shade Agent uses to update the price of Ethereum in the Sepolia contract. This API is used so the user knows which account to fund for gas. 3) [**transaction**](https://github.com/NearDeFi/shade-agent-template/blob/main/src/routes/transaction.ts) - This is where the core logic of the agent is defined. When this API is called, the agent will build and sign a transaction. We'll look deeper into this API route in the next part. @@ -25,84 +25,58 @@ The project has three different APIs: ## Signing Transactions -In the [transaction API Route](https://github.com/NearDeFi/shade-agent-template/blob/main/src/routes/ethAccount.ts), we can see how we use the `requestSignature` function from the `shade-agent-js` library so the Shade Agent can sign a multichain transaction. +In the [transaction API Route](https://github.com/NearDeFi/shade-agent-template/blob/main/src/routes/transaction.ts), the `requestSignature` function from the `shade-agent-js` library is used to sign a transaction. In this example, we're signing a transaction to call an Ethereum contract to update the stored price of ETH. First, we retrieve the price of ETH (in this example, the function queries two different APIs and calculates the average). -Next, we build the transaction and `transaction payload` to be signed. To do this, we're using the `chainsig.js library`. +Next, we build the `transaction payload` to be signed. To do this, we're using the `chainsig.js` library. Using this library, we: -1. `Derive the Ethereum addresses` that will be sending the transaction. This function takes the agent contract account Id since this is the predecessor account that is calling the Chain Signatures [MPC contract](https://github.com/Near-One/mpc/tree/main/libs/chain-signatures/contract), and a path. The path can be whatever string you like, different paths will derive different addresses. +1. `Derive the Ethereum address` that will be sending the transaction. This function takes the agent contract account ID since this is the predecessor account that is calling the Chain Signatures [MPC contract](https://github.com/Near-One/mpc/tree/main/libs/chain-signatures/contract), and a path. The path can be whatever string you like, different paths will derive different addresses. 2. Create the `data`. This is what action we're performing, in this case, a function call to update the price in the contract. 3. `Build the transaction and the transaction payload` by inputting the derived address, the target Ethereum smart contract, and the data. + url="https://github.com/NearDeFi/shade-agent-template/blob/specify-keytype/src/routes/transaction.ts#L64-L80" + start="65" end="81" /> -Once we have the payload (also known as the hash), we can call the `requestSignature` function to sign the transaction. +Once we have the payload (also known as the hash), we can call the `requestSignature` function to sign the transaction. We specify the `keyType` as `Ecdsa` as we're signing for a blockchain that uses the `secp256k1` signature scheme. + url="https://github.com/NearDeFi/shade-agent-template/blob/specify-keytype/src/routes/transaction.ts#L37-L40" + start="37" end="41" /> The result is the `signature`. We then attach the signature to the Ethereum transaction and broadcast it to the target network. + url="https://github.com/NearDeFi/shade-agent-template/blob/specify-keytype/src/routes/transaction.ts#L44-L50" + start="44" end="51" /> --- -## Modifying this Example +## Using Different Chains -The simplest way to create your own Shade Agent is to modify the example template and alter the transaction payload being signed in the [transaction.ts](https://github.com/NearDeFi/shade-agent-template/blob/main/src/routes/transaction.ts) API route. +We set up a chain adapter for Ethereum Sepolia in the [Ethereum.ts](https://github.com/NearDeFi/shade-agent-template/blob/main/src/utils/ethereum.ts) file using the `chainsig.js` library. This library allows us to easily construct transaction payloads to be signed by the agent. -The `requestSignature` function supports signing for any blockchain that uses the `secp256k1` and `ed25519`signature scheme (Bitcoin, Ethereum, Solana, Sui, Doge, Cosmos, etc.). This function supports any arbitrary payload, allowing you to send multiple different transaction payloads through this function. By default, the `requestSignature` function signs for the `secp256k1` scheme. To switch to `ed25519`, specify the `keyType` in the arguments of the call as `Eddsa`. - -In this example, we're using the [chainsig.js library](https://neardefi.github.io/chainsig.js/), which supports transaction building for several different chains. By defining a different [chain adapter](https://github.com/NearDeFi/shade-agent-template/blob/main/src/utils/ethereum.ts#L42-L51) and setting a different RPC provider, you can easily start building transactions for other chains the library supports. - -Review our [chain signature docs](../../../chain-abstraction/chain-signatures/implementation.md) for building transactions to learn how to integrate different chains. Note that step 3 of requesting a signature differs here; instead, we use the `requestSignature` function from the `shade-agent-js`. - -:::tip -If you're seeking inspiration for what to build, consider reviewing our [ideas page](../examples.md). -::: - ---- - -## How the Quickstart Works - -The Shade Agent Framework abstracts away a lot of the complexity of deploying a Shade Agent. Here we will illuminate key parts of how the deployment flow works. There are different flows for local and TEE deployment, which are selected by changing the contract prefix to `ac-proxy.` and `ac-sandbox.`, respectively. + -### Local Deployment -1) A `fake agent contract` is deployed to `ac-proxy.NEAR_ACCOUNT_ID` using NEAR's global contracts and initializes it with NEAR_ACCOUNT_ID as the owner. The contract is fake as it doesn't require the agent to be running in a TEE to register. -2) The `shade-agent-api image` is fetched from Docker Hub and is run locally on port 3040. -3) Inside the image, a fake agent account is deterministically derived using your funding account Id as a derivation path. -4) The agent account is funded using the NEAR_ACCOUNT_ID. -5) The `approve_codehash` function is called by the NEAR_ACCOUNT_ID. -6) The `register_agent` function is called by the fake agent. No verification actually happens here, as we know the agent is not running in a TEE. -7) Whenever you use `requestSignature`, it calls the agent contract to get a signature without requiring a valid agent. +You can set up chain adapters for a variety of chains, including EVM, Bitcoin, NEAR, Solana, SUI, XRP, Cosmos, and more to allow your agent to interact with multiple different chains. You can see a full list of the chains currently supported [here](https://github.com/NearDeFi/chainsig.js/tree/main?tab=readme-ov-file#supported-chains), but feel free to contribute any chain that is not yet supported. -### TEE deployment -1) A Docker image for your agent code is built and pushed to Docker Hub. -2) A `real agent contract` is deployed to ac-sandbox.NEAR_ACCOUNT_ID using NEAR's global contracts and initializes it with the NEAR_ACCOUNT_ID as the owner. The contract is real as it requires the agent to be running in a TEE to register. -3) A `TEE is deployed` to Phala Cloud with your agent image (on port 3000) and the sandbox API image (on port 3040). -4) Inside the TEE, an agent account is randomly derived using the `TEE's hardware-based entropy`. -5) The `approve_codehash` function is called by the NEAR_ACCOUNT_ID. -6) The `register_agent` function is called by the agent. The agent is checked to be running in a TEE and running the correct code. -7) Whenever you use `requestSignature`, the agent calls the agent contract, checks that the agent is verified, and returns a signature. +Implementation details differ slightly from chain to chain; as such, we recommend you review our [chain signature docs](../../../chain-abstraction/chain-signatures/implementation.md). Note that step 3 of requesting a signature is different; we use the `requestSignature` function from `shade-agent-js`. -The CLI code can be found [here](https://github.com/NearDeFi/shade-agent-cli/blob/main), and the shade-agent-api code, along with the global contract code, can be found in this [repo](https://github.com/NearDeFi/shade-agent-js). +If you are using a chain that uses the `ed25519` signature scheme (NEAR, Solana, SUI, Aptos, etc.), you should specify the `keyType` as `Eddsa` when calling `requestSignature`. ---- +--- -## Using Different Languages +## Next Steps -To build Shade Agents in different programming languages, you can call the APIs directly, instead of using the functions provided by shade-agent-js. The functions and APIs can be found [here](https://github.com/NearDeFi/shade-agent-js/blob/main/src/api.ts). +Now that you've explored the basics of Shade Agents, we recommend diving deeper into the [framework overview](../framework/overview.md) to understand the core concepts needed for building production-ready Shade Agents. \ No newline at end of file diff --git a/docs/ai/shade-agents/quickstart/deploying.md b/docs/ai/shade-agents/quickstart/deploying.md index 50e1ea65190..78f1bfb08c9 100644 --- a/docs/ai/shade-agents/quickstart/deploying.md +++ b/docs/ai/shade-agents/quickstart/deploying.md @@ -43,7 +43,8 @@ On the [next page](./components.md), you'll see how to edit this agent for your - Create a `NEAR testnet account` and record the account name and `seed phrase`: ```bash - near account create-account sponsor-by-faucet-service example-name.testnet autogenerate-new-keypair print-to-terminal network-config testnet create + export ACCOUNT_ID=example-name.testnet + near account create-account sponsor-by-faucet-service $ACCOUNT_ID autogenerate-new-keypair save-to-keychain network-config testnet create ``` replacing `example-name.testnet` with a unique account Id. @@ -60,7 +61,7 @@ On the [next page](./components.md), you'll see how to edit this agent for your What is a Phala Cloud -Phala Cloud is a service that offers secure and private hosting in a TEE using [Dstack](https://docs.phala.network/overview/phala-network/dstack). Phala Cloud makes it easy to run a TEE, that's why we use it in our template! +Phala Cloud is a cloud service that supports hosting applications in a TEE. It makes it easy to run an agent in TEE. @@ -154,13 +155,13 @@ You can interact with your agent via the APIs directly or via a lightweight fron For Phala deployments, swap localhost:3000 for your deployment URL. -- Get the Agent account Id and its balance: +- Get the Agent account ID and its balance: ``` http://localhost:3000/api/agent-account ``` -- Get the derived Ethereum Sepolia price pusher account Id and its balance (you will need to fund this account): +- Get the derived Ethereum Sepolia price pusher account ID and its balance (you will need to fund this account): ``` http://localhost:3000/api/eth-account @@ -184,4 +185,10 @@ npm run dev To use the frontend with your Phala deployment change the `API_URL` to Phala URL in your [config.js](https://github.com/NearDeFi/shade-agent-template/blob/main/frontend/src/config.js) file. - +--- + +## Next Steps + +Now that you've successfully deployed your first Shade Agent, proceed to the [key components page](./components.md) to understand how agents work and learn how to customize it for your specific use case. + + \ No newline at end of file diff --git a/docs/ai/shade-agents/security.md b/docs/ai/shade-agents/security.md index 958c2f5fe88..43b86452077 100644 --- a/docs/ai/shade-agents/security.md +++ b/docs/ai/shade-agents/security.md @@ -2,7 +2,7 @@ id: security title: Security Considerations sidebar_label: Security Considerations -description: This document outlines security considerations for deploying Shade Agents on the NEAR blockchain, including duplicate actions, transaction restrictions, and RPC trust. +description: "This document outlines security considerations for deploying Shade Agents on the NEAR blockchain, including duplicate actions, transaction restrictions, and RPC trust." --- import { SigsSupport } from '@site/src/components/sigsSupport'; diff --git a/website/sidebars.js b/website/sidebars.js index 6eede089db4..37cfe5efdd3 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -143,21 +143,32 @@ const sidebar = { 'ai/introduction', { "Shade Agents": [ + "ai/shade-agents/introduction", + "ai/shade-agents/examples", { - "Getting Started": [ + "Quickstart": [ 'ai/shade-agents/quickstart/deploying', - "ai/shade-agents/quickstart/components", + "ai/shade-agents/quickstart/components", ] }, { - "Concepts": [ - "ai/shade-agents/introduction", - "ai/shade-agents/examples", - "ai/shade-agents/custom-agent-contract", - "ai/shade-agents/security", - "ai/shade-agents/plugins", + "Framework": [ + "ai/shade-agents/framework/overview", + "ai/shade-agents/framework/api", + "ai/shade-agents/framework/cli", + "ai/shade-agents/framework/environment-variables", ], }, + { + "Custom Agent Contracts": [ + "ai/shade-agents/custom-contracts/overview", + "ai/shade-agents/custom-contracts/agent-guard-rails", + "ai/shade-agents/custom-contracts/near-agents", + "ai/shade-agents/custom-contracts/yield-for-agent", + ] + }, + "ai/shade-agents/plugins", + "ai/shade-agents/security", ] }, {