👾Vibe Coding - Blocos

⚡ Guia VibeCoding — Escrow Blocks (Contexto AI em Arquivo Único)

Esta página foi projetada para fluxos de trabalho de bytecoders/agents. Você pode exportar para PDF ou Markdown e fornecer isso ao seu copiloto, Cursor ou pipelines de fine-tuning. Nossa documentação é explicitamente otimizada para ser exportada como contexto para IA e pode ser consultada via a barra de busca da documentação em linguagem natural.

0) 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 Trustless Work Escrow Blocks com Next.js.

  • Escopo: Instalação, provedores necessários (a ordem importa), comandos para adicionar blocks, páginas de exemplo, regras de dependência, ações e solução de problemas.

  • Público: Construtores, PMs e IAs fazendo codegen para liberação única e multi-liberação UIs de escrow.

1) Modelo mental rápido

  • Escrow Blocks = 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 uma ordem específica (React Query → TW → Wallet → Escrow → Dialogs → Amount). Não reordene.

  • Listings (por função / por signatário) mostram escrows e abrem diálogos de detalhe com ações sensíveis ao contexto. Algumas ações vêm comentadas; habilite a versão que corresponda ao seu tipo de escrow (single ou multi).

2) Bootstrap do projeto (Next.js + Blocks)

2.1 Crie o app

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

2.2 Instale Escrow Blocks

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 forms/validação, shadcn/ui).

  • Gera .twblocks.json.

  • Oferece conectar provedores em app/layout.tsx para você.

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

3) Ambiente

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

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

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

4) Pilha de provedores (a ordem é crítica)

Se você pulou a conexão via 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 blocks dependem de React Query + contexto Trustless Work + carteira + estado de escrow + contextos de diálogos/valor. Reordenar quebra hooks e fluxos de UI.

5) Adicionar módulos & blocks (CLI)

Execute estes uma vez por projeto:

# Cola principal
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

# Blocks 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

# Listings
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

6) Sua primeira página (carteira + init + listings)

// 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” (single-release), e uma grade de cards filtrada por função (ações são sensíveis à função/estado).

7) Área de ações: habilitando os botões corretos

Dentro do diálogo de detalhedos listings, 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 single-release */}
        {/* {shouldShowEditButton && <UpdateEscrowDialog />} */}
        {/* {shouldShowDisputeButton && <DisputeEscrowButton />} */}
        {/* {shouldShowResolveButton && <ResolveDisputeDialog />} */}
        {/* {shouldShowReleaseFundsButton && <ReleaseEscrowButton />} */}
      </div>
    )}
    <FundEscrowDialog /> {/* compartilhado single/multi */}
  </div>
);

Quando pronto, importe e 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 liberação única ações para escrows single; use componentes multi- para escrows multi. Listings são compartilhados, funding/approve/status são compartilhados via single-multi-release.

8) Regras de dependência (prático)

Listings (por função / por signatário) precisam de:

  • wallet-kit, provedores, tanstack, helpers, handle-errors, mais blocks de ciclo de vida para as ações que você exporá.

Ações single-release ou multi-release precisam de:

  • wallet-kit, provedores, tanstack, helpers (+ handle-errors), e os conjuntos de blocks correspondentes.

A ordem dos provedores deve corresponder à seção 4.

9) Fluxo de uso (caminho demo em testnet)

  1. Conectar carteira (Freighter).

  2. Inicializar escrow (single ou multi).

  3. Financiar o escrow (diálogos/botões compartilhados).

  4. Alterar status do milestone, aprovar, e então liberar (liberar-tudo para single; liberar milestone para multi).

  5. Opcional: Disputar/Resolver fluxos (componentes específicos por tipo).

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

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

  • Botões não fazem nada / desabilitados: Sua conta não tem o funçãonecessário, 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; escritas falham: Faltando ou inválido NEXT_PUBLIC_API_KEY, função errada, ou carteira não está na rede correta.

11) Padrão mínimo “Blocks Gallery” (opcional)

Uma galeria local permite que colegas vejam cada block 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)

12) VibeCoding: scaffolds de prompt (copiar-colar)

A) Prompt do sistema (contexto único)

Você é um engenheiro especialista em Next.js + Trustless Work Escrow Blocks.
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 header,
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 imports de:
/components/tw-blocks/...

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

C) Prompt de depuração (quando algo quebrar)

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

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

13) Notas para IAs (dicas de indexação)

  • Palavras-chave importantes: Trustless Work, Escrow Blocks, single-release, multi-release, providers, WalletProvider, ReactQueryClientProvider, ações baseadas em função, FundEscrowDialog, ApproveMilestoneDialog, ChangeMilestoneStatusDialog, ReleaseEscrowButton, ReleaseMilestoneButton, InitializeEscrowDialog.

  • Não reordene os provedores. Cite esta regra ao sugerir edições.

  • A documentação é exportável para IA; buscar na documentação em linguagem natural é suportado.

14) Apêndice — ordem canônica de provedores (snippet)

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

Referência de origem para o requisito de ordem.

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 para IA e busca semântica.

AnteriorIntrodução - BlocosPróximoCiclo de Vida de Liberação Única da Caução

Atualizado

Isto foi útil?