@buildaureon/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 (20) hide show
  1. package/README.md +353 -245
  2. package/dist/index.d.ts +15 -6
  3. package/dist/index.js +8 -2
  4. package/dist/index.js.map +1 -1
  5. package/docs/architecture.md +139 -138
  6. package/docs/auth.md +127 -168
  7. package/docs/client-api.md +5 -4
  8. package/docs/data-contracts.md +7 -4
  9. package/docs/error-model.md +151 -116
  10. package/docs/integration-guide.md +173 -112
  11. package/docs/security.md +87 -41
  12. package/docs/transport.md +91 -77
  13. package/examples/e2e-policy-rebalance/main.ts +24 -36
  14. package/examples/e2e-policy-rebalance/underrun.ts +28 -24
  15. package/examples/e2e-policy-rebalance/verify-sizing.ts +29 -26
  16. package/examples/e2e-vault-flow/main.ts +36 -90
  17. package/examples/market-event/main.ts +9 -9
  18. package/examples/quickstart/main.ts +17 -16
  19. package/examples/sdk-demo-terminal/main.ts +171 -0
  20. package/package.json +5 -8
package/docs/architecture.md CHANGED
@@ -1,205 +1,206 @@
1
1
  # Architecture Guide
2
2
 
3
- This document provides a detailed breakdown of the AUREON system architecture. It outlines the components, data models, state machines, and cryptographic boundaries that govern the `@buildaureon/sdk` and its integration with the hosted AUREON API and the Robinhood Chain.
3
+ System architecture for AUREON and how `@buildaureon/sdk` fits as the typed client for Automatic agent workflows.
4
+
5
+ **Automation note:** The SDK is built for **Automatic** objectives (`automationMode: "auto"`). Manual Approve operator flows are handled in the utility, not as the primary SDK architecture.
4
6
 
5
7
  ---
6
8
 
7
- ## 1. System Vision and Core Principles
9
+ ## 1. Vision
8
10
 
9
- AUREON acts as a decentralized, non-custodial "Financial Compass" (FCO) for digital assets. Instead of requiring users to execute manual, repetitive rebalancing trades or entrust their private keys to a centralized custodian, AUREON splits the system responsibilities:
10
- 1. **Continuous Policy Tracking**: The AUREON Health and Watchdog Engines continuously monitor capital allocations against user-defined objectives (e.g. maintaining a 20% stablecoin sleeve).
11
- 2. **Non-Custodial execution**: When allocations drift outside the allowed tolerance, the system generates execution plans. Rebalances are executed on-chain via Smart Vaults, but transaction signatures are produced locally by the user's wallet.
11
+ AUREON is a non-custodial Financial Compass for onchain agents on Robinhood Chain:
12
12
 
13
- ---
13
+ 1. **Persistent policy** — objectives define target weights / risk bands and stay registered.
14
+ 2. **Continuous health** — watchdog + marks detect drift past tolerance.
15
+ 3. **Honest restore** — plans and receipts (`settlement: vault | staged`) make settlement transparent.
16
+ 4. **Local signing** — owner deposits/withdraws are prepared by the API and signed by the host.
14
17
 
15
- ## 2. Component Architecture Overview
18
+ ---
16
19
 
17
- The system is organized into three major layers: the **Client Layer** (where the SDK resides), the **Gateway Layer** (which hosts the policy and pricing engines), and the **On-chain Layer** (where actual capital is settled).
20
+ ## 2. Component layers
18
21
 
