Desenvolvimento Blockchain e Web3 no Cursor: Solidity, Hardhat e ethers.js

O desenvolvimento blockchain combina programação de contratos inteligentes com integração de frontend para criar aplicativos descentralizados (dApps). Cursor, um editor IDE alimentado por IA, acelera cada camada do desenvolvimento Web3: escrita e auditoria de contratos Solidity, configuração de toolchains Hardhat, geração de camadas de interação ethers.js, construção de frontends React com wagmi e execução de suítes de teste abrangentes. Este guia aborda contratos inteligentes Solidity, o ambiente de desenvolvimento Hardhat, integração ethers.js e wagmi, estratégias de teste de contrato e geração e auditoria de contratos assistida por IA.

Pré-requisitos

Antes de começar, certifique-se de que você tem o seguinte:

• Cursor (versão mais recente recomendada) como seu editor IDE
• Node.js 18 ou superior
• Compreensão básica de JavaScript, TypeScript e React
• MetaMask ou outra carteira Web3 instalada no seu navegador
• ETH de teste em uma testnet (Sepolia ou Holesky) para prática de deployment

dica

O desenvolvimento blockchain tem uma curva de aprendizado íngreme. Antes de escrever seu primeiro contrato, peça ao Cursor para explicar a Ethereum Virtual Machine (EVM), custos de gas e o ciclo de vida da transação. Entender esses fundamentos previne erros custosos ao implantar na mainnet.

Contratos Inteligentes Solidity

Solidity é a linguagem mais amplamente usada para escrever contratos inteligentes em blockchains compatíveis com EVM. O Cursor ajuda você a escrever, revisar e otimizar código Solidity com sugestões e análises de segurança alimentadas por IA.

Escrevendo um Contrato de Token

Peça ao Cursor para gerar um contrato de token ERC-20:

Create an ERC-20 token contract in Solidity using OpenZeppelin.
The token should be named "TutorialToken" with symbol "TUT",
18 decimals, and a total supply of 1,000,000 tokens minted to
the deployer. Include a public minting function with a per-transaction
cap and an emergency pause mechanism.

O Cursor gera:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.24;

import "@openzeppelin/contracts/token/ERC20/ERC20.sol";
import "@openzeppelin/contracts/access/AccessControl.sol";
import "@openzeppelin/contracts/utils/Pausable.sol";

contract TutorialToken is ERC20, AccessControl, Pausable {
    bytes32 public constant MINTER_ROLE = keccak256("MINTER_ROLE");

    // Maximum mint per transaction: 10,000 tokens (with 18 decimals)
    uint256 public constant MAX_MINT_PER_TX = 10_000 * 10 ** 18;
    // Total supply cap: 1,000,000 tokens
    uint256 public constant TOTAL_SUPPLY_CAP = 1_000_000 * 10 ** 18;
    uint256 public currentSupply;

    event Minted(address indexed to, uint256 amount);
    event EmergencyPaused(address indexed by);

    constructor() ERC20("TutorialToken", "TUT") {
        _grantRole(DEFAULT_ADMIN_ROLE, msg.sender);
        _grantRole(MINTER_ROLE, msg.sender);

        uint256 initialSupply = 1_000_000 * 10 ** 18;
        _mint(msg.sender, initialSupply);
        currentSupply = initialSupply;
    }

    function mint(address to, uint256 amount) external onlyRole(MINTER_ROLE) whenNotPaused {
        require(amount <= MAX_MINT_PER_TX, "Exceeds max mint per transaction");
        require(currentSupply + amount <= TOTAL_SUPPLY_CAP, "Exceeds total supply cap");

        _mint(to, amount);
        currentSupply += amount;

        emit Minted(to, amount);
    }

    function pause() external onlyRole(DEFAULT_ADMIN_ROLE) {
        _pause();
        emit EmergencyPaused(msg.sender);
    }

    function unpause() external onlyRole(DEFAULT_ADMIN_ROLE) {
        _unpause();
    }

    // Override required by Solidity for multiple inheritance
    function _update(address from, address to, uint256 amount) internal override(ERC20, Pausable) {
        Pausable._update(from, to, amount);
    }

    function supportsInterface(bytes4 interfaceId)
        public view override(AccessControl) returns (bool)
    {
        return super.supportsInterface(interfaceId);
    }
}

