@edge-protocol/sdk 0.4.1 → 0.4.4
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.
- package/README.md +159 -145
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,21 +1,18 @@
|
|
|
1
1
|
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
◎ EDGE · built on Sui
|
|
5
|
-
```
|
|
3
|
+
# @edge-protocol/sdk
|
|
6
4
|
|
|
7
|
-
|
|
5
|
+
### Programmable Trust for Autonomous AI Agents on Sui
|
|
8
6
|
|
|
7
|
+
[](https://npmjs.com/package/@edge-protocol/sdk)
|
|
8
|
+
[](https://npmjs.com/package/@edge-protocol/sdk)
|
|
9
|
+
[](src/test.ts)
|
|
9
10
|
[](https://sui.io)
|
|
10
|
-
[](https://npmjs.com/package/@edge-protocol/sdk)
|
|
12
|
-
[](#testing)
|
|
13
|
-
[](LICENSE)
|
|
14
|
-
[](https://overflow.sui.io)
|
|
11
|
+
[](LICENSE)
|
|
15
12
|
|
|
16
|
-
**
|
|
13
|
+
**Give agents your rules, not your keys.**
|
|
17
14
|
|
|
18
|
-
|
|
15
|
+
[Live Demo](https://edge-web-cyan.vercel.app) · [Full Docs](https://github.com/fluturecode/edge/blob/main/packages/sdk/DOCS.md) · [GitHub](https://github.com/fluturecode/edge)
|
|
19
16
|
|
|
20
17
|
</div>
|
|
21
18
|
|
|
@@ -23,145 +20,212 @@
|
|
|
23
20
|
|
|
24
21
|
## The Problem
|
|
25
22
|
|
|
26
|
-
|
|
23
|
+
```
|
|
24
|
+
Option A: Give the agent full wallet access → catastrophic risk
|
|
25
|
+
Option B: Human approves every transaction → defeats the purpose
|
|
26
|
+
Option C: Build custom policy logic → 6-8 weeks of work
|
|
27
|
+
```
|
|
27
28
|
|
|
28
|
-
**
|
|
29
|
+
**EdgePass is Option D** — a programmable trust boundary that lets agents transact autonomously within user-defined limits, enforced on-chain via Sui Move.
|
|
29
30
|
|
|
30
31
|
---
|
|
31
32
|
|
|
32
|
-
##
|
|
33
|
+
## Install
|
|
33
34
|
|
|
34
|
-
|
|
35
|
+
```bash
|
|
36
|
+
npm install @edge-protocol/sdk
|
|
37
|
+
# or
|
|
38
|
+
pnpm add @edge-protocol/sdk
|
|
39
|
+
# or
|
|
40
|
+
yarn add @edge-protocol/sdk
|
|
41
|
+
```
|
|
35
42
|
|
|
36
|
-
|
|
43
|
+
---
|
|
37
44
|
|
|
38
|
-
|
|
39
|
-
|
|
45
|
+
## Quickstart
|
|
46
|
+
|
|
47
|
+
```typescript
|
|
48
|
+
import { EdgePass, MIST_PER_SUI } from '@edge-protocol/sdk';
|
|
49
|
+
|
|
50
|
+
const sdk = new EdgePass({ network: 'mainnet', enokiApiKey: 'YOUR_KEY' });
|
|
51
|
+
|
|
52
|
+
// 1. Create a trust boundary (once)
|
|
53
|
+
const pass = await sdk.create(
|
|
54
|
+
EdgePass.fromTemplate('festival', {
|
|
55
|
+
approvedMerchants: ['Shuttle Express', 'Hydra Bar'],
|
|
56
|
+
owner: userAddress,
|
|
57
|
+
}),
|
|
58
|
+
signer
|
|
59
|
+
);
|
|
60
|
+
|
|
61
|
+
// 2. Execute autonomously (many times)
|
|
62
|
+
const outcome = await sdk.execute(pass, {
|
|
63
|
+
merchant: 'Shuttle Express',
|
|
64
|
+
amount: 18_500_000_000n, // 18.5 SUI in MIST
|
|
65
|
+
}, signer);
|
|
66
|
+
|
|
67
|
+
switch (outcome.status) {
|
|
68
|
+
case 'approved': // ✅ executed on-chain, digest on Walrus
|
|
69
|
+
case 'escalated': // ⚠️ notify user, await approval
|
|
70
|
+
case 'blocked': // 🚫 policy rejected, reason logged
|
|
71
|
+
}
|
|
40
72
|
```
|
|
41
73
|
|
|
42
74
|
---
|
|
43
75
|
|
|
44
|
-
##
|
|
76
|
+
## Templates
|
|
45
77
|
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
51
|
-
|
|
78
|
+
Pre-configured trust boundaries for common use cases:
|
|
79
|
+
|
|
80
|
+
```typescript
|
|
81
|
+
EdgePass.fromTemplate('festival', { owner }) // $300 · auto <$50 · escalate >$100 · 48h
|
|
82
|
+
EdgePass.fromTemplate('gaming', { owner }) // $50 · auto <$2 · escalate >$10 · 4h
|
|
83
|
+
EdgePass.fromTemplate('subscription', { owner }) // $200 · auto <$20 · escalate >$50 · 30d
|
|
84
|
+
EdgePass.fromTemplate('defi', { owner }) // $10k · auto <$500 · escalate >$1k · 7d
|
|
85
|
+
EdgePass.fromTemplate('enterprise', { owner }) // $50k · auto <$1k · escalate >$5k · 30d
|
|
52
86
|
```
|
|
53
87
|
|
|
88
|
+
Override any field:
|
|
89
|
+
|
|
54
90
|
```typescript
|
|
55
|
-
|
|
91
|
+
const pass = await sdk.create(
|
|
92
|
+
EdgePass.fromTemplate('defi', {
|
|
93
|
+
budget: 25_000n * MIST_PER_SUI,
|
|
94
|
+
approvedMerchants: ['DeepBook', 'Cetus'],
|
|
95
|
+
owner: userAddress,
|
|
96
|
+
}),
|
|
97
|
+
signer
|
|
98
|
+
);
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
---
|
|
102
|
+
|
|
103
|
+
## Full API
|
|
104
|
+
|
|
105
|
+
### `new EdgePass(config)`
|
|
106
|
+
|
|
107
|
+
```typescript
|
|
108
|
+
const sdk = new EdgePass({
|
|
109
|
+
network: 'mainnet' | 'testnet' | 'devnet',
|
|
110
|
+
enokiApiKey: string,
|
|
111
|
+
});
|
|
112
|
+
```
|
|
56
113
|
|
|
57
|
-
|
|
114
|
+
### `sdk.create(config, signer)` → `EdgePassObject`
|
|
58
115
|
|
|
59
|
-
|
|
116
|
+
Mint a new EdgePass on Sui. Returns the EdgePass object with its on-chain ID.
|
|
117
|
+
|
|
118
|
+
```typescript
|
|
60
119
|
const pass = await sdk.create({
|
|
61
120
|
budget: 300n * MIST_PER_SUI,
|
|
62
121
|
autoThreshold: 50n * MIST_PER_SUI,
|
|
63
122
|
escalateThreshold: 100n * MIST_PER_SUI,
|
|
64
|
-
|
|
123
|
+
maxPerTransaction: 200n * MIST_PER_SUI, // optional
|
|
124
|
+
approvedMerchants: ['Shuttle Express'],
|
|
65
125
|
expiryMs: 48 * 60 * 60 * 1000,
|
|
66
126
|
owner: userAddress,
|
|
67
127
|
}, signer);
|
|
68
128
|
|
|
69
|
-
//
|
|
129
|
+
console.log(pass.id); // Sui object ID — verifiable on Suiscan
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
### `sdk.execute(pass, request, signer)` → `TransactionOutcome`
|
|
133
|
+
|
|
134
|
+
Execute a transaction against the EdgePass. Policy enforced before touching the chain.
|
|
135
|
+
|
|
136
|
+
```typescript
|
|
70
137
|
const outcome = await sdk.execute(pass, {
|
|
71
138
|
merchant: 'Shuttle Express',
|
|
72
139
|
amount: 18_500_000_000n,
|
|
73
140
|
}, signer);
|
|
74
141
|
|
|
75
|
-
// outcome.status
|
|
142
|
+
// outcome.status → 'approved' | 'escalated' | 'blocked'
|
|
143
|
+
// outcome.digest → tx digest (if approved)
|
|
144
|
+
// outcome.reason → explanation (if escalated or blocked)
|
|
76
145
|
```
|
|
77
146
|
|
|
78
|
-
|
|
147
|
+
### `sdk.validate(pass, request)` → `PolicyValidation`
|
|
79
148
|
|
|
80
|
-
|
|
149
|
+
Preview the outcome without executing. Zero network calls. Use for UI previews.
|
|
81
150
|
|
|
82
|
-
```
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
▼
|
|
86
|
-
Agent calls sdk.execute() (many times)
|
|
87
|
-
│
|
|
88
|
-
├── PolicyEngine validates (pure TS, no network)
|
|
89
|
-
│ ├── active? expired? merchant approved? budget remaining?
|
|
90
|
-
│ ├── amount > escalateThreshold? → ⚠️ escalate to user
|
|
91
|
-
│ └── amount ≤ autoThreshold? → ✅ auto-approve
|
|
92
|
-
│
|
|
93
|
-
├── ExecutionEngine builds PTB (atomic)
|
|
94
|
-
│ validate → execute → update spent → emit event
|
|
95
|
-
│
|
|
96
|
-
└── Walrus writes immutable audit log
|
|
151
|
+
```typescript
|
|
152
|
+
const preview = sdk.validate(pass, { merchant, amount });
|
|
153
|
+
// { allowed: boolean, requiresEscalation: boolean, reason: string }
|
|
97
154
|
```
|
|
98
155
|
|
|
99
|
-
|
|
156
|
+
### `sdk.revoke(pass, signer)`
|
|
157
|
+
|
|
158
|
+
Revoke an EdgePass. All future `execute()` calls return `blocked` immediately.
|
|
159
|
+
|
|
160
|
+
### `sdk.remainingBudget(pass)` → `bigint`
|
|
100
161
|
|
|
101
|
-
|
|
162
|
+
Returns remaining budget in MIST.
|
|
102
163
|
|
|
103
|
-
|
|
104
|
-
|----------|--------|---------|
|
|
105
|
-
| 🚌 Shuttle Express | $18.50 | ✅ Auto-approved · on-chain tx confirmed |
|
|
106
|
-
| 🍹 Hydra Bar | $32.00 | ✅ Auto-approved · on-chain tx confirmed |
|
|
107
|
-
| 🎟 Stage Access VIP | $75.00 | ✅ Auto-approved · on-chain tx confirmed |
|
|
108
|
-
| ☠️ ShadyTokens.xyz | $0.01 | 🚫 Blocked — not in allowlist |
|
|
109
|
-
| 🎤 Artist Meet & Greet | $149.00 | ⚠️ Escalated — exceeds $100 threshold |
|
|
164
|
+
### `sdk.isValid(pass)` → `boolean`
|
|
110
165
|
|
|
111
|
-
|
|
166
|
+
Returns `true` if the pass is active and not expired.
|
|
112
167
|
|
|
113
|
-
|
|
114
|
-
|
|
168
|
+
### `EdgePass.fromTemplate(template, overrides)` → `EdgePassConfig`
|
|
169
|
+
|
|
170
|
+
Create a config from a pre-built template.
|
|
115
171
|
|
|
116
172
|
---
|
|
117
173
|
|
|
118
|
-
##
|
|
174
|
+
## Policy Validation Rules
|
|
175
|
+
|
|
176
|
+
PolicyEngine validates in this order:
|
|
119
177
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
|
|
123
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
| 🔒 **Seal** | Encrypted trust policies (Phase 3) |
|
|
178
|
+
1. Pass must be active
|
|
179
|
+
2. Pass must not be expired
|
|
180
|
+
3. Merchant must be in approved list
|
|
181
|
+
4. Amount must not exceed remaining budget
|
|
182
|
+
5. Amount must not exceed `maxPerTransaction` (if set)
|
|
183
|
+
6. If amount > `escalateThreshold` → escalate
|
|
184
|
+
7. If amount ≤ `autoThreshold` → auto-approve
|
|
128
185
|
|
|
129
186
|
---
|
|
130
187
|
|
|
131
|
-
##
|
|
188
|
+
## Why Sui
|
|
189
|
+
|
|
190
|
+
Five primitives make this only possible on Sui:
|
|
191
|
+
|
|
192
|
+
- **zkLogin** — invisible wallet from Google, no seed phrase
|
|
193
|
+
- **Sponsored Transactions** — users never pay gas
|
|
194
|
+
- **PTBs** — atomic policy + execution + audit in one block
|
|
195
|
+
- **Object Model** — EdgePass owned directly by user, not a contract
|
|
196
|
+
- **Walrus** — immutable audit receipts, no database needed
|
|
197
|
+
|
|
198
|
+
---
|
|
132
199
|
|
|
133
|
-
|
|
200
|
+
## Live Demo
|
|
201
|
+
|
|
202
|
+
Festival Mode: Claude autonomously manages purchases within an EdgePass.
|
|
134
203
|
|
|
135
204
|
```
|
|
136
|
-
|
|
137
|
-
|
|
138
|
-
|
|
205
|
+
🧠 Claude: "Shuttle from parking — $18.50"
|
|
206
|
+
⚙️ PolicyEngine: ✅ auto-approved · trusted merchant
|
|
207
|
+
⛓ Sui: execute_transaction · Success · Suiscan verified
|
|
208
|
+
|
|
209
|
+
🧠 Claude: "Artist meet & greet — $149"
|
|
210
|
+
⚙️ PolicyEngine: ⚠️ escalated · exceeds $100 threshold
|
|
211
|
+
👤 User: approves via modal
|
|
212
|
+
|
|
213
|
+
3 transactions · $54.50 spent · 0 wallet popups
|
|
139
214
|
```
|
|
140
215
|
|
|
141
|
-
[
|
|
216
|
+
[See it live →](https://edge-web-cyan.vercel.app)
|
|
142
217
|
|
|
143
218
|
---
|
|
144
219
|
|
|
145
|
-
##
|
|
220
|
+
## Testing
|
|
146
221
|
|
|
147
222
|
```bash
|
|
148
|
-
|
|
149
|
-
cd edge && pnpm install
|
|
150
|
-
|
|
151
|
-
# Set env vars
|
|
152
|
-
cp apps/web/.env.example apps/web/.env.local
|
|
153
|
-
# Add NEXT_PUBLIC_ENOKI_API_KEY, ENOKI_SECRET_KEY, NEXT_PUBLIC_GOOGLE_CLIENT_ID
|
|
154
|
-
|
|
155
|
-
# Run
|
|
156
|
-
cd apps/web && pnpm dev # → localhost:3000
|
|
157
|
-
|
|
158
|
-
# Test SDK
|
|
159
|
-
cd packages/sdk && pnpm test
|
|
223
|
+
pnpm test
|
|
160
224
|
```
|
|
161
225
|
|
|
162
226
|
```
|
|
163
|
-
✓ auto-approves under
|
|
164
|
-
✓ escalates above
|
|
227
|
+
✓ auto-approves under threshold
|
|
228
|
+
✓ escalates above threshold
|
|
165
229
|
✓ blocks unlisted merchant
|
|
166
230
|
✓ blocks when budget exceeded
|
|
167
231
|
✓ blocks when expired
|
|
@@ -171,69 +235,19 @@ cd packages/sdk && pnpm test
|
|
|
171
235
|
|
|
172
236
|
---
|
|
173
237
|
|
|
174
|
-
##
|
|
175
|
-
|
|
176
|
-
| Action | Tx Digest | Status |
|
|
177
|
-
|--------|-----------|--------|
|
|
178
|
-
| EdgePass created | [2wstpGwQ...](https://suiscan.xyz/testnet/tx/2wstpGwQgb8v6CDKdAmVjJBAHZ873MPFNMBNfvQutFKF) | ✅ Confirmed |
|
|
179
|
-
| Shuttle Express $18.50 | on-chain | ✅ Confirmed |
|
|
180
|
-
| Hydra Bar $32.00 | on-chain | ✅ Confirmed |
|
|
181
|
-
| Stage Access VIP $75.00 | on-chain | ✅ Confirmed |
|
|
182
|
-
| Walrus audit log | [Tly_O_M8...](https://walruscan.com/testnet/blob/Tly_O_M8YpJw-AZqWJ1JRv9xlgZ_W11Er3xoD4BtZlw) | ✅ Live |
|
|
183
|
-
|
|
184
|
-
---
|
|
185
|
-
|
|
186
|
-
## Repo Structure
|
|
238
|
+
## Move Contract
|
|
187
239
|
|
|
188
240
|
```
|
|
189
|
-
|
|
190
|
-
|
|
191
|
-
│ ├── app/api/
|
|
192
|
-
│ │ ├── sponsor/ # Enoki sponsorship (server-side)
|
|
193
|
-
│ │ └── sign/ # zkLogin signing + Sui RPC
|
|
194
|
-
│ └── lib/
|
|
195
|
-
│ ├── zklogin.ts # ZK proof via Enoki
|
|
196
|
-
│ ├── signer.ts # buildSigner
|
|
197
|
-
│ └── walrus.ts # Audit log storage
|
|
198
|
-
├── packages/sdk/ # @edge-protocol/sdk
|
|
199
|
-
│ └── src/core/
|
|
200
|
-
│ ├── EdgePass.ts # Main API
|
|
201
|
-
│ ├── PolicyEngine.ts # Validation logic
|
|
202
|
-
│ └── ExecutionEngine.ts # PTB builder
|
|
203
|
-
└── contracts/navis/ # Move contract
|
|
204
|
-
└── sources/edge_pass.move
|
|
241
|
+
Package: 0x9f4065009494aa5acd92a5c72a6c22ce80939b2bddae3b34345459bc98d2501d
|
|
242
|
+
Network: Sui Testnet (Mainnet coming)
|
|
205
243
|
```
|
|
206
244
|
|
|
207
245
|
---
|
|
208
246
|
|
|
209
|
-
## Roadmap
|
|
210
|
-
|
|
211
|
-
- [x] zkLogin onboarding — real ZK proof via Enoki
|
|
212
|
-
- [x] EdgePass creation — real on-chain Move object
|
|
213
|
-
- [x] PolicyEngine — 6/6 tests passing
|
|
214
|
-
- [x] Festival Mode — real on-chain execution
|
|
215
|
-
- [x] Walrus audit logs — live on testnet with real digests
|
|
216
|
-
- [x] Move contract — testnet deployed
|
|
217
|
-
- [x] GitHub Actions CI/CD pipeline
|
|
218
|
-
- [ ] AI agent demo
|
|
219
|
-
- [ ] `@edge-protocol/sdk` on npm
|
|
220
|
-
- [ ] Mainnet deployment
|
|
221
|
-
- [ ] Seal full encryption
|
|
222
|
-
|
|
223
|
-
---
|
|
224
|
-
|
|
225
|
-
## Why It Matters
|
|
226
|
-
|
|
227
|
-
The agentic web needs programmable trust. Without it, agents either interrupt users constantly or operate with no guardrails. Edge is the missing primitive — open SDK, on-chain policy, zero UX friction.
|
|
228
|
-
|
|
229
|
-
> *The best infrastructure is invisible.*
|
|
230
|
-
|
|
231
|
-
---
|
|
232
|
-
|
|
233
247
|
<div align="center">
|
|
234
248
|
|
|
235
|
-
|
|
249
|
+
*The best infrastructure is invisible.*
|
|
236
250
|
|
|
237
|
-
MIT License
|
|
251
|
+
Built for [Sui Overflow 2026](https://overflow.sui.io) · MIT License
|
|
238
252
|
|
|
239
253
|
</div>
|
package/package.json
CHANGED