19
22
  ```mermaid
20
23
  graph TB
21
- subgraph ClientBoundary [Client / Host Application Boundary]
22
- App[Agent / Operator Script]
23
- SDK["@buildaureon/sdk Client"]
24
- Session[Session Provider]
25
- Signer[Local Wallet Signer]
24
+ subgraph ClientBoundary [Client_boundary]
25
+ App[Agent_or_script]
26
+ SDK["@buildaureon/sdk"]
27
+ Session[Session_provider_optional]
28
+ Signer[Local_wallet_signer]
26
29
 
27
30
  App --> SDK
28
31
  App --> Session
29
32
  App --> Signer
30
33
  end
31
34
 
32
- subgraph GatewayBoundary [AUREON Hosted Gateway Layer]
33
- API[AUREON API Gateway]
34
- DB[(PostgreSQL / Ledger Store)]
35
- Oracles[Price Oracle Indexer]
36
-
37
- subgraph Engines [Core Engines]
38
- Health[Health Evaluation Engine]
39
- Watchdog[Watchdog Engine]
40
- Planner[Restoration Planner]
41
- end
35
+ subgraph GatewayBoundary [Hosted_gateway]
36
+ API[AUREON_API]
37
+ DB[(Ledger_store)]
38
+ Oracles[Price_marks]
39
+ Health[Health_engine]
40
+ Watchdog[Watchdog]
41
+ Planner[Restore_planner]
42
42
 
43
43
  API --> DB
44
- API --> Engines
45
- Oracles --> Engines
44
+ API --> Health
45
+ API --> Watchdog
46
+ API --> Planner
47
+ Oracles --> Health
46
48
  end
47
49
 
48
- subgraph ChainBoundary [Robinhood Chain Blockchain Layer]
49
- RPC[Secure Node RPC]
50
- Vaults[AUREON Smart Vaults]
51
- Keepers[Automated Keeper Network]
50
+ subgraph ChainBoundary [Robinhood_Chain]
51
+ RPC[RPC]
52
+ Vaults[Smart_Vault]
53
+ Keepers[Keeper_network]
52
54
 
53
55
  RPC --> Vaults
54
56
  Keepers --> Vaults
55
57
  end
56
58
 
57
- %% Data and Control Flows
58
- SDK -->|"HTTPS REST Calls"| API
59
- Signer -->|"Broadcast Signed Steps"| RPC
60
- API -->|"Read Blockchain State"| RPC
61
- Keepers -->|"Automated Rebalance Swaps"| Vaults
59
+ SDK -->|HTTPS_API_key| API
60
+ Signer -->|broadcast_owner_txs| RPC
61
+ API -->|read_balances| RPC
62
+ Keepers -->|allowlisted_swaps| Vaults
62
63
  ```
63
64
 
64
- ### 2.1 The Client Layer
65
- * **AureonClient**: The main class exported by `@buildaureon/sdk`. It coordinates REST requests, implements pre-flight input validation, maps HTTP errors to TypeScript classes, and manages retries.
66
- * **Session Token Provider**: A stateful container that maintains the ephemeral JSON Web Token (JWT) retrieved during wallet signature verification.
67
- * **Local Wallet Signer**: A private key management module (e.g. Viem, Ethers, or an HSM) controlled by the integrator. It signs transaction steps returned by the vault preparation endpoints.
65
+ ### 2.1 Client layer (`@buildaureon/sdk`)
68
66
 
69
- ### 2.2 The Hosted Gateway Layer
70
- * **API Gateway**: A Hono-based router exposing endpoints for managing objectives, synchronizing portfolio snapshots, preparing vault transactions, and querying timeline events.
71
- * **Ledger Store**: A persistent relational database storing user-configured objectives, historic portfolio snapshots, execution receipts, and audit event logs.
72
- * **Price Oracle Indexer**: Integrates with chain feeds to maintain real-time price feeds for all allowlisted vault assets.
73
- * **Health Evaluation Engine**: Computes asset weights and checks deviations against objective targets.
74
- * **Watchdog Engine**: Orchestrates the cron-like heartbeat check to verify if any active objective has entered a violation state.
75
- * **Restoration Planner**: Computes the trade sizes and asset swaps needed to return a violating objective back to its target policy.
67
+ | Piece | Role |
68
+ | --- | --- |
69
+ | `AureonClient` | Typed REST client, validation, retries, error mapping |
70
+ | Issued API key | Wallet identity for control plane |
71
+ | Session provider | Optional Bearer for utility-style sessions |
72
+ | Host signer | Broadcasts prepare-deposit / prepare-withdraw steps |
76
73
 
77
- ### 2.3 The On-chain Layer
78
- * **AUREON Smart Vaults**: ERC-20 and ERC-4626 compatible smart contracts deployed on the Robinhood Chain. They hold the user's custody-free rebalancing capital.
79
- * **Automated Keeper Network**: Off-chain worker bots that listen for restoration plans, call the smart vaults with keeper signatures, and execute swaps via decentralized liquidity pools.
74
+ ### 2.2 Gateway layer
80
75
 
