Web3 + AI Hybrid Stack Setup Guide (IPFS + The Graph + LangChain)

# Create Next.js project with TypeScript
npx create-next-app@latest web3-ai-app --typescript --tailwind --app --no-src-dir
cd web3-ai-app

# Install Web3 core dependencies
npm install wagmi viem @tanstack/react-query
npm install @rainbow-me/rainbowkit

# Install IPFS client
npm install ipfs-http-client

# Install The Graph client
npm install @apollo/client graphql

# Install LangChain for AI
npm install langchain @langchain/openai

# Install Vercel AI SDK
npm install ai

// lib/wagmi.ts
import { getDefaultConfig } from '@rainbow-me/rainbowkit';
import { mainnet, polygon, optimism, arbitrum, base } from 'wagmi/chains';

export const config = getDefaultConfig({
  appName: 'Web3 AI Hybrid App',
  projectId: process.env.NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID!,
  chains: [mainnet, polygon, optimism, arbitrum, base],
  ssr: true, // Enable SSR for Next.js App Router
});

// app/providers.tsx
'use client';
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { RainbowKitProvider, darkTheme } from '@rainbow-me/rainbowkit';
import { WagmiProvider } from 'wagmi';
import { config } from '@/lib/wagmi';
import '@rainbow-me/rainbowkit/styles.css';

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <WagmiProvider config={config}>
      <QueryClientProvider client={queryClient}>
        <RainbowKitProvider theme={darkTheme()}>
          {children}
        </RainbowKitProvider>
      </QueryClientProvider>
    </WagmiProvider>
  );
}

// lib/ipfs.ts
import { create } from 'ipfs-http-client';

// Configuration for Infura IPFS (alternative: Pinata, Web3.Storage)
const projectId = process.env.IPFS_PROJECT_ID;
const projectSecret = process.env.IPFS_PROJECT_SECRET;
const auth = 'Basic ' + Buffer.from(projectId + ':' + projectSecret).toString('base64');

export const ipfsClient = create({
  host: 'ipfs.infura.io',
  port: 5001,
  protocol: 'https',
  headers: {
    authorization: auth,
  },
});

// Upload file to IPFS with pinning
export async function uploadToIPFS(file: File): Promise<string> {
  try {
    const buffer = await file.arrayBuffer();
    const result = await ipfsClient.add(Buffer.from(buffer), {
      pin: true, // Ensure content is pinned
      progress: (bytes) => console.log(`Uploaded ${bytes} bytes`),
    });
    return result.cid.toString();
  } catch (error) {
    console.error('IPFS upload error:', error);
    throw new Error('Failed to upload to IPFS');
  }
}

// Retrieve content from IPFS
export async function retrieveFromIPFS(cid: string): Promise<Uint8Array> {
  const chunks = [];
  for await (const chunk of ipfsClient.cat(cid)) {
    chunks.push(chunk);
  }
  return Buffer.concat(chunks);
}

// Generate IPFS gateway URL (use public gateway for read)
export function getIPFSUrl(cid: string): string {
  return `https://ipfs.io/ipfs/${cid}`;
}

# Install The Graph CLI
npm install -g @graphprotocol/graph-cli

# Initialize a new subgraph
graph init --product subgraph-studio my-web3-subgraph

# Navigate to subgraph directory
cd my-web3-subgraph

# schema.graphql
type NFT @entity {
  id: ID!
  tokenId: BigInt!
  owner: Bytes!
  metadataURI: String!
  metadataCID: String # IPFS CID extracted from URI
  mintedAt: BigInt!
  transfers: [Transfer!]! @derivedFrom(field: "nft")
}

type Transfer @entity {
  id: ID!
  nft: NFT!
  from: Bytes!
  to: Bytes!
  transactionHash: Bytes!
  timestamp: BigInt!
}

type Metadata @entity {
  id: ID! # IPFS CID
  name: String
  description: String
  image: String
  attributes: [Attribute!]!
}

type Attribute @entity {
  id: ID!
  traitType: String!
  value: String!
}

// src/mapping.ts
import { Transfer as TransferEvent } from '../generated/MyNFT/MyNFT';
import { NFT, Transfer } from '../generated/schema';
import { MyNFT } from '../generated/MyNFT/MyNFT';

