Skip to content

Commit 3a6ab45

Browse files
chungquantinchungquantin
authored
Add application from Elastic Labs for Polkadot Agent Kit (#2549)
1 parent 2cd3248 commit 3a6ab45

File tree

1 file changed

+388
-0
lines changed

1 file changed

+388
-0
lines changed

‎applications/polkadot_agent_kit.md

Lines changed: 388 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,388 @@
1+
# Polkadot Agent Kit
2+
3+
- **Team Name:** Elastic Labs (https://elasticlabs.org/) - Core contributors of [OpenGuild Community](https://openguild.wtf).
4+
- **Payment Address:**
5+
- **DOT**: 15NL11ZoE9KUY54VWUzC3mawgzsQ2UcniXKSAFUa1hC8vnKd (Elastic Labs Multisig)
6+
- **[Level](https://github.com/w3f/Grants-Program/tree/master#level_slider-levels):** 2
7+
8+
## Project Overview
9+
10+
### Overview
11+
12+
[Polkadot Agent Kit](https://github.com/elasticlabs-org/polkadot-agent-kit) is an open-source library provides developers with a set of tools to build AI Agents that interact autonomously with the Polkadot SDK-based networks.
13+
14+
- Main repository: https://github.com/elasticlabs-org/polkadot-agent-kit
15+
- Telegram Chatbot Polkadot Agent: https://github.com/elasticlabs-org/polkadot-agent-kit/tree/main/examples/telegram-bot
16+
17+
### Motivation & Ecosystem Fit
18+
19+
Polkadot is widely recognized for its powerful cross-chain capabilities and secure transaction infrastructure. However, interacting with these features—especially through XCM and cross-chain asset transfers—often requires navigating a complex and fragmented developer experience.
20+
21+
Executing a simple asset transfer across parachains or from Polkadot to another chain can involve multiple intricate steps, making it difficult for developers and users to integrate these capabilities into their applications smoothly.
22+
23+
Not only that, with its complexity in different runtime architecture & network configuration, each Polkadot SDK-based networks requires a different way to interact with.
24+
25+
With these challenges in mind, the Polkadot Agent Kit was created to simplify development and reduce the complexity of interacting with Polkadot SDK-based networks through autonomous, agent-driven capabilities.
26+
27+
### Key Features
28+
29+
Below are the high-level overview of the library features, a detailed breakdown of each feature and the plan for development is listed in the later sections:
30+
31+
- **_Secure wallet management_**: Mnemonic-derived wallets or Proxy-based, Multisig-based.
32+
33+
- **_Cross-chain interactions and queries_**: Primarily built on top of the two protocols XCM & ISMP. Below are common use cases of agent kits:
34+
- Seamlessly multi-hop transfer across parachains and the relaychain.
35+
- Interact with different DeFi protocols in the Polkadot ecosystem.
36+
- **_Basic local chain transactions_**
37+
- (e.g. Query balances, mint new asset & NFTs).
38+
- **_Third-party integrations including:_**
39+
40+
- **_Social clients_**: Seamlessly integrates with third-party social clients to distribute the agentic feature easier.
41+
- Telegram, Discord, Twitter.
42+
- **_Agent Interoperability_**: Expand the features of AI agents by integrating with External Context Providers (ECP), enrichs the knowledge base of the agent built with this library.
43+
- MCP Server, Langchain Actions, Google A2A.
44+
45+
## Project Details
46+
47+
Our team has successfully finished the initial phase of the Polkadot Agent Kit, which can be found and used in the repository: https://github.com/elasticlabs-org/polkadot-agent-kit
48+
49+
### Installation Guide
50+
51+
Ensure your NodeJS environment is at least v23.9.0:
52+
53+
```
54+
pnpm i @polkadot-agent-kit/sdk
55+
```
56+
57+
### Features
58+
59+
#### Multiple Substrate Network Connections
60+
61+
Polkadot Agent Kit uses [Polkadot API](https://github.com/polkadot-api/polkadot-api) as the core client library to set up the connection with Substrate-based chains. You can discover [the list of supported chains in the library codebase](https://github.com/elasticlabs-org/polkadot-agent-kit/blob/main/packages/common/src/chains/supported-chains.ts).
62+
63+
```typescript
64+
// By importing the SDK, Polkadot API descriptors are automatically initalized.
65+
import { PolkadotAgentKit } from "@polkadot-agent-kit/sdk";
66+
67+
// Create an agent - no initialization needed.
68+
const agent = new PolkadotAgentKit({
69+
privateKey: process.env.PRIVATE_KEY,
70+
chains: [
71+
{ name: "westend", url: "wss://westend-rpc.polkadot.io" },
72+
{
73+
name: "polkadot_assethub",
74+
url: "wss://statemint.api.onfinality.io/public-ws",
75+
},
76+
{
77+
name: "paseo_hydradx",
78+
url: "wss://pas-rpc.stakeworld.io",
79+
},
80+
],
81+
});
82+
83+
// Initialize the specific single connection in the list of chains.
84+
const connection = await agent.getConnection("westend");
85+
```
86+
87+
#### Key Types and Mnemonic Support
88+
89+
The Polkadot AI Agent Kit now supports both Sr25519 and Ed25519 key types with dynamic configuration, as well as mnemonic phrase key generation.
90+
91+
#### Key Type Configuration
92+
93+
You can specify which key type to use when creating your agent:
94+
95+
```typescript
96+
// Create an agent with Sr25519 keys
97+
const agent = new PolkadotAgentKit({
98+
privateKey: process.env.PRIVATE_KEY,
99+
keyType: "Sr25519", // Use Sr25519 for signing (default is Ed25519)
100+
chains: [{ name: "westend", url: "wss://westend-rpc.polkadot.io" }],
101+
});
102+
```
103+
104+
#### Mnemonic Phrase Support
105+
106+
You can now create an agent using a mnemonic phrase instead of a raw private key:
107+
108+
```typescript
109+
// Create an agent from a mnemonic phrase
110+
const agent = new PolkadotAgentKit({
111+
mnemonic: "word1 word2 word3 ... word12", // Your 12 or 24 word mnemonic
112+
derivationPath: "", // Optional derivation path (default: '')
113+
keyType: "Sr25519", // Optional key type (default: Ed25519)
114+
chains: [{ name: "westend", url: "wss://westend-rpc.polkadot.io" }],
115+
});
116+
```
117+
118+
#### Using Both Key Types and Delegation
119+
120+
You can mix key types and use both private keys and mnemonics with delegation:
121+
122+
```typescript
123+
// Advanced configuration with different key types
124+
const agent = new PolkadotAgentKit({
125+
// Main account with mnemonic
126+
mnemonic: "word1 word2 word3 ... word12",
127+
derivationPath: "//0",
128+
keyType: "Sr25519",
129+
130+
// Delegate account with private key
131+
delegatePrivateKey: "0x1234...",
132+
delegateKeyType: "Ed25519",
133+
134+
// Or delegate with mnemonic
135+
// delegateMnemonic: 'word1 word2 word3 ... word12',
136+
// delegateDerivationPath: '//1',
137+
// delegateKeyType: 'Sr25519',
138+
139+
chains: [{ name: "westend", url: "wss://westend-rpc.polkadot.io" }],
140+
});
141+
```
142+
143+
#### Using the agent to execute with onchain actions
144+
145+
The Polkadot Agent Kit abstracts complex blockchain interactions into simple prompts. Instead of manually constructing transactions and handling network-specific logic, developers can trigger powerful on-chain actions with a single line of code:
146+
147+
```typescript
148+
await agent.prompt("Vote Proposal #123 on OpenGov");
149+
await agent.prompt("Transfer 10 DOT from Asset Hub to Coretime Chain");
150+
await agent.prompt("Mint an NFT on Asset Hub");
151+
await agent.prompt("Stake 100 DOT on a DeFi protocol");
152+
```
153+
154+
Under the hood, the agent parses natural-language instructions, identifies the correct transaction type, constructs the necessary extrinsics, handles signature authorization (via Proxy/Multisig if needed), and submits the transaction to the network — all autonomously.
155+
156+
Without the Polkadot Agent Kit, developers must manually interact with the Polkadot.js API, construct extrinsics, manage wallets, and handle network-specific encoding.
157+
158+
Here’s an example of how you'd implement the same actions manually:
159+
160+
```typescript
161+
import { ApiPromise, WsProvider, Keyring } from "@polkadot/api";
162+
163+
// Connect to a Hydradx node on Polkadot Relaychain.
164+
const provider = new WsProvider("wss://statemint.api.onfinality.io/public-ws");
165+
const api = await ApiPromise.create({ provider });
166+
167+
// Create a wallet from mnemonic phrase.
168+
const keyring = new Keyring({ type: "sr25519" });
169+
const account = keyring.addFromUri("your mnemonic here");
170+
171+
// Transfer 10 DOT from Asset Hub to Coretime Chain (requires XCM call)
172+
await api.tx.xcmPallet.limitedReserveTransferAssets(
173+
{
174+
V3: {
175+
parents: 0,
176+
interior: {
177+
X1: {
178+
Parachain: <Coretime_Parachain_ID>,
179+
},
180+
},
181+
},
182+
},
183+
{
184+
V3: {
185+
fun: {
186+
Fungible: <amount>,
187+
},
188+
id: {
189+
Concrete: {
190+
parents: 0,
191+
interior: 'Here',
192+
},
193+
},
194+
},
195+
},
196+
{
197+
V3: {
198+
parents: 0,
199+
interior: {
200+
X1: {
201+
AccountId32: {
202+
id: <destination_account_id_as_bytes>,
203+
network: 'Any',
204+
},
205+
},
206+
},
207+
},
208+
},
209+
0,
210+
{
211+
Unlimited: null,
212+
}
213+
).signAndSend(account);
214+
```
215+
216+
Now imagine how many lines of code needed to replicate the same functionalities of the below agent prompt:
217+
218+
```typescript
219+
await agent.prompt(
220+
"Transfer 10 DOT from Asset Hub to Hydration, swap to USDT with
221+
Omnipool and deposit USDT to Bifrost to provide liquid staking."
222+
);
223+
```
224+
225+
Polkadot Agent Kit is all about developer experience!
226+
227+
## Architecture
228+
229+
| Package | Path | Description |
230+
| :--------- | :----------------- | :-------------------------------------------------------------------------------------------- |
231+
| **Common** | `packages/common*` | Defines RPC endpoints, chain configurations, API interfaces, and types shared across the SDK. |
232+
| **Core** | `packages/core` | Implements on-chain and off-chain functions used internally by the LLM package. |
233+
| **LLM** | `packages/llm` | Provides tools and action calls for integrating with large language models (LLMs). |
234+
| **SDK** | `packages/sdk` | Main developer-facing SDK. Exposes APIs from Common, Core, and LLM for external use. |
235+
236+
## Technology Stack
237+
238+
1. **_Blockchain Interaction:_** Using Polkadot API (PAPI) for querying Polkadot SDK-based chains and submitting transactions.
239+
2. **_Cross-chain protocols integrations:_** [XCM](http://docs.polkadot.com/develop/interoperability/intro-to-xcm/), [ISMP](https://github.com/polytope-labs/ismp), [PVQ](https://github.com/open-web3-stack/PVQ). To avoid reinventing the wheels, we plan to work with [`ParaSpell`](https://paraspell.github.io/) team to provide a seamless integrations.
240+
3. **AI Layer & External Context Provides (ECPs):** Leverage the existing LangChain framework for natural language processing, enhanced with a custom tools to expand agent's capabilities. On the other hand, provide an option to integrate with ECPs (MCP Client/Server, A2A-compliant agents, Langchain actions).
241+
4. **DevOps:** Docker for containerized deployment, GitHub Actions for CI, and Vitest for unit testing and e2e testing. This stack ensures compatibility with the Polkadot ecosystem while providing a robust foundation for new features.
242+
243+
## Team :busts_in_silhouette:
244+
245+
### Team Members
246+
247+
- Tin Chung ([Github](https://github.com/chungquantin) / [Website](https://www.chungquantin.com)):
248+
- **Project Role**: General Manager
249+
- Dustin Ho ([Github](https://github.com/CocDap))
250+
- **Project Role**: Lead Engineer
251+
- Andrew Chau ([Github](https://github.com/chauanhtuan185)):
252+
- **Project Role**: Engineer
253+
254+
### Contact 📞
255+
256+
- **Contact Name:** Tin Chung
257+
- **Contact Email:** [[email protected]](mailto:[email protected])
258+
259+
### Legal Structure
260+
261+
- **Registered Address:** No legal structure yet.
262+
- **Registered Legal Entity:** No legal structure yet.
263+
264+
### Team’s Experience
265+
266+
- Tin Chung ([Github](https://github.com/chungquantin) / [Website](https://www.chungquantin.com)):
267+
- **Background**:
268+
- Polkadot Blockchain Academy Wave 5 Graduate.
269+
- Core blockchain engineer of a parachain team on Polkadot.
270+
- Currently leading developer relation function of the OpenGuild (Polkadot SEA) community.
271+
- 3+ years experience working with blockchain technology: Bitcoin Lightning Network, Solana, Ethereum & Polkadot.
272+
- Experienced with contribution to OSS in Polkadot ecosystem: `ink!`, `pop-cli`, `polkadot-sdk` and more.
273+
- Dustin Ho ([Github](https://github.com/CocDap))
274+
- **Background**:
275+
- PBA-X Graduate 2025
276+
- Core engineer at blockchain layer-1 using Polkadot SDK
277+
- 4+ years experiences with blockchain technology: Polkadot, Near, Solana, Ethereum, ...
278+
- Andrew Chau ([Github](https://github.com/chauanhtuan185)):
279+
- **Background**:
280+
- PBA-X graduate
281+
- Ex Backend Engineer at Walless | Open-source wallet on multi-chain
282+
- 2+ years experience working with blockchain technology: Solana, Ethereum
283+
- 2+ years experience working with LLM and AI: LangChain, Tensorflow, PyTorch
284+
285+
### Team Code Repo
286+
287+
- https://github.com/elasticlabs-org/polkadot-agent-kit
288+
289+
### Team github accounts 🧑‍💻
290+
291+
- [Tin Chung](https://github.com/chungquantin)
292+
- [Dustin Ho](https://github.com/CocDap)
293+
- [Andrew Chau](https://github.com/chauanhtuan185)
294+
295+
### Team LinkedIn Profiles 🧑‍🎓
296+
297+
- [Tin Chung](https://www.linkedin.com/in/chungquantin/)
298+
- [Dustin Ho](https://www.linkedin.com/in/dung-dinh-880bb0219/)
299+
300+
## Development Status :open_book:
301+
302+
- Core Functionality: A command-line interface (CLI) for creating agents that interact with Polkadot Ecosystem via the Polkadot API, leveraging LangChain for natural language processing.
303+
- Integration: Connection to Polkadot testnets (e.g., Westend) and mainnets
304+
- Status: As of March 31, 2025, the repository has been tested with ~100 daily transactions on testnets, demonstrating stability for basic use cases.
305+
- Version: 1.0.0-alpha . Available on npm package . Link: https://www.npmjs.com/package/@polkadot-agent-kit/sdk
306+
307+
- Codebase: https://github.com/elasticlabs-org/polkadot-agent-kit
308+
309+
## Development Roadmap :nut_and_bolt:
310+
311+
### Overview
312+
313+
- **Total Estimated Duration:** 3 months
314+
- **Full-Time Equivalent (FTE):** 2
315+
- **Total Costs:** 30,000 USD
316+
- **DOT %:** 60%
317+
318+
### Milestone 1 — Core SDK with XCM Capabilities
319+
320+
- **Estimated duration:** 1 month
321+
- **FTE:** 2
322+
- **Costs:** 9,000 USD
323+
324+
| Number | Deliverable | Specification |
325+
| ------: | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
326+
| **0a.** | License | MIT |
327+
| **0b.** | Documentation | Documentation Page + Quickstart tutorial. |
328+
| **0c.** | Testing and Testing Guide | Unit tests + E2E tests guide + CI pipeline. |
329+
| 1a. | Migrate to ParaSpell | Migrate from raw XCM implementation to use ParaSpell as the underlying XCM library. |
330+
| 1b. | Multi-hop XCM Transferring | Support multi-hop asset transferring via XCM between parachains (reserve transfers) and parachain to relaychain (teleport). |
331+
| 1c. | Transact | Support XCM transact to allow agent sending runtime calls cross-chain. |
332+
| 2. | Agentic XCM integration-texts codebase | Thorough test coverage for XCM functionalities |
333+
334+
### Milestone 2 — DeFi Integrations & External Context Providers
335+
336+
- **Estimated duration:** 1 month
337+
- **FTE:** 2
338+
- **Costs:** 10,000 USD
339+
340+
| Number | Deliverable | Specification |
341+
| ------: | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
342+
| **0a.** | License | MIT |
343+
| **0b.** | Documentation | API reference + advanced guide |
344+
| **0c.** | Testing and Testing Guide | Integration/stress tests + guide |
345+
| 1a. | Agentic DeFi Tools: Hydration | Support swapping on Hydration |
346+
| 1b. | Agentic DeFi Tools: Bifrost | Support minting vDOT |
347+
| 1c. | Agentic DeFi Tools: Relaychain Nomination Pools | Support Nomination Pool staking on Relaychain |
348+
| 2a. | Host a Model Context Protocol (MCP) server | Compatible with the structure required of MCP protocol to easily set up a MCP server on top of the library. |
349+
| 2b. | Convertible to Lanchain tools | Easily convert the langchain tools |
350+
351+
### Milestone 3 — Agent Kit Playground & Examples
352+
353+
- **Estimated duration:** 1 month
354+
- **FTE:** 2
355+
- **Costs:** 10,000 USD
356+
357+
| Number | Deliverable | Specification |
358+
| ------: | ------------------------- | ---------------------------------------------------------------- |
359+
| **0a.** | License | MIT |
360+
| **0b.** | Documentation | Full API reference site + SDK docs |
361+
| **0c.** | Testing and Testing Guide | Extended test suite + user guide |
362+
| 1. | Playground App | Browser application allows developers to play with the agent kit |
363+
| 2. | Replit Examples | Add examples to run the agent kit on Replit |
364+
365+
## Future Plans
366+
367+
Polkadot Agent Kit aims to become the go-to open-source toolkit for developers building agentic applications on Polkadot SDK-based networks. After completing milestones, we intend to have a follow-up proposal to Web3Foundation for:
368+
369+
### Expand Functionality:
370+
371+
- Auditting & Security Analysis.
372+
373+
- Pop Agent Kit CLI - Allows developers to initialize the agent kit starter code base easily.
374+
- Support multiple LLM models - Consider migrating the codebase to LiteLLM to support more LLM models.
375+
- Eliza OS compabitibility - Allows developers to integrate the Polkadot Agent Kit as Eliza OS plugin.
376+
- Options to deploy AI agents: Vercel AI SDK Deployment & PHALA TEE Deployment (This will need to be reconsidered in the future).
377+
378+
### Potential Ecosystem Integrations:
379+
380+
- Hydration
381+
- Apillon
382+
- PolkaAssembly
383+
384+
### Developer onboarding and distribution (additional scope - voluntary):
385+
386+
- Launch comprehensive documentation, quick-start guides, and interactive demos to lower the barrier to entry for new developers.
387+
- Utilize OpenGuild as a distribution platform through online/offlines workshop, collaborate with Polkadot’s flagship events to distribute/promote the kit.
388+
- Introduce open-source bounties at OpenGuild’s meetups to incentivize developers to build agentic applications using the kit, increase mindshare.

0 commit comments

Comments
 (0)