Vibe Coding | SDK Blocks

Guia VibeCoding (contexto de IA em arquivo único)

Criado para fluxos de trabalho com agentes.

Exporte esta página para PDF ou Markdown.

Então alimente seu copiloto (Cursor, Claude, etc).

O que este arquivo é

Propósito: Dar a uma IA (ou a um humano muito rápido) todo o contexto necessário para instalar, conectar e usar Blocos de Escrow de Trabalho Trustless com Next.js.
Escopo: Instalação, provedores necessários (a ordem importa), comandos para adicionar blocos, páginas de exemplo, regras de dependência, ações e solução de problemas.
Público: Construtores, PMs e IAs fazendo codegen para lançamento único e vários lançamentos UIs de escrow.

Modelo mental rápido

Blocos de Escrow = componentes React pré-construídos + hooks que conversam com a API/SDK do Trustless Work para ciclos de vida de escrow.
Provedores devem envolver seu app em um ordem específica (React Query → TW → Wallet → Escrow → Dialogs → Amount). Não reordene.
Listagens (por papel / por assinante) mostram escrows e abrem diálogos de detalhe com ações sensíveis ao contexto. Algumas ações são comentadas; habilite a versão que corresponde ao seu tipo de escrow (único ou múltiplo).

Bootstrap do projeto (Next.js + Blocos)

2.1 Crie o app

npx create-next-app@latest tw-blocks-dapp --typescript --tailwind
cd tw-blocks-dapp

2.2 Instale os Blocos de Escrow

npm install @trustless-work/blocks

2.3 Execute o CLI (recomendado)

npx trustless-work init

O que ele faz (resumo):

Instala dependências (@tanstack/react-query, bibliotecas de formulários/validação, shadcn/ui).
Gera .twblocks.json.
Oferece para conectar provedores em app/layout.tsx por você.

Você também pode adicionar módulos incrementalmente com npx trustless-work add <module>.

Ambiente

Crie .env.local (leituras podem funcionar sem uma chave; fluxos de escrita precisam dela):

# Necessário para chamadas autenticadas (quando você começar a agir)
NEXT_PUBLIC_API_KEY=sua_chave_api_aqui

Obtenha sua chave de API no dApp quando estiver pronto para avançar além dos fluxos de desenvolvimento somente leitura. (Índice da documentação + fluxo do dApp referenciados em outros lugares.)

Pilhas de provedores (a ordem é crítica)

Se você pulou a conexão pelo CLI, adicione estes provedores nesta ordem exata.

// app/layout.tsx
import "./globals.css";
import { ReactQueryClientProvider } from "@/components/tw-blocks/providers/ReactQueryClientProvider";
import { TrustlessWorkProvider } from "@/components/tw-blocks/providers/TrustlessWork";
import { WalletProvider } from "@/components/tw-blocks/wallet-kit/WalletProvider";
import { EscrowProvider } from "@/components/tw-blocks/providers/EscrowProvider";
import { EscrowDialogsProvider } from "@/components/tw-blocks/providers/EscrowDialogsProvider";
import { EscrowAmountProvider } from "@/components/tw-blocks/providers/EscrowAmountProvider";

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <ReactQueryClientProvider>
          <TrustlessWorkProvider>
            <WalletProvider>
              <EscrowProvider>
                <EscrowDialogsProvider>
                  <EscrowAmountProvider>
                    {children}
                  </EscrowAmountProvider>
                </EscrowDialogsProvider>
              </EscrowProvider>
            </WalletProvider>
          </TrustlessWorkProvider>
        </ReactQueryClientProvider>
      </body>
    </html>
  );
}

Por que isso importa: Os blocos dependem de React Query + contexto Trustless Work + carteira + estado de escrow + contextos de diálogos/valor. Reordenar quebra hooks e fluxos de UI.

Adicionar módulos & blocos (CLI)

Execute estes uma vez por projeto:

# Cola central
npx trustless-work add wallet-kit
npx trustless-work add providers
npx trustless-work add tanstack
npx trustless-work add helpers
npx trustless-work add handle-errors

# Blocos de ciclo de vida
npx trustless-work add escrows/single-release
npx trustless-work add escrows/multi-release
npx trustless-work add escrows/single-multi-release

