Skip to content

Commit 1d77ad3

Browse files
atejadaatejada
authored
Merge branch 'main' into Update-L2-language-to-indicate-were-already-an-L2
2 parents 7a4eac5 + e08c701 commit 1d77ad3

File tree

238 files changed

+4930
-1823
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

238 files changed

+4930
-1823
lines changed

‎.github/workflows/links.yml

+5-1
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,11 @@ jobs:
2929
--verbose
3030
--no-progress
3131
--cache --max-cache-age 1d
32-
'./docs/cel2/**/*.html'
32+
'./**/*.html'
33+
'./**/*.js'
34+
'./**/*.md'
35+
'./**/*.rst'
36+
'./**/*.tsx'
3337
env:
3438
GITHUB_TOKEN: ${{secrets.GITHUB_TOKEN}}
3539

‎docs/build/build-on-socialconnect.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -47,4 +47,4 @@ To dive deeper into SocialConnect, explore the following sections in the documen
4747
- **Guides**: Step-by-step instructions for various tasks.
4848
- **Protocol**: Detailed information about the protocol's architecture and components.
4949
- **Examples**: Practical examples, including a Next.js example.
50-
- **Contracts**: Information about the smart contracts used in SocialConnect.
50+
- **Contracts**: Information about the smart contracts used in SocialConnect.

‎docs/build/build-with-ai/build-with-goat/mint-nft-agent.md

