> For the complete documentation index, see [llms.txt](https://docs.trustlesswork.com/trustless-work/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.trustlesswork.com/trustless-work/v1-pt/ia/vibe-coding-or-sdk-blocks.md). # Vibe Coding | SDK Blocks ### Guia VibeCoding (contexto de IA em arquivo único) Criado para fluxos de trabalho com agentes. {% hint style="info" %} Exporte esta página para PDF ou Markdown. Então alimente seu copiloto (Cursor, Claude, etc). {% endhint %} *** ### 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 ```bash npx create-next-app@latest tw-blocks-dapp --typescript --tailwind cd tw-blocks-dapp ``` #### 2.2 Instale os Blocos de Escrow ```bash npm install @trustless-work/blocks ``` #### 2.3 Execute o CLI (recomendado) ```bash 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 `. *** ### Ambiente Crie `.env.local` (leituras podem funcionar sem uma chave; fluxos de escrita precisam dela): ```bash # 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**. ```tsx // 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 ( {children} ); } ``` **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: ```bash # 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) ```tsx // 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 (

Demo Trustless Work

); } ``` **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: ```tsx // escrows/escrows-by-role/details/Actions.tsx (exemplo) return (

{/* Render actions conditionally by flags + roles */} {hasConditionalButtons && (

{/* Somente lançamento único */} {/* {shouldShowEditButton && } */} {/* {shouldShowDisputeButton && } */} {/* {shouldShowResolveButton && } */} {/* {shouldShowReleaseFundsButton && } */}

)} {/* compartilhado single/multi */}

); ``` Quando pronto, importe & habilite: ```tsx // 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) 1. **Conectar carteira** (Freighter). 2. **Inicializar escrow** (único ou múltiplo). 3. **Financiar** o escrow (diálogos/botões compartilhados). 4. **Mudar status do marco**, **aprovar**, e então **liberar** (release-all para single; **liberar marco** para multi). 5. 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 **papel**exigido, 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 ```tsx {children} ``` 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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://docs.trustlesswork.com/trustless-work/v1-pt/ia/vibe-coding-or-sdk-blocks.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.