export function handleTransfer(event: TransferEvent): void {
  let tokenId = event.params.tokenId.toString();
  let nft = NFT.load(tokenId);
  
  // Create NFT entity if this is a mint (from address 0x0)
  if (nft == null) {
    nft = new NFT(tokenId);
    nft.tokenId = event.params.tokenId;
    
    // Fetch metadata URI from contract
    let contract = MyNFT.bind(event.address);
    let metadataURI = contract.try_tokenURI(event.params.tokenId);
    if (!metadataURI.reverted) {
      nft.metadataURI = metadataURI.value;
      
      // Extract IPFS CID from URI (e.g., ipfs://QmXxx or https://ipfs.io/ipfs/QmXxx)
      let uri = metadataURI.value;
      if (uri.startsWith('ipfs://')) {
        nft.metadataCID = uri.slice(7);
      } else if (uri.includes('/ipfs/')) {
        let parts = uri.split('/ipfs/');
        nft.metadataCID = parts[1];
      }
    }
    
    nft.mintedAt = event.block.timestamp;
  }
  
  // Update owner
  nft.owner = event.params.to;
  nft.save();
  
  // Create transfer record
  let transfer = new Transfer(
    event.transaction.hash.toHex() + '-' + event.logIndex.toString()
  );
  transfer.nft = tokenId;
  transfer.from = event.params.from;
  transfer.to = event.params.to;
  transfer.transactionHash = event.transaction.hash;
  transfer.timestamp = event.block.timestamp;
  transfer.save();
}

# Deploy to Subgraph Studio
graph codegen  # Generate types from schema
graph build    # Build the subgraph
graph deploy --studio my-web3-subgraph

# Your subgraph will be available at:
# https://api.studio.thegraph.com/query/<deploy-key>/my-web3-subgraph/version/latest

// lib/apollo-client.ts
import { ApolloClient, InMemoryCache, gql } from '@apollo/client';

const SUBGRAPH_URL = process.env.NEXT_PUBLIC_SUBGRAPH_URL!;

export const apolloClient = new ApolloClient({
  uri: SUBGRAPH_URL,
  cache: new InMemoryCache(),
});

// Example query: Get NFTs with IPFS metadata
export const GET_NFTS = gql`
  query GetNFTs($first: Int!, $skip: Int!, $owner: Bytes) {
    nfts(
      first: $first
      skip: $skip
      where: { owner: $owner }
      orderBy: mintedAt
      orderDirection: desc
    ) {
      id
      tokenId
      owner
      metadataURI
      metadataCID
      mintedAt
      transfers {
        from
        to
        timestamp
      }
    }
  }
`;

// Example usage in a component
export async function fetchUserNFTs(address: string) {
  const { data } = await apolloClient.query({
    query: GET_NFTS,
    variables: {
      first: 50,
      skip: 0,
      owner: address.toLowerCase(),
    },
  });
  return data.nfts;
}

// lib/langchain.ts
import { ChatOpenAI } from '@langchain/openai';
import { PromptTemplate } from 'langchain/prompts';
import { LLMChain } from 'langchain/chains';
import { Tool } from 'langchain/tools';
import { initializeAgentExecutorWithOptions } from 'langchain/agents';
import { apolloClient, GET_NFTS } from './apollo-client';

// Initialize LLM
const model = new ChatOpenAI({
  modelName: 'gpt-4-turbo-preview',
  temperature: 0.2, // Lower temperature for more deterministic analysis
  openAIApiKey: process.env.OPENAI_API_KEY,
});

// Custom tool: Query blockchain data via The Graph
class BlockchainQueryTool extends Tool {
  name = 'blockchain_query';
  description = 'Query blockchain data indexed by The Graph. Use this to get NFT ownership, transfer history, and metadata.';

  async _call(query: string): Promise<string> {
    try {
      // Parse natural language query into GraphQL (simplified example)
      const { data } = await apolloClient.query({
        query: GET_NFTS,
        variables: { first: 10, skip: 0 },
      });
      return JSON.stringify(data.nfts, null, 2);
    } catch (error) {
      return `Error querying blockchain: ${error}`;
    }
  }
}

// Custom tool: Analyze smart contract code
class ContractAnalysisTool extends Tool {
  name = 'analyze_contract';
  description = 'Analyze Solidity smart contract code for security vulnerabilities, gas optimization, and best practices.';

