Skip to content

Commit de300a6

Browse files
joaquim-vergesjoaquim-verges
committed
[Docs] Add Vault SDK documentation and guides
1 parent 0eff648 commit de300a6

File tree

8 files changed

+595
-1
lines changed

8 files changed

+595
-1
lines changed

‎apps/portal/src/app/vault/sdk/api-reference/page.mdx

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# API Reference
2+
3+
This section lists every exported function from **@thirdweb-dev/vault-sdk** grouped by broad capability. All functions are fully typed – hover in your editor for exact type information.
4+
5+
---
6+
7+
## 1. Client utilities
8+
9+
| Function | Description |
10+
| --- | --- |
11+
| `createVaultClient({ secretKey })` | Uses your project secret key to establish a connection to your Vault instance and returns a `VaultClient`. Create **one** client per Vault instance and reuse it. |
12+
| `ping({ client, request })` | Health-check endpoint mainly used in examples and tests. Returns the current server time. |
13+
14+
```ts
15+
const client = await createVaultClient({ secretKey: "PROJECT_SECRET_KEY" });
16+
await ping({ client, request: { message: "pong?" } });
17+
```
18+
19+
---
20+
21+
## 2. Service Accounts
22+
23+
| Function | When to use |
24+
| --- | --- |
25+
| `createServiceAccount({ request })` | Bootstrap a brand-new Vault. Returns the **admin key** and **rotation code**. _Run once during provisioning_. |
26+
| `getServiceAccount({ request })` | Retrieve metadata for the current service account. Requires **admin key** or a token with `serviceAccount:read` policy. |
27+
| `rotateServiceAccount({ request })` | Rotate (invalidate) the admin key **and** all existing access tokens in a single atomic operation. Authenticate with the **rotation code**. |
28+
29+
Example – rotate an account after a key leak:
30+
31+
```ts
32+
await rotateServiceAccount({
33+
client,
34+
request: {
35+
auth: { rotationCode: process.env.VAULT_ROTATION_CODE! },
36+
},
37+
});
38+
```
39+
40+
---
41+
42+
## 3. EOAs (Wallets)
43+
44+
| Function | Purpose |
45+
| --- | --- |
46+
| `createEoa` | Create a new EOA (wallet) inside the Vault. Optionally attach arbitrary `metadata` for later querying. |
47+
| `listEoas` | Pagination-aware listing with optional metadata filters. |
48+
| `signTransaction` | Ask the Vault to sign an EVM transaction (legacy, 2930, 1559, 4844 or 7702). |
49+
| `signMessage` | Sign a plain string / hex message. |
50+
| `signTypedData` | Sign EIP-712 typed data with full generic type safety. |
51+
| `signAuthorization` | Sign an [`Authorization`](#authorization) struct used by some L2s / account-abstraction schemes. |
52+
| `signStructuredMessage` | Sign EIP-4337 user-operations (v0.6 & v0.7). |
53+
54+
```ts
55+
// sign a 1559 tx
56+
import { parseTransaction, signTransaction } from "@thirdweb-dev/vault-sdk";
57+
58+
const tx = parseTransaction({
59+
to: "0x...",
60+
value: 0n,
61+
chainId: 1,
62+
maxFeePerGas: 30n * 10n ** 9n,
63+
maxPriorityFeePerGas: 1n * 10n ** 9n,
64+
gasLimit: 21_000,
65+
});
66+
67+
await signTransaction({
68+
client,
69+
request: {
70+
auth: { accessToken: process.env.VAULT_SIG_TOKEN! },
71+
options: { from: "0xEoaAddress", transaction: tx },
72+
},
73+
});
74+
```
75+
76+
> **Note**: `parseTransaction` is a convenience helper that normalises user-supplied objects – you can also build the canonical tx object yourself.
77+
78+
---
79+
80+
## 4. Access Tokens
81+
82+
| Function | Purpose |
83+
| --- | --- |
84+
| `createAccessToken` | Mint a **base token** scoped by policies & metadata. Requires **admin key**. |
85+
| `createSignedAccessToken` | Pure-client helper that turns a *base* token into a short-lived, signed JWT (prefixed with `vt_sat_`). No server round-trip required. |
86+
| `listAccessTokens` | List existing tokens with pagination and optional metadata filters. |
87+
| `revokeAccessToken` | Immediately invalidate a token (or all derived signed tokens) by `id`. |
88+
89+
```ts
90+
// Derive a time-boxed signed token for a serverless function
91+
const sat = await createSignedAccessToken({
92+
vaultClient: client,
93+
baseAccessToken: process.env.VAULT_BASE_TOKEN!,
94+
additionalPolicies: [
95+
{ type: "eoa:signMessage", chainId: 1, messagePattern: "^0x.*" },
96+
],
97+
expiryTimestamp: Math.floor(Date.now() / 1000) + 60 * 5, // 5 min
98+
});
99+
```
100+
101+
---
102+
103+
## 5. Utilities
104+
105+
| Function | Notes |
106+
| --- | --- |
107+
| `parseTransaction` | Normalises user input into a canonical `EthereumTypedTransaction` (supports Legacy, 2930, 1559, 4844, 7702). Throws `ParseTransactionError` on invalid input. |
108+
| `ParseTransactionError` | Custom error class thrown by the above helper. |
109+
110+
```ts
111+
try {
112+
parseTransaction({ gas: 100_000 });
113+
} catch (err) {
114+
if (err instanceof ParseTransactionError) {
115+
console.error(err.message);
116+
}
117+
}
118+
```
119+
120+
---
121+
122+
### Types
123+
124+
All request & response shapes are exported as TypeScript types so you can easily model higher-level abstractions:
125+
126+
```ts
127+
import type { CreateEoaPayload, SignMessagePayload, PolicyComponent } from "@thirdweb-dev/vault-sdk";
128+
```
129+
130+
Refer to the generated `.d.ts` files for the complete list.

‎apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# Guide – Managing Access Tokens
2+
3+
Access tokens let you delegate finely-scoped permissions to services, cron jobs or external partners without sharing the admin key.
4+
5+
This guide covers:
6+
7+
1. Creating a **base** access token (server-side)
8+
2. Deriving short-lived **signed** tokens client-side
9+
3. Listing and revoking tokens
10+
11+
---
12+
13+
## 1. Create a base token
14+
15+
Base tokens are created **once** and stored securely (e.g. in your secrets manager). They cannot be scoped by expiry – instead you define *policies* that control which operations are allowed.
16+
17+
```ts
18+
import { createVaultClient, createAccessToken } from "@thirdweb-dev/vault-sdk";
19+
20+
const client = await createVaultClient({ secretKey: "PROJECT_SECRET_KEY" });
21+
22+
const res = await createAccessToken({
23+
client,
24+
request: {
25+
auth: { adminKey: process.env.VAULT_ADMIN_KEY! },
26+
options: {
27+
policies: [
28+
{
29+
type: "eoa:signMessage",
30+
allowlist: ["0xEoaAddress"],
31+
messagePattern: "^0x.*", // only allow hex messages
32+
},
33+
],
34+
expiresAt: new Date("2030-01-01").toISOString(),
35+
metadata: { env: "prod", owner: "backend" },
36+
},
37+
},
38+
});
39+
40+
console.log("base token", res.data.accessToken);
41+
```
42+
43+
---
44+
45+
## 2. Create a signed access token (JWT)
46+
47+
A **signed access token (SAT)** is a JWT created entirely on the client side. You derive it from a base token, embed additional policies and set a short expiry.
48+
49+
```ts
50+
import { createSignedAccessToken } from "@thirdweb-dev/vault-sdk";
51+
52+
const sat = await createSignedAccessToken({
53+
vaultClient: client,
54+
baseAccessToken: res.data.accessToken,
55+
additionalPolicies: [
56+
{ type: "eoa:signMessage", chainId: 1 },
57+
],
58+
expiryTimestamp: Math.floor(Date.now() / 1000) + 300, // 5 minutes
59+
});
60+
61+
// Prefix: vt_sat_<JWT>
62+
console.log(sat);
63+
```
64+
65+
Send SATs to un-trusted environments (browser, serverless) – they only work until the expiry timestamp and can be revoked centrally by revoking their base token.
66+
67+
---
68+
69+
## 3. List & revoke
70+
71+
```ts
72+
import { listAccessTokens, revokeAccessToken } from "@thirdweb-dev/vault-sdk";
73+
74+
// List the first 10 tokens created by "backend"
75+
const list = await listAccessTokens({
76+
client,
77+
request: {
78+
auth: { adminKey: process.env.VAULT_ADMIN_KEY! },
79+
options: { page: 1, pageSize: 10 },
80+
},
81+
});
82+
83+
const tokenId = list.data.items[0].id;
84+
85+
// Revoke it
86+
await revokeAccessToken({
87+
client,
88+
request: {
89+
auth: { adminKey: process.env.VAULT_ADMIN_KEY! },
90+
options: { id: tokenId },
91+
},
92+
});
93+
```
94+
95+
Once revoked, **all signed tokens derived** from the base are automatically invalidated.
96+
97+
---
98+
99+
### Best practices
100+
101+
1. **Never ship base tokens to browsers** – always derive SATs.
102+
2. **Keep expiries short** (minutes) for web-apps and serverless functions.
103+
3. **Scope by metadata** to share the same policies across many EOAs.

‎apps/portal/src/app/vault/sdk/guides/creating-eoas/page.mdx

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
# Guide – Creating & Managing EOAs
2+
3+
This guide walks you through creating your first Externally Owned Account (EOA) inside the Vault and querying it later.
4+
5+
## Prerequisites
6+
7+
- A running Vault instance.
8+
- The **admin key** or a token with the `eoa:create` / `eoa:read` policies.
9+
- The Vault SDK installed (see Installation).
10+
11+
---
12+
13+
## 1. Create a new EOA
14+
15+
```ts
16+
import { createVaultClient, createEoa } from "@thirdweb-dev/vault-sdk";
17+
18+
const client = await createVaultClient({
19+
secretKey: "PROJECT_SECRET_KEY",
20+
});
21+
22+
const res = await createEoa({
23+
client,
24+
request: {
25+
auth: { adminKey: process.env.VAULT_ADMIN_KEY! },
26+
options: {
27+
metadata: {
28+
team: "treasury",
29+
purpose: "eth-cold-storage",
30+
},
31+
},
32+
},
33+
});
34+
35+
if (!res.success) throw new Error(res.error.message);
36+
37+
console.log("EOA address", res.data.address);
38+
```
39+
40+
### Metadata
41+
42+
`metadata` accepts arbitrary key-value pairs that can later be used for filtering (`listEoas`) or for access-token policies.
43+
44+
---
45+
46+
## 2. Listing EOAs
47+
48+
```ts
49+
import { listEoas } from "@thirdweb-dev/vault-sdk";
50+
51+
const list = await listEoas({
52+
client,
53+
request: {
54+
auth: { adminKey: process.env.VAULT_ADMIN_KEY! },
55+
options: {
56+
page: 1,
57+
pageSize: 20,
58+
},
59+
},
60+
});
61+
62+
for (const eoa of list.data.items) {
63+
console.log(eoa.address, "metadata:", eoa.metadata);
64+
}
65+
```
66+
67+
You can build richer UIs by using the pagination data (`page`, `pageSize`, `totalRecords`).
68+
69+
---
70+
71+
## 3. Best practices
72+
73+
1. **Group wallets via metadata** – e.g. `{ env: "prod" }`, `{ team: "ops" }`.
74+
2. **Use access tokens for app-specific actions** – never ship the admin key to client-side code.
75+
3. **Rotate when you onboard/offboard admins** – see the rotation guide.

0 commit comments

Comments
 (0)