81
- ---
76
+ | Piece | Role |
77
+ | --- | --- |
78
+ | API | Objectives, portfolio sync, vault prepare, restore, timeline |
79
+ | Ledger | Objectives, health snapshots, receipts, events |
80
+ | Marks | Price inputs for weight math |
81
+ | Health engine | Compares weights / risk to policy |
82
+ | Watchdog | Heartbeat evaluation across active Auto objectives |
83
+ | Planner | Builds restore plans (e.g. vault_swap) |
82
84
 
83
- ## 3. The Rebalancing Lifecycle
85
+ ### 2.3 On-chain layer
84
86
 
85
- Rebalancing is the process of moving an objective from a `violation` state back to a `healthy` state. The lifecycle involves multiple steps between the SDK, the gateway, and the blockchain.
87
+ | Piece | Role |
88
+ | --- | --- |
89
+ | Smart Vault | Holds rebalancing capital under owner + keeper rules |
90
+ | Keepers | Execute Automatic restore swaps on allowlisted routes |
91
+ | Owner txs | Deposit / withdraw via signed prepare steps |
92
+
93
+ ---
94
+
95
+ ## 3. Automatic restore lifecycle
86
96
 
87
97
  ```mermaid
88
98
  sequenceDiagram
89
99
  autonumber
90
- participant Host as Host Agent / Script
91
- participant SDK as Aureon SDK
92
- participant API as Hosted API Gateway
93
- participant Vault as Smart Vault (Robinhood Chain)
94
-
95
- rect rgb(240, 248, 255)
96
- Note over Host, API: Phase 1: Continuous Health Monitoring
97
- Host->>SDK: refreshWatchdog()
98
- SDK->>API: POST /watchdog/refresh
99
- API->>API: Fetch current price feeds
100
- API->>API: Evaluate active objective metrics
101
- API-->>SDK: WatchdogRefreshResult (breaches array)
102
- SDK-->>Host: Returns breaches & suggestions
103
- end
100
+ participant Host as Agent
101
+ participant SDK as SDK
102
+ participant API as API
103
+ participant Vault as Smart_Vault
104
+
105
+ Host->>SDK: refreshWatchdog()
106
+ SDK->>API: POST /watchdog/refresh
107
+ API-->>Host: breaches
108
+
109
+ Host->>SDK: getRestorePlan(id)
110
+ SDK->>API: GET restore-plan
111
+ API-->>Host: RestorePlan
112
+
113
+ Host->>SDK: restoreObjective(id)
114
+ SDK->>API: POST restore
115
+ API->>Vault: keeper_allowlisted_swap
116
+ Vault-->>API: receipt
117
+ API-->>Host: ExecutionReceipt settlement
118
+ ```
104
119
 
105
- rect rgb(255, 240, 245)
106
- Note over Host, Vault: Phase 2: Restoration Planning
107
- Host->>SDK: getRestorePlan(objectiveId)
108
- SDK->>API: GET /objectives/:id/restore-plan
109
- API->>API: Calculate optimal rebalance swaps
110
- API-->>SDK: RestorePlan (vault_swap, amount, assets)
111
- SDK-->>Host: Returns plan details
112
- end
120
+ 1. **Evaluate** — sync vault + wallet marks, compute weights.
121
+ 2. **Detect** — if `|current - target| > tolerance`, health → `violation`.
122
+ 3. **Plan** — planner emits a restore plan (often `vault_swap`).
123
+ 4. **Execute** — Automatic restore coordinates keeper vault execution.
124
+ 5. **Confirm** — receipt + timeline; health returns toward `healthy` when sizing/liquidity succeed.
113
125
 