  async _call(contractCode: string): Promise<string> {
    const prompt = PromptTemplate.fromTemplate(`
Analyze the following Solidity smart contract for:
1. Security vulnerabilities (reentrancy, integer overflow, access control)
2. Gas optimization opportunities
3. Best practice violations
4. Compliance with common standards (ERC-20, ERC-721, etc.)

Contract Code:
{contractCode}

Provide a detailed analysis with severity ratings and recommendations.
    `);

    const chain = new LLMChain({ llm: model, prompt });
    const result = await chain.call({ contractCode });
    return result.text;
  }
}

// Initialize agent with tools
export async function createWeb3AIAgent() {
  const tools = [
    new BlockchainQueryTool(),
    new ContractAnalysisTool(),
  ];

  const agent = await initializeAgentExecutorWithOptions(tools, model, {
    agentType: 'openai-functions',
    verbose: true,
  });

  return agent;
}

// Example: Analyze a contract from user input
export async function analyzeSmartContract(contractCode: string): Promise<string> {
  const agent = await createWeb3AIAgent();
  const result = await agent.call({
    input: `Analyze this smart contract and identify any security issues: ${contractCode}`,
  });
  return result.output;
}

// app/api/analyze-contract/route.ts
import { OpenAIStream, StreamingTextResponse } from 'ai';
import { Configuration, OpenAIApi } from 'openai-edge';

// Edge Runtime configuration
export const runtime = 'edge';

const config = new Configuration({
  apiKey: process.env.OPENAI_API_KEY,
});
const openai = new OpenAIApi(config);

export async function POST(req: Request) {
  const { contractCode } = await req.json();

  if (!contractCode) {
    return new Response('Missing contract code', { status: 400 });
  }

  const prompt = `Analyze this Solidity smart contract for security vulnerabilities, gas optimizations, and best practices:\n\n${contractCode}`;

  const response = await openai.createChatCompletion({
    model: 'gpt-4-turbo-preview',
    stream: true,
    messages: [
      {
        role: 'system',
        content: 'You are a smart contract security expert. Analyze contracts for vulnerabilities, provide severity ratings, and suggest fixes.',
      },
      {
        role: 'user',
        content: prompt,
      },
    ],
    temperature: 0.2,
    max_tokens: 2000,
  });

  // Stream the response back to the client
  const stream = OpenAIStream(response);
  return new StreamingTextResponse(stream);
}

// lib/contract-interaction.ts
import { useContractWrite, usePrepareContractWrite, useWaitForTransaction } from 'wagmi';
import { parseEther, formatEther } from 'viem';

// Example: Safe NFT minting with transaction simulation
export function useSafeMint(contractAddress: `0x${string}`, abi: any) {
  // Step 1: Prepare and simulate transaction
  const { config, error: prepareError } = usePrepareContractWrite({
    address: contractAddress,
    abi: abi,
    functionName: 'mint',
    args: [1], // quantity
    value: parseEther('0.1'), // mint price
    // Wagmi automatically simulates the transaction
  });

  // Step 2: Execute transaction
  const { data, write, isLoading: isWriteLoading } = useContractWrite(config);

  // Step 3: Wait for confirmation
  const { isLoading: isTxLoading, isSuccess } = useWaitForTransaction({
    hash: data?.hash,
    confirmations: 2, // Wait for 2 block confirmations
  });

  return {
    mint: write,
    isLoading: isWriteLoading || isTxLoading,
    isSuccess,
    error: prepareError,
    txHash: data?.hash,
  };
}

// Example: Gas estimation utility
export async function estimateGasWithBuffer(
  client: any,
  transaction: any
): Promise<bigint> {
  try {
    const estimatedGas = await client.estimateGas(transaction);
    // Add 20% buffer to estimated gas
    return (estimatedGas * 120n) / 100n;
  } catch (error) {
    console.error('Gas estimation failed:', error);
    throw new Error('Transaction would fail. Please check parameters.');
  }
}

// Example: Safe multicall for batch reads
import { multicall } from '@wagmi/core';