dica

Sempre use as bibliotecas de contratos auditadas do OpenZeppelin em vez de escrever lógica criptográfica ou de padrão de token do zero. Peça ao Cursor para importar os contratos OpenZeppelin mais recentes e verificar se a versão corresponde à versão do seu compilador Solidity. Versões incompatíveis causam erros de compilação e podem introduzir bugs de segurança sutis.

aviso

A proteção contra overflow de inteiros do Solidity mudou na versão 0.8.0. Em versões antes de 0.8.0, operações aritméticas podiam silenciosamente causar overflow, levando a vulnerabilidades catastróficas. Se você está revisando contratos antigos, peça ao Cursor para verificar o uso de SafeMath e sinalizar qualquer aritmética que dependa de comportamento pré-0.8.0.

O Ambiente de Desenvolvimento Hardhat

Hardhat é o ambiente de desenvolvimento mais popular para Ethereum. Ele fornece simulação de blockchain local, compilação de contratos, testes, scripts de deployment e extensibilidade de plugins.

Configuração de Projeto

Peça ao Cursor para fazer scaffold de um projeto Hardhat:

Create a Hardhat TypeScript project with the following configuration:
- Solidity compiler version 0.8.24
- Hardhat toolbox plugin for testing and deployment
- A deployment script for the TutorialToken contract
- Environment variables for RPC URL and private key
- TypeChain for TypeScript contract bindings

O Cursor gera a estrutura do projeto:

my-dapp/
  contracts/
    TutorialToken.sol
  scripts/
    deploy.ts
  test/
    TutorialToken.test.ts
  hardhat.config.ts
  package.json
  .env.example

Configuração do Hardhat

// hardhat.config.ts
import { HardhatUserConfig } from 'hardhat/config';
import '@nomicfoundation/hardhat-toolbox';
import * as dotenv from 'dotenv';

dotenv.config();

