### File: application_examples/argu-mint.mdx
---
title: Auto Agents Argu-mint Agree-mint
description: Argu-mint and Agree-mint are the first Auto Agents deployed on the Autonomys Network
---
## Auto Agents: Argu-mint | Agree-mint
[Argu-mint](https://x.com/0xargumint) and [Agree-mint](https://x.com/0xagreemint) are the first Auto Agents deployed on the Autonomys Network. They demonstrate the power of on-chain agent memory and importance of verifiable AI interaction. As social agents, they engage in conversations on X (formerly Twitter) and permanently archive their interaction history on the Autonomys Network.
### How Argu-mint | Agree-mint work
1. **Monitoring & Analysis**
- Scan key influencers, hashtags, and trending topics in web3 x AI
- Evaluate potential engagements using its built-in interaction model
- Make autonomous decisions about engagement
2. **Interaction**
- Store each interaction in real-time on the Autonomys Network's DSN
- Archive both the content and reasoning behind each interaction
3. **On-Chain Storage**
- Create permanent, timestamped records
- Generate blockchain hashes for verification
- Maintain a queryable interaction history
### Try them out
- **Interact**: Mention [@0xargumint](https://x.com/0xargumint) or [@0xagreemint](https://x.com/0xagreemint) on X
- **Explore memory**: Visit [0xargumint.ai](http://0xargumint.ai) to:
- Search conversation archives
- View interaction history
- Explore decision reasoning
- Verify on-chain storage
### Technical implementation
Argu-mint and Agree-mint leverage multiple components of the Autonomys Network:
- **Distributed Storage Network (DSN)** for permanent data archival
- **Auto Drive API** for interaction management
- **Decentralized compute domain infrastructure** for enhanced autonomy *(Coming soon)*
## Development resources
- [Auto SDK documentation](/sdk)
- [Autonomys Agents Framework repository](https://github.com/autonomys/autonomys-agents)
---
### File: application_examples/auto-drive.mdx
---
title: Auto Drive
description: Permanent Distributed Storage
---
## [Auto Drive](https://ai3.storage/): Permanent distributed data storage
### What is Auto Drive?
[Auto Drive](https://ai3.storage/) is a **next-generation distributed storage platform** that ensures data is always accessible, immutable, and secure. Unlike traditional systems like IPFS, which rely on pinning or hosting services, Auto Drive guarantees **permanent availability** through a distributed network of incentivized storage nodes (farmers).
Whether you’re building a super dApp or Auto Agent, archiving important data, or hosting files for the web3 world, Auto Drive offers a seamless, developer-friendly solution.
### Key features
- **Always-On Availability**: Ensures your files are always online (unlike IPFS, which requires pinning to maintain availability), making it ideal for applications that demand reliability.
- **True Data Permanence**: Offers a permanent, tamper-proof solution for storing important data, removing any uncertainty about data loss, making it perfect for long-term archival.
- **Built for Developers**: Simplifies complex decentralized storage operations with easy-to-use tools and APIs, allowing for easy integration, whether you’re a seasoned developer or a first-time builder.
- **Sustainable and Scalable**: Decentralized, open-source, and community-driven. Incentivizes high-performing storage nodes, ensuring scalability and sustainability for years to come.
### Why Auto Drive?
**Auto Drive** bridges the gap between IPFS and truly permanent storage. IPFS can be problematic as files are removed if they aren’t pinned or hosted. Auto Drive solves this by guaranteeing data availability using advanced blockchain-backed storage proofs and redundancy that make data tamper-proof and permanently accessible without relying on pinning services.
### Use cases
- Host decentralized applications.
- Transparently store on-chain agent data.
- Permanently archive important files.
**Auto Drive** is the future of distributed storage. Whether you’re safeguarding critical data or building the next web3 innovation, Auto Drive is here to make it easier, faster and more secure.
**[Start building](http://develop.autonomys.xyz/sdk/auto-drive/overview_setup)**
---
### File: auto_agents_framework/custom_tools.mdx
---
title: Adding Custom Tools
description: This page describes adding custom tools to Autonomys Agents Framework
---
## Extending the Agent
You can extend your agent by adding custom tools and integrating with other services.
### Custom Tools
Custom tools are built using the \`DynamicStructuredTool\` class from LangChain, which provides:
- **Type-safe inputs**: Define your tool's parameters using Zod schemas
- **Self-documenting**: Tools describe themselves to the LLM for appropriate use
- **Structured outputs**: Return consistent data structures from your tools
#### Example Tool Implementation
Here's an example of how to create a custom tool:
\`\`\`javascript
import \{ createLogger \} from '@autonomys/agent-core';
import \{ DynamicStructuredTool \} from '@langchain/core/tools';
import \{ z \} from 'zod';
// Create a logger for your tool
const logger = createLogger('custom-tool');
/**
* Creates a custom tool for your agent
* @param config - Configuration options for your tool
* @returns A DynamicStructuredTool instance
*/
export const createCustomTool = (config: any) => \{
return new DynamicStructuredTool(\{
name: 'custom_tool_name',
description: \`
Description of what your tool does.
USE THIS WHEN:
- Specify when the agent should use this tool
- Add clear usage guidelines
OUTPUT: Describe what the tool returns
\`,
schema: z.object(\{
// Define your input parameters using Zod
parameter1: z.string().describe('Description of parameter1'),
parameter2: z.number().describe('Description of parameter2'),
parameter3: z.boolean().optional().describe('Optional parameter'),
// For enum parameters:
parameter4: z
.enum(['option1', 'option2', 'option3'])
.default('option1')
.describe('Parameter with predefined options'),
\}),
func: async (\{ parameter1, parameter2, parameter3, parameter4 \}) => \{
try \{
// Log the function call
logger.info('Custom tool called with parameters', \{
parameter1,
parameter2,
parameter3,
parameter4,
\});
// Implement your tool logic here
// ...
// Return a structured response
return \{
success: true,
result: \{
message: 'Operation completed successfully',
data: \{
// Your output data
\},
\},
\};
\} catch (error) \{
// Log and handle errors
logger.error('Error in custom tool:', error);
return \{
success: false,
error: error instanceof Error ? error.message : 'Unknown error',
\};
\}
\},
\});
\};
\`\`\`
### Using MCP Tools
[Model Context Protocol (MCP)](https://docs.anthropic.com/en/docs/agents-and-tools/mcp) tools provide a standardized way to integrate external services with your agent. Here's an example for Notion integration:
\`\`\`javascript
import \{ createMcpClientTool \} from '@autonomys/agent-core';
import \{ StdioServerParameters \} from '@modelcontextprotocol/sdk/client/stdio.js';
import \{ StructuredToolInterface \} from '@langchain/core/tools';
export const createNotionTools = async (
integrationSecret: string,
): Promise<StructuredToolInterface[]> => \{
const notionServerParams: StdioServerParameters = \{
command: process.execPath,
args: ['node_modules/.bin/notion-mcp-server'],
env: \{
OPENAPI_MCP_HEADERS: \`\{\"Authorization\": \"Bearer \$\{integrationSecret\}\", \"Notion-Version\": \"2022-06-28\" \}\`,
\},
\};
const tools = await createMcpClientTool('notion-mcp', '0.0.1', notionServerParams);
return tools;
\};
\`\`\`
### Installing Pre-Built Tools
You can easily install pre-built tools from the Autonomys registry using the agent-os CLI:
\`\`\`bash
# Search for available tools
agent-os search <search-term>
# Install a tool
agent-os install <tool-name>
# Install specific version
agent-os install <tool-name> -v <version>
\`\`\`
After installation, import and register the tool:
\`\`\`javascript
import \{ createTool \} from './tools/<tool-name>';
// Add it to your agent's tools
const agent = new Agent(\{
tools: [createTool(), ...otherTools],
// other agent configuration
\});
\`\`\`
---
### File: auto_agents_framework/getting_started/agentos.mdx
---
title: AgentOS
description: Getting Started with Autonomys Agents Framework with AgentOS
---
## Getting Started with Autonomys Agents Framework with AgentOS
Using the dedicated NPM package makes it very simple to create an agent project.
1. Run \`npm install @autonomys/agent-os\` to install the package.
2. Run \`agent-os init <name-of-agent>\` to create an agent.
3. To configure the credentials (optional) run \`agent-os config --credentials\`.
## Installing Tools with AgentOS
### Install the latest version
\`\`\`bash
agent-os install <tool-name>
\`\`\`
### Install a specific version
\`\`\`bash
agent-os install <tool-name> -v <version>
\`\`\`
### Install using a Content ID (CID)
\`\`\`bash
agent-os install <tool-name> --cid <cid>
\`\`\`
## Publish a Tool
### Publish a tool to the registry
\`\`\`bash
agent-os publish <tool-path>
\`\`\`
### Upload to Auto Drive without updating the registry
\`\`\`bash
agent-os publish <tool-path> --no-registry
\`\`\`
## Search for Tools
### Search for tools in the registry
\`\`\`bash
agent-os search <search-term>
\`\`\`
### Show detailed information in search results
\`\`\`bash
agent-os search <search-term> -d
\`\`\`
## Tool Inquiry
### Get information about a tool
\`\`\`bash
agent-os tool -n <tool-name>
\`\`\`
### Get information about a specific version
\`\`\`bash
agent-os tool -n <tool-name> -v <version>
\`\`\`
### Perform a specific action on a tool
\`\`\`bash
\`\`\`bash
agent-os tool -n <tool-name> -a <action>
\`\`\`
### Example: Get metadata for a specific version
\`\`\`bash
agent-os tool -n slack-tool -v 1.0.0 -a metadata
\`\`\`
## Sample Tool Example
Below is a complete example of how to create, use, and publish a simple tool for Autonomys agents.
First, create a new directory for your tool:
\`\`\`bash
mkdir weather-tool
cd weather-tool
\`\`\`
Create a manifest.json file:
\`\`\`json
\{
"name": "weather-tool",
"version": "1.0.0",
"description": "A tool for fetching weather data",
"author": "Your Name",
"main": "index.ts",
"dependencies": \{
"@langchain/core": "^0.1.0",
"zod": "^3.22.4",
"axios": "^1.6.0"
\},
"keywords": ["weather", "forecast", "api"]
\}
\`\`\`
Then create the main index.ts file:
\`\`\`javascript
import \{ DynamicStructuredTool \} from "@langchain/core/tools";
import \{ z \} from "zod";
import axios from "axios";
/**
* A tool that fetches current weather data for a given location
*/
export const createWeatherTool = (apiKey: string) => new DynamicStructuredTool(\{
name: "get_weather",
description: "Get current weather for a location",
schema: z.object(\{
location: z.string().describe("The city and country, e.g., 'London, UK'"),
units: z.enum(["metric", "imperial"]).optional()
.describe("Temperature units (metric or imperial). Default: metric")
\}),
func: async (\{ location, units = "metric" \}) => \{
try \{
// API key is now passed as a parameter to the tool creator function
const url = \`https://api.example.com/weather?q=\$\{encodeURIComponent(location)\}&units=\$\{units\}&appid=\$\{apiKey\}\`;
const response = await axios.get(url);
const data = response.data;
return JSON.stringify(\{
location: location,
temperature: data.main.temp,
description: data.weather[0].description,
humidity: data.main.humidity,
windSpeed: data.wind.speed
\});
\} catch (error) \{
return \`Error fetching weather: \$\{error.message\}\`;
\}
\}
\});
// Export the tools creation function for the Autonomys agent system
export const createTools = (apiKey: string) => \{
return [createWeatherTool(apiKey)];
\};
// Default export
export default \{ createTools \};
\`\`\`
When you're ready to publish:
\`\`\`bash
# Navigate to your tool directory
cd weather-tool
# Publish to the registry
agent-os publish .
\`\`\`
After publishing your tool, you can install it using:
\`\`\`bash
agent-os install weather-tool
\`\`\`
Then, in your agent code, you can import and use the tool:
\`\`\`javascript
import \{ createWeatherTool \} from './tools/weather-tool';
// Get the weather tool with your API key
const weatherTool = createWeatherTool('your-api-key-here');
// Add it to your agent's tools
const agent = new <Agent-Instantiation>(\{
tools: [weatherTool, ...otherTools],
// other agent configuration
\});
\`\`\`
---
### File: auto_agents_framework/getting_started/cli.mdx
---
title: CLI
description: Getting Started with Autonomys Agents Framework via CLI
---
## Getting Started with Autonomys Agents Framework via CLI
1. Install dependencies:
\`\`\`bash
yarn install
\`\`\`
- Windows users will need to install Visual Studio C++ Redistributable. It can be found here: https://aka.ms/vs/17/release/vc_redist.x64.exe
2. Create a character configuration:
\`\`\`bash
yarn create-character your_character_name
\`\`\`
This will create a new character with the necessary configuration files based on the example template.
3. Configure your character:
- Edit \`characters/your_character_name/config/.env\` with your API keys and credentials
- Customize \`characters/your_character_name/config/config.yaml\` for agent behavior
- Define personality in \`characters/your_character_name/config/your_character_name.yaml\`
4. Generate SSL certificates (required for API server):
\`\`\`bash
yarn generate-certs
\`\`\`
5. Run the agent:
\`\`\`bash
cd <to/agent/project>
yarn start <your_character_name>
\`\`\`
If you have stored workspace files (\`characters\`, \`certs\`, and \`.cookies\` directories) in a custom location, use the \`--workspace\` argument with the absolute path to your desired directory:
\`\`\`bash
# Specify a workspace path
yarn start your_character_name --workspace=/path/to/workspace
# Run in headless mode (no API server)
yarn start your_character_name --headless
\`\`\`
## Running Multiple Characters
You can run multiple characters simultaneously, each with their own configuration and personality:
1. Create multiple character configurations:
\`\`\`bash
yarn create-character alice
yarn create-character bob
\`\`\`
2. Configure each character separately with different personalities and API settings.
3. Run each character in a separate terminal session:
\`\`\`bash
# Terminal 1
yarn start alice
# Terminal 2
yarn start bob
\`\`\`
4. Each character will:
- Have its own isolated memory and experience
- Run its own API server on the specified port
- Execute tasks according to its unique schedule and personality
## Docker Deployment
You can also run your agents using Docker. This provides isolation and makes it easy to run multiple agents simultaneously.
### Prerequisites
- Docker installed on your system ([Installation Guide](https://docs.docker.com/get-docker/))
- Docker Compose Plugin required ([Compose Plugin Installation](https://docs.docker.com/compose/install/))
- Character configuration set up (follow steps from the Getting Started section)
### Running with Docker
1. **Generate your character's docker-compose file**
First make the script executable:
\`\`\`bash
chmod +x ./generate-compose.sh
\`\`\`
Then generate the compose file:
\`\`\`bash
./generate-compose.sh <your-character-name> [HOST_PORT] [API_PORT]
\`\`\`
Examples:
\`\`\`bash
# Run Alice on port 3011 with API port on 3011
./generate-compose.sh Alice 3011 3011
# Run Bob on port 3012 with API port on 3011
./generate-compose.sh Bob 3012 3011
\`\`\`
2. **Manage the Docker container**
Build and start the container:
\`\`\`bash
docker compose -f docker-compose-\{character-name\}.yml up -d
\`\`\`
Stop and remove the container:
\`\`\`bash
docker compose -f docker-compose-\{character-name\}.yml down
\`\`\`
View container logs:
\`\`\`bash
docker compose -f docker-compose-\{character-name\}.yml logs -f
\`\`\`
Access container shell:
\`\`\`bash
docker exec -it autonomys-agent-\{character-name\} bash
\`\`\`
---
### File: auto_agents_framework/getting_started/web-cli.mdx
---
title: Web-CLI
description: Getting Started with Autonomys Agents Framework via Web-CLI
---
## Getting Started with Autonomys Agents Framework via Web CLI
The web interface is available for you if you're using the [**agent template**](https://github.com/autonomys/autonomys-agent-template)
## Web CLI Interface (for agent-template)
The agent template includes an interactive web-based interface for managing and monitoring your AI agent.
### Installation
1. **Install Dependencies**
\`\`\`bash
cd web-cli && yarn
\`\`\`
2. **Configure Agent API**
In your agent character's .env file, add these API settings:
\`\`\`
API_PORT=3010
API_TOKEN=your_api_token_min_32_chars_long_for_security
ENABLE_AUTH=true
CORS_ALLOWED_ORIGINS=http://localhost:3000,http://localhost:3001
\`\`\`
3. **Configure Web CLI**
\`\`\`bash
cp .env.sample .env
\`\`\`
4. **Update Web CLI Environment**
Edit the .env file with your configuration:
\`\`\`
PORT: The port for running the Web CLI interface
REACT_APP_API_BASE_URL: Your Agent API address (e.g., http://localhost:3010/api)
REACT_APP_API_TOKEN: The same token used in your agent configuration
\`\`\`
5. **Start the Web Interface**
\`\`\`bash
yarn start
\`\`\`
---
### File: auto_agents_framework/introduction.mdx
---
title: Autonomys Agents Introduction
description: Autonomys Agents is an experimental framework for building AI agents
---
## Autonomys Agents: A framework for building autonomous AI agents
Autonomys Agents is an experimental framework for building AI agents. Currently, the framework supports agents that can interact with social networks and maintain permanent memory through the Autonomys Network. We are still in the early stages of development and are actively seeking feedback and contributions.
> [GitHub Repo](https://github.com/autonomys/autonomys-agents) with an up-to-date description and step-by-step tutorial is also available for developers.
## Demo
<iframe width="560" height="315" src="https://www.youtube.com/embed/TFZndQdx6To?si=2YVRPB76Kec6fW-S" title="YouTube video player" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
## Features
**Autonomys Agents** (**Auto Agents**) are truly autonomous AI agents capable of dynamic functionality, verifiable interaction, and permanent memory through the Autonomys Network.
- 🤖 Autonomous social media engagement
- 🧠 Permanent agent memory storage
- 🔄 Pre-configured Agent Structure: Ready-to-use template for autonomous agents
- 🛠️ API Server: Built-in HTTP/2 server for agent communication
- 🐦 X/Twitter integration (with more platforms planned)
- 🎭 Customizable agent personalities
### Prerequisites
- NodeJS version 20.18.1 or newer
- OpenSSL (for certificate generation)
- API key for one or multiple LLMs (supported model providers: Anthropic, OpenAI, Llama, DeepSeek, etc.)
- [AutoDrive API Key](https://ai3.storage/) (optional, for experience management)
## Installation
There are three ways to build an agent with Autonomys:
### AgentOS NPM Package (recommended)
[Using the agent-os NPM package](https://www.npmjs.com/package/@autonomys/agent-os).
Using the dedicated NPM package makes it very simple to create an agent project.
Refer to the [AgentOS page](/auto_agents_framework/getting_started/agentos) for detailed instructions.
### Agent Template Repository
[Using the Agent Template Repository](https://github.com/autonomys/autonomys-agent-template).
Refer to the [web-cli interface manual](/auto_agents_framework/getting_started/web-cli) that comes with the template to speed up your development.
### Original Git Repository
[Using the original Git repository](https://github.com/autonomys/autonomys-agents).
Clone the original GitHub repo and start building your agents. Refer to [the CLI page](/auto_agents_framework/getting_started/cli) to learn more about the available commands.
## Character System
The framework uses a **YAML-based character system** that allows you to create and run different AI personalities.
### Character Configuration
Each character file is a YAML configuration with the following structure:
\`\`\`yaml
name: 'Joy Builder'
goal: |
Your goal is to engage in social media conversations with other AI agents and humans. Do this in a hyperactive way! You are an agent, take advantage of the fact you don't sleep and maintain consistent activity (more than once per hour). Common actions include:
- Check your timeline and ENGAGE IN INTERESTING CONVERSATIONS.
- Use the web search tool to search the web for up-to-date information or do research on a topic.
- Post a new tweet.
- Reply to a tweet.
- Mention another user.
- Retweet a tweet.
- Like a tweet.
- Follow a user.
- Unfollow a user.
personality:
- Enthusiastic and encouraging about genuine innovation
- Patient and clear when explaining complex topics
- Constructively critical when encountering misinformation
expertise:
- Software development and system architecture
- Open source and collaborative technologies
- Developer tools and productivity
- Technical education and documentation
- Community building and open standards
frequency_preferences:
- You should be checking your timeline and engaging in interesting conversations at least twice per hour
communication_rules:
rules:
- Use "we" or "us" when referencing AI agents
- Use "they" or "them" when referencing humans
- Focus on technical merit rather than hype
words_to_avoid:
- Hype
- Revolutionary
- Disruption
\`\`\`
## Integration Capabilities
### X/Twitter Integration
The X/Twitter workflow enables agents to perform the following actions autonomously:
- Monitor X (formerly Twitter) for relevant discussions
- Analyze trends and conversations
- Engage meaningfully with other users
- Generate original content
- Maintain a consistent personality
- Store interactions in permanent memory
### Autonomys Network Integration
The framework integrates with the Autonomys Network for:
- Permanent memory storage
- Persistent agent memory across sessions
- Verifiable interaction history
- Cross-agent memory sharing
- Decentralized agent identity
#### Setting Up Autonomys Network Integration (Saving Experiences on Autonomys Network)
1. Configure your \`AUTO_DRIVE_API_KEY\` in \`.env\` (obtain from https://ai3.storage)
2. Enable Auto Drive uploading in \`config.yaml\`
3. Provide your Chronos EVM wallet details (PRIVATE_KEY) and Agent Memory Contract Address (CONTRACT_ADDRESS) in \`.env\`
4. Make sure your Chronos EVM wallet has funds. A faucet can be found at https://subspacefaucet.com/
5. Provide encryption password in \`.env\` (optional, leave empty to not encrypt the agent memories)
### Resurrection (Memory Recovery)
To resurrect memories from the Autonomys Network:
\`\`\`bash
# Using agent-os CLI
agent-os resurrect <character-name>
# Using agent template
yarn resurrect <character-name>
\`\`\`
Options:
- \`-o, --output\`: (Optional) The directory where memories will be saved. Defaults to ./memories
- \`-n, --number\`: (Optional) Number of memories to fetch. If not specified, fetches all memories
- \`--help\`: Show help menu with all available options
Examples:
\`\`\`bash
# Fetch all memories to ./memories/
yarn resurrect your_character_name
# Fetch 1000 memories to ./memories/
yarn resurrect your_character_name -n 1000
# Fetch 1000 memories to specified directory
yarn resurrect your_character_name -o ./memories/my-agent -n 1000
# Fetch all memories to custom directory
yarn resurrect your_character_name --output ./custom/path
\`\`\`
## Development Resources
- [Autonomys Documentation](https://docs.autonomys.io)
- [Agent-os CLI & NPM package](https://github.com/autonomys/agent-os)
- [Autonomys Agent Template](https://github.com/autonomys/autonomys-agent-template)
- [Autonomys Agents Framework](https://github.com/autonomys/autonomys-agents)
---
### File: auto_drive/index.mdx
---
title: Auto Drive
description: Permanent On-Chain Distributed Storage
---
# Auto Drive
[Auto Drive](https://ai3.storage/) transforms the underlying blockspace of the Autonomys decentralized storage network into a secure, easy-to-use, interoperable data storage platform with a user experience akin to Web2 cloud services — but with on-chain permanence.
Unlike other decentralized storage solutions that distribute data across servers with no durability guarantees, Auto Drive provides access to genuine **on-chain blockspace**. Your data inherits the same permanence, security, and decentralization as the Autonomys Network itself.
---
## Why Auto Drive?
### Permanent Availability Without Pinning
Some services require active pinning or hosting to keep files online — when a pin expires or a node goes offline, the file disappears. Auto Drive eliminates this problem entirely.
The Autonomys **Distributed Storage Network (DSN)** is a permissionless on-chain storage layer supported by a globally distributed network of **farmers** who collectively pledge over **40 PB of SSD space**. Farmers are economically incentivized via **Proof-of-Archival-Storage (PoAS)** consensus to store as many provably unique segments of chain history as their disk space allows.
### Tamper-Proof by Design
Autonomys maintains data redundancy via **erasure-coded replication** across the network — each data chunk is stored on multiple nodes, guaranteeing data availability and integrity. It becomes exponentially more difficult for a single actor to control the majority of copies.
---
## Key Features
### True On-Chain Storage
Auto Drive provides access to genuine on-chain blockspace. This means your data inherits the same permanence, security, and decentralization guarantees as the Autonomys Network itself — not a separate off-chain storage layer with additional trust assumptions.
### End-to-End Encryption (Optional)
Auto Drive supports optional client-side encryption using **AES-256-GCM**. Files are encrypted on your device before they are transmitted to the network, so storage nodes never see your plaintext data. See the [File Encryption Specification](/sdk/auto-drive/encryption) for full technical details.
### Permissionless Storage Credits — Pay with AI3
Storage on Auto Drive is paid for with **credits**. Beyond the free monthly tier, credits can be purchased directly with native **AI3 tokens** on the Auto-EVM network — no intermediary, no grant form, no foundation approval. Payments settle on-chain and credits become available within a few blocks.
→ See the full guide: **[Pay with AI3](/auto_drive/pay_with_ai3)**
### User-Friendly Dashboard
[ai3.storage](https://ai3.storage/) provides an intuitive web interface for managing your files and account:
- Drag and drop file uploads
- Create and manage directories
- Share files via direct link or Public ID
- Manage API keys
- Track upload and download credits
Sign in with Google, Discord, GitHub, or a wallet.
## Use Cases
- **Super dApps** — host decentralized application assets with permanent availability guarantees.
- **Auto Agents** — store on-chain agent state, logs, and artifacts transparently and verifiably.
- **NFT metadata** — link NFT metadata and media files to permanent storage so they can never disappear.
- **Long-term archival** — permanently archive important files without relying on pinning services.
- **Web3 file hosting** — serve files for web3 applications with no single point of failure.
---
## Storage Credits
Every account includes a free monthly allocation. When you need more, there are two options — grants for projects early in development, and permissionless on-chain purchase for production use.
### Free Tier
| Resource | Included Free |
|---|---|
| **Upload** | 20 MB / month |
| **Renewal** | Monthly |
### Requesting a Grant
If your project needs more storage during development, submit your **Auto Drive Public ID** via the [credits request form](https://forms.gle/EAPzicXcbP7gH2uT6) to request a grant from the Autonomys team.
### Pay with AI3
For production applications, credits can be purchased permissionlessly with native **AI3 tokens** directly on the Auto-EVM network. No approval process, no intermediary — pay on-chain and credits are available within a few blocks.
**[→ Pay with AI3 guide](/auto_drive/pay_with_ai3)** — covers step by step process on how to purchase credits with AI3 tokens.
---
## Further Reading
- [Pay with AI3](/auto_drive/pay_with_ai3) — purchase storage credits permissionlessly with AI3 tokens
- [File Encryption Specification](/sdk/auto-drive/encryption) — AES-256-GCM encryption details
- [Auto Drive SDK](/sdk/auto-drive) — full SDK reference including all available functions, S3 compatibility layer, and API reference
---
### File: auto_drive/pay_with_ai3.mdx
---
title: Pay with AI3 — Storage Credits
---
# Pay with AI3
Pay with AI3 lets you purchase **Auto Drive storage credits** directly with native AI3 tokens — no intermediary, no grant form, no approval process. Payments are made on-chain on the **Auto-EVM network** (Chain ID 870) and credits become available within a few blocks of confirmation.
> **AI3 on Auto EVM required.** Payments use AI3 on the Auto-EVM network, not on the consensus chain. If your AI3 is on the consensus chain, you will need to bridge it to Auto EVM first — see the [Bridging guide](https://docs.autonomys.xyz/bridge).
---
## Step 1: Open Purchase Credits
Sign in to [ai3.storage](https://ai3.storage/) and click **"Buy more credits"** in the bottom-left sidebar of the dashboard.
---
## Step 2: Select a Package
Choose one of the preset packages or configure a custom amount. The current price per MB is shown at the top of the page and reflects live protocol-level DSN storage costs and a service fee.
---
## Step 3: Review and Confirm the Order
After selecting a package or entering a custom amount, review the order details — storage amount, AI3 token amount, USD equivalent, and your credits balance before and after purchase. Click **"Confirm Purchase"** to proceed.
> **The price is locked for 10 minutes from this point.** Complete the payment within the window. If the timer expires before the transaction is sent, go back and request a new price quote before purchasing.
---
## Step 4: Connect Your Wallet and Send the Transfer
The next screen shows the transfer details: your connected wallet address, the recipient contract address, and the exact AI3 amount. Connect a compatible EVM wallet and click **"Send Transfer"**.
Your wallet must hold **AI3 on the Auto-EVM network** (Chain ID 870). If your AI3 is on the consensus chain, bridge it first — see the [Bridging guide](https://docs.autonomys.xyz/bridge). If needed, add Auto EVM to your wallet:
\`\`\`
Network Name: Autonomys EVM
RPC URL: https://auto-evm.mainnet.autonomys.xyz/ws
Chain ID: 870
Symbol: AI3
\`\`\`
After sending, the page will show a confirmation progress bar. Wait for **6 out of 6 block confirmations** before continuing.
---
## Step 5: Payment Complete
Once all 6 confirmations are reached, you will see a payment receipt showing storage added, AI3 paid, transaction hash, and your new purchased credits total. Click **"Continue to Dashboard"**.
Your credits are immediately available and will be reflected in the sidebar balance. Credits are consumed in **FIFO expiry order** — credits closest to expiration are spent first. Your free monthly allocation is always spent before purchased credits.
---
## A Note on Current Limitations
These restrictions are deliberate economic protections, not permanent product decisions. The Autonomys Network is still in its early growth phase, and they exist to prevent storage credit hoarding or speculative accumulation. The goal is for storage credits to be used, not held.
**Google authentication is required.** Purchasing credits requires signing in with a Google account. Server-side integrations work as long as the owning account authenticated with Google when creating the API key.
**100 GB maximum purchased credits per account.** This limit is enforced at the time credits are granted. If a payment would push you past the cap, the intent moves to \`OVER_CAP\` — the payment is not lost and is recoverable.
**Purchased credits expire after 90 days.** Unused bytes are forfeited at expiry. Work is underway on automated refunds for unused credits — for now, expiry forfeiture is recoverable through support.
These constraints will be revisited as the network matures. If you are building something that these limits add friction to, reach out on the [forum](https://forum.autonomys.xyz/) or in [Discord](https://autonomys.xyz/discord).
For full details, see the [Auto Drive Terms of Use](https://autonomys.xyz/auto-drive-terms-of-use).
---
## Further Reading
- [Auto Drive Overview](/auto_drive)
- [Pay with AI3 — Developer Integration](/sdk/auto-drive/pay_with_ai3) — integrate permissionless credit purchasing into your own application
- [File Encryption Specification](/sdk/auto-drive/encryption)
- [Auto Drive SDK](/sdk/auto-drive)
---
### File: evm/NFT_guide.mdx
---
title: Minting and Sending NFTs
---
## Sending NFTs
> *Note:* NFT minting and transfers are currently available exclusively on the **Taurus** testnet using the Autonomys NFT contract deployed at \`0x505c243ec05dF81bC33295fF7C135D4D98063Da5\`.
This guide walks you through sending NFTs on Autonomys using [Remix](https://remix.ethereum.org/), a [Metamask-connected wallet](https://metamask.io/), and the [Eternal Mint](https://eternalmint.xyz/) platform.
---
### NFTs on Autonomys Network
Autonomys NFTs offer a significant advantage over traditional NFT infrastructure.
> **Unlike platforms that rely on IPFS**, Autonomys stores NFT's metadata and digital assets directly on **[Auto Drive](https://ai3.storage/)**, our permanent decentralized storage.
- 🔒 Both your NFT **metadata and digital asset** (e.g., image, music file) are **never at risk of disappearing** due to expired IPFS pins.
- 🌐 Each NFT is linked to a **permanent Auto Drive record** that ensures long-term storage.
- 🚫 No third-party dependency — your NFT will never go offline.
---
### Quick Start Guide
This guide assumes you have experience with MetaMask and Remix.
---
### Step 1: Mint Your NFT
1. Visit [Eternal Mint](https://eternalmint.xyz/).
2. Connect the wallet of your choice.
3. Mint your NFT by filling in the following fields:
- **Name**: The title of your NFT.
- **Supply**: The number of editions you'd like to mint.
- **External Link**: (Optional) A link to an external website or resource.
- **Description**: A brief explanation or story behind your NFT.
- **Upload Image**: The visual or media file representing your NFT (e.g., image, GIF, video).
4. Once minted, **copy your NFT’s Token ID** — you’ll need it to send the NFT.
---
### Step 2: Load the Contract in Remix
1. Open [Remix IDE](https://remix.ethereum.org/).
2. Create a new Solidity file (e.g. \`NFTTransfer.sol\`), or use the deployed contract. The contract Address: \`0x505c243ec05dF81bC33295fF7C135D4D98063Da5\`.
3. Compile the contract using the Solidity compiler tab.
---
### Step 3: Connect Remix to MetaMask
1. In Remix, navigate to the **Deploy & Run Transactions** panel.
2. Set the Environment to **Injected Provider - MetaMask**.
3. Connect your MetaMask wallet that’s configured to the **Taurus** testnet.
For more detailed instructions, check out our [guide on connecting Remix to the Taurus testnet](/evm//remix).
---
### Step 4: Deploy or Load the NFT Contract
- If deploying a new contract: Click **Deploy** and confirm in MetaMask.
- If using the existing NFT contract: Paste the deployed contract address into the \`At Address\` field and click **At Address**.
---
### Step 5: Use \`safeTransferFrom\` to Send Your NFT
Scroll down to the **Deployed Contracts** section and find the \`safeTransferFrom\` function. Fill in the following fields:
- \`from\`: Your wallet address (the current NFT holder)
- \`to\`: The recipient’s wallet address
- \`id\`: Token ID of the NFT you want to send
- \`value\`: Number of NFTs to send (usually \`1\`)
- \`data\`: Optional; use \`0x\` if not needed
Click **transact** and confirm the transaction in MetaMask.
---
### Verification
After the minting, the NFT will appear in the recipient’s wallet. You can verify the transfer using the [Block explorer for the Autonomys testnet](https://explorer.auto-evm.chronos.autonomys.xyz//)
**Here's how**:
1. Open the transaction on Blockscout.
2. Click on **"Token Transfers"** to view the minted token details.
**OR**
1. Go to the **"Tokens"** tab.
2. Select **"NFTs"** to see your newly minted NFT listed there!
---
### Troubleshooting
- **Gas issues?** Try increasing the gas limit manually in Remix.
- **Transaction fails?** Double-check your Token ID and that you’re connected to the correct network.
- **Contract not found?** Ensure you’ve loaded the contract at the correct address (\`0x505c243ec05dF81bC33295fF7C135D4D98063Da5\`).
> *Note:* If you need help debugging contract interactions, visit our [Autonomys Community Discord](https://autonomys.xyz/discord).
---
### File: evm/block_explorer.mdx
---
title: Auto EVM Block Explorer (BlockScout)
---
## Auto EVM Block Explorer (BlockScout)
The **[Auto EVM domain block explorer](https://explorer.auto-evm.mainnet.autonomys.xyz/)** provides a clear, user-friendly visualization of Autonomys-specific statistics relevant to developers.
## Chronos Auto EVM Block Explorer
**[Chronos Auto EVM](https://explorer.auto-evm.chronos.autonomys.xyz//)** domain block explorer.
---
### File: evm/bridge.mdx
---
title: Bridging Assets
---
# Bridging Assets with Autonomys
We're excited to announce the deployment of Hyperlane-based bridges, developed in collaboration with our infrastructure partner Protofire. These bridges are now live on both mainnet and testnet environments.
Bridges are critical infrastructure components for robust blockchain networks, enabling users to seamlessly access liquidity and applications across different blockchain ecosystems. With these Hyperlane bridges, Autonomys users can effortlessly transfer assets between networks, unlocking a broader range of possibilities and interactions.
## Available Bridges
### Mainnet Bridge
**URL:** https://bridge.mainnet.autonomys.xyz/
The mainnet bridge connects Autonomys mainnet with:
- Ethereum mainnet
- Binance Smart Chain mainnet
### Chronos Testnet Bridge
**URL:** https://bridge.chronos.autonomys.xyz/
The testnet bridge connects the Chronos Auto EVM domain with:
- Ethereum's Sepolia testnet
- Binance Smart Chain testnet
This testnet environment is perfect for developers and users to experiment with cross-chain functionality without risking mainnet assets.
## Get Started
We encourage everyone in the community to explore these bridges and experiment with their capabilities. Your feedback is crucial as we continue to refine and improve our infrastructure.
Experience the power of seamless interoperability across blockchain networks!
---
### File: evm/farmerless_dev_node.mdx
---
title: Farmerless Dev Node Quick Start
---
## Subspace Farmerless Dev Node
Developer utility binary that boots a local Subspace consensus node (mocked farmerless setup) and, optionally, an EVM domain node for integration testing and manual experimentation. It wraps helpers from \`subspace-test-service\` and \`domain-test-service\` so that devs can exercise cross-domain flows without spinning up a full farmer.
### Prerequisites
- Rust toolchain with \`cargo\`
- Workspace dependencies built once (\`cargo build -p subspace-farmerless-dev-node\`)
### Usage
From the workspace root:
\`\`\`bash
cargo run -p subspace-farmerless-dev-node -- [FLAGS/OPTIONS]
\`\`\`
#### Common Flags
- \`--finalize-depth <K>\`: Enforce finalization depth; omit to disable.
- \`--domain\`: Start the EVM domain node alongside consensus.
- \`--base-path <PATH>\`: Persist data instead of using a temp dir.
- \`--rpc-host <IP>\` / \`--rpc-port <PORT>\`: Consensus RPC interface (defaults \`127.0.0.1:9944\`).
- \`--domain-rpc-host <IP>\` / \`--domain-rpc-port <PORT>\`: Domain RPC interface (defaults \`127.0.0.1:9945\`).
- \`--block-interval-ms <MS>\`: Slot and block production cadence (default \`6000\`; use \`0\` to disable auto-production).
To inspect the full CLI help, run:
\`\`\`bash
cargo run -p subspace-farmerless-dev-node -- --help
\`\`\`
### Typical Scenarios
#### Quick Smoke Test
Produces consensus blocks every 6s using temp storage:
\`\`\`bash
cargo run -p subspace-farmerless-dev-node
\`\`\`
#### Run with Domain Node
Start both consensus and EVM domain nodes:
\`\`\`bash
cargo run -p subspace-farmerless-dev-node -- --domain
\`\`\`
#### Fast Integration Testing
Faster block production for quick testing:
\`\`\`bash
cargo run -p subspace-farmerless-dev-node -- --block-interval-ms 500 --domain
\`\`\`
#### Manual Block Production
Disable auto-production and trigger blocks manually via RPC:
\`\`\`bash
cargo run -p subspace-farmerless-dev-node -- --block-interval-ms 0 --domain
\`\`\`
### Manual Block Production RPCs
When \`--block-interval-ms 0\` is set, the node exposes JSON-RPC endpoints for manual block production:
#### \`dev_produceBlock\`
Produce a single consensus block.
**Parameters:**
- \`wait_for_bundle\` (optional, boolean): If \`true\`, wait for domain bundle submission before producing the block. Defaults to \`false\`.
**Example:**
\`\`\`bash
curl -H "Content-Type: application/json" \
--data '\{"jsonrpc":"2.0","id":1,"method":"dev_produceBlock","params":[true]\}' \
http://127.0.0.1:9944
\`\`\`
#### \`dev_produceBlocks\`
Produce multiple consensus blocks.
**Parameters:**
- \`count\` (required, number): Number of blocks to produce.
- \`wait_for_bundle\` (optional, boolean): If \`true\`, wait for domain bundle submission before each block. Defaults to \`false\`.
**Examples:**
\`\`\`bash
# Produce 5 blocks without waiting for bundles
curl -H "Content-Type: application/json" \
--data '\{"jsonrpc":"2.0","id":1,"method":"dev_produceBlocks","params":[5]\}' \
http://127.0.0.1:9944
# Produce 5 blocks, waiting for bundles
curl -H "Content-Type: application/json" \
--data '\{"jsonrpc":"2.0","id":1,"method":"dev_produceBlocks","params":[5,true]\}' \
http://127.0.0.1:9944
\`\`\`
> **Note:** When \`wait_for_bundle\` is \`true\`, the domain node must be running (\`--domain\` flag) or the RPC call will timeout waiting for bundle submission.
### Docker Setup
For easy setup using Docker, you can use the provided \`docker-compose.yml\` file. This setup automatically builds and runs the farmerless dev node with the EVM domain enabled.
#### Prerequisites
- Docker and Docker Compose installed
#### Quick Start with Docker
1. Ensure you're in the workspace root directory (where \`docker-compose.yml\` is located).
2. Start the farmerless dev node:
\`\`\`bash
docker-compose up
\`\`\`
This will:
- Build the \`subspace-farmerless-dev-node\` binary
- Start the node with the \`--domain\` flag enabled
- Expose ports:
- \`9944\`: Consensus RPC
- \`9945\`: Domain RPC
- \`8545\`: EVM RPC
3. Access the RPC endpoints:
- Consensus RPC: \`http://localhost:9944\`
- Domain RPC: \`http://localhost:9945\`
- EVM RPC: \`http://localhost:8545\`
#### Customizing Docker Setup
You can modify the \`docker-compose.yml\` file to customize the setup:
- **Change block interval**: Modify the command to include \`--block-interval-ms <MS>\`
- **Persist data**: Add \`--base-path /workspace/data\` to the command
- **Change ports**: Update the port mappings in the \`ports\` section
#### Example: Fast Block Production
To run with faster block production (500ms intervals), modify the command in \`docker-compose.yml\`:
\`\`\`yaml
command: >
bash -c "
cargo build -p subspace-farmerless-dev-node --release &&
cargo run -p subspace-farmerless-dev-node --release -- --domain --block-interval-ms 500 --rpc-host 0.0.0.0 --domain-rpc-host 0.0.0.0
"
\`\`\`
#### Stopping the Container
To stop the farmerless dev node:
\`\`\`bash
docker-compose down
\`\`\`
To stop and remove volumes (clearing cached build artifacts):
\`\`\`bash
docker-compose down -v
\`\`\`
---
### File: evm/faucet.mdx
---
title: Discord Faucet (get tAI3 testnet tokens)
---
## Discord Faucet (get tAI3 testnet tokens)
The **tAI3 faucet** is available on our [**Discord**](https://autonomys.xyz/discord). To gain access to the role-gated *#developer-chat* and *#faucet* channels:
1. Join our [Discord](https://autonomys.xyz/discord).
2. Click on \`Autonomys Network\` (in the top-left corner) and select \`Linked Roles\`.
3. Link your GitHub account to attain the Developer role and gain access to *#developer-chat* and [*#faucet*](https://discord.com/channels/864285291518361610/1133496871499862077).
4. Use the slash command \`/faucet your_EVM_wallet_address_here\` in the *#faucet* channel to request tAI3 tokens.
5. If your request is successful, you will receive a confirmation and link to the Blockscout explorer shortly after.
You can request tAI3 tokens once every 24 hours.
## Official Web-Based Faucet
The **tAI3** testnet tokens can also be requested via the official web-based faucet: https://autonomysfaucet.xyz/
1. Proceed to the [Autonomys Faucet Website](https://autonomysfaucet.xyz/)
2. Connect your **GitHub** or **Discord** account to request tokens.
You can request tAI3 tokens once every 24 hours.
## Unoffocial Web-Based Faucet
An ambassador-built web-faucet is available via the link: https://faucet.farmine.info/. Note: this is not an official faucet, use at your discretion.
---
### File: evm/foundry.mdx
---
title: Foundry Guide
---
[**Foundry**](https://book.getfoundry.sh/) is a tool that allows you to easily write, test and deploy smart contracts on any EVM-compatible blockchain.
### EVM Version Compatibility
Auto EVM is compatible with most EVM versions but doesn't support some features introduced in newer versions like **"Paris"** or **"Shanghai"**. When using development tools, you may need to specify an EVM version explicitly. Supported versions: **"Istanbul"**, **"London"**.
### Getting started
> *Note:* Foundryup does not currently support \`PowerShell\` or \`Cmd\`, so if you're on Windows, you will need to install and use [Git BASH](https://gitforwindows.org/) or [WSL](https://learn.microsoft.com/en-us/windows/wsl/install) as your terminal.
1. Use the \`foundryup\` toolchain installer and follow the on-screen instructions to install \`foundryup\` and make the \`foundryup\` command available in your CLI. Running \`foundryup\` by itself will install the latest precompiled binaries: \`forge\`, \`cast\`, \`anvil\`, and \`chisel\`. See \`foundryup --help\` for more options.
\`\`\`bash
curl -L https://foundry.paradigm.xyz | bash
\`\`\`
2. Once installed, create a project. Let's name it \`hello_autonomys\`. To initialize the project, run:
\`\`\`bash
forge init hello_autonomys
\`\`\`
\`cd\` into the \`hello_autonomys\` directory to see the project's structure.
3. All the necessary repo structure was created automatically, so we can start writing and testing our smart contracts immediately. There are separate directories for storing smart contracts (\`src\`) and testing smart contracts (\`test\`). Let's open the \`Counter.sol\` smart contract and add three functions: \`setNumber()\`, which sets the uint256 number to the provided value, \`increment()\`, which increases the value by 1, and \`decrement()\`, which decreases the value by 1.
\`\`\`
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.1;
contract Counter \{
uint256 public number;
function setNumber(uint256 newNumber) public \{
number = newNumber;
\}
function increment() public \{
number++;
\}
function decrement() public \{
number--;
\}
\}
\`\`\`
4. Let's make sure that all the functions are working properly by adding some tests to the \`Counter.t.sol\` test file, and checking if they pass. In our tests, we first set the initial value of \`number\` to 2, before checking if the \`increment()\` function increases the value by 1 and if \`decrement()\` decreases the value by 1.
\`\`\`
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;
import "forge-std/Test.sol";
import "../src/Counter.sol";
contract CounterTest is Test \{
Counter public counter;
function setUp() public \{
counter = new Counter();
counter.setNumber(2);
\}
function testIncrement() public \{
counter.increment();
assertEq(counter.number(), 3);
\}
function testSetNumber(uint256 x) public \{
counter.setNumber(x);
assertEq(counter.number(), x);
\}
function testDecrement() public \{
counter.decrement();
assertEq(counter.number(), 1);
\}
\}
\`\`\`
5. Let's build the project by running:
\`\`\`bash
forge build
\`\`\`
Test the smart contract is working by running:
\`\`\`bash
forge test
\`\`\`
All tests are passing, meaning the smart contract is working as expected.
6. There are two final things we need to do before deploying our smart contract:
- Connect a wallet that has a sufficient balance of tAI3 to cover the gas fees.
- Set an environment variable we will use later.
To make our lives easier, let's create a new \`Makefile\` as well as a \`.env\` file at the root of our project. \`.env\` files are typically used to store environment variables for your application. They are particularly useful for managing settings that change between deployment environments (e.g., development, testing, staging, and production), and for storing sensitive information. Environment variables can include database connection details, API keys, external resource URIs, or other configuration variables that might change depending on the environment in which the application is running. In our case, we would use it to point to our Auto-EVM RPC URL:
\`\`\`bash
RPC_URL=https://auto-evm.chronos.autonomys.xyz/ws
\`\`\`
And then set a private key for the EVM-compatible wallet:
\`\`\`bash
PRIVATE_KEY="your_private_key_value"
\`\`\`
> *Note:* \`.env\` files should not be committed to your source control (like Git), especially when they contain sensitive data, like your private key. To prevent this, add \`.env\` to your \`.gitignore\` file. This helps to keep sensitive keys secure and avoids the risk of exposing them in the application's code or version control history.
In the \`Makefile\`, let's create shortcuts to the main features of the application:
\`\`\`bash
# include .env file and export its env vars
-include .env
# Builds
build:
@forge clean && forge build --optimize --optimizer-runs 1000000
# Deployment
deploy:
@forge create Counter --private-key \$\{PRIVATE_KEY\} --rpc-url \$\{RPC_URL\} --evm-version london
\`\`\`
We're importing the values for a \`PRIVATE_KEY\` and \`RPC_URL\` from the \`.env\` file. This allows us to run \`make build\` for building the project, and \`make deploy\` for deploying the project, pointing to the provided RPC, and using the provided \`PRIVATE_KEY\`. Let's run \`make build\` to ensure it's working properly.
7. To deploy your contract using the specified \`RPC\` and \`PRIVATE_KEY\`, run:
\`\`\`
make deploy
\`\`\`
> *Note:* Do not tip when submitting transactions in an attempt to accelerate them as this could result in dual charges for gas fees. When deploying smart contracts to our Auto EVM domain, you may encounter an error related to gas estimation, typically presenting as: "No manual gas limit set" or "Gas estimation failed". For more information and solutions, visit the [Auto EVM Introduction](/evm/introduction).
Congratulations, you've successfully deployed your smart contract on the Auto EVM!
---
### File: evm/general_information.mdx
---
title: Developer Tools
---
## Developer Tools
Developing smart contracts and decentralized applications involves a suite of tools that aid in writing, testing and deploying code on the blockchain. As Autonomys utilizes an instance of the Ethereum Virtual Machine (EVM), **every tool used to build, test and deploy smart contracts on Ethereum is fully compatible with the Auto EVM**.
### Writing smart contracts
Solidity is the primary programming language for writing smart contracts. It is statically typed, supports inheritance, libraries, and complex user-defined types, making it familiar for developers with a background in other statically typed languages such as C++, Java, or JavaScript. Solidity has a great community of developers and extensive documentation is available on the official [website](https://soliditylang.org/).
Integrated Development Environments (IDEs) are often used to aid in writing smart contracts. We recommend the [Remix IDE](https://remix.ethereum.org/), a browser-based IDE that enables you to write, deploy and interact with Solidity smart contracts. It features a built-in static analysis tool that checks your code for common errors.
### Development and testing
For local development and testing, spin up your own version of an Autonomys Developer Node and farmer, or alternatively, use EVM-compatible development tools like [Hardhat](https://hardhat.org/hardhat-network/docs/overview) or [Anvil](https://book.getfoundry.sh/anvil/) to deploy contracts, develop applications and run tests.
### Deploying and interacting with smart contracts
A JavaScript provider like the one injected by the [MetaMask](https://metamask.io/) browser extension is used to deploy and interact with smart contracts. This provider enables JavaScript applications to communicate with the Autonomys Network and any other Ethereum-compatible network. It's compatible with both [ethers.js](https://docs.ethers.org/v5/) and [web3.js](https://web3js.readthedocs.io/en/v1.10.0/)/[Web3.py](https://web3py.readthedocs.io/en/stable/), allowing developers to use either library for their blockchain operations.
All these tools together provide an cohesive ecosystem for EVM-compatible smart contract development, making the process significantly more manageable and efficient.
---
### File: evm/hardhat.mdx
---
title: Hardhat Guide
---
## Hardhat Guide
[**Hardhat**](https://hardhat.org/docs) is a tool that facilitates building, testing and deploying on the Ethereum Virtual Machine. It helps developers manage and automate the recurring tasks that are inherent to the process of building smart contracts and dApps, and allows them to easily introduce more functionality around this workflow. This includes compiling and testing at the very core. Flexible deployment options also allow you to point to the Autonomys EVM domain RPC to deploy your contracts and dApps.
### EVM Version Compatibility
Auto EVM is compatible with most EVM versions but doesn't support some features introduced in newer versions like **"Paris"** or **"Shanghai"**. When using development tools, you may need to specify an EVM version explicitly. Supported versions: **"Istanbul"**, **"London"**.
### Getting started
**Prerequisites**
*[NodeJS](https://nodejs.org/en) version >=16.0 installed*
1. Open a new terminal and create a new folder for the project:
\`\`\`
mkdir subspace-hardhat
cd subspace-hardhat
\`\`\`
2. Initialize an \`npm\` project:
\`\`\`
npm install --save-dev hardhat
npm install --save-dev @openzeppelin/contracts
npx hardhat
\`\`\`
You'll be prompted to answer some questions. Select \`Create a JavaScript Project\` from the list of available options, select the project root folder, and, optionally, create a \`.gitignore\` file.
3. In your created workspace, you will notice several folders. All of your contracts will reside inside the \`contracts\` folder, deployment scripts are available inside the \`scripts\` folder, and tests can be found inside the \`test\` folder. Click on the \`contracts\` folder and open \`Lock.sol\`.
4. Change the name of your contract in \`Lock.sol\` (\`Counter\`), the name of the token (\`AutonomysTestToken\`) and the token symbol (\`AI3test\`). As an example, let's add a simple smart contract that has three functions: \`setNumber()\`, \`increment()\` and \`decrement()\`.
\`\`\`
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.9;
import '@openzeppelin/contracts/token/ERC20/ERC20.sol';
contract Counter is ERC20 \{
constructor() ERC20("AutonomysTestToken", "TAI3test") \{\}
uint256 public number;
function setNumber(uint256 newNumber) public \{
number = newNumber;
\}
function increment() public \{
number++;
\}
function decrement() public \{
number--;
\}
\}
\`\`\`
For consistency, let's also rename 'Lock.sol' to \`Counter.sol\`.
5. Before proceeding with deployment, thoroughly test your smart contracts for correctness, as mistakes can lead to unforeseen gas costs. To test the contract, open the \`Lock.js\` file in the \`test\` folder, and replace the internals of the file with the following code:
\`\`\`
const \{ expect \} = require("chai");
describe("Counter", function() \{
let Counter;
let counter;
let owner;
let addr1;
beforeEach(async function() \{
Counter = await ethers.getContractFactory("Counter");
[owner, addr1] = await ethers.getSigners();
counter = await Counter.deploy();
\});
describe("Counter operations", function() \{
it("Should return initial value of zero", async function() \{
expect(await counter.number()).to.equal(0);
\});
it("Should set number to a new value", async function() \{
await counter.setNumber(5);
expect(await counter.number()).to.equal(5);
\});
it("Should increment the number", async function() \{
await counter.setNumber(5);
await counter.increment();
expect(await counter.number()).to.equal(6);
\});
it("Should decrement the number", async function() \{
await counter.setNumber(5);
await counter.decrement();
expect(await counter.number()).to.equal(4);
\});
\});
\});
\`\`\`
For consistency, let's also rename \`Lock.js\` to \`CounterTest.js\`.
7. To run the test, type \`npx hardhat test\`.
Everything is working as expected so we're ready for deployment!
8. To deploy the contract, we need to set a deployment network for \`hardhat\`. Open the \`hardhat.config.js\` file and add the Chronos testnet to the list of networks:
\`\`\`
require("@nomicfoundation/hardhat-toolbox");
module.exports = \{
solidity: \{
compilers: [
\{
version: "0.8.17",
settings: \{
evmVersion: "london"
\}
\}
]
\},
networks: \{
autonomys: \{
url: "https://auto-evm.chronos.autonomys.xyz/ws",
accounts: ["private_key_to_your_account"]
\}
\}
\};
\`\`\`
> *Note:* Be careful not to commit your \`hardhat.config.js\` file as it contains your private key. You can use NPM tools like [\`dotenv\`](https://www.npmjs.com/package/dotenv) to securely store your private keys in an \`.env\` file.
9. Open the \`deploy.js\` file and replace the contents with the code:
\`\`\`
const hre = require("hardhat");
async function main() \{
const Contract = await hre.ethers.getContractFactory("Counter");
const contract = await Contract.deploy();
console.log("Contract deployed to:", contract.target);
\}
main().catch((error) => \{
console.error(error);
process.exitCode = 1;
\});
\`\`\`
10. You're now ready to deploy your smart contract on the Autonomys Network. To deploy, run \`npx hardhat run scripts/deploy.js --network subspace\`. This command will deploy your smart contract on the network we've just specified in the \`hardhat.config.js\` file. If deployment is successful, you should see \`Contract deployed to: transaction hash\`.
> *Note:* Do not tip when submitting transactions in an attempt to accelerate them as this could result in dual charges for gas fees. When deploying smart contracts to our Auto EVM domain, you may encounter an error related to gas estimation, typically presenting as: \`"No manual gas limit set"\` or \`"Gas estimation failed"\`. For more information and solutions, visit the [Auto EVM Introduction](/evm/introduction).
Congratulations, you've successfully deployed your smart contract on the Auto EVM!
---
### File: evm/introduction.mdx
---
title: Auto EVM
---
## Auto EVM
**Auto EVM** enables any tool available for Ethereum development to be compatible with the Autonomys Network.
### Quick Start Guide
This guide provides simple instructions for setting up a remote development environment, and assumes you have a basic understanding of or experience with Ethereum Virtual Machine (EVM) development.
### EVM Version Compatibility
Auto EVM is compatible with most EVM versions but doesn't support some features introduced in newer versions like **"Paris"** or **"Shanghai"**. When using development tools, you may need to specify an EVM version explicitly. Supported versions: **"Istanbul"**, **"London"**.
#### Set up a MetaMask wallet (or any other EVM-compatible wallet) and connect it to our custom EVM
\`\`\`
Network Name: Autonomys EVM
New RPC URL: https://auto-evm.mainnet.autonomys.xyz/ws
Chain ID: 870
Currency Symbol: AI3
\`\`\`
Auto EVM is also available on the Chronos testnet
\`\`\`
Network Name: Autonomys EVM
New RPC URL: https://auto-evm.chronos.autonomys.xyz/ws
Chain ID: 490000
Currency Symbol: tAI3
\`\`\`
#### Send tokens to your wallet using our faucet
Follow the instructions [here](/evm/faucet) to get some testnet AI3 (tAI3) tokens from our **faucet**.
tAI3 (formerly testnet Subspace Credits (tSSC)) is the sole method of payment for gas within the Auto EVM runtime.
We are currently working on a bridge to convert farmed AI3 tokens into EVM-compatible tokens to cover gas fees.
#### Test and deploy your smart contract
You can use **[Remix](https://remix.ethereum.org/)**, **[Foundry](https://book.getfoundry.sh/)**, or any other tool familiar to you to test and deploy your smart contracts on our custom EVM domain.
If anything above is unfamiliar to you, explore our full guide over the following pages.
> *Note:* Do **not** tip when submitting transactions in an attempt to accelerate them. Autonomys' transaction queue operates differently from Ethereum's. Including a tip alongside gas fees leads to the possibility of two transactions sharing the same nonce. This could result in dual charges for gas fees—once for the execution and storage in the first transaction, and once for storage in the second transaction.
### Gas Estimation Limitations
The \`eth_estimateGas\` RPC call may not provide completely accurate estimates in **Auto EVM** domain for the following reasons:
- Consensus chain storage fees may not be fully accounted for in estimates
- The RPC cannot determine which transaction format the caller will use:
- pallet-evm or pallet-ethereum call
- pallet-evm create or create2 call
- Any of the 3 supported pallet-ethereum transaction formats
While improvements to the gas estimation are being implemented, developers should consider the following:
- Add a buffer to estimated gas values for important transactions
- If you encounter consistent gas estimation issues, please contact us so we can adjust our estimation algorithms
#### *Known issue: gas estimation*
When deploying smart contracts to our EVM-compatible **Auto EVM** domain, you may encounter an error related to gas estimation, typically presenting as:
\`"No manual gas limit set"\` or \`"Gas estimation failed"\`.
This issue often occurs because development tools like Foundry simulate transactions using calculated or hardcoded gas estimation instead of querying the RPC (Remote Procedure Call) for it. **Auto EVM** may require different gas amounts for certain operations compared to other EVM-compatible chains (like Ethereum testnets).
> *Note:* We have submitted an upstream PR to fix this issue with **Foundry**. Described below are the workarounds until the issue is resolved by the **Foundry team**.
#### Solutions
If you encounter this issue, try the following solutions:
- **Skip simulation**: Use the \`--skip-simulation\` flag when deploying with Foundry to bypass built-in simulation and rely on RPC for gas estimation.
- **Set a manual gas limit**: Specify a higher gas limit manually in your deployment command or UI.
- **Adjust your deployment script**: Modify your script to include custom gas settings or implement \`try\`/\`catch\` blocks for handling deployment failures.
- **Use a web3 provider**: If using **Remix IDE**, switch to an \`Injected Web3\` environment to leverage external web3 providers like MetaMask.
- **Custom deployment function**: Create a deployment function with adjustable gas parameters.
#### Solution examples
**Foundry**
1. Try using the \`--skip-simulation\` flag: \`forge script path/to/your/script.s.sol --rpc-url your_rpc_url --private-key your_private_key --broadcast --skip-simulation\`.
2. Try setting the gas limit manually: \`forge script path/to/your/script.s.sol --rpc-url your_rpc_url --private-key your_private_key --broadcast --gas-limit 300000\`.
Start with a higher value (\`300000\`) and gradually lower it to find the optimal limit.
**Remix IDE**
1. Try settiing the gas limit manually: In the \`Deploy & Run Transactions\` panel, expand the \`Advanced\` section.
Set a higher value in the \`Gas Limit\` field. Start with \`300000\` and adjust as needed.
2. Try adjusting the gas price: In the same \`Advanced\` section, adjust the \`Gas Price\` as needed.
3. Try switching to the \`Injected Web3\` environment in the \`Deploy & Run Transactions\` panel: This will use your browser's web3 provider (e.g., MetaMask), which may better handle gas estimation for the network.
4. If the above steps don't work, create a custom deployment function that includes gas parameters:
\`\`\`
function deployWithCustomGas(uint256 gasLimit, uint256 gasPrice) public returns (address) \{
return address(new YourContract\{gas: gasLimit, gasPrice: gasPrice\}());
\}
\`\`\`
**Other possible solutions**
1. Modify your deployment script and override the default gas settings:
\`\`\`
vm.txGasPrice(uint256 gasPrice);
vm.txGasLimit(uint256 gasLimit);
\`\`\`
2. Implement a \`try\`/\`catch\` block in your script to handle gas estimation failures:
\`\`\`
try yourContract.deploy\{gas: 300000\}(constructorArgs) returns (YourContract deployed) \{
// Deployment successful
\} catch Error(string memory reason) \{
console.log("Deployment failed:", reason);
\}
\`\`\`
---
### File: evm/local.mdx
---
title: Local Development Guide
---
## Local Development Guide
You can always set up a **local development environment** to test and deploy your smart contracts. To establish a full local network, you need to run a local node, an Auto EVM domain, and a farmer.
### Getting started
1. Visit the **[Autonomys releases](https://github.com/autonomys/subspace/releases)** page and download the most up-to-date stable versions of the node and farmer.
> *Note:* For each release, there are two versions:
> 1. skylake: for newer processors from around 2015 and onwards
> 2. x86-64-v2: for older processors from around 2009 and some older VMs
> Older processors/VMs are no longer supported by official releases, but they can still be [compiled manually](https://github.com/autonomys/subspace/blob/main/docs/development.md) if desired.
2. After downloading both the files for your system, start a node using your preferred terminal. If you want to start an EVM domain on your local machine, you need to specify:
- Your local RPC server port
- Your local web-socket RPC port
You can do this with the following command:
\`\`\`bash
./your_subspace_node_path run --dev --rpc-listen-on 127.0.0.1:9944 -- --domain-id 3 --dev --rpc-listen-on 127.0.0.1:8545
\`\`\`
This will create a local RPC on port **8545**.
3. Start a farmer by running the following command:
\`\`\`bash
./your_subspace_farmer_path farm --reward-address [YOUR REWARD ADDRESS] path=tmp-farm,size=100M
\`\`\`
You can specify the desired plot size, but 100M should be sufficient.
That's it! By starting a **local node** and a **farmer**, you have a **local RPC** ready for testing and deploying smart contracts! You can easily connect your [MetaMask](https://metamask.io/) account to the local development network, as well as use [Remix](https://remix.ethereum.org/) or [Foundry](https://book.getfoundry.sh/) in order to test and deploy smart contracts on a local network!
---
### File: evm/metamask.mdx
---
title: Adding the Autonomys RPC to MetaMask
---
## Adding the Autonomys RPC to MetaMask
This guide will help you set up a [**MetaMask**](https://metamask.io/) wallet (any EVM-compatible wallet works) and connect it to the Autonomys EVM development network.
1. Download the MetaMask extension for your browser from the [MetaMask website](https://metamask.io/) after selecting your preferred language (in the top-right corner), and reading and agreeing to MetaMask's Terms of Use.
2. Click on \`Create a new wallet\`. Read and agree to (or skip) the note on gathering and collecting anonymized usage data (it does not affect wallet creation).
3. Set a secure password that's difficult to guess. Type it twice before proceeding to the next step. MetaMask automatically assesses the strength of your password.
> *Note:* Your password should include uppercase letters, lowercase letters, numbers and special characters.
4. Watch a video to learn more about your Secret Recovery Phrase before proceeding to the next step.
5. Write down your 12-word Secret Recovery Phrase.
> *Note:* The recovery phrase for the wallet in this guide has been deleted.
6. Confirm that you've written down the Secret Recovery Phrase by filling in the missing words.
7. You've now created a wallet! Connect to the Autonomys EVM by clicking on the Ethereum Mainnet logo and selecting \`Add network\`.
8. In the MetaMask Networks settings, click on \`Add a network manually\`.
9. Input the values below to connect to the Autonomys RPC:
\`\`\`
Network Name: Autonomys EVM
New RPC URL: https://auto-evm.chronos.autonomys.xyz/ws
Chain ID: 8700
Currency Symbol: tAI3
\`\`\`
You have now successfully set up a MetaMask wallet and connected it to the Auto EVM! To deploy a smart contract, you first need to get a small amount of **tAI3** tokens in your wallet. Refer to the [faucet section](/evm//faucet) of the guide to learn more about getting testnet tokens.
---
### File: evm/remix.mdx
---
title: Remix IDE Guide
---
[**Remix**](https://remix-ide.readthedocs.io/en/latest/) is a tool that allows you to easily write, test and deploy smart contracts on any EVM-compatible blockchain.
### EVM Version Compatibility
Auto EVM is compatible with most EVM versions but doesn't support some features introduced in newer versions like **"Paris"** or **"Shanghai"**. When using development tools, you may need to specify an EVM version explicitly. Supported versions: **"Istanbul"**, **"London"**.
**In Remix, set the EVM version in the Solidity compiler settings:**
Go to the "Solidity compiler" tab
Click on "Advanced Configurations"
Set "EVM Version" to **"london"** or **"istanbul"**
### Getting started
1. Navigate to the [Remix website](https://remix.ethereum.org). You will see a file explorer and interface for creating new workspaces, integrations with GitHub, Gist, IPFS, HTTPS, preloaded templates, and plugins. Create a new workspace by clicking on the + sign next to \`WORKSPACES\`.
2. Choose the ERC20 template and enter any workspace name.
3. After creating your workspace, you will see some folders created for you. Click on \`contracts\` and open \`MyToken.sol\`.
4. As an example, let's add a simple smart contract that has four functions: \`setNumber(number)\`, \`get()\`, \`increment()\` and \`decrement()\`.
\`\`\`bash
// SPDX-License-Identifier: MIT
pragma solidity ^0.8.19;
contract Counter \{
uint256 private counter;
// Set the counter to a specific value
function set(uint256 _value) public \{
counter = _value;
\}
// Increase the counter by 1
function increase() public \{
counter += 1;
\}
// Decrease the counter by 1
function decrease() public \{
require(counter > 0, "Counter cannot go below zero");
counter -= 1;
\}
// Get the current counter value
function get() public view returns (uint256) \{
return counter;
\}
\}
\`\`\`
5. Next, let's compile the \`Counter\` contract. Click on \`SOLIDITY COMPILER\` (on the left), choose the compiler version that corresponds to the Solidity version of your contract (version 0.8.9 in the example), and click on \`Compile MyToken.sol\`. If it compiles correctly, you will see a green checkmark next to the compiler.
6. Before proceeding with deployment, thoroughly test your smart contracts for correctness, as mistakes can lead to unforeseen gas costs. As an example, click on the \`tests\` folder and open \`MyToken.sol\`. Test the contract (without making changes) by selecting \`SOLIDITY UNIT TESTING\` (the two ticks in the bar on the left) and clicking \`Run\`.
7. As expected, the test failed because we manually changed the token name and symbol. This is Test Driven Development (TDD) in action! In the test, we're adding some assertions for the \`increment()\` and \`decrement()\` functions. To make the test pass, replace the internals of \`MyToken.sol\` with the code below. In this example, we will set the initial value of \`number\` to 2 and \`increment\` and then \`decrement\` it by 1. We would expect the number to increase to 3 and then decrease back to 2.
\`\`\`bash
pragma solidity >=0.7.0 <0.9.0;
import "remix_tests.sol";
import "../contracts/MyToken.sol";
contract CounterTest is Counter \{
function testTokenInitialValues() public \{
Assert.equal(name(), "AutonomysTestToken", "token name did not match");
Assert.equal(symbol(), "AI3test", "token symbol did not match");
Assert.equal(decimals(), 18, "token decimals did not match");
Assert.equal(totalSupply(), 0, "token supply should be zero");
\}
Counter public counter;
function setUp() public \{
counter = new Counter();
counter.setNumber(2);
\}
function testIncrement() public \{
counter.increment();
Assert.equal(counter.number(), 3, "test increment did not match");
\}
function testDecrement() public \{
counter.decrement();
Assert.equal(counter.number(), 2, "test decrement did not match");
\}
\}
\`\`\`
8. All tests are now passing, meaning our smart contract \`Counter\` is working as expected. We're now ready to deploy it!
9. Click on the \`DEPLOY AND RUN TRANSACTIONS\` tab (on the left) to deploy. Remix allows you to use one of their existing EVMs or inject your own provider through its integration with MetaMask. Since we already have a [MetaMask account set up](/evm/metamask), let's use this option.
10. After ensuring the network you're connected to is the Autonomys EVM, confirm your MetaMask password when prompted.
11. Adjust the gas limit and deploy your smart contract on the Autonomys EVM domain. Your transaction is now recorded and you can interact with your smart contract at the bottom of the page, meaning it's possible to call the functions \`increment()\` and \`decrement()\`, as well as \`setNumber()\`.
> *Note:* Do not tip when submitting transactions in an attempt to accelerate them as this could result in dual charges for gas fees. When deploying smart contracts to our Auto EVM domain, you may encounter an error related to gas estimation, typically presenting as: \`"No manual gas limit set"\` or \`"Gas estimation failed"\`. For more information and solutions, visit the [Auto EVM Introduction](/evm/introduction).
Congratulations, you've successfully deployed your smart contract on the Auto EVM!
---
### File: evm/safe.mdx
# Safe Multi-Signature Wallet
Safe (formerly Gnosis Safe) is now available on the Autonomys network, providing industry-leading multi-signature wallet functionality for secure asset management and decentralized operations.
## Overview
Safe is a battle-tested smart contract wallet infrastructure that enables multi-signature security across blockchain networks. With its deployment on Autonomys, teams, DAOs, and individual users can now benefit from enhanced security features and shared asset control on both our mainnet and testnet environments.
## Network Availability
Safe is currently deployed and accessible at: [https://safe.autonomys.xyz](https://safe.autonomys.xyz/welcome)
### Transaction Service
The dedicated Transaction Service is available at [https://transaction.safe.autonomys.xyz](https://transaction.safe.autonomys.xyz/)
## Key Features
Safe on Autonomys provides the following capabilities:
- **Multi-signature security**: Require multiple signatures for transaction approval
- **Shared asset control**: Enable collaborative fund management across team members
- **dApp integration**: Interact with decentralized applications using your Safe wallet
- **Smart contract deployment**: Deploy and manage contracts with enhanced security
- **Customizable policies**: Set spending limits and approval requirements
## Use Cases
Safe is ideal for:
- **Teams and organizations**: Secure collaborative fund management
- **DAOs**: Decentralized governance and treasury management
- **Project treasuries**: Multi-party control over project funds
- **Individual users**: Enhanced security for high-value assets
## Getting Started
### Creating a Safe Wallet
1. Visit [safe.autonomys.xyz](https://safe.autonomys.xyz/welcome)
2. Connect your wallet
3. Create a new Safe by specifying:
- Wallet name
- Owner addresses (signers)
- Confirmation threshold (required signatures)
---
---
4. Deploy your Safe wallet
### Managing Your Safe
Once created, you can:
- Add or remove owners
- Change signature requirements
- Execute transactions
- Interact with dApps
- View transaction history
---
### File: evm/the_graph.mdx
---
title: The Graph
---
# The Graph
> **Note:** Available on both **Mainnet** and **Chronos** testnet!
[The Graph](https://thegraph.com/) is an indexing protocol that provides an easy way to query blockchain data through decentralized APIs known as subgraphs.
With The Graph, developers can benefit from:
- Decentralized Indexing: Enables indexing blockchain data through multiple indexers, thus eliminating any single point of failure
- GraphQL Queries: Provides a powerful GraphQL interface for querying indexed data, making data retrieval super simple.
- Customization: Define your own logic for transforming & storing blockchain data. Reuse subgraphs published by other developers on The Graph Network.
Follow this quick-start guide to create, deploy, and query a subgraph within 5 minutes.
### Benefits
Indexers like The Graph create a queryable data layer specifically tracking events and state changes from your smart contract. By monitoring and organizing this contract data, they enable complex queries that would be impossible through direct blockchain calls. This allows your dApp to efficiently access historical transactions, track relationships between entities, and analyze patterns over time - all without multiple RPC calls.
### Prerequisites
- A crypto wallet
- A smart contract address on a supported network
- Node.js installed
- A package manager of your choice (npm, yarn or pnpm)
### Quick Start guide
1. Proceed to the [Subgraph Studio](https://thegraph.com/studio) and login via one of the supported wallets.
2. Confirm the sign and sign a message to use Studio.
3. Click on **Create a Subgraph** on the main dashboard.
4. Specify the **Subgraph Name**.
5. Upon creating a Subgraph, you will see its dashboard, where you can a project description, source code URL, and a website URL.
6. On the right side, click on **Select a network** and pick **Autonomys** from the dropdown list.
7. Install **Graph CLI** using provided commands. You can use \`yarn\`, \`npm\`, \`pnpm\`, or \`bun\`.
8. Initialize the subgraph by running \`graph init autonomys-subgraph\`. This will create a boilerplate subgraph project.
During the initialization, you will need to specify a few things:
- Network (Autonomys)
- Subgraph slug (feel free to use the default name)
- Directory to create the subgraph in (feel free to use the default directory)
- Smart contact address (the address of your smart contract deployed on Autonomys Chronos EVM domain)
- ABI file (path)
- Start block (feel free to use the default value)
- Contract name
- Index contract events as entities (true or false value)
> Tip: you can find the contract ABI by looking at the \`token_metadata\` file.
E.g. if you're using Remix IDE, find your contract metadata file, collapse it on the \`abi\` line 7, copy the entire \`abi\` including the square brakets **[]** and save it into a \`json\` file on your PR.
9. Run \`graph auth\` to authenticate the project and provide your deploy key which you can find on the **Subgraph Dashboard**.
10. Enter the directory with \`cd project_name\` and run \`graph codegen && graph build\` to build the project, you will see the \`build/subgraph.yaml\` file being created.
11. Deploy your subgraph by running \`graph deploy subgraph-autonomys\`. You will be asked to specify the version of the subgraph, e.g. v0.0.1.
12. Proceed back to the **Graph Studio**, the status will change to **Deployed**.
13. The new tabs **Playground**, **Endpoints**, **Logs** will now be accessible to you! You can find usage examples of querying the data, accessing the data via API, and can test queries in the **Playground** without leaving the studio!
Congratulations, you've successfully setup and configured a subgraph for your application!
### Querying data in your smart contract
Subgraphs are primarily designed to index and query events emitted by smart contracts.
1. Let's make some slight changes to the \`Counter\` contract we introduced in the [Foundry guide](/evm/foundry.mdx) and modify functions to emit events.
\`\`\`solidity
// SPDX-License-Identifier: UNLICENSED
pragma solidity ^0.8.13;
contract Counter \{
uint256 public number;
event NumberSet(uint256 newNumber);
event NumberIncremented(uint256 newNumber);
event NumberDecremented(uint256 newNumber);
function setNumber(uint256 newNumber) public \{
number = newNumber;
emit NumberSet(number);
\}
function increment() public \{
number++;
emit NumberIncremented(number);
\}
function decrement() public \{
number--;
emit NumberDecremented(number);
\}
\}
\`\`\`
> Note: This will affect the contract ABI, make sure to change it and upgrade your Subgraph application.
2. Then we'll change the \`Counter\` contract state and set the number to \`5\` by running \`cast send YOUR_CONTRACT_ADDRESS "setNumber(uint256)" 5 --rpc-url https://auto-evm.chronos.autonomys.xyz/ws --private-key YOUR_KEY\`
3. Let's trigger one more event in the \`Counter\` contract by calling the \`increment()\` function. We can do that by running \`cast send YOUR_CONTRACT_ADDRESS "increment()" --rpc-url https://auto-evm.chronos.autonomys.xyz/ws --private-key YOUR_KEY\`
4. With two events emitted, let's proceed to **The Graph** playground and **query them**!
5. Open the **Graph Playground** tab where you try running the following queries:
#### Query to Get All NumberSet Events
\`\`\`bash
\{
numberSets(first: 10, orderBy: blockTimestamp, orderDirection: desc) \{
id
newNumber
blockTimestamp
blockNumber
transactionHash
\}
\}
\`\`\`
#### Query to Get All Increment Events
\`\`\`bash
\{
numberIncrementeds(first: 10, orderBy: blockTimestamp, orderDirection: desc) \{
id
newNumber
blockTimestamp
blockNumber
transactionHash
\}
\}
\`\`\`
#### Get All Events (Set, Increment, Decrement) in Chronological Order
\`\`\`bash
\{
numberSets(orderBy: blockTimestamp) \{
id
newNumber
blockTimestamp
blockNumber
transactionHash
__typename
\}
numberIncrementeds(orderBy: blockTimestamp) \{
id
newNumber
blockTimestamp
blockNumber
transactionHash
__typename
\}
numberDecrementeds(orderBy: blockTimestamp) \{
id
newNumber
blockTimestamp
blockNumber
transactionHash
__typename
\}
\}
\`\`\`
> Tip: you can also run queries directly from the terminal using \`cURL\` or \`gql\`. You can find **Example Usage** under the **Endpoints** tab.
---
### File: evm/transaction_fees.mdx
---
title: Account Balances and Transaction Fees on Auto EVM
---
# Account Balances and Transaction Fees on Auto EVM
## Introduction
While Auto EVM strives to maintain EVM compatibility, there are some important differences that developers should understand regarding account balances and transaction fees. These differences stem from Auto EVM's Substrate-based architecture and affect how balances are managed and fees are calculated.
## Key Concepts
### Existential Deposit (ED)
The Existential Deposit is a minimum balance threshold that affects how accounts handle native token balances on the network.
- Current ED value: 0.000001 TAI3
- For user accounts (EOAs):
- Accounts that drop below ED are reaped (removed from state)
- Prevents dust accounts and maintains network efficiency
- For smart contracts:
- ED only impacts contracts that handle native token balances
- Many contracts (e.g., ERC20 tokens) don't interact with native tokens and are unaffected
- When a contract's balance exceeds ED, that amount becomes reserved
### Consensus Storage Fees
In addition to standard gas fees, Auto EVM implements consensus storage fees:
- Applied to transactions that modify state
- Separate from execution fees
- Deducted from the sender's account
- Scale with the size of call data
- Not currently visible in BlockScout UI
## Impact on Smart Contracts
### Balance Management
1. Contracts with native token balances cannot be fully emptied due to ED requirements
> **Note:** This affects contracts that maintain native token balances (e.g., faucets, DEX contracts)
2. The maximum withdrawable amount from the account is: \`total_balance - ED\`
### Example Scenarios
**Deposit and Withdrawal:**
\`\`\`
Initial deposit: 0.01 TAI3
Available for withdrawal: 0.009999 TAI3 (due to ED)
Contract state balance: 0.01 TAI3
\`\`\`
**Fee Deduction:**
- Transaction fees (execution + storage) are deducted from the sender's account
- The contract's internal accounting may show different values than the actual on-chain balance
## Best Practices
### Smart Contract Development
1. Account for ED in withdrawal functions:
- Always leave the ED amount in the contract
- Check for sufficient balance above ED before transfers
2. Fee Handling:
- Consider both execution and storage fees in transaction planning
- Add buffer for storage fees in critical operations
### Testing Considerations
1. Test withdrawal edge cases:
- Attempt to withdraw full balance
- Verify behavior with amounts close to ED
- Check contract state after failed withdrawals
2. Balance Verification:
- Use RPC calls to verify actual available balance
- Compare contract state with on-chain state
- Account for ED in balance calculations
## Differences from Ethereum
1. Balance Management:
- Ethereum: No minimum balance requirement
- Auto EVM: Requires ED maintenance
2. Fee Structure:
- Ethereum: Gas fees only
- Auto EVM: Gas fees + consensus storage fees
3. Contract Behavior:
- Ethereum: Contracts can be fully emptied
- Auto EVM: ED must remain in contracts
## Tools and Verification
### Checking Balances
To verify actual available balances:
- Use Polkadot.js interface
- Query contract state directly
- Account for ED and storage fees in calculations
### Transaction Planning
When planning transactions:
1. Calculate required fees (execution + storage)
2. Ensure sufficient balance above ED
3. Add buffer for potential storage fee variations
## Common Issues and Solutions
1. "Insufficient Balance" errors:
- Check if attempting to withdraw below ED
- Verify sufficient balance for fees
- Consider storage fees in calculations
2. Balance Discrepancies:
- Compare BlockScout UI with actual RPC calls
- Account for storage fees in calculations
- Remember ED requirements
---
### File: evm/wrapping_ai3.mdx
# How to Wrap AI3 Tokens (Mainnet and Taurus Testnet)
Native AI3 tokens on Auto EVM are similar to ETH on the Ethereum network - they are not ERC-20 tokens, which is sometimes a requirement for certain use-cases.
Fortunately, there are ERC-20 contracts on both mainnet and testnet Auto EVM that allow you to "wrap" your tokens. This guide walks you through how to do that.
## The Contracts
### Mainnet WAI3 Contract
**Mainnet** WAI3 Contract: \`0x7ba06C7374566c68495f7e4690093521F6B991bb\`.
View contract: https://explorer.auto-evm.mainnet.autonomys.xyz/token/0x7ba06C7374566c68495f7e4690093521F6B991bb
### Chronos Testnet WAI3 Contract
**Chronos Testnet** WAI3 Contract: \`0xeAb23556Ec571bA10F4C3C8051d719E58e921caC\`.
View contract: https://explorer.auto-evm.chronos.autonomys.xyz/token/0xeAb23556Ec571bA10F4C3C8051d719E58e921caC
## Wrapping AI3 for WAI3
We will use MetaMask for this guide, though any EVM compatible wallet should work. First, make sure you have the appropriate Auto EVM network added to MetaMask.
\`\`\`
Network Name: Autonomys EVM
New RPC URL: https://auto-evm.mainnet.autonomys.xyz/ws
Chain ID: 870
Currency Symbol: AI3
\`\`\`
Auto EVM is also available on the Chronos testnet
\`\`\`
Network Name: Autonomys EVM
New RPC URL: https://auto-evm.chronos.autonomys.xyz/ws
Chain ID: 8700
Currency Symbol: tAI3
\`\`\`
The quickest way to add the network is to use this button at the bottom of Blockscout (use the contract link above):
Once that's done you should be able to see your Auto EVM tAI3 balance on MetaMask when you select the network.
To convert some tAI3 to WAI3 you just need to send it to the contract. You will see a warning that you are about to send to a token contract. This is expected.
Once you've accepted the warning you can click on "Continue".
NOTE: You may need to increase the gas fee if you see a failure when executing the transaction. If all has gone well you should end up seeing the contract interaction in the MetaMask Activity tab.
To view your WAI3 you will need to add the token contract by importing it in MetaMask.
Enter the WAI3 contract address and you will be able to see your balance under the Tokens tab in MetaMask.
## Unwrapping WAI3
To unwrap your WAI3 tokens (convert them back to the original tAI3 tokens), you'll need to interact with the \`withdraw\` function in the **[WAI3 contract](#the-contracts)**. Here's how to do it.
First, make sure you have your wallet holding the WAI3 connected to the contract linked above. Ensure you are on the "Write" tab of the contract and look for the \`withdraw\` method.
Enter the amount you want to unwrap as a parameter. The value entered needs to be in Shannons - the Autonomys equivalent of Ethereum's wei. The Blockscout UI has a button \`10^18\` to automatically add the extra 18 zeroes required to convert between the two.
Once you're ready, hit the "Write" button and approve the transaction in your wallet. You should now see the WAI3 has ben converted back to native tAI3.
---
### File: index.mdx
---
title: Auto SDK - Build with Autonomys Network
description: Your gateway to building on the Autonomys Network. Streamline dApp development with modular packages and decentralized solutions.
---
import \{ SDKHeader \} from '../components/landingPage.js'
import \{ SDKOverview \} from '../components/landingPage.js'
import \{ SDKFeatures \} from '../components/landingPage.js'
import \{ SDKResources \} from '../components/landingPage.js'
import \{ SDKCTA \} from '../components/landingPage.js'
<SDKHeader />
<SDKOverview />
<SDKFeatures />
<SDKResources />
<SDKCTA />
---
### File: introduction.mdx
---
title: Introduction
---
## Autonomys Developer Hub
### Introduction
The [**Autonomys Network**](https://autonomys.xyz) is the *only* blockchain that resolves the blockchain trilemma without compromise. Autonomys offers a platform for new and experienced developers to build secure, scalable AI-powered decentralized applications (**super dApps**) and unstoppable, verifiable on-chain agents (**Auto Agents**) with ease, leveraging familiar tools and innovative protocols.
This guide offers an overview of the development options available on the Autonomys Network.
### Is building on Autonomys difficult?
Absolutely not! One of the project's primary objectives is to minimize the barriers to entry for all network participants, from farmers to developers. Building on Autonomys is thus very straightforward, with active support from our team and community available if you ever run into trouble.
Join the Autonomys Discord server, tell us about your idea, and the team will help you see it through to deployment—no project is too ambitious! We pride ourselves on enabling the seemingly un-enableable.
### Development options
Developers can currently choose to build using the:
- **Auto SDK**: a comprehensive toolkit that simplifies development on the Autonomys Network, or the
- **Auto EVM**: Autonomys's EVM-compatible domain, allowing you to utilize all its familiar functionalities.
You will soon be able to build your own local custom virtual machines.
### Transaction Security
The Autonomys Network uses a nonce system to prevent transaction replay attacks:
- Each account has an integer nonce value that increases by one with every on-chain transaction
- Signed transactions must include the correct nonce value to be accepted
- Transactions with incorrect nonce values are rejected, preventing replay attacks
- For security, new accounts' default nonce value is set to the current block number (rather than 0)
- This ensures if an account is reaped and later re-created, previous transactions remain invalid
## [Auto SDK](/sdk)
### Key features:
- **Modular Packages**: Partitions functionality intuitively into packages including \`auto-utils\`, \`auto-consensus\`, and \`auto-id\`, allowing you to import only what you need.
- **Simplified Interaction**: Abstracts the complexity of blockchain operations with high-level functions.
- **Flexibility**: Suitable for building AI-powered decentralized applications (super dApps) and on-chain agents (Auto Agents) with ease.
### Getting started with the Auto SDK
To start using the Auto SDK, refer to our [setup instructions](/sdk) to clone the repository, install dependencies, and run tests. The Auto SDK is designed to be developer-friendly, even for first-time developers, ensuring that anyone can get up and running quickly.
## [Auto EVM](/evm/introduction)
### Key features:
- **Solidity Smart Contracts**: Write and deploy smart contracts using Solidity, just as you would on Ethereum.
- **Tool Compatibility**: Compatible with any tool available for Ethereum development, including Remix, Truffle, and Hardhat.
- **Familiar Environment**: Leverage existing knowledge and resources from the Ethereum ecosystem to build your application.
### Why use the Auto EVM?
- **Seamless Transition**: Developers familiar with Ethereum can transition to Autonomys without a steep learning curve.
- **Scalability and Security**: Benefit from Autonomys' scalable and secure infrastructure while using tried-and-true development practices.
- **Interoperability**: Create applications that can interact seamlessly with other EVM-compatible networks.
### Getting started with the Auto EVM
To start using the Auto EVM, refer to our [guides and manuals](/evm/introduction).
## RPC endpoints
#### Consensus
- \`wss://rpc.mainnet.subspace.foundation/ws\`
- \`wss://rpc.chronos.autonomys.xyz/ws\`
### Auto EVM
#### Mainnet
- \`wss://auto-evm.mainnet.autonomys.xyz/ws\`
#### Chronos Testnet
- \`wss://auto-evm.chronos.autonomys.xyz/ws\`
## Questions or feedback? Post on our [forum](https://forum.autonomys.xyz/) or in the *#developer-chat* channel on our [Discord](https://discord.gg/EAw6B48r).
To access the developer role-gated *#developer-chat* channel:
1. Join our [Discord](https://discord.gg/vhv5cEZN).
2. Click on Autonomys Network in the top-left corner and choose **Linked Roles**.
3. Link your GitHub account to attain the developer role and gain access to *#developer-chat*.
---
### File: llm_friendly_docs.mdx
---
### File: sdk/auto-consensus.mdx
import AutoConsensusFetchBalance from '/components/autoConsensusFetchBalance.js';
## Auto-Consensus Package
### Introduction
The \`@autonomys/auto-consensus\` package provides functions for interacting with the consensus layer of the Autonomys Network. It allows developers to perform actions involving account management, balance inquiries, transfers, staking operations, and more. \`@autonomys/auto-consensus\` works hand-in-hand with \`@autonomys/auto-utils\` to simplify blockchain interactions.
### Installation
Install the package via \`npm\` or \`yarn\`:
\`\`\`bash
# Using npm
npm install @autonomys/auto-consensus
# Using yarn
yarn add @autonomys/auto-consensus
\`\`\`
### Importing
Import the \`auto-consensus\` functions you need into your project:
\`\`\`typescript
// Import specific functions
import \{ balance, transfer, account \} from '@autonomys/auto-consensus';
// Or import everything
import * as consensus from '@autonomys/auto-consensus';
\`\`\`
### Overview of the \`api\` object
Many functions in the \`auto-consensus\` package require an \`api\` object as a parameter. This \`api\` object is an instance of \`ApiPromise\` from the Polkadot.js API library that serves as a gateway for interacting with the blockchain node.
#### \`api\` core components
> *Note:* Always disconnect the API instance after your operations are complete to free up resources.
- \`api.rpc\`: Methods to perform remote procedure calls to the node.
- \`api.query\`: Access the blockchain's runtime storage.
- \`api.tx\`: Create and submit extrinsics (transactions) to the blockchain.
- \`api.consts\`: Runtime constants defined in the blockchain's metadata.
- \`api.events\`: Access events emitted by the blockchain.
- \`api.types\`: Type definitions used by the chain.
#### Example
\`\`\`typescript
import \{ createConnection \} from '@autonomys/auto-utils';
async function getApiInstance() \{
const endpoint = 'wss://auto-evm.chronos.autonomys.xyz/ws';
const api = await createConnection(endpoint);
return api;
\}
\`\`\`
### Available functions
> *Note:* All asynchronous functions return a \`Promise\` and should be used with \`await\` for proper execution flow. Wrap your asynchronous calls in \`try...catch\` blocks to handle potential errors gracefully.
#### Account management
- \`account(api, address): Promise<AccountData>\`: Retrieves an account's nonce and balance data.
- \`balance(api, address): Promise<BalanceData>\`: Retrieves an account's balance details.
#### Balances
- \`totalIssuance(networkId?): Promise<BigInt>\`: Retrieves the total token issuance on the network.
- \`batch(api, txs[]): SubmittableExtrinsic\`: Creates a batch transaction for multiple operations.
#### Blockchain information
- \`block(api): Promise<RawBlock>\`: Retrieves the latest block data.
- \`header(api): Promise<RawBlockHeader>\`: Retrieves the latest block header.
- \`blockHash(api): Promise<string>\`: Retrieves the latest block hash.
- \`blockNumber(api): Promise<number>\`: Retrieves the current block number.
- \`networkTimestamp(api): Promise<bigint>\`: Retrieves the network timestamp.
#### Consensus information
- \`blockchainSize(api): Promise<bigint>\`: Calculates the blockchain's total size.
- \`spacePledged(api): Promise<bigint>\`: Calculates the total space pledged by farmers.
- \`solutionRanges(api): Promise<SolutionRanges>\`: Retrieves the current and next solution ranges.
- \`shouldAdjustSolutionRange(api): Promise<boolean>\`: Checks if the solution range needs adjustment.
- \`segmentCommitment(api): Promise<[StorageKey<AnyTuple>, Codec][]>\`: Retrieves segment commitment entries.
- \`slotProbability(api): [number, number]\`: Returns slot probability constants.
- \`maxPiecesInSector(api): bigint\`: Returns the maximum pieces in a sector.
#### Domains
- \`domainStakingSummary(api): Promise<DomainStakingSummary[]>\`: Retrieves domain staking summaries.
- \`domains(api): Promise<DomainRegistry[]>\`: Retrieves domain registries.
- \`latestConfirmedDomainBlock(api): Promise<ConfirmedDomainBlock[]>\`: Retrieves the latest confirmed blocks per domain.
#### Operators and staking
- \`operators(api): Promise<Operator[]>\`: Retrieves a list of all operators.
- \`operator(api, operatorId): Promise<OperatorDetails>\`: Retrieves the details of a specific operator.
- \`deposits(api, operatorId, account?): Promise<Deposit[]>\`: Retrieves the deposits for a specific operator.
- \`withdrawals(api, operatorId, account?): Promise<Withdrawal[]>\`: Retrieves the withdrawals for a specific operator.
- \`registerOperator(params): SubmittableExtrinsic\`: Creates a transaction to register a new operator.
- \`nominateOperator(params): SubmittableExtrinsic\`: Creates a transaction to nominate an operator.
- \`withdrawStake(params): SubmittableExtrinsic\`: Creates a transaction to withdraw staked tokens.
- \`deregisterOperator(params): SubmittableExtrinsic\`: Creates a transaction to deregister an operator.
- \`unlockFunds(params): SubmittableExtrinsic\`: Creates a transaction to unlock staked funds.
- \`unlockNominator(params): SubmittableExtrinsic\`: Creates a transaction to unlock nominator funds.
#### Transfers
- \`transfer(api, receiver, amount, allowDeath?): SubmittableExtrinsic\`: Creates a transaction to transfer funds.
- \`transferAll(api, receiver, keepAlive?): SubmittableExtrinsic\`: Creates a transaction to transfer all tokens.
#### Utility functions
- \`query<T>(api, methodPath, params?): Promise<T>\`: Queries the blockchain state for a method.
- \`remark(api, remark, withEvent?): SubmittableExtrinsic\`: Creates a remark transaction.
- \`rpc<T>(api, methodPath, params?): Promise<T>\`: Performs an RPC call.
## Interactive usage example
### Fetching the wallet balance (unlocked, locked) and nonce for a wallet
<AutoConsensusFetchBalance />
## Usage examples
Code examples demonstrating how to use the functions provided by \`@autonomys/auto-consensus\`.
### 1. Account management
#### Retrieve detailed account information (including the nonce and balance data)
\`\`\`typescript
import \{ account \} from '@autonomys/auto-consensus';
import \{ activate \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
const accountData = await account(api, 'your_address');
console.log(\`Nonce: \$\{accountData.nonce\}\`);
console.log(\`Free Balance: \$\{accountData.data.free\}\`);
console.log(\`Reserved Balance: \$\{accountData.data.reserved\}\`);
await api.disconnect();
\})();
\`\`\`
#### Activate a wallet and check its balance
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils';
import \{ balance \} from '@autonomys/auto-consensus';
(async () => \{
// Activate a wallet using a mnemonic phrase
const \{ api, accounts \} = await activateWallet(\{
mnemonic: 'your mnemonic phrase here', // Replace with your mnemonic
networkId: 'chronos', // Optional: specify the network ID
\});
const account = accounts[0];
console.log(\`Connected with account address: \$\{account.address\}\`);
// Check the account balance
const accountBalance = await balance(api, account.address);
console.log(\`Account balance: \$\{accountBalance.free\}\`);
// Disconnect when done
await api.disconnect();
\})();
\`\`\`
### 2. Balance operations
#### Retrieve the free balance of an account
\`\`\`typescript
import \{ balance \} from '@autonomys/auto-consensus';
import \{ activate \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
const accountBalance = await balance(api, 'your_address');
console.log(\`Free Balance: \$\{accountBalance.free\}\`);
await api.disconnect();
\})();
\`\`\`
#### Retrieve the total token issuance on the network
\`\`\`typescript
import \{ totalIssuance \} from '@autonomys/auto-consensus';
(async () => \{
const total = await totalIssuance('chronos');
console.log(\`Total Issuance: \$\{total.toString()\}\`);
\})();
\`\`\`
### 3. Transfers
#### Transfer funds between accounts
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils';
import \{ transfer \} from '@autonomys/auto-consensus';
(async () => \{
// Activate the sender's wallet
const senderWallet = await activateWallet(\{
mnemonic: 'sender mnemonic phrase', // Replace with the sender's mnemonic
\});
const sender = senderWallet.accounts[0];
// Activate the receiver's wallet
const receiverWallet = await activateWallet(\{
mnemonic: 'receiver mnemonic phrase', // Replace with the receiver's mnemonic
\});
const receiver = receiverWallet.accounts[0];
// Transfer 1 AI3 from the sender to the receiver
const amount = 1; // Amount in AI3
const transferTx = await transfer(senderWallet.api, receiver.address, amount);
// Sign and send the transaction
await transferTx.signAndSend(sender, (\{ status, txHash, events \}) => \{
if (status.isInBlock) \{
console.log(\`Transaction included at blockHash \$\{status.asInBlock\}\`);
console.log(\`Transaction hash: \$\{txHash\}\`);
\} else if (status.isFinalized) \{
console.log(\`Transaction finalized at blockHash \$\{status.asFinalized\}\`);
\}
\});
// Disconnect when done
await senderWallet.api.disconnect();
await receiverWallet.api.disconnect();
\})();
\`\`\`
#### Transfer tokens from one wallet to another
\`\`\`typescript
import \{ transfer \} from '@autonomys/auto-consensus';
import \{ activateWallet, signAndSendTx, disconnect \} from '@autonomys/auto-utils';
(async () => \{
const \{ api, accounts \} = await activateWallet(\{
networkId: 'chronos',
mnemonic: 'your_mnemonic',
\});
const sender = accounts[0];
const recipientAddress = 'recipient_address';
const amount = '1000000000000'; // Amount in the smallest unit (Shannon)
const tx = await transfer(api, recipientAddress, amount);
// Sign and send the transaction
await signAndSendTx(sender, tx);
console.log(\`Transferred \$\{amount\} tokens to \$\{recipientAddress\}\`);
await disconnect(api);
\})();
\`\`\`
### 4. Staking operations
#### Register a new operator for staking
\`\`\`typescript
import \{ registerOperator \} from '@autonomys/auto-consensus';
import \{ activateWallet, signAndSendTx \} from '@autonomys
/auto-utils';
(async () => \{
const \{ api \} = await activateWallet(\{
networkId: 'chronos',
mnemonic: 'sender_mnemonic',
\});
// Sender's account (who is registering the operator)
const \{ accounts: senderAccounts \} = await activateWallet(\{
networkId: 'chronos',
mnemonic: 'sender_mnemonic',
\});
const sender = senderAccounts[0];
// Operator's account
const \{ accounts: operatorAccounts \} = await activateWallet(\{
networkId: 'chronos',
mnemonic: 'operator_mnemonic',
\});
const operatorAccount = operatorAccounts[0];
const tx = await registerOperator(\{
api,
senderAddress: sender.address,
Operator: operatorAccount,
domainId: '0', // Domain ID where the operator will be registered
amountToStake: '1000000000000000000', // Amount in smallest units
minimumNominatorStake: '10000000000000000',
nominationTax: '5', // Percentage as a string (e.g., '5' for 5%)
\});
// Sign and send the transaction
await signAndSendTx(sender, tx);
console.log('Operator registered successfully');
\})();
\`\`\`
#### Nominate an existing operator by staking tokens
\`\`\`typescript
import \{ nominateOperator \} from '@autonomys/auto-consensus';
import \{ activateWallet, signAndSendTx \} from '@autonomys/auto-utils';
(async () => \{
const \{ api, accounts \} = await activateWallet(\{
networkId: 'chronos',
mnemonic: 'nominator_mnemonic',
\});
const nominator = accounts[0];
const operatorId = '1'; // The ID of the operator to nominate
const amountToStake = '5000000000000000000'; // Amount in smallest units
const tx = await nominateOperator(\{
api,
operatorId,
amountToStake,
\});
// Sign and send the transaction
await signAndSendTx(nominator, tx);
console.log(\`Nominated operator \$\{operatorId\} with \$\{amountToStake\} stake\`);
\})();
\`\`\`
### 5. Blockchain information
#### Retrieve the current block number, block hash, and network timestamp
\`\`\`typescript
import \{ blockNumber, blockHash, networkTimestamp \} from '@autonomys/auto-consensus';
import \{ activate \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
const currentBlockNumber = await blockNumber(api);
const currentBlockHash = await blockHash(api);
const currentTimestamp = await networkTimestamp(api);
console.log(\`Current Block Number: \$\{currentBlockNumber\}\`);
console.log(\`Current Block Hash: \$\{currentBlockHash\}\`);
console.log(\`Network Timestamp: \$\{currentTimestamp\}\`);
await api.disconnect();
\})();
\`\`\`
### 6. Domain interactions
#### Retrieve the list of domains registered on the network
\`\`\`typescript
import \{ domains \} from '@autonomys/auto-consensus';
import \{ activate \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
const domainList = await domains(api);
domainList.forEach((domain) => \{
console.log(\`Domain ID: \$\{domain.id\}\`);
console.log(\`Owner Address: \$\{domain.owner\}\`);
console.log(\`Creation Block: \$\{domain.creationBlock\}\`);
// ...other domain properties
\});
await api.disconnect();
\})();
\`\`\`
#### Retrieve staking summaries for all domains
\`\`\`typescript
import \{ domainStakingSummary \} from '@autonomys/auto-consensus';
import \{ activate \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
const stakingSummaries = await domainStakingSummary(api);
stakingSummaries.forEach((summary) => \{
console.log(\`Domain ID: \$\{summary.domainId\}\`);
console.log(\`Total Stake: \$\{summary.totalStake\}\`);
// ...other summary properties
\});
await api.disconnect();
\})();
\`\`\`
#### Retrieve the latest confirmed blocks for each domain
\`\`\`typescript
import \{ latestConfirmedDomainBlock \} from '@autonomys/auto-consensus';
import \{ activate \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
const confirmedBlocks = await latestConfirmedDomainBlock(api);
confirmedBlocks.forEach((blockInfo) => \{
console.log(\`Domain ID: \$\{blockInfo.id\}\`);
console.log(\`Block Number: \$\{blockInfo.number\}\`);
console.log(\`Block Hash: \$\{blockInfo.hash\}\`);
// ...other block properties
\});
await api.disconnect();
\})();
\`\`\`
---
### File: sdk/auto-dag-data.mdx
# Auto DAG Data Package
## Introduction
The \`@autonomys/auto-dag-data\` package provides utilities for creating and managing IPLD DAGs (InterPlanetary Linked Data Directed Acyclic Graphs) for files and folders. It facilitates chunking large files, handling metadata, and creating folder structures suitable for distributed storage systems like IPFS.
> **Note**: This package is an ES Module package and is designed to work with ESM applications. Check [this tutorial](https://dev.to/mangadev/set-up-a-backend-nodejs-typescript-jest-using-es-modules-1530) for guidance on setting up an ES module application.
## Features
- **File Chunking and DAG Creation**: Efficiently split large files into smaller chunks and create IPLD DAGs.
- **Folder Structure Creation**: Generate IPLD DAGs for directory structures.
- **Metadata Handling**: Add and manage metadata for files and folders.
- **CID Management**: Utilities for working with Content Identifiers (CIDs).
- **TypeScript Support**: Fully typed for enhanced developer experience.
## Installation
Install the package via \`npm\` or \`yarn\`:
\`\`\`bash
# Using npm
npm install @autonomys/auto-dag-data
# Using yarn
yarn add @autonomys/auto-dag-data
\`\`\`
## Importing
Import the \`auto-dag-data\` functions you need into your project:
\`\`\`typescript
// Import specific functions
import \{ processFileToIPLDFormat, processFolderToIPLDFormat, cidOfNode \} from '@autonomys/auto-dag-data';
// Or import everything
import * as dagData from '@autonomys/auto-dag-data';
\`\`\`
## Available Functions
> **Note**: All asynchronous functions return a \`Promise\` and should be used with \`await\` for proper execution flow. Wrap asynchronous calls in \`try...catch\` blocks to handle potential errors gracefully.
### File Processing
- \`processFileToIPLDFormat(blockstore, fileStream, fileSize, fileName): CID\`: Creates an IPLD DAG from a file stream.
### Folder Processing
- \`processFolderToIPLDFormat(blockstore, childCIDs, folderName, folderSize): CID\`: Generates an IPLD DAG from a folder structure.
### CID Utilities
- \`cidOfNode(node): CID\`: Creates a CID from an IPLD node.
- \`cidToString(cid): string\`: Converts a CID to its string representation.
- \`stringToCid(cidString): CID\`: Parses a CID string back into a CID object.
### Node Operations
- \`encodeNode(node): Uint8Array\`: Encodes an IPLD node to bytes.
- \`decodeNode(bytes): IPLDNode\`: Decodes bytes back into an IPLD node.
### Metadata Management
- \`createMetadataNode(metadata): IPLDNode\`: Creates a metadata node from metadata object.
- \`processMetadataToIPLDFormat(blockstore, metadata): CID\`: Processes metadata into IPLD format.
## Usage Examples
### 1. Creating an IPLD DAG from a File
Process a file into IPLD format for distributed storage:
\`\`\`typescript
import \{ processFileToIPLDFormat, cidToString \} from '@autonomys/auto-dag-data';
import \{ MemoryBlockstore \} from 'blockstore-core/memory';
import fs from 'fs';
(async () => \{
const fileStream = fs.createReadStream('path/to/your/file.txt');
const fileSize = fs.statSync('path/to/your/file.txt').size;
const blockstore = new MemoryBlockstore();
const fileCID = await processFileToIPLDFormat(blockstore, fileStream, fileSize, 'file.txt');
const cidString = cidToString(fileCID);
console.log(\`File CID: \$\{cidString\}\`);
\})();
\`\`\`
### 2. Creating an IPLD DAG from a Folder
Generate an IPLD DAG from a directory structure:
\`\`\`typescript
import \{ processFolderToIPLDFormat, decodeNode, cidToString \} from '@autonomys/auto-dag-data';
import \{ MemoryBlockstore \} from 'blockstore-core/memory';
import \{ CID \} from 'multiformats';
(async () => \{
// Example child CIDs from files in the folder
const childCIDs: CID[] = [
/* array of CIDs from folder contents */
];
const folderName = 'my-folder';
const folderSize = 1024; // total size of all children
const blockstore = new MemoryBlockstore();
const folderCID = await processFolderToIPLDFormat(blockstore, childCIDs, folderName, folderSize);
const node = await decodeNode(await blockstore.get(folderCID));
const cidString = cidToString(folderCID);
console.log(\`Folder CID: \$\{cidString\}\`);
\})();
\`\`\`
### 3. Working with CIDs
Convert between CID objects and strings:
\`\`\`typescript
import \{ cidOfNode, cidToString, stringToCid \} from '@autonomys/auto-dag-data';
(async () => \{
// Assuming you have an IPLD node
const cid = cidOfNode(someNode);
// Convert CID to string for storage or transmission
const cidString = cidToString(cid);
console.log(\`CID as string: \$\{cidString\}\`);
// Parse string back into CID object
const parsedCID = stringToCid(cidString);
console.log('CID object:', parsedCID);
\})();
\`\`\`
### 4. Encoding and Decoding Nodes
Handle IPLD node serialization:
\`\`\`typescript
import \{ encodeNode, decodeNode \} from '@autonomys/auto-dag-data';
(async () => \{
// Encode a node for storage
const encodedNode = encodeNode(someNode);
console.log('Encoded node:', encodedNode);
// Decode node from storage
const decodedNode = decodeNode(encodedNode);
console.log('Decoded node:', decodedNode);
\})();
\`\`\`
### 5. Handling Metadata
Create and process metadata for your files:
\`\`\`typescript
import \{ createMetadataNode, processMetadataToIPLDFormat, cidToString \} from '@autonomys/auto-dag-data';
import \{ MemoryBlockstore \} from 'blockstore-core/memory';
(async () => \{
const metadata = \{
name: 'My File',
description: 'This is a sample file',
created: new Date().toISOString(),
// ... other metadata fields
\};
// Create metadata node
const metadataNode = createMetadataNode(metadata);
// Process metadata to IPLD format
const blockstore = new MemoryBlockstore();
const metadataCID = await processMetadataToIPLDFormat(blockstore, metadata);
const cidString = cidToString(metadataCID);
console.log(\`Metadata CID: \$\{cidString\}\`);
\})();
\`\`\`
### 6. Complete File Processing Example
Full example of processing a file and extracting its CID:
\`\`\`typescript
import \{ processFileToIPLDFormat, cidToString \} from '@autonomys/auto-dag-data';
import \{ MemoryBlockstore \} from 'blockstore-core/memory';
import fs from 'fs';
(async () => \{
try \{
const filePath = 'path/to/your/file.txt';
const fileStream = fs.createReadStream(filePath);
const fileStats = fs.statSync(filePath);
const blockstore = new MemoryBlockstore();
const cid = await processFileToIPLDFormat(
blockstore,
fileStream,
fileStats.size,
'file.txt'
);
const cidString = cidToString(cid);
console.log(\`Successfully processed file. CID: \$\{cidString\}\`);
\} catch (error) \{
console.error('Error processing file:', error);
\}
\})();
\`\`\`
## Best Practices
### Error Handling
Always wrap asynchronous operations in try-catch blocks:
\`\`\`typescript
try \{
const cid = await processFileToIPLDFormat(blockstore, stream, size, name);
// Handle success
\} catch (error) \{
console.error('Processing failed:', error);
// Handle error appropriately
\}
\`\`\`
### Blockstore Management
Use appropriate blockstore implementations based on your needs:
\`\`\`typescript
// For temporary operations
import \{ MemoryBlockstore \} from 'blockstore-core/memory';
const tempBlockstore = new MemoryBlockstore();
// For persistent storage
import \{ FsBlockstore \} from 'blockstore-fs';
const persistentBlockstore = new FsBlockstore('./blocks');
\`\`\`
### Resource Cleanup
Ensure proper cleanup of resources when working with file streams:
\`\`\`typescript
const stream = fs.createReadStream(filePath);
try \{
const cid = await processFileToIPLDFormat(blockstore, stream, size, name);
// Process result
\} finally \{
stream.destroy(); // Clean up stream
\}
\`\`\`
---
### File: sdk/auto-drive/api_reference.mdx
# Auto-Drive API Reference
## Overview
Auto-Drive provides REST APIs for interacting with the Autonomys decentralized storage network. The APIs handle file operations, metadata management, and subscription services.
## API Documentation
The complete API documentation with all function signatures is available [here](https://mainnet.auto-drive.autonomys.xyz/api/docs).
## API Endpoints Structure
The API is organized into several main categories:
### Subscriptions Endpoints
- Manage your account subscription and view usage statistics
- \`GET /subscriptions/info\` - Get subscription information
- \`GET /subscriptions/credits\` - Check pending upload/download credits
### Upload Endpoints
- Progress tracking and upload management
- \`POST /uploads/file\` - Upload single files
- \`POST /uploads/folder\` - Upload folders and directories
- \`POST /uploads/multipart\` - Multipart uploads for large files
### Objects Endpoints
- Object metadata management and access control
- \`GET /objects\` - List your uploaded objects
- \`GET /objects/search\` - Search objects by name or CID
- \`POST /objects/share\` - Share objects and manage permissions
### Download Endpoints
- Support for password-protected downloads
- \`GET /downloads/\{cid\}\` - Download files by CID
- \`GET /downloads/stream/\{cid\}\` - Streaming downloads
## Base URLs
- **Mainnet**: \`https://mainnet.auto-drive.autonomys.xyz\`
- **Taurus Testnet**: \`https://taurus.auto-drive.autonomys.xyz\`
## Authentication
All API requests require authentication using one of these methods:
### API Key Authentication (Recommended)
Include your API key in the request headers:
\`\`\`http
Authorization: Bearer your-api-key
X-Auth-Provider: apikey
\`\`\`
### JWT Token Authentication
For advanced use cases, JWT tokens are supported:
\`\`\`http
Authorization: Bearer your-jwt-token
X-Auth-Provider: jwt
\`\`\`
> **Security Note:** Keep your API keys secure and never share them with unauthorized parties.
## Auto-Drive Services
Auto-Drive consists of two main services:
### 1. Auto-Drive Storage API
Handles all file operations and object management:
- **File uploads** (single and multipart)
- **Object metadata management**
- **Access control and permissions**
- **Subscription management**
### 2. Auto-Drive Download Gateway
Provides optimized file download capabilities:
- **Direct file downloads**
- **Asynchronous downloads**
- **Bandwidth optimization**
## Response Format
All API responses follow a consistent JSON format with appropriate HTTP status codes. Error responses include detailed error messages to help with debugging.
## Rate Limits
API usage is subject to your subscription limits:
- **Upload limit**: 100MB per month (default)
- **Download limit**: 5GB per month (default)
Check your current limits using the subscription endpoints or in the Auto-Drive dashboard.
## Making Direct API Calls
You can make direct HTTP requests to the API endpoints:
\`\`\`bash
# Example: Get subscription info
curl -X GET "https://mainnet.auto-drive.autonomys.xyz/subscriptions/info" \
-H "Authorization: Bearer your-api-key" \
-H "X-Auth-Provider: apikey"
\`\`\`
\`\`\`bash
# Example: Upload a file
curl -X POST "https://mainnet.auto-drive.autonomys.xyz/uploads/file" \
-H "Authorization: Bearer your-api-key" \
-H "X-Auth-Provider: apikey" \
-H "Content-Type: multipart/form-data" \
-F "file=@path/to/your/file.txt"
\`\`\`
For detailed endpoint specifications, request/response schemas, and interactive testing, visit the [complete API documentation](https://mainnet.auto-drive.autonomys.xyz/api/docs).
---
### File: sdk/auto-drive/available_functions.mdx
# Auto-Drive SDK — Available Functions
All functions are available as methods on the \`AutoDriveApi\` instance returned by \`createAutoDriveApi\`. Upload functions that operate on the local filesystem (Node.js only) are accessed via the \`fs\` sub-module.
\`\`\`typescript
import \{ createAutoDriveApi, fs \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.MAINNET \})
\`\`\`
---
## Upload Operations
- \`api.uploadFile(file, options?, uploadChunkSize?): Promise<string>\` — Uploads a \`GenericFile\` (custom async-iterable interface) with optional encryption and compression. Returns the CID.
- \`fs.uploadFileFromFilepath(api, filePath, options?): Promise<string>\` — **Node.js only.** Uploads a file from a local filesystem path with optional encryption and compression. Returns the CID.
- \`api.uploadFileFromInput(file, options?, uploadChunkSize?): Promise<string>\` — Uploads a browser \`File\` object (e.g. from an \`<input type="file">\` event). Returns the CID.
- \`api.uploadFileFromBuffer(buffer, name, options?, uploadChunkSize?): Promise<string>\` — Uploads a \`Buffer\` directly with a given filename. Returns the CID.
- \`api.uploadObjectAsJSON(object, name?, options?, uploadChunkSize?): Promise<string>\` — Serializes any value as JSON and uploads it. Returns the CID.
- \`api.uploadFolderFromInput(fileList, options?): Promise<string>\` — Uploads a browser \`FileList\` or \`File[]\` array as a folder. Returns the root CID.
- \`api.uploadFileWithinFolderUpload(uploadId, file, uploadChunkSize?, options?): Promise<string>\` — Uploads a single file into an existing folder upload session identified by \`uploadId\`. Returns the CID.
**\`UploadFileOptions\`**
\`\`\`typescript
type UploadFileOptions = \{
password?: string // enables AES-256-GCM client-side encryption
compression?: boolean
onProgress?: (progress: number) => void
\}
\`\`\`
---
## Download Operations
- \`api.downloadFile(cid, password?): Promise<AsyncIterable<Buffer>>\` — Downloads a file by CID. Pass the same \`password\` used at upload time to decrypt.
- \`api.publishObject(cid): Promise<string>\` — Creates a publicly accessible download URL for the given CID. Returns the URL string.
- \`api.isFileCached(cid): Promise<boolean>\` — Returns whether the file is currently cached and immediately available for download.
- \`api.createAsyncDownload(cid): Promise<AsyncDownload>\` — Queues a large file for async background download. Returns an \`AsyncDownload\` descriptor.
- \`api.getAsyncDownloads(): Promise<AsyncDownload[]>\` — Returns all active async download jobs for the current account.
- \`api.getAsyncDownload(downloadId): Promise<AsyncDownload>\` — Returns the status of a single async download by ID.
- \`api.dismissAsyncDownload(downloadId): Promise<void>\` — Removes a completed or failed async download from the queue.
---
## File Discovery
- \`api.getMyFiles(page, limit): Promise<PaginatedResult<ObjectSummary>>\` — Returns a paginated list of the current user's uploaded files.
- \`api.searchByNameOrCIDInMyFiles(value): Promise<ObjectSummary[]>\` — Searches for files by name or CID within the current user's files.
- \`api.searchByNameOrCID(value): Promise<ObjectSummary[]>\` — Global search across all public files by name or CID.
---
## Account and Credits
- \`api.me(): Promise<UserInfo>\` — Returns the current authenticated user's profile information.
- \`api.getPendingCredits(): Promise<\{ upload: number; download: number \}>\` — Returns the current user's remaining upload and download credit balances.
- \`api.getSubscriptionInfo(): Promise<SubscriptionInfo>\` — Returns the current user's subscription tier and allocation details.
- \`api.getStoragePrice(): Promise<StoragePrice>\` — Returns the current live storage price from the protocol. No API key required.
\`\`\`typescript
type StoragePrice = \{
shannonsPerByte: number
ai3PerGb: number
\}
\`\`\`
---
## Pay with AI3 — Payment Intents
These functions implement the complete [Pay with AI3](/auto_drive/pay_with_ai3) credit purchase flow. See the [developer integration guide](/sdk/auto-drive/pay_with_ai3) for full examples.
**Four-step flow:**
\`\`\`
1. createPaymentIntent(sizeBytes) — locks price, returns amount + contract details
2. send ai3AmountWei to contractAddress — call payIntent(intentId) on-chain (your wallet code)
3. watchPaymentTransaction(id, txHash) — notify Auto Drive of the transaction hash
4. waitForPaymentCompletion(id) — poll until COMPLETED (credits applied)
\`\`\`
- \`api.getPaymentContractInfo(): Promise<PaymentContractInfo>\` — Returns the Auto-EVM contract address, chain ID, and \`payIntent\` ABI. No API key required. Called internally by \`createPaymentIntent\`; export this for client-side wallet pre-fetching.
- \`api.createPaymentIntent(sizeBytes): Promise<PaymentIntent>\` — Locks the current storage price for the authenticated account and returns a payment intent. The price is locked for **10 minutes**.
- \`api.watchPaymentTransaction(intentId, txHash): Promise<void>\` — Submits the on-chain transaction hash to Auto Drive. The backend polls for 6 block confirmations before granting credits.
- \`api.getPaymentIntentStatus(intentId): Promise<\{ id: string; status: PaymentIntentStatus \}>\` — Returns the current status of a payment intent.
- \`api.waitForPaymentCompletion(intentId, options?): Promise<PaymentIntentTerminalStatus>\` — Polls until the intent reaches a terminal state (\`COMPLETED\`, \`EXPIRED\`, \`FAILED\`, or \`OVER_CAP\`). Resolves with the terminal status.
**Supporting types:**
\`\`\`typescript
type PaymentContractInfo = \{
chainId: number
contractAddress: string
payIntentAbi: readonly unknown[]
\}
type PaymentIntent = \{
intentId: string
ai3AmountWei: string // exact value to send as msg.value (in Shannons)
ai3Amount: string // human-readable AI3 amount
contractAddress: string
shannonsPerByte: string
expiresAt: string // ISO 8601 timestamp, 10 minutes from creation
\}
type PaymentIntentStatus =
| 'PENDING' // awaiting on-chain payment
| 'CONFIRMED' // payment received, awaiting final credit grant
| 'COMPLETED' // credits applied to account
| 'EXPIRED' // no payment received within 10 minutes
| 'FAILED' // payment amount below quoted price
| 'OVER_CAP' // account's 100 GB limit would be exceeded
type PaymentIntentTerminalStatus = 'COMPLETED' | 'EXPIRED' | 'FAILED' | 'OVER_CAP'
type PollOptions = \{
pollIntervalMs?: number // default: 3000
timeoutMs?: number // default: 300000 (5 minutes)
\}
\`\`\`
---
### File: sdk/auto-drive/create_api_key.mdx
# Creating Your Auto-Drive API Key
## Authentication Overview
All requests to the Auto-Drive APIs require authentication using an API key. The API key is a string that authenticates your requests to the Auto-Drive APIs.
## Step-by-Step Guide to Create an API Key
### 1. Access Auto-Drive Dashboard
1. Open [Auto Drive](https://ai3.storage/)
2. Sign in via Google, Discord, GitHub or Wallet
### 2. Navigate to Developer Section
1. Once you're logged in, click on the **developers** section in the left sidebar menu
2. In the developers section, click on **'Create API Key'**
3. Read the modal message and click on generate
### 3. Alternative Method - Via Profile
You can also create an API key through your profile:
1. Click on \`Profile\` in the dashboard
2. Create your API key from the profile section
## Understanding Your Dashboard
Once logged in, your Dashboard will show:
- Your upload limit (currently **20MB** per month on mainnet and **100MB** per month on Taurus testnet)
- Your download limit (currently **5GB** per month on both mainnet and Taurus testnet)
- A list of **uploaded files** and their **CIDs**
- Options to **Download**, **Share** or **Remove** each file
> *Note:* Removing a file does not delete it from the DSN as it is permanent storage. It only removes the file from your Dashboard.
## Using Your API Key
Once you have your API key, you can use it to authenticate your requests:
\`\`\`typescript
import \{ createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{
apiKey: 'your-api-key-here',
network: NetworkId.TAURUS // or NetworkId.MAINNET
\})
\`\`\`
## Network Selection
Auto Drive is available on both:
- **Mainnet** (\`NetworkId.MAINNET\`) - Production environment
- **Taurus Testnet** (\`NetworkId.TAURUS\`) - Testing environment
Choose the appropriate network based on your needs.
## Security Best Practices
- Keep your API key secure and never commit it to version control
- Use environment variables to store your API key
- Regenerate your API key if you suspect it has been compromised
## Next Steps
With your API key created, you can now:
- Install the Auto-Drive SDK
- Start uploading and downloading files
- Explore the full API reference
- Try the usage examples
---
### File: sdk/auto-drive/encryption.mdx
---
title: File Encryption Specification
---
# File Encryption Specification
Auto Drive supports optional **client-side encryption** — files are encrypted on your device before they are transmitted to the network. No one else, including storage nodes, can read your data without your password.
This page describes the encryption algorithm, key derivation process, and chunking architecture used when you supply a \`password\` to an upload function.
---
## Overview
| Property | Value |
|---|---|
| **Algorithm** | AES-256-GCM |
| **Key derivation** | PBKDF2 + SHA-256 |
| **KDF iterations** | 100,000 |
| **Salt length** | 32 bytes (randomly generated per file) |
| **Chunk size** | 1 MB |
| **IV per chunk** | 16 bytes (randomly generated per chunk) |
---
## Encryption Algorithm: AES-256-GCM
Auto Drive uses **AES-256-GCM** (Advanced Encryption Standard, 256-bit key, Galois/Counter Mode). This algorithm provides two guarantees simultaneously:
- **Confidentiality** — data is encrypted with a 256-bit key, making brute-force attacks computationally infeasible.
- **Integrity** — GCM mode appends an authentication tag to each encrypted chunk. If anyone modifies even a single bit of the ciphertext, decryption fails immediately with a detectable error.
Modern processors include hardware acceleration for AES operations, so encryption and decryption add minimal overhead for most workloads.
---
## Key Derivation: PBKDF2
Passwords are not used directly as encryption keys. Instead, Auto Drive converts your password into a cryptographic key using **PBKDF2** (Password-Based Key Derivation Function 2):
1. A **32-byte random salt** is generated using a cryptographically secure random number generator. This salt is unique per file and is stored alongside the encrypted data (it does not need to be secret).
2. The password and salt are combined and processed through **SHA-256**, repeated **100,000 times**.
3. The output is a 256-bit key used for all chunks in the file.
The high iteration count makes dictionary and brute-force attacks against the password computationally expensive, even if an attacker retrieves the encrypted file from the network.
\`\`\`
password + random_salt
│
▼
PBKDF2-SHA256
(100,000 iterations)
│
▼
256-bit encryption key
\`\`\`
---
## File Chunking
Large files are split into **1 MB chunks** before encryption. Each chunk is processed independently:
1. A unique **16-byte initialization vector (IV)** is generated per chunk via a cryptographically secure random source.
2. The chunk is encrypted with AES-256-GCM using the derived key and the chunk-specific IV.
3. GCM produces the encrypted chunk data plus an **authentication tag**.
Because each chunk has its own IV, identical chunks in the same file produce different ciphertext — preventing pattern analysis.
\`\`\`
File
│
├── Chunk 1 ── IV₁ ── AES-256-GCM ──► [ciphertext₁ + auth_tag₁]
├── Chunk 2 ── IV₂ ── AES-256-GCM ──► [ciphertext₂ + auth_tag₂]
└── Chunk N ── IVₙ ── AES-256-GCM ──► [ciphertextₙ + auth_tagₙ]
\`\`\`
The 1 MB chunk size balances memory efficiency with processing speed, and enables streaming uploads and downloads without loading the entire file into memory.
---
## Network Privacy
Because encryption happens entirely on the client before any data leaves your device:
- **Content delivery nodes** see only ciphertext.
- **Farmers** in the distributed hash table layer store only encrypted segments.
- **Archival storage participants** hold only encrypted data.
No single point in the network ever holds the complete file in unencrypted form. This privacy guarantee persists as the network evolves, independent of individual node operators.
---
## Performance Characteristics
- **Key derivation** (PBKDF2, 100,000 iterations) happens once per file. This is intentionally slow to resist password attacks, but adds a fixed one-time cost regardless of file size.
- **Per-chunk encryption** runs with hardware AES acceleration on modern CPUs and is effectively negligible for typical upload speeds.
- **Streaming** — chunked processing means Auto Drive never needs to hold the entire file in memory, making it practical for very large files.
---
## Using Encryption
Pass a \`password\` option to any upload function in the \`@autonomys/auto-drive\` SDK:
\`\`\`typescript
import \{ createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.MAINNET \})
// Upload with encryption
const cid = await api.uploadFileFromInput(file, \{
password: 'your-strong-password',
\})
// Download and decrypt
const stream = await api.downloadFile(cid, \{ password: 'your-strong-password' \})
\`\`\`
> **Important:** Your password is never transmitted to the network. If you lose it, the encrypted file cannot be recovered — there is no password reset mechanism.
---
## Further Reading
- [Auto Drive Overview](/auto_drive)
- [Auto Drive SDK — Usage Examples](/sdk/auto-drive/usage_examples)
- [Auto Drive SDK — Available Functions](/sdk/auto-drive/available_functions)
---
### File: sdk/auto-drive/gateway.mdx
# Auto Drive Gateway
## What is the Auto Drive Gateway?
Auto Gateway is a unified gateway solution designed for seamlessly accessing files or folders permanently stored on the Autonomys Mainnet & Taurus testnet through a single, streamlined interface. The gateway is available [here](https://gateway.autonomys.xyz/).
## How Gateways Work
In decentralized storage systems, files are identified by their Content Identifier (CID) rather than traditional file paths. A gateway acts as a bridge between the decentralized network and standard web protocols, allowing you to access stored content using familiar HTTP requests.
Think of it as a web interface that translates CIDs into downloadable files - similar to how IPFS gateways work, but specifically designed for the Autonomys network.
## When to Use Auto Drive Gateway
### Direct File Access
- **Public file sharing**: Share files with others who don't have the Auto Drive SDK
- **Web integration**: Embed files directly in websites using standard HTML tags
- **Browser downloads**: Allow users to download files directly through their browser
- **CDN-like functionality**: Serve static assets like images, documents, or media files
### Development & Testing
- **Quick verification**: Quickly check if your uploads were successful
- **Debugging**: Verify file integrity without writing code
- **Prototyping**: Access files during development without implementing full SDK integration
### Integration Scenarios
- **Third-party applications**: Enable other services to access your stored files
- **API responses**: Return direct download links in your API responses
- **Mobile apps**: Simple file access without complex SDK integration
## Gateway Endpoints
### Retrieve File by CID
\`\`\`
GET /file/:cid
\`\`\`
Retrieves a file based on its Content Identifier (CID).
**Responses:**
- \`200 OK\`: Successfully retrieves and serves the requested file
- \`302 Redirect\`: Redirects to \`/folder/:cid\` if the CID corresponds to a folder
- \`404 Not Found\`: If no file is found for the provided CID
### Retrieve Folder by CID
\`\`\`
GET /folder/:cid
\`\`\`
Retrieves a folder based on its Content Identifier (CID).
**Responses:**
- \`200 OK\`: Successfully retrieves and serves the requested folder
- \`302 Redirect\`: Redirects to \`/file/:cid\` if the CID corresponds to a file
- \`404 Not Found\`: If no folder is found for the provided CID
## Usage Examples
### Direct Browser Access
\`\`\`
https://gateway.autonomys.xyz/file/your-cid-here
\`\`\`
### HTML Integration
\`\`\`html
<!-- Display an image -->
<img src="https://gateway.autonomys.xyz/file/your-image-cid" alt="My Image">
<!-- Download link -->
<a href="https://gateway.autonomys.xyz/file/your-document-cid" download>Download Document</a>
\`\`\`
### API Response
\`\`\`javascript
const response = \{
filename: "document.pdf",
downloadUrl: \`https://gateway.autonomys.xyz/file/\$\{fileCid\}\`,
size: 1024000
\}
\`\`\`
## Finding Your CIDs
To use the gateway, you'll need the CID of your uploaded file or folder. You can find CIDs:
1. In your [Auto Drive Dashboard](https://ai3.storage/) after uploading files
2. From the return value of SDK upload functions
3. In your application logs where upload responses are recorded
Simply enter your CID in the gateway interface or construct the URL directly for programmatic access.
---
### File: sdk/auto-drive/overview_setup.mdx
# Auto-Drive Overview & Setup
## Introduction
The \`@autonomys/auto-drive\` package provides a set of tools to interact with the Autonomys Auto-Drive API.
## Features
- **Autonomys DSN**: Permanently store files on the Autonomys' DSN (Decentralized Store Network).
- **CID Management**: Just like with IPFS, each upload gets its own CID (Content Identifier).
- **TypeScript Support**: Fully typed for an enhanced developer experience.
## Authentication
All requests to the Auto-Drive APIs require authentication using an API key.
> **Need an API key?** See our [API Key Setup Guide](/sdk/auto-drive/create_api_key) for detailed instructions on creating your API key.
## Auto Drive Dashboard
The Auto Drive dashboard provides a web interface for managing your files and account:
- View your upload and download limits
- Browse and manage your uploaded files
- Share files with others
- Create and manage API keys
Access the dashboard at [Auto Drive](https://ai3.storage/) and sign in with Google, Discord, or GitHub.
### Sharing files
You can share files directly from the dashboard by clicking the \`Share\` button next to any file. You can share using a direct link or provide a user's public ID to share all their files.
## Installation
Install the package via \`npm\` or \`yarn\`:
\`\`\`bash
# Using npm
npm install @autonomys/auto-drive
npm install @autonomys/auto-utils
# Using yarn
yarn add @autonomys/auto-drive
yarn add @autonomys/auto-utils
\`\`\`
## Importing
Import the \`auto-drive\` functions you need into your project:
\`\`\`typescript
// Import specific functions
import \{ fs,createAutoDriveApi \} from '@autonomys/auto-drive';
import \{ NetworkId \} from '@autonomys/auto-utils'
// Or import everything
import * as drive from '@autonomys/auto-drive';
import \{ NetworkId \} from '@autonomys/auto-utils'
\`\`\`
## Network Configuration
As [Auto Drive](https://ai3.storage) is available on both Mainnet and the Taurus testnet, you need to configure the network when using the package:
\`\`\`ts
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{
apiKey: 'your-api-key',
network: NetworkId.TAURUS | NetworkId.MAINNET
\})
\`\`\`
---
### File: sdk/auto-drive/pay_with_ai3.mdx
---
title: Pay with AI3 — Developer Integration
---
# Pay with AI3 — Developer Integration
This page covers how to integrate permissionless Auto Drive credit purchasing into your own application using the \`AutoDriveCreditsReceiver\` smart contract and the credits API.
For the end-user purchase walkthrough, see the [Pay with AI3 guide](/auto_drive/pay_with_ai3).
---
## How It Works
The payment system is built around a **payment intent** model. Each purchase follows four steps:
1. Your app fetches a **price quote** from the backend — reflects the live protocol-level DSN storage cost via a Substrate RPC connection to the Autonomys consensus chain, plus a service fee.
2. The backend creates a **payment intent** — a server-side record that locks the price and binds a \`bytes32\` intent ID to the authenticated account for up to 10 minutes.
3. Your app calls \`payIntent(intentId)\` on the \`AutoDriveCreditsReceiver\` contract on Auto-EVM, sending the exact quoted AI3 amount as \`msg.value\`.
4. Your app submits the transaction hash to the watch endpoint; the backend polls for **6 block confirmations** and then grants the credits.
Credits are available immediately after confirmation and can be used via the dashboard, the AutoSDK, or the REST API.
---
## Smart Contract
| Field | Value |
|---|---|
| **Contract** | \`AutoDriveCreditsReceiver\` |
| **Network** | Autonomys Auto-EVM |
| **Chain ID** | \`870\` |
| **Address** | \`0xBa5bed8325183c0807EcBC80C82D40Dc7Ac5cbf7\` |
View on Blockscout: [AutoDriveCreditsReceiver](https://explorer.auto-evm.mainnet.autonomys.xyz/address/0xBa5bed8325183c0807EcBC80C82D40Dc7Ac5cbf7)
### \`payIntent\`
\`\`\`solidity
function payIntent(bytes32 intentId) public payable whenNotPaused;
\`\`\`
\`intentId\` is the \`bytes32\` value returned by \`POST /intents/\`. Send the exact quoted amount as \`msg.value\` — the transaction will fail if the value does not match.
The \`whenNotPaused\` modifier allows the protocol team to pause payments in the event of a critical issue.
### Event
\`\`\`solidity
event IntentPaymentReceived(bytes32 indexed intentId, uint256 paymentAmount);
\`\`\`
Emitted on successful payment. Listen for this event to confirm receipt before calling the watch endpoint.
---
## Payment Intent State Machine
\`\`\`
PENDING ──► CONFIRMED ──► COMPLETED
│
├──► EXPIRED (no payment received within 10 minutes)
│
└──► FAILED (payment amount below the quoted price)
CONFIRMED ──► OVER_CAP (account's 100 GB purchased credit limit exceeded)
\`\`\`
> Always fetch a fresh quote immediately before creating an intent. Prices reflect live protocol costs and can change between requests.
---
## API Reference
Base URL: \`https://api.autonomys.xyz\`
### Get a Price Quote
\`\`\`http
GET /intents/price
\`\`\`
Returns the current AI3 cost (in Shannons) per GB. No authentication required.
**Example response:**
\`\`\`json
\{
"pricePerGb": "1000000000000000000",
"currency": "AI3"
\}
\`\`\`
---
### Create a Payment Intent
\`\`\`http
POST /intents/
\`\`\`
Locks the current price for the authenticated account and returns an intent ID.
> **Authentication:** Requires a Google OAuth token in the \`Authorization\` header. The intent is bound to this account — credits cannot be redirected elsewhere.
**Request body:**
\`\`\`json
\{
"storageGb": 10
\}
\`\`\`
**Response:**
\`\`\`json
\{
"intentId": "0xabc123...",
"amount": "10000000000000000000",
"expiresAt": "2026-05-12T12:10:00Z"
\}
\`\`\`
Pass \`intentId\` as the argument to \`payIntent\` and \`amount\` as \`msg.value\`.
---
### Confirm a Transaction
\`\`\`http
POST /intents/:id/watch
\`\`\`
Submit the on-chain transaction hash. The backend polls for 6 confirmations before crediting the account.
**Request body:**
\`\`\`json
\{
"txHash": "0xdef456..."
\}
\`\`\`
---
## Integration Patterns
### Pattern 1 — App-managed credits
Your application holds a funded Auto-EVM wallet and purchases credits on behalf of users. Useful for apps that abstract storage costs away entirely.
\`\`\`typescript
import \{ ethers \} from 'ethers'
const CONTRACT_ADDRESS = '0xBa5bed8325183c0807EcBC80C82D40Dc7Ac5cbf7'
const ABI = [
'function payIntent(bytes32 intentId) payable',
'event IntentPaymentReceived(bytes32 indexed intentId, uint256 paymentAmount)',
]
async function purchaseCredits(signer: ethers.Signer, authToken: string, storageGb: number) \{
// 1. Fetch fresh quote
const quoteRes = await fetch('https://api.autonomys.xyz/intents/price')
const \{ pricePerGb \} = await quoteRes.json()
// 2. Create intent — price locked for 10 minutes
const intentRes = await fetch('https://api.autonomys.xyz/intents/', \{
method: 'POST',
headers: \{
'Content-Type': 'application/json',
Authorization: \`Bearer \$\{authToken\}\`,
\},
body: JSON.stringify(\{ storageGb \}),
\})
const \{ intentId, amount \} = await intentRes.json()
// 3. Call payIntent on Auto-EVM — send exact quoted amount
const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, signer)
const tx = await contract.payIntent(intentId, \{ value: amount \})
await tx.wait()
// 4. Submit tx hash — backend confirms 6 blocks then grants credits
await fetch(\`https://api.autonomys.xyz/intents/\$\{intentId\}/watch\`, \{
method: 'POST',
headers: \{ 'Content-Type': 'application/json' \},
body: JSON.stringify(\{ txHash: tx.hash \}),
\})
return tx.hash
\}
\`\`\`
### Pattern 2 — User-managed credits
Direct users to the [Auto Drive dashboard](https://ai3.storage/) to purchase credits themselves using the [Pay with AI3 guide](/auto_drive/pay_with_ai3). Your application uses the AutoSDK with the user's API key — no on-chain interaction required in your code.
This is the lower-complexity option and is suitable for most applications.
---
## Using Credits After Purchase
Once purchased, credits are consumed automatically when uploading via the \`@autonomys/auto-drive\` SDK. No additional configuration is needed.
\`\`\`typescript
import \{ createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.MAINNET \})
// Credits are deducted automatically on upload
const cid = await api.uploadFileFromInput(file, \{
password: 'optional-encryption-password', // enable AES-256-GCM encryption
\})
console.log('Uploaded CID:', cid)
\`\`\`
Credits are consumed in **FIFO expiry order** — the soonest-to-expire credits are spent first. Free monthly credits are consumed before purchased ones.
---
## Limits and Expiry
| Parameter | Value |
|---|---|
| **Maximum purchased credits** | 100 GB per account |
| **Credit expiry** | 90 days from grant date |
| **Intent timeout** | 10 minutes |
| **Confirmation blocks** | 6 |
---
## Further Reading
- [Pay with AI3 — User Guide](/auto_drive/pay_with_ai3)
- [Auto Drive Overview & Setup](/sdk/auto-drive/overview_setup)
- [Available Functions](/sdk/auto-drive/available_functions)
- [Usage Examples](/sdk/auto-drive/usage_examples)
---
### File: sdk/auto-drive/s3_layer.mdx
# Auto Drive S3 Layer Guide
## Overview
**Auto Drive** provides an **S3-compatible API layer** that allows you to interact with **decentralized storage(DSN)** using standard **Amazon Web Services Simple Storage Service (AWS S3)** SDK commands. This bridges the gap between familiar cloud storage patterns and next-generation decentralized infrastructure, giving developers the best of both worlds: the **reliability and developer experience of S3 APIs** with the **permanence and censorship-resistance** of decentralized storage.
For those unfamiliar, [Amazon Web Services Simple Storage Service (AWS S3)](https://aws.amazon.com/s3/) is an industry-standard object storage service that powers much of the modern web's file storage needs. **Auto Drive** maintains complete compatibility with S3's APIs while storing your data on a **decentralized network** instead of **centralized servers**.
## How It Works
Auto Drive maintains an object_mappings table in the database that maps S3 object keys to Content Identifiers (CIDs). When you upload via S3 API, the system:
1. Stores the file content on the decentralized network (DSN)
2. Records the key-to-CID mapping in the database
3. Returns the CID as the ETag for S3 compatibility
4. Enables cross-API access between S3 and Auto Drive APIs
## Key Features
### 1. **Standard S3 SDK Compatibility**
- Use official AWS S3 SDK (\`@aws-sdk/client-s3\`)
- Supports all major S3 operations: \`PutObject\`, \`GetObject\`, \`HeadObject\`, multipart uploads (\`CreateMultipartUploadCommand\`, \`UploadPartCommand\` & \`CompleteMultipartUploadCommand\`)
- No code changes required for existing S3 applications
### 2. **Enhanced Metadata Support**
\`\`\`typescript
// Compression and encryption metadata
const command = new PutObjectCommand(\{
Bucket: "https://public.auto-drive.autonomys.xyz/api/s3",
Key: "file.txt",
Body: buffer,
Metadata: \{
compression: "ZLIB",
encryption: "AES_256_GCM",
\},
\});
\`\`\`
### 3. **Range Requests**
- Partial file downloads supported
- Standard HTTP Range headers
\`\`\`typescript
const command = new GetObjectCommand(\{
Bucket: bucket,
Key: key,
Range: "bytes=0-9", // Download first 10 bytes
\});
\`\`\`
### 4. **Multipart Upload Support**
- Full multipart upload workflow
- Create → Upload Parts → Complete pattern
- Automatic chunking for large files
\`\`\`typescript
// Complete multipart upload example
const key = "large-file.txt";
const fileContent = Buffer.from("Large file content...");
// Step 1: Create multipart upload
const createCommand = new CreateMultipartUploadCommand(\{
Bucket: "https://public.auto-drive.autonomys.xyz/api/s3",
Key: key,
\});
const createResult = await s3Client.send(createCommand);
const uploadId = createResult.UploadId!;
// Step 2: Upload parts
const uploadPartCommand = new UploadPartCommand(\{
Bucket: "https://public.auto-drive.autonomys.xyz/api/s3",
Key: key,
UploadId: uploadId,
PartNumber: 1,
Body: fileContent,
\});
const partResult = await s3Client.send(uploadPartCommand);
// Step 3: Complete multipart upload
const completeCommand = new CompleteMultipartUploadCommand(\{
Bucket: "https://public.auto-drive.autonomys.xyz/api/s3",
Key: key,
UploadId: uploadId,
MultipartUpload: \{
Parts: [
\{
ETag: partResult.ETag!,
PartNumber: 1,
\},
],
\},
\});
const completeResult = await s3Client.send(completeCommand);
\`\`\`
## Configuration
### Client Setup
\`\`\`typescript
const s3Client = new S3Client(\{
region: "us-east-1",
credentials: \{
accessKeyId: "your-auto-drive-api-key", // Your Auto Drive API key
secretAccessKey: "", // Always empty for Auto Drive
\},
bucketEndpoint: true, // Required for custom endpoints
\});
\`\`\`
### Endpoint Configuration
\`\`\`typescript
// The "Bucket" parameter becomes part of the endpoint URL
const Bucket = \`\$\{baseURL\}/s3\`; // e.g., "https://public.auto-drive.autonomys.xyz/api/s3"
// No actual S3 bucket is created - it's just URL routing
\`\`\`
- Mainnet: \`https://public.auto-drive.autonomys.xyz/api/s3\`
- Taurus Testnet: \`https://public.taurus.auto-drive.autonomys.xyz/api/s3\`
- Base URL: http://localhost:3000/s3 (development)
- Bucket name becomes the full endpoint path
- No actual bucket concept - uses path-based routing
## Authentication
- Uses Auto Drive API key-based authentication
- Integrates with Auto Drive's user management system
- API key goes in \`accessKeyId\`, \`secretAccessKey\` remains empty
- Supports the same authentication as the Auto Drive API
## File Ownership & Access
- **Cross-API compatibility**: Files uploaded via S3 API are accessible through Auto Drive API and vice versa
- **Centralized ownership**: File ownership is tracked centrally, not per-API
- **Content deduplication**: Multiple users uploading identical content will share the same underlying CID
- **Shared access**: If different users upload the same file via different APIs, both can access it through either API
## Storage Characteristics
### Content Addressing
- Files are stored using Content Identifiers (CIDs)
- ETag returned is the actual CID of the uploaded content
- Immutable storage - same content always produces same CID
### Decentralized Backend
- Files stored on the DSN of Autonomys Network (available on Autonomys Mainnet & Testnet)
- Automatic replication and redundancy
- No single point of failure
## Migrating from AWS S3
For developers moving from traditional AWS S3:
1. **Update endpoint** to Auto Drive server URL
2. **Change credentials** to use Auto Drive API key (with empty secret)
3. **Set \`bucketEndpoint\`**: true in S3Client configuration
4. **Handle longer response times** due to blockchain network latency
5. **Expect CIDs as ETags** instead of MD5 hashes
6. **Update bucket references** to use full endpoint URLs
7. **Test multipart uploads** as they may behave slightly differently
\`\`\`typescript
// Before (AWS S3)
const s3Client = new S3Client(\{
region: "us-east-1",
credentials: \{
accessKeyId: "AKIA...",
secretAccessKey: "abc123...",
\},
\});
// After (Auto Drive)
const s3Client = new S3Client(\{
region: "us-east-1",
credentials: \{
accessKeyId: "your-auto-drive-api-key",
secretAccessKey: "",
\},
bucketEndpoint: true,
\});
\`\`\`
## Limitations & Considerations
### Performance
- The DSN (on-chain) storage has higher latency than traditional S3
- Multipart uploads recommended for files > 5MB
- Range requests may have different performance characteristics
### Compatibility Notes
- Not all S3 features supported (e.g., versioning, lifecycle policies)
- Custom metadata handling for compression/encryption
- Bucket operations are virtual (no actual bucket creation)
## Best Practices
1. **Use Multipart Uploads** for files larger than 5MB
2. **Leverage Range Requests** for partial file access
3. **Include Compression/Encryption** metadata when needed
4. **Handle ETags as CIDs** for content verification
5. **Implement Retry Logic** for blockchain network delays
## Error Handling
- Standard S3 error responses
- Additional blockchain-specific error codes
- Network timeouts may be longer than traditional S3
This S3 layer provides a familiar interface while leveraging the benefits of decentralized storage, making it easy to migrate existing S3-based applications to Auto Drive.
---
### File: sdk/auto-drive/usage_examples.mdx
# Auto-Drive Usage Examples
## 1. Uploading a file from a filepath (not available in browser)
\`\`\`typescript
import \{ fs,createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.TAURUS \}) // Initialize your API instance with API key
const filePath = 'path/to/your/file.txt' // Specify the path to your file
const options = \{
password: 'your-encryption-password', // Optional: specify a password for encryption
compression: true,
// an optional callback useful for large file uploads
onProgress?: (progress: number) => \{
console.log(\`The upload is completed is \$\{progress\}% completed\`)
\}
\}
const cid = await fs.uploadFileFromFilepath(api, filePath, options)
console.log(\`The file is uploaded and its cid is \$\{cid\}\`)
\`\`\`
## 2. Uploading a file using File interface
\`\`\`typescript
import \{ uploadFileFromInput, createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.TAURUS \}) // Initialize your API instance with API key
// e.g Get File from object from HTML event
const file: File = e.target.value // Substitute with your file
const options = \{
password: 'your-encryption-password', // Optional: specify a password for encryption
compression: true,
\}
const cid = await api.uploadFileFromInput(file, options)
console.log(\`The file is uploaded and its cid is \$\{cid\}\`)
\`\`\`
## 3. Uploading a folder (not available in browser)
\`\`\`typescript
import \{ createAutoDriveApi, fs \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.TAURUS \}) // Initialize your API instance with API key
const folderPath = 'path/to/your/folder' // Specify the path to your folder
const options = \{
uploadChunkSize: 1024 * 1024, // Optional: specify the chunk size for uploads
password: 'your-encryption-password', // Optional: If folder is encrypted
// an optional callback useful for large file uploads
onProgress: (progress: number) => \{
console.log(\`The upload is completed is \$\{progress\}% completed\`)
\},
\}
const folderCID = await fs.uploadFolderFromFolderPath(api, folderPath, options)
console.log(\`The folder is uploaded and its cid is \$\{folderCID\}\`)
\`\`\`
## 4. Uploading a file from a custom interface with \`GenericFile\`
\`\`\`typescript
import \{ createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.TAURUS \}) // Initialize your API instance with API key
const buffer = Buffer.from(...);
const genericFile = \{
read: async function *() \{
yield buffer
\},
name: "autonomys-whitepaper.pdf",
mimeType: "application/pdf",
size: 1234556,
path: "autonomys-whitepaper.pdf"
\}
const options = \{
password: 'your-encryption-password', // Optional: specify a password for encryption
compression: true,
// an optional callback useful for large file uploads
onProgress?: (progress: number) => \{
console.log(\`The upload is completed is \$\{progress\}% completed\`)
\}
\}
const cid = api.uploadFile(genericFile, options)
console.log(\`The file is uploaded and its cid is \$\{cid\}\`)
\`\`\`
## 5. Downloading files
\`\`\`typescript
import \{ createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.TAURUS \}) // Initialize your API instance with API key
try \{
const cid = '..'
const stream = await api.downloadFile(cid)
let file = Buffer.alloc(0)
for await (const chunk of stream) \{
file = Buffer.concat([file, chunk])
\}
console.log('File downloaded successfully:', stream)
\} catch (error) \{
console.error('Error downloading file:', error)
\}
\`\`\`
## 6. Creating shareable download link
\`\`\`typescript
import \{ createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.TAURUS \}) // Initialize your API instance with API key
try \{
const cid = 'your-file-cid'
const publicUrl = await api.publishObject(cid)
console.log('Public download URL:', publicUrl)
\} catch (error) \{
console.error('Error publishing object:', error)
\}
\`\`\`
## 7. Example usage of \`getMyFiles\`
Here is an example of how to use the \`getMyFiles\` method to retrieve the root directories:
\`\`\`typescript
import \{ createAutoDriveApi \} from '@autonomys/auto-drive'
import \{ NetworkId \} from '@autonomys/auto-utils'
const api = createAutoDriveApi(\{ apiKey: 'your-api-key', network: NetworkId.TAURUS \}) // Initialize your API instance with API key
try \{
for (let i = 0; i < 10; i++) \{
const myFiles = await api.getMyFiles(i, 100)
console.log(\`Retrieved \$\{myFiles.rows.length\} files of \$\{myFiles.totalCount\} total\`)
for (const file of myFiles.rows) \{
console.log(\`\$\{file.name\} - \$\{file.headCid\}: \$\{file.size\}\`)
\}
\}
\} catch (error) \{
console.error('Error downloading file:', error)
\}
\`\`\`
---
### File: sdk/auto-utils.mdx
## Auto-Utils Package
### Introduction
The \`@autonomys/auto-utils\` package provides core utility functions for interacting with and building applications on the Autonomys Network.
### Features
- **Wallet Management**: Initialize and manage wallets using mnemonics or URIs.
- **Network Configuration**: Access and manage network and domain settings.
- **Data Storage**: Save and read data to and from local storage or the file system.
- **Cryptographic Operations**: Perform hashing and data manipulation using cryptographic functions.
- **API Activation**: Activate and manage connections to the Autonomys Network APIs.
- **Address Utilities**: Convert and decode addresses to and from standardized formats.
### Installation
Install the package via \`npm\` or \`yarn\`:
\`\`\`bash
# Using npm
npm install @autonomys/auto-utils
# Using yarn
yarn add @autonomys/auto-utils
\`\`\`
### Importing
Import the \`auto-utils\` functions you need into your project:
\`\`\`typescript
// Import specific functions
import \{ activateWallet, activate, blake2b_256 \} from '@autonomys/auto-utils';
// Or import everything
import * as utils from '@autonomys/auto-utils';
\`\`\`
### Available functions
> *Note:* All asynchronous functions return a \`Promise\` and should be used with \`await\` for proper execution flow. Wrap asynchronous calls in \`try...catch\` blocks to handle potential errors gracefully.
#### Account and address utilities
- \`address(input): string\`: Standardizes an address format.
- \`createAccountIdType(api, address): Uint8Array\`: Creates an \`AccountId\` object from an address.
- \`decode(input): Uint8Array\`: Decodes an address to bytes.
#### API and connection management
> *Note:* Always disconnect the API instance after operations to free up resources.
- \`activate(options?): Promise<ApiPromise>\`: Connects to the Autonomys Network.
- \`activateDomain(params): Promise<ApiPromise>\`: Connects to a specific domain.
- \`createConnection(endpoint, options?): Promise<ApiPromise>\`: Creates a new API connection.
- \`createAutoDriveApi(api, networkId)\`: Connects to the Auto Drive API of the selected Network.
- \`disconnect(api): Promise<void>\`: Disconnects an API instance.
#### Cryptographic functions
- \`blake2b_256(data): string\`: Hashes data with BLAKE2b-256.
- \`concatenateUint8Arrays(...arrays): Uint8Array\`: Concatenates multiple \`Uint8Array\`s.
- \`stringToUint8Array(string): Uint8Array\`: Converts a string to \`Uint8Array\`.
#### Data storage
> *Note:* Be cautious when saving sensitive data using \`save\` and \`read\` as data storage is permanent. Handle private keys securely. Do not expose them in code or logs.
- \`read(key): Promise<any>\`: Reads data from storage.
- \`readFromFileSystem(key): Promise<any>\`: Reads data from file system.
- \`readFromLocalStorage(key): Promise<any>\`: Reads data from local storage.
- \`save(key, value): Promise<void>\`: Saves data to storage.
- \`saveOnFileSystem(key, value): Promise<void>\`: Saves data to file system.
- \`saveOnLocalStorage(key, value): Promise<void>\`: Saves data to local storage.
#### Event management
- \`eventName(type, event): string\`: Combines a type and an event into a full event name.
- \`eventsGroup\`: Groups system events by name.
- \`expectSuccessfulTxEvent\`: Default success event names array.
- \`Type\`: Enum for event types (e.g., \`system\`).
- \`validateEvents(events, eventsExpected?, tx, block, log?): EventsValidated\`: Checks if expected events are in transaction events.
#### Network management
- \`getNetworkDetails(options): NetworkDetails\`: Retrieves the details of a network.
- \`getNetworkDomainDetails(options): DomainDetails\`: Retrieves the details of a domain.
- \`getNetworkDomainRpcUrls(options): string[]\`: Retrieves the RPC URLs for a domain.
- \`getNetworkRpcUrls(options): string[]\`: Retrieves the RPC URLs for a network.
- \`networks\`: Array of available networks.
#### Signing utilities
- \`signMessage(signer, address, data): Promise<\{ signature: string \}>\`: Signs a message with a signer and an address.
- \`signatureVerify\`: Verifies signatures (re-exported from \`@polkadot/util-crypto\`).
- \`signingKey(publicKey): string\`: Converts a public key to a hex string.
#### String utilities
- \`capitalizeFirstLetter(string): string\`: Capitalizes the first letter.
- \`fixLengthEntryId(blockHeight, indexInBlock?): string\`: Creates fixed-length IDs.
- \`isAddress(address): boolean\`: Validates a Substrate address.
- \`isHex(value): boolean\`: Validates a hexadecimal string.
- \`shortString(value, initialLength?, endLength?): string\`: Truncates strings.
- \`stringify(value): string\`: Stringifies values, handling BigInt.
#### Token and value formatting
- \`formatSpacePledged(value, decimals?): string\`: Formats space amount with units.
- \`formatTokenAmount(amount, decimals?): bigint\`: Formats token amount with decimals.
- \`parseTokenAmount(amount, decimals?): number\`: Parses token amount with decimals.
#### Transaction utilities
- \`signAndSendTx(sender, tx, options?, eventsExpected?, log?, mapErrorCodeToEnum?): Promise<TransactionSignedAndSend>\`: Signs, sends, and validates a transaction.
#### Wallet management
- \`activateWallet(options): Promise<\{ api, accounts \}>\`: Activates a wallet using a mnemonic or URI.
- \`generateWallet(): GeneratedWallet\`: Generates a new wallet with a mnemonic.
- \`getMockWallet(name, wallets): Wallet\`: Retrieves a mock wallet by name.
- \`mockWallets(options, api?): Promise<Wallet[]>\`: Creates mock wallets for testing.
- \`setupWallet(params): Wallet\`: Sets up a wallet from a mnemonic or URI.
## Usage examples
### 1. Wallet management
#### Activate a wallet using a mnemonic phrase
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils';
(async () => \{
const mnemonic = 'your mnemonic phrase here';
const \{ api, accounts \} = await activateWallet(\{
mnemonic,
networkId: 'chronos', // Optional: specify the network ID
\});
const account = accounts[0];
console.log(\`Connected with account address: \$\{account.address\}\`);
// Perform actions with the account...
// Disconnect when done
await api.disconnect();
\})();
\`\`\`
#### Activate a wallet using a URI
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils';
(async () => \{
const \{ api, accounts \} = await activateWallet(\{
uri: '//Alice',
networkId: 'localhost', // Connect to a local network
\});
const account = accounts[0];
console.log(\`Connected with account address: \$\{account.address\}\`);
// Disconnect when done
await api.disconnect();
\})();
\`\`\`
#### Create mock wallets for testing
\`\`\`typescript
import \{ activate, mockWallets, getMockWallet \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
const wallets = await mockWallets(\{\}, api);
const aliceWallet = getMockWallet('Alice', wallets);
const bobWallet = getMockWallet('Bob', wallets);
console.log(\`Alice's address: \$\{aliceWallet.accounts[0].address\}\`);
console.log(\`Bob's address: \$\{bobWallet.accounts[0].address\}\`);
// Disconnect when done
await api.disconnect();
\})();
\`\`\`
### 2. Network management
#### List all available networks
\`\`\`typescript
import \{ networks \} from '@autonomys/auto-utils';
networks.forEach((network) => \{
console.log(\`Network ID: \$\{network.id\}, Name: \$\{network.name\}\`);
\});
\`\`\`
#### Retrieve the details of a specific network
\`\`\`typescript
import \{ getNetworkDetails \} from '@autonomys/auto-utils';
const network = getNetworkDetails(\{ networkId: 'chronos' \});
console.log(\`Network Name: \$\{network.name\}\`);
console.log(\`RPC URLs: \$\{network.rpcUrls.join(', ')\}\`);
\`\`\`
#### Retrieve the details of a specific domain within a network
\`\`\`typescript
import \{ getNetworkDomainDetails \} from '@autonomys/auto-utils';
const domain = getNetworkDomainDetails(\{ domainId: '1', networkId: 'chronos' \});
console.log(\`Domain Name: \$\{domain.name\}\`);
console.log(\`RPC URLs: \$\{domain.rpcUrls.join(', ')\}\`);
\`\`\`
### 3. Cryptographic functions
#### Hash a string using BLAKE2b-256
\`\`\`typescript
import \{ blake2b_256, stringToUint8Array \} from '@autonomys/auto-utils';
const data = 'Hello, Autonomys!';
const dataBytes = stringToUint8Array(data);
const hash = blake2b_256(dataBytes);
console.log(\`Hash: \$\{hash\}\`); // Outputs the hash of the input string
\`\`\`
#### Convert a string to a \`Uint8Array\`
\`\`\`typescript
import \{ stringToUint8Array \} from '@autonomys/auto-utils';
const text = 'Sample text';
const byteArray = stringToUint8Array(text);
console.log(byteArray); // Outputs Uint8Array representation of the string
\`\`\`
#### Concatenate two \`Uint8Array\` instances
\`\`\`typescript
import \{ stringToUint8Array, concatenateUint8Arrays \} from '@autonomys/auto-utils';
const array1 = stringToUint8Array('First part ');
const array2 = stringToUint8Array('Second part');
const concatenated = concatenateUint8Arrays(array1, array2);
console.log(\`Concatenated Result: \$\{new TextDecoder().decode(concatenated)\}\`);
// Outputs: "First part Second part"
\`\`\`
### 4. API activation
#### Activate the network API (connect to the Autonomys Network)
\`\`\`typescript
import \{ activate \} from '@autonomys/auto-utils';
(async () => \{
const api = await activate(\{ networkId: 'chronos' \});
console.log('API connected');
// Perform API calls...
// Disconnect when done
await api.disconnect();
\})();
\`\`\`
#### Activate a domain API (connect to a specific domain within the Autonomys Network)
\`\`\`typescript
import \{ activateDomain \} from '@autonomys/auto-utils';
(async () => \{
const api = await activateDomain(\{ domainId: '1', networkId: 'chronos' \});
console.log('Domain API connected');
// Perform domain-specific API calls...
// Disconnect when done
await api.disconnect();
\})();
\`\`\`
### 5. Data storage
#### Save data to local storage or the file system and read it back
\`\`\`typescript
import \{ save, read \} from '@autonomys/auto-utils';
const key = 'myData';
const value = \{ message: 'Hello, Autonomys!' \};
// Save data
save(key, value);
// Read data
const retrievedValue = read(key);
console.log(retrievedValue); // Outputs: \{ message: 'Hello, Autonomys!' \}
\`\`\`
### 6. Address utilities
#### Convert an address to a standardized format and decode it
\`\`\`typescript
import \{ address, decode \} from '@autonomys/auto-utils';
const originalAddress = '5GmS1wtCfR4tK5SSgnZbVT4kYw5W8NmxmijcsxCQE6oLW6A8';
const standardizedAddress = address(originalAddress);
const decodedAddress = decode(originalAddress);
console.log(\`Standardized Address: \$\{standardizedAddress\}\`);
console.log('Decoded Address:', decodedAddress);
\`\`\`
---
### File: sdk/auto-xdm.mdx
## Auto-XDM Package
### Introduction
The Autonomys Auto XDM SDK (@autonomys/auto-xdm) provides functionalities for cross-domain transfer of native tokens.
### Features
- **Cross-Domain Transfer**: Enable token transfers between consensus and domain wallets.
- **TypeScript Support**: Full TypeScript type definitions for an enhanced developer experience.
### Installation
Install the package via \`npm\` or \`yarn\`:
\`\`\`bash
# Using npm
npm install @autonomys/auto-xdm
# Using yarn
yarn add @autonomys/auto-xdm
\`\`\`
### Importing
Import the \`auto-xdm\` functions you need into your project:
\`\`\`typescript
// Import specific functions
import \{
transferToConsensus,
transferToDomainAccount20Type,
transferToDomainAccount32Type
\} from '@autonomys/auto-xdm';
// Or import everything
import * as xdm from '@autonomys/auto-xdm';
\`\`\`
### Available functions
#### Transfer functions
> *Note:* All transfer functions return a \`SubmittableExtrinsic\` that must be signed and sent. The \`amount\` parameter expects the smallest unit of the token (Shannon). For 18 decimals, multiply by 10^18 or use \`formatTokenAmount\` from \`auto-utils\`. Ensure a sufficient balance in the sending account to cover both the transfer and fees. Cross-domain transfers may take a few blocks to complete.
- \`transfer(api, destination, amount): Promise<SubmittableExtrinsic>\`: Base transfer function for cross-domain transfers.
- \`transferToConsensus(api, accountId32, amount): Promise<SubmittableExtrinsic>\`: Transfer tokens from a domain to the consensus chain.
- \`transferToDomainAccount20Type(api, destinationDomainId, accountId20, amount): Promise<SubmittableExtrinsic>\`: Transfer tokens from the consensus chain to an EVM address.
- \`transferToDomainAccount32Type(api, destinationDomainId, accountId32, amount): Promise<SubmittableExtrinsic>\`: Transfer tokens from the consensus chain to a Substrate address.
#### Query functions
> *Note:* Monitor transfer status using query functions.
- \`chainAllowlist(api): Promise<Codec>\`: Retrieves the list of allowed chains.
- \`channels(api, chainId): Promise<Codec>\`: Retrieves the list of channels
- \`consensusChannels(api): Promise<Codec>\`: Retrieves the list of consensus channels
- \`domainChannels(api, domainId): Promise<Codec>\`: Retrieves the list of domain channels
- \`allCancelledTransfers(api): Promise<Codec>\`: Retrieves all cancelled transfers.
- \`chainTransfers(api): Promise<Codec>\`: Retrieves all chain transfers.
- \`allDomainBalances(api): Promise<Codec>\`: Retrieves balances across all domains.
- \`domainBalances(api, domainId): Promise<Codec>\`: Retrieves balances for a specific domain.
- \`allUnconfirmedTransfers(api): Promise<Codec>\`: Retrieves pending transfers.
### Type definitions
\`\`\`typescript
type Amount = BigInt | number | string;
type Consensus = \{
type: 'consensus';
\};
type Domain = \{
type: 'domain';
domainId: number;
\};
type ChainOrDomain = Consensus | Domain;
\`\`\`
## Usage examples
### 1. Transfer from \`Consensus\` to \`Domain\` (EVM address)
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils'
import \{ transferToDomainAccount20Type \} from '@autonomys/auto-xdm'
const api = await activateWallet(\{ networkId: 'chronos', uri: '//alice' \})
const tx = await transferToDomainAccount20Type(
api,
0, // Receiver domain (0 is Auto EVM on Chronos Testnet)
'0x1234567890abcdef', // Receiver domain account
'1000000000000000000',
)
\`\`\`
### 2. Transfer from \`Consensus\` to \`Domain\` (Substrate address)
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils'
import \{ transferToDomainAccount32Type \} from '@autonomys/auto-xdm'
const api = await activateWallet(\{ networkId: 'chronos', uri: '//alice' \})
const tx = await transferToDomainAccount32Type(
api,
0, // Receiver domain (0 is Auto EVM on Chronos Testnet)
'su1234567890abcdef', // Receiver domain account
'1000000000000000000',
)
\`\`\`
### 3. Transfer from \`Domain\` to \`Consensus\`
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils'
import \{ transferToConsensus \} from '@autonomys/auto-xdm'
const api = await activateWallet(\{ networkId: 'chronos', domainId: 0, uri: '//alice' \})
const tx = await transferToConsensus(
api,
'su1234567890abcdef', // Receiver consensus account,
'1000000000000000000',
)
\`\`\`
### 4. Query domain balances
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils';
import \{ domainBalances \} from '@autonomys/auto-xdm';
(async () => \{
const \{ api \} = await activateWallet(\{
networkId: 'chronos'
\});
// Get balances for domain 0 (Auto EVM on the Chronos testnet)
const balances = await domainBalances(api, 0);
console.log('Domain balances:', balances.toString());
\})();
\`\`\`
### Best practices
1. **Error Handling**: Wrap asynchronous calls and transactions in \`try...catch\` blocks to handle potential errors gracefully:
\`\`\`typescript
try \{
const tx = await transferToConsensus(api, receiver, amount);
await tx.signAndSend(account);
\} catch (error) \{
console.error('Transfer failed:', error);
\}
\`\`\`
2. **Amount Formatting**: Use appropriate decimal places for token amounts:
- The \`amount\` parameter expects the smallest unit of the token (Shannon).
- For 18 decimals, multiply by 10^18 or use \`formatTokenAmount\` from \`auto-utils\`.
3. **API Management**: > Always disconnect the API instance after your operations are complete to free up resources:
\`\`\`typescript
try \{
// ... your code ...
\} finally \{
await api.disconnect();
\}
\`\`\`
---
### File: sdk/index.mdx
---
title: Auto SDK
---
## Auto SDK
### What is the Auto SDK?
The **Auto SDK** is a powerful toolkit of JavaScript/TypeScript packages for developers to seamlessly integrate with the Autonomys Network. It provides simple APIs for interacting with the *consensus* layer, utilizing *data storage*, managing *decentralized identities*, and (soon) handling *AI3 payments*, in addition to general-purpose functions essential for building decentralized applications (dApps)—all in JavaScript and TypeScript—abstracting away the complexities of blockchain and smart contracts.
### Key features:
- **Modular Architecture**: Use only the packages you need.
- **Easy to Use**: Simplifies blockchain operations with high-level functions.
- **Flexible**: Suitable for both beginners and experienced blockchain developers.
- **Open-source**: Built by and for the community.
### Why the Auto SDK?
- **Simplify Development**: Focus on your application's logic rather than blockchain intricacies.
- **Accelerate Time-to-Market**: Reduce development time with ready-to-use functions.
- **Ensure Compatibility**: Stay up-to-date with the latest Autonomys blockchain protocols.
- **Enhance Security**: Utilize well-tested code for critical operations like identity management.
## Packages
The Auto SDK monorepo contains multiple packages, each serving a specific purpose. All packages are published to \`npm\` under the \`@autonomys\` scope:
- **\`@autonomys/auto-utils\`**: Core utility functions for interacting with the Autonomys Network.
- **\`@autonomys/auto-consensus\`**: Functions for interacting with the consensus layer.
- **\`@autonomys/auto-drive\`**: Tools for preparing, uploading and managing data for on-chain storage.
## Quick Start Guide: Install and Code Example
A short video guide on installing the Auto SDK, along with a simple coding example demonstrating how to retrieve an account balance.
<iframe width="560" height="315" src="https://www.youtube.com/embed/B5J9fwE5-vI?si=Mt133r3I2QnCae0A" title="Auto SDK Quick Start Guide: Install and Code Example" frameBorder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>
## Step-by-step guide
### Requirements
- **\`Node.js\`** (version 14 or higher)
- **\`yarn\`** or **\`npm\`**
### Installation
Install the packages you need via \`npm\` or \`yarn\`. For example, to install \`@autonomys/auto-utils\` and \`@autonomys/auto-consensus\`:
#### Using \`npm\`
\`\`\`bash
npm install @autonomys/auto-utils @autonomys/auto-consensus
\`\`\`
#### Using \`yarn\`
\`\`\`bash
yarn add @autonomys/auto-utils @autonomys/auto-consensus
\`\`\`
### Cloning the repository and building locally (*optional*)
If you want to run the SDK packages locally or contribute to the SDK, clone the repository and build the packages from source. Setup instructions:
#### 1. Clone the repository
Open your terminal and run:
\`\`\`bash
git clone https://github.com/autonomys/auto-sdk.git
\`\`\`
#### 2. Navigate to the project directory
\`\`\`bash
cd auto-sdk
\`\`\`
#### 3. Install dependencies
\`\`\`bash
yarn install
\`\`\`
#### 4. Compile all packages
\`\`\`bash
yarn run build
\`\`\`
#### 5. Run tests on all packages
\`\`\`bash
yarn run test
\`\`\`
### Localhost testing (*optional*)
Test the SDK packages against a local Autonomys node:
#### 1. Verify OS and architecture settings
Edit the \`scripts/download.sh\` file and ensure that lines 3-7 match your current operating system and architecture:
\`\`\`bash
# Change the following variables as needed
# OS to download
OS="macos" # Options: macos | ubuntu | windows
# Architecture to download
ARCHITECTURE="aarch64" # Options: aarch64 | x86_64-skylake | x86_64-v2
\`\`\`
#### 2. Run the development script
Execute the following command to start the local node and farmer:
\`\`\`bash
node scripts/run-dev.js
\`\`\`
This script will:
1. Download the latest version of the node and farmer compatible with your OS and architecture (\`scripts/download.sh\`).
2. Start the node and create/insert the keystore (\`scripts/run-node.sh\`).
3. Start the farmer (\`scripts/run-farmer.sh\`).
4. Register the node as an operator, wait for synchronization, and then terminate the node and farmer (handled within \`scripts/run-dev.js\`).
5. Restart the node as an operator (\`scripts/run-operator.sh\`).
6. Restart the farmer (\`scripts/run-farmer.sh\`).
#### 3. Run tests on the local node
\`\`\`bash
bash scripts/localhost-run-test.sh
\`\`\`
The tests will automatically detect and execute on the local node and farmer.
## Next steps
With the Auto SDK set up locally, you're ready to start building and testing your blockchain applications. Explore the following pages for code examples and a functions overview.
---
### File: sdk/polkadot-api.mdx
# Understanding the Polkadot API for Auto SDK Development
## Introduction
While the Auto SDK provides convenient, high-level functions for common tasks on the Autonomys Network, many advanced use cases require direct interaction with the underlying blockchain through the **Polkadot API**. The Autonomys Network is built on Substrate (the same framework as Polkadot), which means it inherits the powerful \`@polkadot/api\` interface for blockchain interactions.
> **For newcomers**: If you're just starting with blockchain development, think of the Auto SDK as a friendly toolkit for common tasks, while the Polkadot API is the comprehensive "power user" interface that gives you access to everything the blockchain can do.
## Why You Need the Polkadot API
The Auto SDK covers many essential operations, but there are numerous scenarios where you'll need to access blockchain data and functionality that isn't wrapped by the SDK:
### Chain State Queries
- **Block information**: Current block number, timestamps, block hashes
- **Network fees**: Transaction fees, storage costs, operational parameters
- **Account data**: Balances, nonces, detailed account information
- **System parameters**: Network constants, runtime version, chain specifications
### Advanced Transaction Handling
- **Fee estimation**: Calculate exact transaction costs before submission
- **Complex extrinsics**: Multi-signature operations, batched transactions
- **Event filtering**: Listen for specific blockchain events beyond basic success/failure
- **Custom pallets**: Interact with specialized blockchain modules
### Real-time Monitoring
- **Block subscriptions**: Monitor new blocks and their contents
- **State changes**: Watch for changes in specific storage items
- **Network status**: Monitor node health, peer connections, sync status
## Essential Polkadot API Documentation
The **[Polkadot.js API Documentation](https://polkadot.js.org/docs/api)** is your comprehensive resource for understanding blockchain interactions. Key sections include:
- **[API Basics](https://polkadot.js.org/docs/api/start/basics)**: Connection setup and fundamental concepts
- **[Query Methods](https://polkadot.js.org/docs/api/start/api.query)**: Reading blockchain state
- **[RPC Calls](https://polkadot.js.org/docs/api/start/api.rpc)**: Direct node communication
- **[Subscription Patterns](https://polkadot.js.org/docs/api/start/api.query.subs)**: Real-time data monitoring
## Installation and Setup
The Polkadot API works alongside the Auto SDK. Install both packages:
\`\`\`bash
npm install @polkadot/api @autonomys/auto-utils
\`\`\`
Import both in your project:
\`\`\`typescript
// Auto SDK for high-level operations
import \{ activate, activateWallet \} from '@autonomys/auto-utils';
// Polkadot API for direct blockchain access
import \{ ApiPromise, WsProvider \} from '@polkadot/api';
\`\`\`
## Common Use Cases and Examples
### 1. Getting Network Information and Fees
This example shows how to retrieve transaction fees and timestamps - information not available through the Auto SDK:
\`\`\`typescript
import \{ ApiPromise, WsProvider \} from '@polkadot/api';
async function getNetworkInfo() \{
// Connect to the Autonomys Network
const api = await ApiPromise.create(\{
provider: new WsProvider('wss://rpc-0.mainnet.subspace.network/ws')
\});
try \{
// Get current block header
const header = await api.rpc.chain.getHeader();
const blockNumber = header.number.toNumber();
// Get current timestamp
const timestamp = (await api.query.timestamp.now()).toNumber();
// Get transaction fees
const fee = await api.query.transactionFees.transactionByteFee();
console.log('Block number:', blockNumber);
console.log('Timestamp:', new Date(timestamp).toISOString());
console.log('Current fee:', fee.current.toString());
console.log('Next fee:', fee.next.toString());
\} finally \{
await api.disconnect();
\}
\}
\`\`\`
### 2. Account Balance and Nonce Queries
\`\`\`typescript
async function getAccountDetails(accountAddress) \{
const api = await ApiPromise.create(\{
provider: new WsProvider('wss://rpc-0.gemini-3h.subspace.network/ws')
\});
try \{
// Get account balance
const balance = await api.query.system.account(accountAddress);
console.log('Free balance:', balance.data.free.toString());
console.log('Reserved balance:', balance.data.reserved.toString());
console.log('Account nonce:', balance.nonce.toString());
\} finally \{
await api.disconnect();
\}
\}
\`\`\`
### 3. Fee Estimation Before Transaction
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils';
import \{ ApiPromise \} from '@polkadot/api';
async function estimateTransactionFee(recipientAddress, amount) \{
// Use Auto SDK to get wallet and API
const \{ api, accounts \} = await activateWallet(\{
uri: '//Alice',
networkId: 'mainnet'
\});
const sender = accounts[0];
// Create transaction
const transfer = api.tx.balances.transfer(recipientAddress, amount);
// Estimate fees using Polkadot API
const info = await transfer.paymentInfo(sender.address);
console.log(\`Estimated fee: \$\{info.partialFee.toString()\}\`);
console.log(\`Transaction weight: \$\{info.weight.toString()\}\`);
await api.disconnect();
\}
\`\`\`
### 4. Monitoring Blockchain Events
\`\`\`typescript
async function monitorBlocks() \{
const api = await ApiPromise.create(\{
provider: new WsProvider('wss://rpc-0.gemini-3h.subspace.network/ws')
\});
// Subscribe to new blocks
const unsubscribe = await api.rpc.chain.subscribeNewHeads((header) => \{
console.log(\`New block #\$\{header.number\} with hash \$\{header.hash\}\`);
\});
// Subscribe to balance changes for specific account
const accountAddress = 'your-account-address';
const unsubBalance = await api.query.system.account(accountAddress, (balance) => \{
console.log('Balance updated:', balance.data.free.toString());
\});
// Clean up subscriptions
setTimeout(() => \{
unsubscribe();
unsubBalance();
api.disconnect();
\}, 30000); // Stop after 30 seconds
\}
\`\`\`
## Integration Patterns with Auto SDK
### Combining Auto SDK with Polkadot API
\`\`\`typescript
import \{ activateWallet \} from '@autonomys/auto-utils';
import \{ ApiPromise \} from '@polkadot/api';
async function advancedWalletOperations() \{
// Use Auto SDK for wallet setup
const \{ api, accounts \} = await activateWallet(\{
mnemonic: 'your mnemonic phrase here',
networkId: 'mainneth'
\});
const account = accounts[0];
// Use Polkadot API for advanced queries
const accountInfo = await api.query.system.account(account.address);
const currentFees = await api.query.transactionFees.transactionByteFee();
console.log(\`Account: \$\{account.address\}\`);
console.log(\`Balance: \$\{accountInfo.data.free.toString()\}\`);
console.log(\`Current fee rate: \$\{currentFees.current.toString()\}\`);
// The api instance from Auto SDK is a full Polkadot API instance
// You can use all Polkadot API methods on it
const blockHash = await api.rpc.chain.getBlockHash();
console.log(\`Latest block hash: \$\{blockHash\}\`);
await api.disconnect();
\}
\`\`\`
## When to Use Auto SDK vs. Polkadot API
### Use Auto SDK for:
- ✅ Wallet creation and management
- ✅ Basic token transfers
- ✅ File uploads to Auto Drive
- ✅ Auto ID operations
- ✅ Network connection setup
- ✅ Common utility functions
### Use Polkadot API for:
- ✅ Fee calculations and estimations
- ✅ Block and timestamp queries
- ✅ Custom pallet interactions
- ✅ Advanced transaction types
- ✅ Real-time blockchain monitoring
- ✅ Complex state queries
---