export async function batchReadNFTMetadata(
  contractAddress: `0x${string}`,
  tokenIds: bigint[]
) {
  const contract = {
    address: contractAddress,
    abi: [/* ERC721 ABI */],
  };

  const results = await multicall({
    contracts: tokenIds.map(tokenId => ({
      ...contract,
      functionName: 'tokenURI',
      args: [tokenId],
    })),
  });

  return results.map((result, i) => ({
    tokenId: tokenIds[i],
    uri: result.status === 'success' ? result.result : null,
    error: result.status === 'failure' ? result.error : null,
  }));
}

// lib/security.ts
import { isAddress, getAddress } from 'viem';

// Validate and normalize Ethereum address
export function validateAddress(address: string): `0x${string}` | null {
  if (!isAddress(address)) {
    return null;
  }
  return getAddress(address); // Returns checksummed address
}

// Verify IPFS content integrity
export async function verifyIPFSContent(
  cid: string,
  expectedHash?: string
): Promise<boolean> {
  try {
    const content = await fetch(`https://ipfs.io/ipfs/${cid}`);
    const buffer = await content.arrayBuffer();
    
    if (expectedHash) {
      const hash = await crypto.subtle.digest('SHA-256', buffer);
      const hashArray = Array.from(new Uint8Array(hash));
      const hashHex = hashArray.map(b => b.toString(16).padStart(2, '0')).join('');
      return hashHex === expectedHash;
    }
    
    return true; // CID itself provides content addressing
  } catch (error) {
    console.error('IPFS content verification failed:', error);
    return false;
  }
}

// Transaction summary for user confirmation
export interface TransactionSummary {
  type: string;
  to: string;
  value: string;
  estimatedGas: string;
  maxCost: string;
  warning?: string;
}

export function generateTransactionSummary(
  tx: any,
  gasEstimate: bigint,
  gasPrice: bigint
): TransactionSummary {
  const maxCost = (gasEstimate * gasPrice) + (tx.value || 0n);
  
  return {
    type: tx.functionName || 'Transfer',
    to: tx.to,
    value: formatEther(tx.value || 0n),
    estimatedGas: gasEstimate.toString(),
    maxCost: formatEther(maxCost),
    warning: maxCost > parseEther('1') ? 'High value transaction!' : undefined,
  };
}

// Content Security Policy headers for Next.js
export const securityHeaders = [
  {
    key: 'Content-Security-Policy',
    value: [
      "default-src 'self'",
      "script-src 'self' 'unsafe-eval' 'unsafe-inline'",
      "style-src 'self' 'unsafe-inline'",
      "img-src 'self' data: https: ipfs.io dweb.link",
      "connect-src 'self' https://*.infura.io https://*.thegraph.com wss://*.walletconnect.com",
      "frame-src 'self' https://verify.walletconnect.com",
    ].join('; '),
  },
  {
    key: 'X-Frame-Options',
    value: 'DENY',
  },
  {
    key: 'X-Content-Type-Options',
    value: 'nosniff',
  },
  {
    key: 'Referrer-Policy',
    value: 'strict-origin-when-cross-origin',
  },
];

# .env.local

# RainbowKit / WalletConnect
NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID=your_project_id_here

# IPFS (Infura, Pinata, or Web3.Storage)
IPFS_PROJECT_ID=your_infura_project_id
IPFS_PROJECT_SECRET=your_infura_secret
# OR
PINATA_API_KEY=your_pinata_key
PINATA_SECRET_KEY=your_pinata_secret

# The Graph
NEXT_PUBLIC_SUBGRAPH_URL=https://api.studio.thegraph.com/query/your-subgraph/your-version/latest

# OpenAI for LangChain
OPENAI_API_KEY=sk-your-openai-api-key

# Optional: Alchemy or Infura RPC (if not using RainbowKit defaults)
NEXT_PUBLIC_ALCHEMY_API_KEY=your_alchemy_key
NEXT_PUBLIC_INFURA_API_KEY=your_infura_key

# Security
NEXTAUTH_SECRET=your_nextauth_secret_for_backend_auth

# Deployment
VERCEL_URL=your-app.vercel.app

# Install Vercel CLI (optional, for CLI deployment)
npm install -g vercel

# Login to Vercel
vercel login

# Deploy to preview
vercel

# Deploy to production
vercel --prod

# Add environment variables via CLI
vercel env add OPENAI_API_KEY production
vercel env add NEXT_PUBLIC_WALLETCONNECT_PROJECT_ID production
vercel env add IPFS_PROJECT_ID production
vercel env add IPFS_PROJECT_SECRET production