# Listagens
npx trustless-work add escrows/escrows-by-role/cards
# opcional:
# npx trustless-work add escrows/escrows-by-role/table
# npx trustless-work add escrows/escrows-by-signer/cards
# npx trustless-work add escrows/escrows-by-signer/table

Sua primeira página (carteira + init + listagens)

// app/page.tsx
"use client";

import { WalletButton } from "@/components/tw-blocks/wallet-kit/WalletButtons";
import { InitializeEscrowDialog } from "@/components/tw-blocks/escrows/single-release/initialize-escrow/dialog/InitializeEscrow";
import { EscrowsByRoleCards } from "@/components/tw-blocks/escrows/escrows-by-role/cards/EscrowsCards";

export default function Home() {
  return (
    <div className="container mx-auto py-8">
      <header className="flex justify-between items-center mb-8">
        <h2 className="text-2xl font-bold">Demo Trustless Work</h2>
        <WalletButton />
      </header>

      <div className="flex justify-end mb-4">
        <InitializeEscrowDialog />
      </div>

      <EscrowsByRoleCards />
    </div>
  );
}

O que você verá: conexão de carteira, “Initialize Escrow” (lançamento único), e uma grade de cards filtrada por papel (ações são sensíveis ao papel/estado).

Ações: habilite os botões certos

Dentro do diálogo de detalhe, algumas ações são comentadas para que você possa habilitar apenas o que precisa por tipo de escrow:

// escrows/escrows-by-role/details/Actions.tsx (exemplo)
return (
  <div className="flex items-start justify-start flex-col gap-2 w-full">
    {/* Render actions conditionally by flags + roles */}
    {hasConditionalButtons && (
      <div className="flex flex-col gap-2 w-full">
        {/* Somente lançamento único */}
        {/* {shouldShowEditButton && <UpdateEscrowDialog />} */}
        {/* {shouldShowDisputeButton && <DisputeEscrowButton />} */}
        {/* {shouldShowResolveButton && <ResolveDisputeDialog />} */}
        {/* {shouldShowReleaseFundsButton && <ReleaseEscrowButton />} */}
      </div>
    )}
    <FundEscrowDialog /> {/* compartilhado single/multi */}
  </div>
);

Quando pronto, importe & habilite:

// escrows/escrows-by-role/details/Actions.tsx (imports)
import { UpdateEscrowDialog } from "../../single-release/update-escrow/dialog/UpdateEscrow";
/* import { UpdateEscrowDialog as UpdateEscrowDialogMultiRelease } from "../../multi-release/update-escrow/dialog/UpdateEscrow"; */
import { FundEscrowDialog } from "../../single-multi-release/fund-escrow/dialog/FundEscrow";
import { DisputeEscrowButton } from "../../single-release/dispute-escrow/button/DisputeEscrow";
import { ResolveDisputeDialog } from "../../single-release/resolve-dispute/dialog/ResolveDispute";
import { ReleaseEscrowButton } from "../../single-release/release-escrow/button/ReleaseEscrow";

Regra prática: Use lançamento único ações para escrows únicos; use componentes multi- para escrows múltiplos. As listagens são compartilhadas, funding/approve/status são compartilhados via single-multi-release.

Regras de dependência (práticas)

Listagens (por papel / por assinante) precisam de:

wallet-kit, providers, tanstack, helpers, handle-errors, mais blocos de ciclo de vida para as ações que você vai expor.

Ações para lançamento único ou vários lançamentos precisam de:

wallet-kit, providers, tanstack, helpers (+ handle-errors), e o(s) conjunto(s) de blocos correspondente(s).

Ordem de provedores deve corresponder à seção 4.

Fluxo de uso (caminho de demonstração em testnet)

Conectar carteira (Freighter).
Inicializar escrow (único ou múltiplo).
Financiar o escrow (diálogos/botões compartilhados).
Mudar status do marco, aprovar, e então liberar (release-all para single; liberar marco para multi).
Opcional: Disputa/Resolver fluxos (componentes específicos por tipo).

Dica: Listagens filtram por papel; as ações visíveis dependem do seu papel + estado do escrow. Adicione a trustline USDC no Freighter para interagir sem problemas.

