Skip to content

Commit 99f34b4

Browse files
saminacodessaminacodes
committed
added vault documentation
1 parent 0259d69 commit 99f34b4

File tree

9 files changed

+337
-0
lines changed

9 files changed

+337
-0
lines changed

‎apps/portal/src/app/Header.tsx‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -45,6 +45,10 @@ const links = [
4545
];
4646

4747
const toolLinks = [
48+
{
49+
name: "Vault",
50+
href: "/vault",
51+
},
4852
{
4953
name: "Chain List",
5054
href: "https://thirdweb.com/chainlist",

‎apps/portal/src/app/vault/get-started/page.mdx‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
import { Callout } from "@doc";
2+
import { createMetadata } from "@/components/Document";
3+
4+
# Get Started with Vault
5+
6+
<Callout variant="info" title="Engine Vault">
7+
Vault is currently in beta as a part of Engine Cloud and will expand into more products. [Learn how to setup and manage your Vault with thirdweb Engine.](/engine/get-started)
8+
9+
</Callout>

‎apps/portal/src/app/vault/key-concepts/access-control/page.mdx‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
2+
3+
# Metadata-Based Access Control
4+
5+
thirdweb Vault uses metadata patterns to map organizational structures directly into access control policies, eliminating the need to duplicate organizational hierarchies within the key management system.
6+
7+
## Entity Tagging
8+
9+
Each EOA can be tagged with arbitrary metadata key-value pairs representing organizational attributes:
10+
11+
```json
12+
{
13+
"team": "trading",
14+
"region": "apac",
15+
"purpose": "treasury",
16+
"riskLevel": "high"
17+
}
18+
```
19+
20+
## Pattern Matching with Rules
21+
22+
Access tokens can be scoped using metadata rules that define precise access patterns:
23+
24+
```json
25+
{
26+
"metadataPatterns": [
27+
{
28+
"key": "team",
29+
"rule": {
30+
"pattern": "^trading$"
31+
}
32+
},
33+
{
34+
"key": "riskLevel",
35+
"rule": {
36+
"op": "lessThan",
37+
"value": 3
38+
}
39+
}
40+
]
41+
}
42+
```
43+
44+
## Practical Implementation Examples
45+
46+
### Departmental Segregation
47+
48+
An organization can create EOAs tagged with departmental metadata and issue access tokens that respect organizational boundaries:
49+
50+
```json
51+
// Policy component for trading department
52+
{
53+
"type": "eoa:signTransaction",
54+
"allowlist": [],
55+
"metadataPatterns": [
56+
{
57+
"key": "department",
58+
"rule": {
59+
"pattern": "^trading$"
60+
}
61+
},
62+
{
63+
"key": "region",
64+
"rule": {
65+
"pattern": "apac"
66+
}
67+
}
68+
],
69+
"payloadPatterns": {
70+
"chainId": [
71+
{
72+
"pattern": "^(1|137)$"
73+
}
74+
],
75+
"value": [
76+
{
77+
"op": "lessThan",
78+
"value": "1000000000000000000"
79+
}
80+
]
81+
}
82+
}
83+
```
84+
85+
### Multi-Team Collaboration
86+
87+
For entities requiring shared access across teams:
88+
89+
```json
90+
// EOA metadata
91+
{
92+
"teams": "finance,trading,compliance",
93+
"purpose": "treasury"
94+
}
95+
96+
// Policy for finance team access
97+
{
98+
"type": "eoa:signMessage",
99+
"allowlist": [],
100+
"metadataPatterns": [
101+
{
102+
"key": "teams",
103+
"rule": {
104+
"pattern": "finance"
105+
}
106+
}
107+
],
108+
"chainId": 1,
109+
"messagePattern": "^Confirm treasury operation:"
110+
}
111+
```

‎apps/portal/src/app/vault/key-concepts/access-tokens/page.mdx‎

Lines changed: 42 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,42 @@
1+
2+
# Access Tokens
3+
Access tokens are a core security mechanism in thirdweb Vault that enable secure, controlled delegation of wallet operations. Created by either user accounts or service accounts, access tokens allow precise, policy-based access to account-owned entities like EOAs.
4+
5+
### Purpose and Benefits
6+
7+
Access tokens serve several critical functions:
8+
9+
- **Delegation without sharing keys**: Grant specific capabilities to services, applications, or team members without exposing your admin key
10+
- **Fine-grained permission control**: Limit exactly what operations can be performed and under what conditions
11+
- **Instant revocation**: Immediately terminate access when needed
12+
- **Auditable access paths**: Track and monitor who has what level of access to your entities
13+
14+
### Policy-Based Control
15+
16+
Each access token is configured with a set of policies that define:
17+
18+
1. **Which operations** can be performed (e.g., signing transactions, reading wallet information)
19+
2. **Which entities** can be accessed (using allowlists or metadata patterns)
20+
3. **What constraints** apply to each operation (e.g., transaction value limits, allowed chains)
21+
22+
An access token can only perform operations explicitly permitted by its policy. For example, you might create an access token that can only:
23+
24+
- Sign transactions on Ethereum mainnet
25+
- With a maximum value of 1 ETH
26+
- To a specific set of contract addresses
27+
- Using only wallets tagged with a particular purpose
28+
29+
### Practical Applications
30+
31+
Access tokens enable critical workflows for blockchain applications:
32+
33+
- **Application integrations**: Let your application sign transactions without holding private keys
34+
- **Team collaboration**: Grant different team members appropriate access levels to shared wallets
35+
- **Automated processes**: Enable secure automated signing for scheduled operations
36+
- **Temporary access**: Create time-limited tokens for specific projects or partnerships
37+
38+
### Using Metadata for Flexible Control
39+
40+
A particularly powerful feature of access tokens is their ability to use metadata patterns for entity access control. Rather than maintaining explicit allowlists, you can tag your EOAs with descriptive metadata and then create access tokens that match specific patterns.
41+
42+
This metadata-based approach provides tremendous flexibility in how you organize and control access to your wallet infrastructure, which is detailed further in the sections below

‎apps/portal/src/app/vault/key-concepts/accounts/page.mdx‎

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
import { Callout } from "@doc";
2+
3+
# Accounts
4+
5+
Vault will support 2 accounts types
6+
7+
1. User Account (*coming soon*):
8+
2. Service Account
9+
10+
## User Account
11+
12+
User accounts can be authenticated by:
13+
14+
1. passkey
15+
2. SIWE
16+
3. OTP (email/SMS)
17+
4. oauth (google etc)
18+
19+
These are meant to be owned and operated by end-users and are ideal for integrating with consumer facing applications that want to provide a web2 like blockchain experience, while still being fully non-custodial.
20+
21+
## Service Accounts
22+
23+
Service accounts in thirdweb Vault provide a hierarchical security model for organizational key management, combining administrative control with precise delegation capabilities. These are ideal for applications where you have programmatic access control needs for wallets, but still want to keep the system non-custodial.
24+
25+
<Callout variant="info" title="Engine Service Accounts">
26+
thirdweb uses vault service accounts to power engine
27+
</Callout>
28+
29+
### Service Account Credentials
30+
31+
A service account has two primary credentials:
32+
33+
1. **Admin Key**: Grants access to every operation on every entity owned by the account
34+
2. **Rotation Code**: Used to invalidate current credentials and generate new ones during security events
35+
36+
Service Accounts can used in combination with access-tokens to build non-custodial programmable access control for your enterprise applications.

‎apps/portal/src/app/vault/key-concepts/entities/page.mdx‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
# Entities
2+
3+
Entities are the resources secured by vault. Entities are owned by a vault account.
4+
Vault currently secures the EOA entity.
5+
6+
## EOA
7+
8+
An EOA (Externally Owned Account) is an EVM account controlled by a private key held by a user. It's a fundamental part of the EVM ecosystem, used for managing funds, initiating transactions, and interacting with smart contracts.
9+
The private key to the EOA is always stored encrypted, and only decrypted within vault.
10+
11+
Vault supports the following EOA related operations (API reference):
12+
13+
```typescript
14+
eoa:list
15+
eoa:create
16+
eoa:signMessage
17+
eoa:signTypedData
18+
eoa:signTransaction
19+
eoa:signStructuredMessage
20+
eoa:signAuthorization
21+
```

‎apps/portal/src/app/vault/layout.tsx‎

Lines changed: 17 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,17 @@
1+
import { DocLayout } from "@/components/Layouts/DocLayout";
2+
import { createMetadata } from "@doc";
3+
import { sidebar } from "./sidebar";
4+
5+
export default async function Layout(props: { children: React.ReactNode }) {
6+
return (
7+
<DocLayout sideBar={sidebar} editPageButton={true}>
8+
{props.children}
9+
</DocLayout>
10+
);
11+
}
12+
13+
export const metadata = createMetadata({
14+
title: "Vault",
15+
description:
16+
"Vault is an open-source non-custodial key management service, secured with TEE architecture (AWS Nitro Enclaves) and designed for blockchain applications.",
17+
});

‎apps/portal/src/app/vault/page.mdx‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
import { createMetadata } from "@/components/Document";
2+
import { DocImage, FeatureCard, OpenSourceCard, Callout } from "@doc";
3+
import { ArrowLeftRight, UserLock, Users, Wallet } from "lucide-react";
4+
5+
6+
export const metadata = createMetadata({
7+
title: "thirdweb Vault",
8+
description: "An open-source, backend server that reads, writes, and deploys contracts at production scale.",
9+
});
10+
11+
12+
# Vault
13+
14+
thirdweb vault is an open-source non-custodial key management service, secured with TEE architecture (AWS Nitro Enclaves) and designed for blockchain applications.
15+
16+
## Features
17+
18+
<div
19+
className="my-4 grid gap-2 md:grid-cols-2 lg:grid-cols-2 "
20+
>
21+
<FeatureCard
22+
title="Non-Custodial Wallets"
23+
description="Generate and manage EOAs where private keys remain encrypted and secure"
24+
iconUrl={<Wallet />}
25+
/>
26+
27+
<FeatureCard
28+
title="Programmatic Signing"
29+
description="Enable applications to request signatures based on rules without exposing keys"
30+
iconUrl={<ArrowLeftRight />}
31+
/>
32+
33+
<FeatureCard
34+
title="Sophisticated Access Models"
35+
description="Delegate signing capabilities with granular access controls"
36+
iconUrl={<UserLock />}
37+
/>
38+
39+
<FeatureCard
40+
title="Flexibility"
41+
description="Basic wallet functionality to multi-user organizations with complex permissioning"
42+
iconUrl={<Users/>}
43+
/>
44+
45+
</div>
46+
47+
With vault, you can build applications where:
48+
49+
- Your users never need to manage private keys
50+
- Your backend services can request signatures without having access to private keys
51+
- Your users can create controlled access for team members, services, or automation
52+
- Security is enforced cryptographically, not through promises

‎apps/portal/src/app/vault/sidebar.tsx‎

Lines changed: 45 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,45 @@
1+
import type { SideBar } from "@/components/Layouts/DocLayout";
2+
import { Key, Rocket, ShieldQuestion, Vault } from "lucide-react";
3+
4+
export const sidebar: SideBar = {
5+
name: "Vault",
6+
links: [
7+
{
8+
name: "Overview",
9+
href: "/vault",
10+
icon: <Vault />,
11+
},
12+
{
13+
name: "Get Started",
14+
href: "/vault/get-started",
15+
icon: <Rocket />,
16+
},
17+
{
18+
name: "Key Concepts",
19+
icon: <Key />,
20+
links: [
21+
{
22+
name: "Entities",
23+
href: "/vault/key-concepts/entities",
24+
},
25+
{
26+
name: "Accounts",
27+
href: "/vault/key-concepts/accounts",
28+
},
29+
{
30+
name: "Access Tokens",
31+
href: "/vault/key-concepts/accounts",
32+
},
33+
{
34+
name: "Access Control",
35+
href: "/vault/key-concepts/access-control",
36+
},
37+
],
38+
},
39+
{
40+
name: "Security",
41+
href: "/vault/key-concepts/security",
42+
icon: <ShieldQuestion />,
43+
},
44+
],
45+
};

0 commit comments

Comments
 (0)