Skip to content

Commit b10f306

Browse files
joaquim-vergesjoaquim-verges
authored
feat: Add Nebula AI chat and transaction execution API (#5948)
1 parent d1c03b0 commit b10f306

File tree

12 files changed

+458
-174
lines changed

12 files changed

+458
-174
lines changed

‎.changeset/warm-dodos-destroy.md

+44
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
---
2+
"thirdweb": minor
3+
---
4+
5+
Introducing Nebula API
6+
7+
You can now chat with Nebula and ask it to execute transactions with your wallet.
8+
9+
Ask questions about real time blockchain data.
10+
11+
```ts
12+
import { Nebula } from "thirdweb/ai";
13+
14+
const response = await Nebula.chat({
15+
client: TEST_CLIENT,
16+
prompt:
17+
"What's the symbol of this contract: 0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
18+
context: {
19+
chains: [sepolia],
20+
},
21+
});
22+
23+
console.log("chat response:", response.message);
24+
```
25+
26+
Ask it to execute transactions with your wallet.
27+
28+
```ts
29+
import { Nebula } from "thirdweb/ai";
30+
31+
const wallet = createWallet("io.metamask");
32+
const account = await wallet.connect({ client });
33+
34+
const result = await Nebula.execute({
35+
client,
36+
prompt: "send 0.0001 ETH to vitalik.eth",
37+
account,
38+
context: {
39+
chains: [sepolia],
40+
},
41+
});
42+
43+
console.log("executed transaction:", result.transactionHash);
44+
```

‎apps/portal/src/app/references/components/TDoc/utils/getSidebarLinkgroups.ts

+2
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,7 @@ const tagsToGroup = {
4242
"@modules": "Modules",
4343
"@client": "Client",
4444
"@account": "Account",
45+
"@nebula": "Nebula",
4546
} as const;
4647

4748
type TagKey = keyof typeof tagsToGroup;
@@ -81,6 +82,7 @@ const sidebarGroupOrder: TagKey[] = [
8182
"@utils",
8283
"@others",
8384
"@account",
85+
"@nebula",
8486
];
8587

8688
function findTag(

‎packages/thirdweb/package.json

+24-54
Original file line numberDiff line numberDiff line change
@@ -123,64 +123,34 @@
123123
"import": "./dist/esm/exports/social.js",
124124
"default": "./dist/cjs/exports/social.js"
125125
},
126+
"./ai": {
127+
"types": "./dist/types/exports/ai.d.ts",
128+
"import": "./dist/esm/exports/ai.js",
129+
"default": "./dist/cjs/exports/ai.js"
130+
},
126131
"./package.json": "./package.json"
127132
},
128133
"typesVersions": {
129134
"*": {
130-
"adapters/*": [
131-
"./dist/types/exports/adapters/*.d.ts"
132-
],
133-
"auth": [
134-
"./dist/types/exports/auth.d.ts"
135-
],
136-
"chains": [
137-
"./dist/types/exports/chains.d.ts"
138-
],
139-
"contract": [
140-
"./dist/types/exports/contract.d.ts"
141-
],
142-
"deploys": [
143-
"./dist/types/exports/deploys.d.ts"
144-
],
145-
"event": [
146-
"./dist/types/exports/event.d.ts"
147-
],
148-
"extensions/*": [
149-
"./dist/types/exports/extensions/*.d.ts"
150-
],
151-
"pay": [
152-
"./dist/types/exports/pay.d.ts"
153-
],
154-
"react": [
155-
"./dist/types/exports/react.d.ts"
156-
],
157-
"react-native": [
158-
"./dist/types/exports/react-native.d.ts"
159-
],
160-
"rpc": [
161-
"./dist/types/exports/rpc.d.ts"
162-
],
163-
"storage": [
164-
"./dist/types/exports/storage.d.ts"
165-
],
166-
"transaction": [
167-
"./dist/types/exports/transaction.d.ts"
168-
],
169-
"utils": [
170-
"./dist/types/exports/utils.d.ts"
171-
],
172-
"wallets": [
173-
"./dist/types/exports/wallets.d.ts"
174-
],
175-
"wallets/*": [
176-
"./dist/types/exports/wallets/*.d.ts"
177-
],
178-
"modules": [
179-
"./dist/types/exports/modules.d.ts"
180-
],
181-
"social": [
182-
"./dist/types/exports/social.d.ts"
183-
]
135+
"adapters/*": ["./dist/types/exports/adapters/*.d.ts"],
136+
"auth": ["./dist/types/exports/auth.d.ts"],
137+
"chains": ["./dist/types/exports/chains.d.ts"],
138+
"contract": ["./dist/types/exports/contract.d.ts"],
139+
"deploys": ["./dist/types/exports/deploys.d.ts"],
140+
"event": ["./dist/types/exports/event.d.ts"],
141+
"extensions/*": ["./dist/types/exports/extensions/*.d.ts"],
142+
"pay": ["./dist/types/exports/pay.d.ts"],
143+
"react": ["./dist/types/exports/react.d.ts"],
144+
"react-native": ["./dist/types/exports/react-native.d.ts"],
145+
"rpc": ["./dist/types/exports/rpc.d.ts"],
146+
"storage": ["./dist/types/exports/storage.d.ts"],
147+
"transaction": ["./dist/types/exports/transaction.d.ts"],
148+
"utils": ["./dist/types/exports/utils.d.ts"],
149+
"wallets": ["./dist/types/exports/wallets.d.ts"],
150+
"wallets/*": ["./dist/types/exports/wallets/*.d.ts"],
151+
"modules": ["./dist/types/exports/modules.d.ts"],
152+
"social": ["./dist/types/exports/social.d.ts"],
153+
"ai": ["./dist/types/exports/ai.d.ts"]
184154
}
185155
},
186156
"browser": {

‎packages/thirdweb/scripts/typedoc.mjs

+1
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@ const app = await Application.bootstrapWithPlugins({
99
"src/extensions/modules/**/index.ts",
1010
"src/adapters/eip1193/index.ts",
1111
"src/wallets/smart/presets/index.ts",
12+
"src/ai/index.ts",
1213
],
1314
exclude: [
1415
"src/exports/*.native.ts",

‎packages/thirdweb/src/ai/chat.test.ts

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
import { describe, expect, it } from "vitest";
2+
import { TEST_CLIENT } from "../../test/src/test-clients.js";
3+
import { TEST_ACCOUNT_A, TEST_ACCOUNT_B } from "../../test/src/test-wallets.js";
4+
import { sepolia } from "../chains/chain-definitions/sepolia.js";
5+
import * as Nebula from "./index.js";
6+
7+
describe.runIf(process.env.TW_SECRET_KEY)("chat", () => {
8+
it("should respond with a message", async () => {
9+
const response = await Nebula.chat({
10+
client: TEST_CLIENT,
11+
prompt: `What's the symbol of this contract: 0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8`,
12+
context: {
13+
chains: [sepolia],
14+
},
15+
});
16+
expect(response.message).toContain("CAT");
17+
});
18+
19+
it("should respond with a transaction", async () => {
20+
const response = await Nebula.chat({
21+
client: TEST_CLIENT,
22+
prompt: `send 0.0001 ETH on sepolia to ${TEST_ACCOUNT_B.address}`,
23+
account: TEST_ACCOUNT_A,
24+
context: {
25+
chains: [sepolia],
26+
walletAddresses: [TEST_ACCOUNT_A.address],
27+
},
28+
});
29+
expect(response.transactions.length).toBe(1);
30+
});
31+
});

‎packages/thirdweb/src/ai/chat.ts

+26
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import { type Input, type Output, nebulaFetch } from "./common.js";
2+
3+
/**
4+
* Chat with Nebula.
5+
*
6+
* @param input - The input for the chat.
7+
* @returns The chat response.
8+
* @beta
9+
* @nebula
10+
*
11+
* @example
12+
* ```ts
13+
* import { Nebula } from "thirdweb/ai";
14+
*
15+
* const response = await Nebula.chat({
16+
* client: TEST_CLIENT,
17+
* prompt: "What's the symbol of this contract: 0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
18+
* context: {
19+
* chains: [sepolia],
20+
* },
21+
* });
22+
* ```
23+
*/
24+
export async function chat(input: Input): Promise<Output> {
25+
return nebulaFetch("chat", input);
26+
}

‎packages/thirdweb/src/ai/common.ts

+114
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
import type { Chain } from "../chains/types.js";
2+
import { getCachedChain } from "../chains/utils.js";
3+
import type { ThirdwebClient } from "../client/client.js";
4+
import {
5+
type PreparedTransaction,
6+
prepareTransaction,
7+
} from "../transaction/prepare-transaction.js";
8+
import type { Address } from "../utils/address.js";
9+
import { toBigInt } from "../utils/bigint.js";
10+
import type { Hex } from "../utils/encoding/hex.js";
11+
import { getClientFetch } from "../utils/fetch.js";
12+
import type { Account } from "../wallets/interfaces/wallet.js";
13+
14+
const NEBULA_API_URL = "https://nebula-api.thirdweb.com";
15+
16+
export type Input = {
17+
client: ThirdwebClient;
18+
prompt: string | string[];
19+
account?: Account;
20+
context?: {
21+
chains?: Chain[];
22+
walletAddresses?: string[];
23+
contractAddresses?: string[];
24+
};
25+
sessionId?: string;
26+
};
27+
28+
export type Output = {
29+
message: string;
30+
sessionId: string;
31+
transactions: PreparedTransaction[];
32+
};
33+
34+
type ApiResponse = {
35+
message: string;
36+
session_id: string;
37+
actions?: {
38+
type: "init" | "presence" | "sign_transaction";
39+
source: string;
40+
data: string;
41+
}[];
42+
};
43+
44+
export async function nebulaFetch(
45+
mode: "execute" | "chat",
46+
input: Input,
47+
): Promise<Output> {
48+
const fetch = getClientFetch(input.client);
49+
const response = await fetch(`${NEBULA_API_URL}/${mode}`, {
50+
method: "POST",
51+
headers: {
52+
"Content-Type": "application/json",
53+
},
54+
body: JSON.stringify({
55+
message: input.prompt, // TODO: support array of messages
56+
session_id: input.sessionId,
57+
...(input.account
58+
? {
59+
execute_config: {
60+
mode: "client",
61+
signer_wallet_address: input.account.address,
62+
},
63+
}
64+
: {}),
65+
...(input.context
66+
? {
67+
context_filter: {
68+
chain_ids:
69+
input.context.chains?.map((c) => c.id.toString()) || [],
70+
signer_wallet_address: input.context.walletAddresses || [],
71+
contract_addresses: input.context.contractAddresses || [],
72+
},
73+
}
74+
: {}),
75+
}),
76+
});
77+
if (!response.ok) {
78+
const error = await response.text();
79+
throw new Error(`Nebula API error: ${error}`);
80+
}
81+
const data = (await response.json()) as ApiResponse;
82+
83+
// parse transactions if present
84+
let transactions: PreparedTransaction[] = [];
85+
if (data.actions) {
86+
transactions = data.actions
87+
.map((action) => {
88+
// only parse sign_transaction actions
89+
if (action.type === "sign_transaction") {
90+
const tx = JSON.parse(action.data) as {
91+
chainId: number;
92+
to: Address | undefined;
93+
value: Hex;
94+
data: Hex;
95+
};
96+
return prepareTransaction({
97+
chain: getCachedChain(tx.chainId),
98+
client: input.client,
99+
to: tx.to,
100+
value: tx.value ? toBigInt(tx.value) : undefined,
101+
data: tx.data,
102+
});
103+
}
104+
return undefined;
105+
})
106+
.filter((tx) => tx !== undefined);
107+
}
108+
109+
return {
110+
message: data.message,
111+
sessionId: data.session_id,
112+
transactions,
113+
};
114+
}

‎packages/thirdweb/src/ai/execute.test.ts

+43
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,43 @@
1+
import { describe, expect, it } from "vitest";
2+
import { TEST_CLIENT } from "../../test/src/test-clients.js";
3+
import { TEST_ACCOUNT_A, TEST_ACCOUNT_B } from "../../test/src/test-wallets.js";
4+
import { sepolia } from "../chains/chain-definitions/sepolia.js";
5+
import { getContract } from "../contract/contract.js";
6+
import * as Nebula from "./index.js";
7+
8+
describe("execute", () => {
9+
it("should execute a tx", async () => {
10+
await expect(
11+
Nebula.execute({
12+
client: TEST_CLIENT,
13+
prompt: `send 0.0001 ETH to ${TEST_ACCOUNT_B.address}`,
14+
account: TEST_ACCOUNT_A,
15+
context: {
16+
chains: [sepolia],
17+
walletAddresses: [TEST_ACCOUNT_A.address],
18+
},
19+
}),
20+
).rejects.toThrow(/insufficient funds for gas/); // shows that the tx was sent
21+
});
22+
23+
// TODO make this work reliably
24+
it.skip("should execute a contract call", async () => {
25+
const nftContract = getContract({
26+
client: TEST_CLIENT,
27+
chain: sepolia,
28+
address: "0xe2cb0eb5147b42095c2FfA6F7ec953bb0bE347D8",
29+
});
30+
31+
const response = await Nebula.execute({
32+
client: TEST_CLIENT,
33+
prompt: `approve 1 token of token id 0 to ${TEST_ACCOUNT_B.address} using the approve function`,
34+
account: TEST_ACCOUNT_A,
35+
context: {
36+
chains: [nftContract.chain],
37+
walletAddresses: [TEST_ACCOUNT_A.address],
38+
contractAddresses: [nftContract.address],
39+
},
40+
});
41+
expect(response.transactionHash).toBeDefined();
42+
});
43+
});

0 commit comments

Comments
 (0)