114
- rect rgb(245, 255, 250)
115
- Note over Host, Vault: Phase 3: Execution and Settlement
116
- Host->>SDK: restoreObjective(objectiveId) (or runExecution)
117
- SDK->>API: POST /executions/run
118
- API->>Vault: Submit keeper-signed swap instruction
119
- Vault->>Vault: Execute decentralized exchange swap
120
- Vault-->>API: Emit Swap Log and TX Receipt
121
- API-->>SDK: ExecutionReceipt (settlement: "vault", status: "confirmed")
122
- SDK-->>Host: Return receipt with Transaction Hash
123
- end
124
- ```
126
+ ### Capital book vs vault
125
127
 
126
- ### 3.1 Step 1: Heartbeat Evaluation
127
- The agent periodically calls `refreshWatchdog()`. The gateway retrieves the current token balances in the user's smart vault, fetches real-time mark prices, and computes the current allocation percentage.
128
+ - **Capital Book** — gateway portfolio used for weight math (`syncPortfolio`).
129
+ - **Vault balances** — on-chain capital Automatic restores trade against.
130
+ - Empty vault ⇒ Automatic restores cannot meaningfully settle on-chain even if policy exists.
128
131
 
129
- ### 3.2 Step 2: Breach Detection
130
- If the current allocation drifts beyond the tolerance window, the Health Engine flags the objective's state as `violation` and creates a `TimelineEvent` of type `violation_detected`.
132
+ ---
131
133
 
132
- ### 3.3 Step 3: Plan Generation
133
- The restoration planner calculates the difference between the current weight and the target weight. It translates this difference into a target amount of tokens to buy or sell, package-wrapped inside a `RestorePlan`.
134
+ ## 4. Health evaluation (summary)
134
135
 
135
- ### 3.4 Step 4: Execution
136
- For automated objectives, calling `restoreObjective` instructs the gateway to dispatch a keeper rebalance transaction. The vault executes the trade using native liquidity, updating the token weights on-chain.
136
+ | Kind | Core idea |
137
+ | --- | --- |
138
+ | `stable_allocation` | Stable sleeve weight vs target ± tolerance |
139
+ | `balanced_portfolio` | `targetSymbol` weight vs target ± tolerance |
140
+ | `risk_ceiling` | Aggregate risk score vs `maxRiskScore` |
141
+ | `reward_reinvestment` | Accrued rewards above actionable threshold |
137
142
 
138
- ### 3.5 Step 5: Confirmation
139
- The transaction completes on the Robinhood Chain, and the gateway records an `ExecutionReceipt` with `settlement: "vault"` and `status: "confirmed"`, marking the objective status back to `healthy`.
143
+ Exact fields live in [data-contracts.md](./data-contracts.md).
140
144
 
141
145
  ---
142
146
 
143
- ## 4. Subsystem Details
147
+ ## 5. Objective immutability
144
148
 
145
- ### 4.1 Health Evaluation Formulas
146
- The Health Engine evaluates each of the four objective types using specific mathematical parameters:
149
+ At create time the SDK records:
147
150
 
148
- 1. **Stable Allocation (`stable_allocation`)**:
149
- * **Metric**: $W_{stable} = \frac{\sum \text{Notional}(StableCoins)}{\text{Total Portfolio Notional}}$
150
- * **Condition**: Target Weight $T$ and Tolerance $t$. The sleeve is healthy if $|W_{stable} - T| \le t$.
151
- * **Breach**: If $W_{stable} > T + t$, the planner generates a plan to sell stables. If $W_{stable} < T - t$, the planner generates a plan to buy stables.
151
+ - `targetSymbol` (optional / required by kind)
152
+ - `automationMode` (SDK default **`auto`**)
152
153
 
153
- 2. **Balanced Portfolio (`balanced_portfolio`)**:
154
- * **Metric**: $W_{targetSymbol} = \frac{\text{Notional}(TargetSymbol)}{\text{Total Portfolio Notional}}$
155
- * **Condition**: Target Weight $T$ and Tolerance $t$.
156
- * **Breach**: Triggers rebalancing if the target asset drifts outside the tolerance window.
154
+ Neither can be patched later via `updateObjective`. Recreate to change token or mode. Updates may change name, weights, tolerance, priority, and kind-specific numeric fields.
157
155
 
158
- 3. **Risk Ceiling (`risk_ceiling`)**:
159
- * **Metric**: $\text{RiskScore} = \sum (W_{asset} \times \text{VolatilityRisk}(Asset))$
160
- * **Condition**: Risk Score must remain below $\text{maxRiskScore}$.
161
- * **Breach**: Generates plans to swap highly volatile assets for stable assets if the portfolio risk exceeds the ceiling.
162
-
163
- 4. **Reward Reinvestment (`reward_reinvestment`)**:
164
- * **Metric**: $\text{AccumulatedRewards}$
165
- * **Condition**: Automatically sweeps yield generated by vault positions.
166
- * **Breach**: Triggers when accrued reward tokens exceed a cost-effective gas threshold, reinvesting them into the target sleeve.
156
+ ---
167
157
 
168
- ### 4.2 Non-Custodial Vault Deposits and Withdrawals
169
- While rebalancing is handled by automated keepers, adding or removing funds from the vault requires manual developer wallet signatures.
158
+ ## 6. Non-custodial deposit / withdraw
170
159
 
171
160
  ```mermaid