Solução de problemas (correções rápidas)

Botões não fazem nada / desabilitados: Sua conta não tem o papelexigido, o estado do escrow não permite essa ação, ou o escrow não está financiado/aprovado ainda.
Hooks falhando / erro de contexto: A ordem dos provedores está errada. Compare com a ordem canônica aqui.
Erro cliente vs servidor: Adicione "use client" às páginas/componentes que consomem hooks.
Erros de ativo: Garanta que o trustline USDC esteja adicionado no Freighter para a rede correta.
Leitura funciona; gravações falham: Faltando ou inválido NEXT_PUBLIC_API_KEY, papel errado, ou carteira não está na rede correta.

Padrão mínimo “Galeria de Blocos” (opcional)

Uma galeria local permite que colegas vejam cada bloco ao vivo:

Servidor de dev: pnpm dev → abra /blocks
Conecte os provedores globais (como acima)
Adicione páginas:
- /blocks/wallet-button
- /blocks/escrows-by-role/cards|table
- /blocks/escrows-by-signer/cards|table
- /blocks/single-release/* (init/update/dispute/resolve/release)
- /blocks/multi-release/* (init/update/dispute/resolve/release-milestone)
- /blocks/single-multi-release/* (fund/approve/change-status)

Estruturas de prompt (copiar-colar)

A) Prompt de sistema (contexto único)

Você é um engenheiro especialista em Next.js + Blocos de Escrow do Trustless Work.
Siga estas regras:
- Use arquivos e caminhos exatamente como fornecidos aqui.
- Mantenha a ordem dos provedores idêntica ao guia.
- Prefira código que compile sem TODOs.
- Quando um tipo de escrow for single vs multi, importe as ações correspondentes.

B) Prompt de tarefa (gerar página + conexão)

Construa uma página Next.js que:
1) mostre um WalletButton no cabeçalho,
2) renderize InitializeEscrowDialog (single-release),
3) liste EscrowsByRoleCards com detalhes funcionais,
4) habilite FundEscrowDialog e ReleaseEscrowButton para single-release.

Use a ordem de provedores de app/layout.tsx e importações de:
/components/tw-blocks/...

Se um componente usar hooks, garanta "use client" no topo.

C) Prompt de depuração (quando as coisas quebram)

A ordem de provedores DADA DEVE ser:
ReactQueryClientProvider > TrustlessWorkProvider > WalletProvider > EscrowProvider > EscrowDialogsProvider > EscrowAmountProvider.

Identifique por que as ações do EscrowsByRoleCards estão desabilitadas. Verifique:
- papel da carteira vs papel do escrow,
- flags de escrow financiado/aprovado,
- importações corretas de ações single vs multi,
- trustline USDC presente no Freighter (Testnet).
Proponha edições de código exatas.

Notas para IAs (dicas de indexação)

Palavras-chave importantes: Trustless Work, Blocos de Escrow, single-release, multi-release, providers, WalletProvider, ReactQueryClientProvider, ações baseadas em papel, FundEscrowDialog, ApproveMilestoneDialog, ChangeMilestoneStatusDialog, ReleaseEscrowButton, ReleaseMilestoneButton, InitializeEscrowDialog.
Não reordene provedores. Cite esta regra ao sugerir edições.
As docs são exportáveis por IA; buscar nas docs em linguagem natural é suportado.

Apêndice: ordem canônica de provedores

<ReactQueryClientProvider>
  <TrustlessWorkProvider>
    <WalletProvider>
      <EscrowProvider>
        <EscrowDialogsProvider>
          <EscrowAmountProvider>
            {children}
          </EscrowAmountProvider>
        </EscrowDialogsProvider>
      </EscrowProvider>
    </WalletProvider>
  </TrustlessWorkProvider>
</ReactQueryClientProvider>

Esta é a ordem de provedores requerida.

Licença para remixar

Use, copie, incorpore e distribua. Se seu agente precisar de mais, aponte-o para o hub completo de docs e referência da API. A documentação geral suporta explicitamente exportação por IA & pesquisa semântica.

AnteriorHabilidade

PróximoVibe Coding | SDK React

Atualizado há 7 meses