@agent-shield/sdk 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +182 -0
  2. package/package.json +2 -2
package/README.md ADDED
@@ -0,0 +1,182 @@
1
+ # @agent-shield/sdk
2
+
3
+ TypeScript SDK for AgentShield — permission-guarded DeFi access for AI agents on Solana.
4
+
5
+ ## Installation
6
+
7
+ ```bash
8
+ npm install @agent-shield/sdk @coral-xyz/anchor @solana/web3.js
9
+ ```
10
+
11
+ Peer dependencies: `@coral-xyz/anchor ^0.32.1`, `@solana/web3.js ^1.95.0`
12
+
13
+ Optional: `flash-sdk ^12.0.3` (only needed for Flash Trade perpetuals)
14
+
15
+ ## Quick Start
16
+
17
+ ```typescript
18
+ import { AgentShieldClient } from "@agent-shield/sdk";
19
+ import { Connection, Keypair, PublicKey } from "@solana/web3.js";
20
+ import { Wallet, BN } from "@coral-xyz/anchor";
21
+
22
+ const connection = new Connection("https://api.devnet.solana.com");
23
+ const wallet = new Wallet(ownerKeypair);
24
+ const client = new AgentShieldClient(connection, wallet);
25
+
26
+ // 1. Create a vault with policy
27
+ await client.createVault({
28
+ vaultId: new BN(1),
29
+ dailySpendingCap: new BN(500_000_000), // 500 USDC (6 decimals)
30
+ maxTransactionSize: new BN(100_000_000), // 100 USDC per tx
31
+ allowedTokens: [USDC_MINT, SOL_MINT],
32
+ allowedProtocols: [JUPITER_PROGRAM_ID],
33
+ maxLeverageBps: 0,
34
+ maxConcurrentPositions: 0,
35
+ feeDestination: feeWallet.publicKey,
36
+ });
37
+
38
+ // 2. Deposit funds
39
+ const [vaultPDA] = client.getVaultPDA(wallet.publicKey, new BN(1));
40
+ await client.deposit(vaultPDA, USDC_MINT, new BN(1_000_000_000));
41
+
42
+ // 3. Register an agent
43
+ await client.registerAgent(vaultPDA, agentKeypair.publicKey);
44
+
45
+ // 4. Agent executes a swap through Jupiter
46
+ const sig = await client.executeJupiterSwap({
47
+ vault: vaultPDA,
48
+ owner: wallet.publicKey,
49
+ vaultId: new BN(1),
50
+ agent: agentKeypair.publicKey,
51
+ inputMint: USDC_MINT,
52
+ outputMint: SOL_MINT,
53
+ amount: new BN(10_000_000),
54
+ slippageBps: 50,
55
+ });
56
+ ```
57
+
58
+ ## API Reference
59
+
60
+ ### Vault Management
61
+
62
+ | Method | Description |
63
+ |--------|-------------|
64
+ | `createVault(params)` | Create a new vault with policy, tracker, and fee destination |
65
+ | `deposit(vault, mint, amount)` | Deposit SPL tokens into the vault |
66
+ | `registerAgent(vault, agent)` | Register an agent signing key on the vault |
67
+ | `updatePolicy(vault, params)` | Update policy fields (owner only) |
68
+ | `revokeAgent(vault)` | Freeze the vault — kill switch |
69
+ | `reactivateVault(vault, newAgent?)` | Unfreeze and optionally rotate agent key |
70
+ | `withdraw(vault, mint, amount)` | Withdraw tokens to owner (owner only) |
71
+ | `closeVault(vault)` | Close vault and reclaim rent |
72
+
73
+ ### Permission Engine
74
+
75
+ | Method | Description |
76
+ |--------|-------------|
77
+ | `authorizeAction(vault, params)` | Validate an agent action against policy and create a session |
78
+ | `finalizeSession(vault, agent, success, ...)` | Close session, record audit, collect fees |
79
+
80
+ ### Transaction Composition
81
+
82
+ These methods build atomic transactions in the pattern `[ValidateAndAuthorize, DeFi_ix, FinalizeSession]`:
83
+
84
+ | Method | Description |
85
+ |--------|-------------|
86
+ | `composePermittedAction(params, computeUnits?)` | Build instruction array for any DeFi action |
87
+ | `composePermittedTransaction(params, computeUnits?)` | Build a complete `VersionedTransaction` |
88
+ | `composePermittedSwap(params, computeUnits?)` | Shorthand for swap-type actions |
89
+ | `composeAndSend(params, signers?, computeUnits?)` | Compose, sign, send, and confirm in one call |
90
+
91
+ ### Jupiter Integration
92
+
93
+ | Method | Description |
94
+ |--------|-------------|
95
+ | `getJupiterQuote(params)` | Fetch a swap quote from Jupiter V6 API |
96
+ | `jupiterSwap(params)` | Build an unsigned `VersionedTransaction` for a Jupiter swap |
97
+ | `executeJupiterSwap(params, signers?)` | Quote, compose, sign, send, and confirm |
98
+
99
+ ### Flash Trade Integration
100
+
101
+ | Method | Description |
102
+ |--------|-------------|
103
+ | `flashTradeOpen(params, poolConfig?)` | Compose an open position through Flash Trade |
104
+ | `flashTradeClose(params, poolConfig?)` | Compose a close position |
105
+ | `flashTradeIncrease(params, poolConfig?)` | Compose an increase position |
106
+ | `flashTradeDecrease(params, poolConfig?)` | Compose a decrease position |
107
+ | `executeFlashTrade(result, agent, signers?)` | Sign, send, and confirm a Flash Trade transaction |
108
+ | `createFlashTradeClient(config?)` | Create/cache a `PerpetualsClient` |
109
+ | `getFlashPoolConfig(poolName?, cluster?)` | Get/cache Flash Trade pool config |
110
+
111
+ ### PDA Helpers
112
+
113
+ ```typescript
114
+ const [vaultPDA, bump] = client.getVaultPDA(owner, vaultId);
115
+ const [policyPDA] = client.getPolicyPDA(vaultPDA);
116
+ const [trackerPDA] = client.getTrackerPDA(vaultPDA);
117
+ const [sessionPDA] = client.getSessionPDA(vaultPDA, agent);
118
+ ```
119
+
120
+ ### Account Fetchers
121
+
122
+ ```typescript
123
+ const vault = await client.fetchVault(owner, vaultId);
124
+ const policy = await client.fetchPolicy(vaultPDA);
125
+ const tracker = await client.fetchTracker(vaultPDA);
126
+
127
+ // Or fetch by address directly
128
+ const vault = await client.fetchVaultByAddress(vaultPDA);
129
+ const policy = await client.fetchPolicyByAddress(policyPDA);
130
+ const tracker = await client.fetchTrackerByAddress(trackerPDA);
131
+ ```
132
+
133
+ ## Types
134
+
135
+ ### Instruction Parameters
136
+
137
+ - **`InitializeVaultParams`** — `vaultId`, `dailySpendingCap`, `maxTransactionSize`, `allowedTokens`, `allowedProtocols`, `maxLeverageBps`, `maxConcurrentPositions`, `feeDestination`
138
+ - **`UpdatePolicyParams`** — All policy fields as optionals (only set fields are updated)
139
+ - **`AuthorizeParams`** — `actionType`, `tokenMint`, `amount`, `targetProtocol`, `leverageBps?`
140
+ - **`ComposeActionParams`** — Full params for composed transactions including `defiInstructions`, `success?`, token accounts
141
+
142
+ ### Account Types
143
+
144
+ - **`AgentVaultAccount`** — owner, agent, feeDestination, vaultId, status, stats
145
+ - **`PolicyConfigAccount`** — caps, whitelists, leverage limits, fee BPS
146
+ - **`SpendTrackerAccount`** — rolling spends, recent transactions
147
+ - **`SessionAuthorityAccount`** — ephemeral session with action type and expiry
148
+
149
+ ### Enums
150
+
151
+ - **`VaultStatus`** — `{ active: {} }`, `{ frozen: {} }`, `{ closed: {} }`
152
+ - **`ActionType`** — `{ swap: {} }`, `{ openPosition: {} }`, `{ closePosition: {} }`, `{ increasePosition: {} }`, `{ decreasePosition: {} }`, `{ deposit: {} }`, `{ withdraw: {} }`
153
+
154
+ ## Constants
155
+
156
+ ```typescript
157
+ import {
158
+ AGENT_SHIELD_PROGRAM_ID, // 4ZeVCqnjUgUtFrHHPG7jELUxvJeoVGHhGNgPrhBPwrHL
159
+ JUPITER_V6_API, // https://quote-api.jup.ag/v6
160
+ JUPITER_PROGRAM_ID, // JUP6LkbZbjS1jKKwapdHNy74zcZ3tLUZoi5QNyVTaV4
161
+ FLASH_TRADE_PROGRAM_ID, // PERPHjGBqRHArX4DySjwM6UJHiR3sWAatqfdBS2qQJu
162
+ } from "@agent-shield/sdk";
163
+ ```
164
+
165
+ ## Architecture
166
+
167
+ The SDK uses **instruction composition** rather than CPI wrapping. This avoids Solana's 4-level CPI depth limit and keeps the compute budget manageable:
168
+
169
+ ```
170
+ Transaction = [
171
+ SetComputeUnitLimit(1_400_000),
172
+ ValidateAndAuthorize, // AgentShield: check policy, create session
173
+ ...DeFi instructions, // Jupiter swap / Flash Trade open / etc.
174
+ FinalizeSession // AgentShield: audit, fees, close session
175
+ ]
176
+ ```
177
+
178
+ All instructions in the transaction succeed or fail atomically.
179
+
180
+ ## License
181
+
182
+ MIT
package/package.json CHANGED
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "name": "@agent-shield/sdk",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "TypeScript SDK for AgentShield — AI Agent Financial Middleware on Solana",
5
5
  "main": "dist/index.js",
6
6
  "module": "dist/index.js",
7
7
  "types": "dist/index.d.ts",
8
- "files": ["dist"],
8
+ "files": ["dist", "README.md"],
9
9
  "sideEffects": false,
10
10
  "scripts": {
11
11
  "build": "tsc",