[Docs] Add Vault SDK documentation and guides #7054
Conversation
|
github-actions
bot
added
the
Portal
How to use the Graphite Merge QueueAdd either label to this PR to merge it via the merge queue:
You must have a Graphite account in order to use the merge queue. Sign up using this link. An organization admin has enabled the Graphite Merge Queue in this repository. Please do not merge from GitHub as this will restart CI on PRs being processed by the merge queue. This stack of pull requests is managed by Graphite. Learn more about stacking. |
size-limit report 📦
|
Codecov ReportAll modified and coverable lines are covered by tests ✅
Additional details and impacted files@@ Coverage Diff @@
## main #7054 +/- ##
==========================================
- Coverage 55.81% 55.59% -0.22%
==========================================
Files 900 901 +1
Lines 57848 58121 +273
Branches 4067 4064 -3
==========================================
+ Hits 32288 32313 +25
- Misses 25454 25703 +249
+ Partials 106 105 -1
🚀 New features to boost your workflow:
|
joaquim-verges
force-pushed
the
_Docs_Add_Vault_SDK_documentation_and_guides
branch
from
bcbc62c to
de300a6
Compare
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
![graphite-app[bot]](https://avatars.githubusercontent.com/in/158384?s=60&v=4){kind=small}
WalkthroughThis update introduces comprehensive documentation for the Vault SDK, including an overview, installation instructions, API reference, and detailed guides for managing EOAs, signing operations, and handling access tokens. The sidebar navigation is extended to include a new "TypeScript SDK" section, organizing the new documentation and guides for easier access. Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Sidebar
participant DocsPages
User->>Sidebar: Navigates to "TypeScript SDK"
Sidebar->>DocsPages: Provides links (Overview, Installation, API Reference, Guides)
User->>DocsPages: Selects a documentation or guide link
DocsPages->>User: Displays selected documentation content (Overview, Installation, API Reference, Guide)
sequenceDiagram
participant Developer
participant VaultSDKDocs
Developer->>VaultSDKDocs: Reads Overview for high-level understanding
Developer->>VaultSDKDocs: Reads Installation to set up SDK
Developer->>VaultSDKDocs: Uses API Reference for function details
Developer->>VaultSDKDocs: Follows Guides for step-by-step workflows (EOAs, Signing, Access Tokens)
Note ⚡️ AI Code Reviews for VS Code, Cursor, WindsurfCodeRabbit now has a plugin for VS Code, Cursor and Windsurf. This brings AI code reviews directly in the code editor. Each commit is reviewed immediately, finding bugs before the PR is raised. Seamless context handoff to your AI code agent ensures that you can easily incorporate review feedback. Note ⚡️ Faster reviews with cachingCodeRabbit now supports caching for code and dependencies, helping speed up reviews. This means quicker feedback, reduced wait times, and a smoother review experience overall. Cached data is encrypted and stored securely. This feature will be automatically enabled for all accounts on May 16th. To opt out, configure Warning Review ran into problems🔥 ProblemsErrors were encountered while retrieving linked issues. Errors (1)
🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
SupportNeed help? Create a ticket on our support page for assistance with any issues or questions. Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 1
♻️ Duplicate comments (1)
apps/portal/src/app/vault/sdk/installation/page.mdx (1)
48-48: Fix missing verb in sentence.There's a grammatical error in this sentence - missing a verb before "a baseUrl".
-`createVaultClient` uses your secret key to establish a connection to the thirdweb vault instance. You can also a baseUrl that points to your own vault instance. Cache the resulting `vault` object and reuse it for all subsequent operations. +`createVaultClient` uses your secret key to establish a connection to the thirdweb vault instance. You can also specify a baseUrl that points to your own vault instance. Cache the resulting `vault` object and reuse it for all subsequent operations.
🧹 Nitpick comments (7)
apps/portal/src/app/vault/sdk/guides/signing/page.mdx (3)
3-3: Add comma after introductory phrase for clarity.
The sentence "In this guide we will request signatures from the Vault for common payload types:" reads more clearly as "In this guide, we will request signatures from the Vault for common payload types:".🧰 Tools
🪛 LanguageTool
[typographical] ~3-~3: It appears that a comma is missing.
Context: ...igning Transactions & Messages In this guide we will request signatures from the Vau...(DURING_THAT_TIME_COMMA)
18-35: Clarify use of top-level await or wrap in async context.
These code snippets useawaitat the top level (e.g.,const client = await createVaultClient(...)), which may require an environment with top-level await support. Consider wrapping them in anasyncfunction or adding a note that the examples assume such support.
90-99: Include client initialization context in EIP-1559 signing example.
The snippet referencesclientwithout showing how it is obtained. For consistency, either import and initialize the client in this block or add a note such as "Assumingclientis created as shown above."apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx (3)
3-3: Consider removing unnecessary hyphen.
In "finely-scoped permissions," the adverb "finely" does not require a hyphen before "scoped". You may prefer "finely scoped permissions" for consistency with common style guides.🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ... Tokens Access tokens let you delegate finely-scoped permissions to services, cron jobs or e...(HYPHENATED_LY_ADVERB_ADJECTIVE)
49-58: Unify client parameter usage across snippets.
The base token and listing/revocation examples use{ client }, whereas the SAT example usesvaultClient: client. To avoid confusion, standardize the parameter name (e.g., always{ client }).
71-78: Clarify client initialization for listing and revoking.
These snippets referenceclientwithout demonstrating its creation. Consider adding a comment like "Assumingclientis created as shown above" or including the initialization snippet for clarity.apps/portal/src/app/vault/sdk/api-reference/page.mdx (1)
14-17: Include import forping.
The snippet callsping({ client, request: ... })but doesn't import it. Addimport { createVaultClient, ping } from "@thirdweb-dev/vault-sdk";or a separate import forpingto avoid confusion.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (7)
apps/portal/src/app/vault/sdk/api-reference/page.mdx(1 hunks)apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx(1 hunks)apps/portal/src/app/vault/sdk/guides/creating-eoas/page.mdx(1 hunks)apps/portal/src/app/vault/sdk/guides/signing/page.mdx(1 hunks)apps/portal/src/app/vault/sdk/installation/page.mdx(1 hunks)apps/portal/src/app/vault/sdk/page.mdx(1 hunks)apps/portal/src/app/vault/sidebar.tsx(2 hunks)
🧰 Additional context used
🪛 LanguageTool
apps/portal/src/app/vault/sdk/page.mdx
[misspelling] ~19-~19: This word is normally spelled as one.
Context: ...Create EOAs (wallets)* – generate new non-custodial accounts inside the Vault. 3. **Sign pa...
(EN_COMPOUNDS_NON_CUSTODIAL)
apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx
[uncategorized] ~3-~3: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ... Tokens Access tokens let you delegate finely-scoped permissions to services, cron jobs or e...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
[uncategorized] ~15-~15: Possible missing comma found.
Context: ...ger). They cannot be scoped by expiry – instead you define policies that control whic...
(AI_HYDRA_LEO_MISSING_COMMA)
apps/portal/src/app/vault/sdk/guides/signing/page.mdx
[typographical] ~3-~3: It appears that a comma is missing.
Context: ...igning Transactions & Messages In this guide we will request signatures from the Vau...
(DURING_THAT_TIME_COMMA)
⏰ Context from checks skipped due to timeout of 90000ms (3)
- GitHub Check: Size
- GitHub Check: Lint Packages
- GitHub Check: Analyze (javascript)
🔇 Additional comments (7)
apps/portal/src/app/vault/sidebar.tsx (1)
3-3: LGTM! Well-structured sidebar addition for the Vault SDK.The new TypeScript SDK section is well-organized with links to all critical documentation components (overview, installation, API reference) and includes a nested guides section. The import for Code2Icon is properly added to support the new section's icon.
Also applies to: 51-85
apps/portal/src/app/vault/sdk/guides/creating-eoas/page.mdx (1)
1-75: LGTM! Well-structured guide for EOA management.The guide provides clear instructions on creating and managing EOAs with appropriate examples. The prerequisites, code samples, explanations of metadata usage, pagination handling, and best practices are all well presented and technically accurate.
apps/portal/src/app/vault/sdk/page.mdx (1)
1-71: LGTM! Comprehensive SDK overview.The page effectively introduces the Vault SDK, its capabilities, common use cases, and includes a clear example. It provides a solid entry point for developers to understand what they can accomplish with the SDK.
🧰 Tools
🪛 LanguageTool
[misspelling] ~19-~19: This word is normally spelled as one.
Context: ...Create EOAs (wallets)* – generate new non-custodial accounts inside the Vault. 3. **Sign pa...(EN_COMPOUNDS_NON_CUSTODIAL)
apps/portal/src/app/vault/sdk/installation/page.mdx (1)
1-47: LGTM! Clear installation and setup instructions.The installation guide provides comprehensive instructions for different package managers, explains peer dependencies, and offers helpful guidance on client initialization and management.
Also applies to: 49-54
apps/portal/src/app/vault/sdk/guides/signing/page.mdx (1)
1-8: Guide is well structured and comprehensive. The introduction, prerequisites, examples, and error handling sections cover the signing workflows clearly and thoroughly.🧰 Tools
🪛 LanguageTool
[typographical] ~3-~3: It appears that a comma is missing.
Context: ...igning Transactions & Messages In this guide we will request signatures from the Vau...(DURING_THAT_TIME_COMMA)
apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx (1)
1-10: The access tokens guide is clear and informative. It effectively covers creation, derivation, listing, revocation, and best practices for managing Vault SDK tokens.🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ... Tokens Access tokens let you delegate finely-scoped permissions to services, cron jobs or e...(HYPHENATED_LY_ADVERB_ADJECTIVE)
apps/portal/src/app/vault/sdk/api-reference/page.mdx (1)
1-10: API Reference is organized and thorough. Grouping functions by capability and providing examples helps developers find relevant information quickly.
| | --- | --- | | ||
| | `createServiceAccount({ request })` | Bootstrap a brand-new Vault. Returns the **admin key** and **rotation code**. _Run once during provisioning_. | | ||
| | `getServiceAccount({ request })` | Retrieve metadata for the current service account. Requires **admin key** or a token with `serviceAccount:read` policy. | | ||
| | `rotateServiceAccount({ request })` | Rotate (invalidate) the admin key **and** all existing access tokens in a single atomic operation. Authenticate with the **rotation code**. | | ||
|
|
There was a problem hiding this comment.
Fix function signature documentation in Service Accounts section.
The table lists createServiceAccount({ request }), getServiceAccount({ request }), and rotateServiceAccount({ request }), but the example and actual SDK require passing { client, request }. Update the table entries to reflect the correct signature including client.
🤖 Prompt for AI Agents
In apps/portal/src/app/vault/sdk/api-reference/page.mdx around lines 24 to 28,
the function signatures in the Service Accounts section incorrectly list only `{
request }` as parameters. Update each function signature in the table to include
both `{ client, request }` to match the actual SDK usage and examples.
Co-authored-by: graphite-app[bot] <96075541+graphite-app[bot]@users.noreply.github.com> Signed-off-by: Joaquim Verges <[email protected]>
| | `signTransaction` | Ask the Vault to sign an EVM transaction (legacy, 2930, 1559, 4844 or 7702). | | ||
| | `signMessage` | Sign a plain string / hex message. | | ||
| | `signTypedData` | Sign EIP-712 typed data with full generic type safety. | | ||
| | `signAuthorization` | Sign an [`Authorization`](#authorization) struct used by some L2s / account-abstraction schemes. | |
There was a problem hiding this comment.
The #authorization anchor link doesn't have a corresponding target in the document. Either add a section explaining the Authorization struct with the proper anchor ID, or remove the link formatting from the reference. This will prevent users from encountering a broken link when they click on it.
| | `signAuthorization` | Sign an [`Authorization`](#authorization) struct used by some L2s / account-abstraction schemes. | | |
| | `signAuthorization` | Sign an `Authorization` struct used by some L2s / account-abstraction schemes. | |
Spotted by Diamond
Is this helpful? React 👍 or 👎 to let us know.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (2)
apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx (2)
3-3: Refine hyphen usage in the compound modifier
Remove the unnecessary hyphen in “finely-scoped,” since adverbs ending in “-ly” do not require a hyphen.- Access tokens let you delegate finely-scoped permissions to services, cron jobs or external partners without sharing the admin key. + Access tokens let you delegate finely scoped permissions to services, cron jobs or external partners without sharing the admin key.🧰 Tools
🪛 LanguageTool
[uncategorized] ~3-~3: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ... Tokens Access tokens let you delegate finely-scoped permissions to services, cron jobs or e...(HYPHENATED_LY_ADVERB_ADJECTIVE)
67-67: Correct hyphenation of “untrusted”
“un-trusted” should be one word.- 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. + Send SATs to untrusted environments (browser, serverless) – they only work until the expiry timestamp and can be revoked centrally by revoking their base token.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
📒 Files selected for processing (1)
apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx(1 hunks)
🧰 Additional context used
🪛 LanguageTool
apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx
[uncategorized] ~3-~3: Although a hyphen is possible, it is not necessary in a compound modifier in which the first word is an adverb that ends in ‘ly’.
Context: ... Tokens Access tokens let you delegate finely-scoped permissions to services, cron jobs or e...
(HYPHENATED_LY_ADVERB_ADJECTIVE)
⏰ Context from checks skipped due to timeout of 90000ms (6)
- GitHub Check: E2E Tests (pnpm, esbuild)
- GitHub Check: E2E Tests (pnpm, webpack)
- GitHub Check: E2E Tests (pnpm, vite)
- GitHub Check: Size
- GitHub Check: Lint Packages
- GitHub Check: Analyze (javascript)
🔇 Additional comments (1)
apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx (1)
73-95:⚠️ Potential issueClose the code fence for the list & revoke example
The list/revoke code block also needs a closing ``` fence after the revoke call.await revokeAccessToken({ client, request: { auth: { adminKey: process.env.VAULT_ADMIN_KEY! }, options: { id: tokenId }, }, }); + ```Likely an incorrect or invalid review comment.
| ```ts | ||
| import { createSignedAccessToken } from "@thirdweb-dev/vault-sdk"; | ||
|
|
||
|
|
||
| const sat = await createSignedAccessToken({ | ||
| vaultClient: client, | ||
| baseAccessToken: process.env.BASE_ACCESS_TOKEN, | ||
|
|
||
| additionalPolicies: [ | ||
| { type: "eoa:signMessage", chainId: 1 }, | ||
| ], | ||
| expiryTimestamp: Math.floor(Date.now() / 1000) + 300, // 5 minutes | ||
| }); | ||
|
|
||
| // Prefix: vt_sat_<JWT> | ||
| console.log(sat); |
There was a problem hiding this comment.
Close the code fence for the signed access token (SAT) example
The SAT snippet starts with ts but lacks a closing fence. Add it right after the console.log(sat); to ensure proper rendering.
console.log(sat);
+ ```🤖 Prompt for AI Agents
In apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx around lines 49
to 64, the TypeScript code block for the signed access token example starts with
a ```ts fence but is missing the closing ``` fence. Add the closing ``` fence
immediately after the line containing console.log(sat); to properly close the
code block and ensure correct markdown rendering.
| ```ts | ||
| import { createVaultClient, createAccessToken } from "@thirdweb-dev/vault-sdk"; | ||
|
|
||
| const client = await createVaultClient({ secretKey: "PROJECT_SECRET_KEY" }); | ||
|
|
||
| const res = await createAccessToken({ | ||
| client, | ||
| request: { | ||
| auth: { adminKey: process.env.VAULT_ADMIN_KEY! }, | ||
| options: { | ||
| policies: [ | ||
| { | ||
| type: "eoa:signMessage", | ||
| allowlist: ["0xEoaAddress"], | ||
| messagePattern: "^0x.*", // only allow hex messages | ||
| }, | ||
| ], | ||
| expiresAt: new Date("2030-01-01").toISOString(), | ||
| metadata: { env: "prod", owner: "backend" }, | ||
| }, | ||
| }, | ||
| }); | ||
|
|
||
| console.log("base token", res.data.accessToken); | ||
| ``` |
There was a problem hiding this comment.
Close the code fence for the base token example
The opening ```ts block at line 17 is not closed, which will break MDX parsing. Add a closing fence after the console.log call.
console.log("base token", res.data.accessToken);
+ ```🤖 Prompt for AI Agents
In apps/portal/src/app/vault/sdk/guides/access-tokens/page.mdx between lines 17
and 41, the TypeScript code block starting with ```ts is not closed, causing MDX
parsing errors. Add a closing code fence ``` immediately after the console.log
statement to properly close the code block.
PR-Codex overview
This PR introduces a new
TypeScript SDKsection in the sidebar and enhances documentation for the Vault SDK, including installation instructions, guides for managing EOAs, signing transactions, and access tokens.Detailed summary
TypeScript SDKin thesidebar.tsx.page.mdx.api-reference/page.mdx.Summary by CodeRabbit