// __tests__/contract-interaction.test.ts
import { renderHook, waitFor } from '@testing-library/react';
import { useContractRead } from 'wagmi';
import { mockContract } from './test-utils';

describe('Contract Interactions', () => {
  it('should read NFT metadata correctly', async () => {
    const { result } = renderHook(() =>
      useContractRead({
        address: mockContract.address,
        abi: mockContract.abi,
        functionName: 'tokenURI',
        args: [1n],
      })
    );

    await waitFor(() => expect(result.current.isSuccess).toBe(true));
    expect(result.current.data).toContain('ipfs://');
  });
});

// Monitoring with Vercel Analytics
import { Analytics } from '@vercel/analytics/react';
import { SpeedInsights } from '@vercel/speed-insights/next';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        {children}
        <Analytics /> {/* Track page views and custom events */}
        <SpeedInsights /> {/* Monitor Core Web Vitals */}
      </body>
    </html>
  );
}

// Custom error tracking
export function trackError(error: Error, context: Record<string, any>) {
  console.error('Error:', error, context);
  
  // Send to error tracking service (Sentry, LogRocket, etc.)
  if (typeof window !== 'undefined' && window.gtag) {
    window.gtag('event', 'exception', {
      description: error.message,
      fatal: false,
      ...context,
    });
  }
}

// app/gallery/page.tsx
'use client';
import { ConnectButton } from '@rainbow-me/rainbowkit';
import { useAccount } from 'wagmi';
import { useQuery } from '@apollo/client';
import { useState } from 'react';
import { GET_NFTS } from '@/lib/apollo-client';
import { getIPFSUrl } from '@/lib/ipfs';

export default function NFTGallery() {
  const { address, isConnected } = useAccount();
  const [analysis, setAnalysis] = useState<Record<string, string>>({});

  // Query NFTs from The Graph
  const { data, loading, error } = useQuery(GET_NFTS, {
    variables: { first: 20, skip: 0, owner: address?.toLowerCase() },
    skip: !isConnected,
  });

  // AI analysis of NFT metadata
  async function analyzeNFT(tokenId: string, metadata: any) {
    const response = await fetch('/api/analyze-nft', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ tokenId, metadata }),
    });
    const reader = response.body?.getReader();
    const decoder = new TextDecoder();
    let result = '';

    while (true) {
      const { done, value } = await reader!.read();
      if (done) break;
      result += decoder.decode(value);
      setAnalysis(prev => ({ ...prev, [tokenId]: result }));
    }
  }

  if (!isConnected) {
    return (
      <div className="flex min-h-screen items-center justify-center">
        <div className="text-center">
          <h1 className="text-3xl font-bold mb-4">Web3 AI NFT Gallery</h1>
          <p className="mb-6 text-gray-600">Connect your wallet to view your NFTs</p>
          <ConnectButton />
        </div>
      </div>
    );
  }

  if (loading) return <div className="p-8">Loading your NFTs...</div>;
  if (error) return <div className="p-8 text-red-600">Error: {error.message}</div>;

  return (
    <div className="min-h-screen p-8">
      <header className="flex justify-between items-center mb-8">
        <h1 className="text-3xl font-bold">Your NFT Gallery</h1>
        <ConnectButton />
      </header>

      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
        {data?.nfts.map((nft: any) => (
          <div key={nft.id} className="border rounded-lg p-4 hover:shadow-lg transition">
            <img
              src={getIPFSUrl(nft.metadataCID)}
              alt={`NFT #${nft.tokenId}`}
              className="w-full aspect-square object-cover rounded mb-4"
            />
            <h3 className="font-semibold mb-2">Token #{nft.tokenId}</h3>
            <p className="text-sm text-gray-600 mb-2">
              {nft.transfers.length} transfers
            </p>
            
            <button
              onClick={() => analyzeNFT(nft.tokenId, nft)}
              className="w-full bg-blue-600 text-white py-2 rounded hover:bg-blue-700 transition"
            >
              ✨ AI Analysis
            </button>
            
            {analysis[nft.tokenId] && (
              <div className="mt-4 p-3 bg-gray-50 rounded text-sm">
                {analysis[nft.tokenId]}
              </div>
            )}
          </div>
        ))}
      </div>
    </div>
  );
}