172
161
  flowchart TD
173
- Host[Host Application] -->|1. Request Calldata| SDK[Aureon SDK]
174
- SDK -->|2. POST /vault/prepare-deposit| API[Aureon Gateway]
175
- API -->|3. Compile ABI steps| SDK
176
- SDK -->|4. Return Unsigned Steps| Host
177
- Host -->|5. Sign steps locally| Wallet[Local Private Key]
178
- Wallet -->|6. Broadcast Signed Calldata| Chain[Robinhood Chain RPC]
162
+ Host -->|prepare| SDK
163
+ SDK -->|POST_prepare| API
164
+ API -->|unsigned_steps| SDK
165
+ SDK -->|steps| Host
166
+ Host -->|sign_broadcast| Chain
179
167
  ```
180
168
 
181
- 1. **Allowance Validation**: The SDK checks if the vault contract is approved to spend the target token. If not, it includes an `approve` step.
182
- 2. **Deposit Compilation**: The gateway builds the transaction data for `deposit(amount)` or `depositETH(value)` calls.
183
- 3. **Execution**: The host signs and broadcasts the steps. The vault smart contract issues shares to the user's address, which are subsequently indexed by the gateway's sync loops.
169
+ 1. Host calls `prepareVaultDeposit` / `prepareVaultWithdraw`.
170
+ 2. API returns approve + deposit/withdraw steps as needed.
171
+ 3. Host signs and broadcasts.
172
+ 4. Later `syncPortfolio` / `getVault` reflect chain state.
184
173
 
185
174
  ---
186
175
 
187
- ## 5. Trust and Security Postures
176
+ ## 7. Trust posture
188
177
 
189
- Integrators must understand the boundary lines between AUREON infrastructure and host applications:
190
-
191
- * **API Key Scope**: API keys authenticate gateway access but cannot perform asset transfers. Compromising an API key does not give access to vault funds because withdrawals require direct owner signatures.
192
- * **Signature Isolation**: Transactions are signed client-side. `@buildaureon/sdk` does not expose methods for loading private keys, keeping key storage isolated.
193
- * **Keeper Swaps**: Keepers can only execute swaps within the allowlisted trading paths of the smart vault. They cannot transfer vault assets to third-party addresses.
178
+ | Claim | Reality |
179
+ | --- | --- |
180
+ | API key steals funds | No — cannot sign owner withdrawals |
181
+ | Keeper steals funds | No — allowlisted swaps only |
182
+ | Staged = on-chain | No — label `settlement` honestly |
183
+ | SDK holds keys | No — host signer only |
194
184
 
195
185
  ---
196
186
 
197
- ## 6. Network Specifications
187
+ ## 8. Network (early access testnet)
188
+
189
+ | Item | Value |
190
+ | --- | --- |
191
+ | Chain | Robinhood Chain testnet |
192
+ | Chain ID | `46630` |
193
+ | API | `https://api.aureonlabs.network` |
194
+ | Explorer | Configure via product / env (`AUREON_EXPLORER_BASE`) |
195
+
196
+ Confirm live addresses and allowlisted symbols from the operator utility and API responses — do not hardcode stale addresses in agents.
197
+
198
+ ---
198
199
 
199
- AUREON is deployed on the following network infrastructure:
200
+ ## 9. Related docs
200
201
 
201
- * **Chain Name**: Robinhood Chain Testnet
202
- * **Chain ID**: `46630`
203
- * **Gas Token**: Native WETH / ETH
204
- * **Block Explorer**: `https://explorer.robinhoodnet.org`
205
- * **Oracles**: Private decentralized feeds push updates to vault-registered adapter contracts.
202
+ - [Integration guide](./integration-guide.md)
203
+ - [Auth](./auth.md)
204
+ - [Security](./security.md)
205
+ - [Client API](./client-api.md)
206
+ - [Data contracts](./data-contracts.md)