+279
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,279 @@
1+
# Tutorial: Build an AI-Powered NFT Minting Agent on Celo
2+
3+
This tutorial guides you through building an AI-powered agent capable of minting NFTs on the Celo blockchain. We will adapt the structure from the previous [token swapping tutorial](./token-swap-agent.md) to create an agent that can mint NFTs based on natural language prompts.
4+
5+
This approach provides direct control over the minting process and utilizes core blockchain interaction libraries. We will use `@ai-sdk/openai` for AI capabilities, `viem` for direct blockchain interaction, and `@goat-sdk` for agent framework components.
6+
7+
### Understanding the Code: AI Agent for NFT Minting (Direct Contract Interaction)
8+
9+
Let's examine the code structure, building upon the token swapping agent example and focusing on NFT minting.
10+
11+
#### 1. Importing Libraries:
12+
13+
```javascript
14+
import readline from "node:readline";
15+
16+
import { openai } from "@ai-sdk/openai";
17+
import { generateText } from "ai";
18+
19+
import { http } from "viem";
20+
import { createWalletClient } from "viem";
21+
import { privateKeyToAccount } from "viem/accounts";
22+
import { celo } from "viem/chains"; // Using Celo chain
23+
24+
import { getOnChainTools } from "@goat-sdk/adapter-vercel-ai";
25+
26+
import { viem } from "@goat-sdk/wallet-viem";
27+
28+
require("dotenv").config();
29+
```
30+
31+
- **Libraries**: We use the core libraries: readline, @ai-sdk/openai, ai, viem, and @goat-sdk.
32+
- **Chain Import**: We directly import celo from viem/chains to configure for the Celo network.
33+
- **Focused Approach**: We are focusing solely on NFT minting in this version with a generic mintNFT tool.
34+
35+
#### 2. Wallet Client Creation:
36+
37+
```javascript
38+
// 1. Create a wallet client
39+
const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY as `0x${string}`);
40+
41+
const walletClient = createWalletClient({
42+
account: account,
43+
transport: http(process.env.RPC_PROVIDER_URL),
44+
chain: celo, // Using Celo chain
45+
});
46+
```
47+
48+
- **Wallet Client**: This section sets up a viem wallet client connected to the Celo network.
49+
50+
#### 3. Getting On-Chain Tools (NFT Minting Focus):
51+
52+
```javascript
53+
// 2. Get your onchain tools for your wallet
54+
const tools = await getOnChainTools({
55+
wallet: viem(walletClient),
56+
plugins: [
57+
// We define a custom mintNFT tool here
58+
{
59+
name: "mintNFT",
60+
description:
61+
"Use this tool to mint an NFT to a specified address. Input should be the recipient address and (optionally) NFT metadata.",
62+
async execute({ recipientAddress, metadata }) {
63+
// Implementation for minting NFT will be added here using viem
64+
// This is a placeholder - actual minting logic needs to be implemented
65+
console.log(
66+
`Minting NFT to address: ${recipientAddress} with metadata:`,
67+
metadata,
68+
);
69+
return "NFT minting initiated (placeholder - not actually minted). Implement actual minting logic in the execute function.";
70+
},
71+
},
72+
],
73+
});
74+
```
75+
76+
- **On-Chain Tools for NFT Minting**: We define a custom mintNFT tool directly within the plugins array.
77+
- **name: "mintNFT"**: The name of the tool, which the AI agent will use to identify and call it.
78+
- **description**: A crucial description that tells the AI agent when and how to use this tool. It specifies that the tool is for minting NFTs and expects recipientAddress and optional metadata as input.
79+
- **execute(recipientAddress, metadata)**: This is the function that will be executed when the AI agent decides to use the mintNFT tool.
80+
- **Placeholder Implementation**: Currently, the execute function is a placeholder. It logs a message indicating that NFT minting is initiated but does not contain actual minting logic.
81+
- **Implementation using viem** (To be added - see "Implementing the mintNFT Tool" section below): The actual implementation of NFT minting within this execute function will involve using viem to interact with an NFT smart contract on Celo. This will include:
82+
- Connecting to the NFT Contract: Using viem to get an instance of your deployed NFT contract using its address and ABI.
83+
- Calling the Mint Function: Using viem to call the minting function of your NFT contract. This will likely involve sending a transaction from your walletClient and paying gas fees in CELO.
84+
- Handling NFT Metadata: If your NFT contract supports metadata, you'll need to incorporate the metadata input into the minting transaction.
85+
86+
#### 4. Command Line Interface and AI Interaction Loop:
87+
88+
```javascript
89+
// 3. Create a readline interface to interact with the agent
90+
const rl = readline.createInterface({
91+
input: process.stdin,
92+
output: process.stdout,
93+
});
94+
95+
while (true) {
96+
const prompt =
97+
(await new Promise()) <
98+
string >
99+
((resolve) => {
100+
rl.question('Enter your prompt (or "exit" to quit): ', resolve);
101+
});
102+
103+
if (prompt === "exit") {
104+
rl.close();
105+
break;
106+
}
107+
108+
console.log("\n-------------------\n");
109+
console.log("TOOLS CALLED");
110+
console.log("\n-------------------\n");
111+
try {
112+
const result = await generateText({
113+
model: openai("gpt-4o-mini"),
114+
tools: tools,
115+
maxSteps: 10, // Maximum number of tool invocations per request
116+
prompt: prompt,
117+
onStepFinish: (event) => {
118+
console.log(event.toolResults);
119+
},
120+
});
121+
122+
console.log("\n-------------------\n");
123+
console.log("RESPONSE");
124+
console.log("\n-------------------\n");
125+
console.log(result.text);
126+
} catch (error) {
127+
console.error(error);
128+
}
129+
console.log("\n-------------------\n");
130+
}
131+
```
132+
133+
- **Interactive Loop**: This provides the command-line interface and AI interaction using generateText.
134+
135+
### Setup Guide for Celo NFT Minting Agent
136+
137+
Follow these steps to set up the AI-powered NFT minting agent on Celo:
138+
139+
#### 1. Clone Repository and Navigate to Example Directory:
140+
141+
Follow steps 1-5 from the [previous tutorial](./token-swap-agent.md) to clone the GOAT repository, navigate to the typescript directory, install dependencies, build the project, and go to the example directory: examples/by-use-case/evm-mint-nft.
142+
143+
#### 2. Configure Environment Variables:
144+
145+
```bash
146+
cp .env.template .env
147+
```
148+
149+
Copy .env.template to .env and populate the following environment variables:
150+
151+
- **OPENAI_API_KEY**: Your OpenAI API key from OpenAI.
152+
- **WALLET_PRIVATE_KEY**: Your private key for the wallet that will mint NFTs on Celo. Security Best Practices: Use a test wallet and handle private keys with extreme caution.
153+
- **RPC_PROVIDER_URL**: The RPC URL for the Celo network (e.g., Celo Alfajores Testnet: https://alfajores-forno.celo-testnet.org). See previous articles for more Celo RPC options.
154+
155+
Example .env file (for Celo Alfajores Testnet):
156+
157+
```
158+
OPENAI_API_KEY=YOUR_OPENAI_API_KEY
159+
WALLET_PRIVATE_KEY=YOUR_PRIVATE_KEY
160+
RPC_PROVIDER_URL=https://alfajores-forno.celo-testnet.org
161+
```
162+
163+
#### 3. Adapt Code for Celo and NFT Minting:
164+
165+
- **Chain Configuration**: In index.ts, ensure you have celo chain imported and configured in createWalletClient as shown in the code examples above.
166+
167+
- **Implement the mintNFT Tool's execute Function**: This is the crucial step to enable actual NFT minting. You need to replace the placeholder implementation in the mintNFT tool's execute function with the actual logic to interact with your NFT smart contract on Celo using viem.
168+
169+
**Implementing the mintNFT Tool's execute Function (Conceptual Steps):**
170+
171+
```javascript
172+
// ... inside the plugins array in getOnChainTools:
173+
{
174+
name: "mintNFT",
175+
description: "...",
176+
async execute({ recipientAddress, metadata }) {
177+
try {
178+
// 1. NFT Contract Address and ABI:
179+
const nftContractAddress = "YOUR_NFT_CONTRACT_ADDRESS"; // Replace with your NFT contract address on Celo
180+
const nftContractAbi = [...]; // Replace with your NFT contract ABI (interface)
181+
182+
// 2. Get Contract Instance using viem:
183+
const nftContract = getContract({
184+
address: nftContractAddress,
185+
abi: nftContractAbi,
186+
publicClient: walletClient, // or use publicClient if you only need to read
187+
});
188+
189+
// 3. Call the mint function (Adapt to your contract's mint function name and parameters):
190+
const mintTxHash = await walletClient.writeContract({
191+
address: nftContractAddress,
192+
abi: nftContractAbi,
193+
functionName: 'mint', // Replace with your contract's mint function name
194+
account: walletClient.account,
195+
args: [recipientAddress, metadata], // Adapt arguments based on your contract's mint function parameters
196+
gas: 2000000, // Adjust gas limit as needed
197+
});
198+
199+
console.log("Mint Transaction Hash:", mintTxHash);
200+
return `NFT mint transaction initiated. Transaction hash: ${mintTxHash}. (Remember to check transaction status on a Celo block explorer.)`;
201+
202+
203+
} catch (error) {
204+
console.error("Error minting NFT:", error);
205+
return `NFT minting failed. Error: ${error.message}`;
206+
}
207+
},
208+
}
209+
```
210+
211+
**Explanation of mintNFT Tool Implementation:**
212+
213+
- **NFT Contract Address and ABI**:
214+
215+
- **nftContractAddress**: You MUST replace "YOUR_NFT_CONTRACT_ADDRESS" with the actual address of your deployed NFT smart contract on the Celo network (Alfajores Testnet or Mainnet).
216+
- **nftContractAbi**: You MUST replace [...] with the ABI (Application Binary Interface) of your NFT smart contract. The ABI defines how to interact with your contract's functions. You can usually get the ABI from your smart contract compilation output (e.g., from Hardhat or Truffle).
217+
218+
- **getContract**: We use viem's getContract function to create a contract instance, allowing us to interact with your deployed NFT contract. We provide the address, abi, and publicClient (or walletClient if you need to send transactions).
219+
220+
- **walletClient.writeContract**: This is the core viem function to send a transaction to your smart contract to call the minting function.
221+
222+
- **address**: NFT contract address.
223+
- **abi**: NFT contract ABI.
224+
- **functionName**: 'mint': Replace 'mint' with the actual name of your minting function in your NFT contract.
225+
- **account**: walletClient.account: Specifies the account (your wallet) that will send the transaction.
226+
- **args**: [recipientAddress, metadata]: Adapt args to match the parameters of your NFT contract's mint function. The example assumes your mint function takes a recipientAddress and metadata. You might need to adjust this based on your contract. Metadata handling will also depend on how your NFT contract stores or handles metadata (e.g., you might pass a URI, or metadata might be handled differently).
227+
- **gas**: 2000000: Sets a gas limit for the transaction. Adjust this value as needed based on your contract's gas requirements. You can estimate gas using viem functions or start with a generous limit and adjust down if needed.
228+
229+
- **Transaction Hash and Error Handling**: The code logs the transaction hash and returns a message. It also includes basic error handling.
230+
231+
**Important Considerations for mintNFT Implementation:**
232+
233+
- **NFT Contract Deployment**: You need to have a deployed NFT smart contract on Celo (Alfajores or Mainnet) to use this agent. You'll need the contract address and ABI.
234+
- **NFT Contract mint Function**: Understand the exact function name, parameters, and any access control or requirements of your NFT contract's minting function.
235+
- **Metadata Handling**: Determine how your NFT contract handles metadata. You might need to adjust the metadata parameter and how you pass it to the mint function.
236+
- **Gas Fees**: Minting transactions require CELO to pay for gas fees. Ensure your wallet has sufficient CELO.
237+
- **Error Handling**: Implement more robust error handling in the execute function to catch potential issues during contract interaction.
238+
- **Security**: Be extremely cautious when dealing with smart contracts and blockchain transactions, especially in production. Thoroughly test your contract and agent in a test environment before deploying to mainnet.
239+
240+
#### 4. Usage Instructions:
241+
242+
**Run the Interactive CLI:**
243+
244+
From the examples/by-use-case/evm-mint-nft directory, run:
245+
246+
```bash
247+
pnpm ts-node index.ts
248+
```
249+
250+
**Chat with the Agent for NFT Minting:**
251+
252+
Interact with the agent using natural language prompts to mint NFTs. Here are example prompts:
253+
254+
- "Mint an NFT for address 0x1234...5678" - Instruct the agent to mint an NFT to the specified recipient address. (Replace 0x1234...5678 with an actual Celo address).
255+
- "Mint an NFT with metadata `{'name': 'My NFT', 'description': 'A test NFT'}`" - Instruct the agent to mint an NFT with specific metadata. (The exact format of metadata and how it's handled will depend on your mintNFT tool implementation and NFT contract).
256+
257+
**Example Interaction:**
258+
259+
```
260+
Enter your prompt (or "exit" to quit): Mint an NFT for address 0xRecipientAddressHere
261+
-------------------
262+
TOOLS CALLED
263+
-------------------
264+
// Output of tool calls will be logged here (from onStepFinish callback)
265+
-------------------
266+
RESPONSE
267+
-------------------
268+
// AI agent's response based on the prompt and tool execution
269+
-------------------
270+
Enter your prompt (or "exit" to quit): exit
271+
```
272+
273+
### Conclusion
274+
275+
This tutorial has provided a guide to building an AI-powered NFT minting agent on Celo. By directly interacting with an NFT smart contract using viem, you gain more control over the minting process.
276+
277+
Remember that the provided mintNFT tool's execute function is a placeholder. You MUST implement the actual NFT minting logic using viem and your deployed NFT smart contract on Celo as described in the "Implementing the mintNFT Tool" section.
278+
279+
Thoroughly test your agent and smart contract in a test environment before deploying to the Celo mainnet. Explore the viem documentation and experiment with different prompts and metadata handling to create a powerful and user-friendly AI-driven NFT minting experience on Celo!

0 commit comments

Comments
 (0)