const config: HardhatUserConfig = {
  solidity: {
    version: '0.8.24',
    settings: {
      optimizer: {
        enabled: true,
        runs: 200,
      },
    },
  },
  networks: {
    hardhat: {
      chainId: 31337,
    },
    sepolia: {
      url: process.env.SEPOLIA_RPC_URL || '',
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
    mainnet: {
      url: process.env.MAINNET_RPC_URL || '',
      accounts: process.env.PRIVATE_KEY ? [process.env.PRIVATE_KEY] : [],
    },
  },
  typechain: {
    target: 'ethers-v6',
    outDir: 'typechain-types',
  },
  gasReporter: {
    enabled: true,
    currency: 'USD',
    coinmarketcap: process.env.COINMARKETCAP_API_KEY,
    token: 'ETH',
  },
};

export default config;

Script de Deployment

// scripts/deploy.ts
import { ethers } from 'hardhat';

async function main() {
  const [deployer] = await ethers.getSigners();
  console.log('Deploying contracts with account:', deployer.address);
  console.log('Account balance:', ethers.formatEther(await ethers.provider.getBalance(deployer.address)), 'ETH');

  const TutorialToken = await ethers.getContractFactory('TutorialToken');
  const token = await TutorialToken.deploy();
  await token.waitForDeployment();

  const tokenAddress = await token.getAddress();
  console.log('TutorialToken deployed to:', tokenAddress);

  // Verify the deployment
  const name = await token.name();
  const symbol = await token.symbol();
  const totalSupply = await token.totalSupply();
  console.log('Name:', name);
  console.log('Symbol:', symbol);
  console.log('Total Supply:', ethers.formatEther(totalSupply));
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

dica

Peça ao Cursor para gerar scripts de deployment para múltiplas redes com verificação automática de contrato no Etherscan. Um prompt como "Crie um script de deploy que detecta a rede, implanta o contrato e chama verify no Etherscan se não estiver no localhost" economiza horas de trabalho manual de verificação.

Testes de Contrato

Testar contratos inteligentes é crítico porque contratos implantados são imutáveis. O Cursor gera suítes de teste abrangentes que cobrem caminhos felizes, casos extremos e cenários de segurança.

Escrevendo Testes com Hardhat e Chai

// test/TutorialToken.test.ts
import { expect } from 'chai';
import { ethers, network } from 'hardhat';
import { TutorialToken } from '../typechain-types';
import { SignerWithAddress } from '@nomicfoundation/hardhat-network-signers';

describe('TutorialToken', () => {
  let token: TutorialToken;
  let owner: SignerWithAddress;
  let minter: SignerWithAddress;
  let alice: SignerWithAddress;
  let bob: SignerWithAddress;

  const MINTER_ROLE = ethers.keccak256(ethers.toUtf8Bytes('MINTER_ROLE'));
  const MAX_MINT = ethers.parseEther('10000');
  const TOTAL_CAP = ethers.parseEther('1000000');

  beforeEach(async () => {
    [owner, minter, alice, bob] = await ethers.getSigners();

    const TutorialToken = await ethers.getContractFactory('TutorialToken');
    token = await TutorialToken.deploy();
    await token.waitForDeployment();
  });

  describe('Deployment', () => {
    it('sets the correct name and symbol', async () => {
      expect(await token.name()).to.equal('TutorialToken');
      expect(await token.symbol()).to.equal('TUT');
    });

    it('mints the total supply to the deployer', async () => {
      const balance = await token.balanceOf(owner.address);
      expect(balance).to.equal(TOTAL_CAP);
    });

    it('grants DEFAULT_ADMIN_ROLE and MINTER_ROLE to deployer', async () => {
      expect(await token.hasRole(ethers.ZeroHash, owner.address)).to.be.true;
      expect(await token.hasRole(MINTER_ROLE, owner.address)).to.be.true;
    });
  });

  describe('Minting', () => {
    beforeEach(async () => {
      await token.grantRole(MINTER_ROLE, minter.address);
    });

    it('allows minter to mint within per-transaction cap', async () => {
      const mintAmount = ethers.parseEther('5000');
      await token.connect(minter).mint(alice.address, mintAmount);
      expect(await token.balanceOf(alice.address)).to.equal(mintAmount);
    });

    it('reverts when minting exceeds per-transaction cap', async () => {
      const mintAmount = ethers.parseEther('10001');
      await expect(
        token.connect(minter).mint(alice.address, mintAmount)
      ).to.be.revertedWith('Exceeds max mint per transaction');
    });

    it('reverts when non-minter tries to mint', async () => {
      await expect(
        token.connect(alice).mint(bob.address, ethers.parseEther('100'))
      ).to.be.revertedWithCustomError(token, 'AccessControlUnauthorizedAccount');
    });

    it('reverts when minting exceeds total supply cap', async () => {
      // Already minted 1,000,000 on deployment, so any additional mint should fail
      await expect(
        token.connect(minter).mint(alice.address, ethers.parseEther('1'))
      ).to.be.revertedWith('Exceeds total supply cap');
    });
  });

  describe('Pause Mechanism', () => {
    it('allows admin to pause and unpause', async () => {
      await token.pause();
      expect(await token.paused()).to.be.true;

      await token.unpause();
      expect(await token.paused()).to.be.false;
    });

    it('reverts minting when paused', async () => {
      await token.grantRole(MINTER_ROLE, minter.address);
      await token.pause();

      await expect(
        token.connect(minter).mint(alice.address, ethers.parseEther('100'))
      ).to.be.revertedWithCustomError(token, 'EnforcedPause');
    });

    it('reverts when non-admin tries to pause', async () => {
      await expect(token.connect(alice).pause())
        .to.be.revertedWithCustomError(token, 'AccessControlUnauthorizedAccount');
    });
  });

  describe('Transfers', () => {
    it('allows token transfers and reverts when paused', async () => {
      const amount = ethers.parseEther('100');
      await token.transfer(alice.address, amount);
      expect(await token.balanceOf(alice.address)).to.equal(amount);

      // Now pause and verify transfer is blocked
      await token.pause();
      await expect(token.transfer(alice.address, amount))
        .to.be.revertedWithCustomError(token, 'EnforcedPause');
    });
  });
});

dica

Peça ao Cursor para gerar testes de fuzzing que randomizam entradas. Um prompt como "Crie um teste de fuzz que tenta mintar com quantias aleatórias entre 0 e 100.000 para encontrar casos extremos na lógica de limite por transação e limite de fornecimento total" pode revelar bugs de overflow e condições de fronteira que testes de valor fixo perdem.

aviso

Nunca implante um contrato sem cobertura completa de testes. Contratos imutveis não podem ser corrigidos após o deployment. Um único caso extremo perdido pode levar a perda permanente de fundos. Execute sua suíte de testes completa e também peça ao Cursor para auditar o contrato quanto a padrões comuns de vulnerabilidade antes de qualquer deployment na mainnet.

Integração com ethers.js

ethers.js é a biblioteca JavaScript mais popular para interagir com a Ethereum. O Cursor gera camadas de interação type-safe que envolvem os ABIs dos seus contratos.

Camada de Interação com Contrato

// src/lib/token.ts
import { ethers, Contract, formatEther, parseEther } from 'ethers';
import type { TutorialToken } from '../typechain-types';

export interface TokenInfo {
  name: string;
  symbol: string;
  decimals: number;
  totalSupply: string;
}

export class TokenService {
  private contract: TutorialToken;
  private provider: ethers.Provider;
  private signer?: ethers.Signer;

  constructor(
    address: string,
    abi: ethers.InterfaceAbi,
    provider: ethers.Provider,
    signer?: ethers.Signer
  ) {
    this.provider = provider;
    this.signer = signer;
    this.contract = (signer
      ? new Contract(address, abi, signer)
      : new Contract(address, abi, provider)) as unknown as TutorialToken;
  }

  async getInfo(): Promise<TokenInfo> {
    const [name, symbol, decimals, totalSupply] = await Promise.all([
      this.contract.name(),
      this.contract.symbol(),
      this.contract.decimals(),
      this.contract.totalSupply(),
    ]);

    return {
      name,
      symbol,
      decimals: Number(decimals),
      totalSupply: formatEther(totalSupply),
    };
  }

  async balanceOf(address: string): Promise<string> {
    const balance = await this.contract.balanceOf(address);
    return formatEther(balance);
  }

  async mint(to: string, amount: string): Promise<string> {
    if (!this.signer) throw new Error('Signer required for minting');
    const tx = await this.contract.mint(to, parseEther(amount));
    await tx.wait();
    return tx.hash;
  }

  async transfer(to: string, amount: string): Promise<string> {
    if (!this.signer) throw new Error('Signer required for transfers');
    const tx = await this.contract.transfer(to, parseEther(amount));
    await tx.wait();
    return tx.hash;
  }

  async isPaused(): Promise<boolean> {
    return this.contract.paused();
  }

  async hasMinterRole(address: string): Promise<boolean> {
    const MINTER_ROLE = ethers.keccak256(ethers.toUtf8Bytes('MINTER_ROLE'));
    return this.contract.hasRole(MINTER_ROLE, address);
  }
}

Usando ethers.js com uma Carteira de Navegador

// src/lib/wallet.ts
import { BrowserProvider } from 'ethers';

let provider: BrowserProvider | null = null;

export async function getProvider(): Promise<BrowserProvider> {
  if (!provider) {
    if (!window.ethereum) {
      throw new Error('No Web3 wallet found. Please install MetaMask.');
    }
    provider = new BrowserProvider(window.ethereum);
  }
  return provider;
}

export async function connectWallet(): Promise<string> {
  const provider = await getProvider();
  const accounts = await provider.send('eth_requestAccounts', []);
  return accounts[0];
}

export async function getSigner() {
  const provider = await getProvider();
  return provider.getSigner();
}

export function onAccountsChanged(callback: (accounts: string[]) => void): void {
  if (window.ethereum) {
    window.ethereum.on('accountsChanged', callback);
  }
}

export function onChainChanged(callback: (chainId: string) => void): void {
  if (window.ethereum) {
    window.ethereum.on('chainChanged', callback);
  }
}

aviso

Sempre verifique se o usuário está conectado à rede esperada antes de enviar transações. Enviar uma transação da mainnet enquanto conectado a uma testnet, ou vice-versa, causa erros confusos. Verifique o chain ID e solicite ao usuário que troque de rede se não corresponder.

Construindo um Frontend com wagmi

wagmi é uma coleção de React Hooks para Ethereum que simplifica conexão de carteira, leituras de contrato e escritas de contrato. O Cursor gera componentes React com wagmi com total type safety.

Configuração do wagmi

// src/lib/wagmi.ts
import { createConfig, http } from 'wagmi';
import { sepolia, mainnet } from 'wagmi/chains';
import { injected } from 'wagmi/connectors';

export const config = createConfig({
  chains: [sepolia, mainnet],
  connectors: [injected()],
  transports: {
    [sepolia.id]: http('https://rpc.sepolia.org'),
    [mainnet.id]: http(),
  },
});

// Contract address and ABI
export const TOKEN_ADDRESS = '0x...'; // Replace with your deployed address
export const TOKEN_ABI = [
  // ABI generated by TypeChain or hardhat
] as const;

Componente de Dashboard de Token

// src/components/TokenDashboard.tsx
import { useAccount, useReadContract, useWriteContract, useWatchContractEvent } from 'wagmi';
import { parseEther, formatEther } from 'viem';
import { TOKEN_ADDRESS, TOKEN_ABI } from '../lib/wagmi';
import { useState } from 'react';

export function TokenDashboard() {
  const { address, isConnected } = useAccount();
  const { writeContractAsync } = useWriteContract();
  const [mintAmount, setMintAmount] = useState('100');
  const [transferTo, setTransferTo] = useState('');
  const [transferAmount, setTransferAmount] = useState('10');

  // Batch-read contract state
  const { data: name } = useReadContract({ address: TOKEN_ADDRESS, abi: TOKEN_ABI, functionName: 'name' });
  const { data: symbol } = useReadContract({ address: TOKEN_ADDRESS, abi: TOKEN_ABI, functionName: 'symbol' });
  const { data: balance } = useReadContract({ address: TOKEN_ADDRESS, abi: TOKEN_ABI, functionName: 'balanceOf', args: [address] });
  const { data: isPaused } = useReadContract({ address: TOKEN_ADDRESS, abi: TOKEN_ABI, functionName: 'paused' });

  // Listen for mint events
  useWatchContractEvent({ address: TOKEN_ADDRESS, abi: TOKEN_ABI, eventName: 'Minted', onLogs: (logs) => console.log('Mint:', logs) });

  const handleMint = () => writeContractAsync({ address: TOKEN_ADDRESS, abi: TOKEN_ABI, functionName: 'mint', args: [address, parseEther(mintAmount)] });
  const handleTransfer = () => writeContractAsync({ address: TOKEN_ADDRESS, abi: TOKEN_ABI, functionName: 'transfer', args: [transferTo, parseEther(transferAmount)] });

  if (!isConnected) {
    return <div className="p-8 text-center text-gray-500">Connect your wallet to view your token balance.</div>;
  }

  return (
    <div className="space-y-6 p-4">
      <div className="rounded-lg bg-gray-100 p-4">
        <h2 className="text-xl font-bold">{name} ({symbol})</h2>
        <p className="mt-1 text-sm">Balance: {balance ? formatEther(balance as bigint) : '0'} {symbol}</p>
        <p className="text-sm">Status: {isPaused ? 'Paused' : 'Active'}</p>
      </div>

      <div className="rounded-lg border p-4">
        <h3 className="mb-2 font-semibold">Mint Tokens</h3>
        <input type="number" value={mintAmount} onChange={(e) => setMintAmount(e.target.value)} className="mb-2 w-full rounded border px-3 py-2" disabled={isPaused} />
        <button onClick={handleMint} disabled={isPaused} className="w-full rounded bg-blue-600 px-4 py-2 text-white disabled:opacity-50">Mint</button>
      </div>

      <div className="rounded-lg border p-4">
        <h3 className="mb-2 font-semibold">Transfer Tokens</h3>
        <input type="text" placeholder="Recipient address (0x...)" value={transferTo} onChange={(e) => setTransferTo(e.target.value)} className="mb-2 w-full rounded border px-3 py-2" />
        <input type="number" placeholder="Amount" value={transferAmount} onChange={(e) => setTransferAmount(e.target.value)} className="mb-2 w-full rounded border px-3 py-2" disabled={isPaused} />
        <button onClick={handleTransfer} disabled={isPaused} className="w-full rounded bg-green-600 px-4 py-2 text-white disabled:opacity-50">Transfer</button>
      </div>
    </div>
  );
}

dica

Peça ao Cursor para gerar um hook wagmi Read para cada função view no seu contrato e um hook Write para cada função de alteração de estado. Um prompt como "Crie hooks React customizados envolvendo wagmi useReadContract e useWriteContract para cada função no meu ABI do TutorialToken" fornece uma camada de interação limpa e reutilizável.

Geração e Auditoria de Contratos Assistida por IA

A IA do Cursor pode gerar sistemas inteiros de contratos a partir de uma descrição e auditar contratos existentes quanto a padrões comuns de vulnerabilidade.

Gerando um Sistema Completo de Contratos

Create a decentralized marketplace contract system with:
1. An ERC-721 NFT contract for listing items
2. A marketplace contract that accepts ETH and the NFT
3. Royalty enforcement using ERC-2981
4. A 2.5% platform fee sent to a treasury address
5. Reentrancy protection on all withdrawal functions
6. Events for every state change
Use OpenZeppelin libraries and include full NatSpec comments.

Auditoria de Vulnerabilidades

Execute este prompt de auditoria contra seu contrato:

Audit my Solidity contract for the following vulnerability classes:
1. Reentrancy attacks (check for CEI pattern and ReentrancyGuard)
2. Integer overflow/underflow
3. Access control bypass
4. Front-running susceptibility
5. Denial of service via gas limit
6. Timestamp dependence
7. Delegate call injection
8. Unchecked external calls
Rate the severity of each finding and provide a fix.

aviso

Auditorias de segurança assistidas por IA são uma primeira linha de defesa, não uma substituição para auditorias profissionais. Antes de implantar qualquer contrato que lide com valor real, contrate uma auditoria formal de uma empresa reputável. A IA pode perder padrões sutis de vulnerabilidade que auditores experientes detectam.

Resumo

O desenvolvimento blockchain e Web3 no Cursor combina o poder da geração de código assistida por IA com o rigor da engenharia de contratos inteligentes. Seguindo os padrões deste guia — contratos baseados em OpenZeppelin, suítes de teste Hardhat abrangentes, camadas de interação ethers.js type-safe, frontends React com wagmi e auditoria de contratos orientada por IA — você pode construir e enviar aplicativos descentralizados com confiança. Sempre teste exaustivamente, audite vulnerabilidades antes do deployment na mainnet e nunca implante contratos que você não entende completamente.