# Vibe Coding | Blocks SDK ### Guía VibeCoding (contexto de IA en un solo archivo) Construido para flujos de trabajo con agentes. {% hint style="info" %} Exporta esta página a PDF o Markdown. Luego aliméntala a tu copiloto (Cursor, Claude, etc.). {% endhint %} *** ### Qué es este archivo * **Propósito:** Dar a una IA (o a un humano muy rápido) todo el contexto necesario para instalar, conectar y usar **Trustless Work Escrow Blocks** con Next.js. * **Alcance:** Instalación, proveedores requeridos (el orden importa), comandos para añadir bloques, páginas de ejemplo, reglas de dependencias, acciones y solución de problemas. * **Audiencia:** Constructores, PMs y AIs que realizan generación de código para **lanzamiento único** y **múltiples lanzamientos** interfaces de escrow. *** ### Modelo mental rápido * **Bloques de Escrow** = componentes React preconstruidos + hooks que se comunican con la API/SDK de Trustless Work para los ciclos de vida de escrow. * **Proveedores** deben envolver tu app en un **orden específico** (React Query → TW → Wallet → Escrow → Dialogs → Amount). No reordenar. * **Listados** (por rol / por firmante) muestran escrows y abren diálogos de detalle con acciones conscientes del contexto. Algunas acciones se entregan **comentadas**; habilita la versión que coincida con tu tipo de escrow (single o multi). *** ### Bootstrap del proyecto (Next.js + Blocks) #### 2.1 Crea la app ```bash npx create-next-app@latest tw-blocks-dapp --typescript --tailwind cd tw-blocks-dapp ``` #### 2.2 Instala Escrow Blocks ```bash npm install @trustless-work/blocks ``` #### 2.3 Ejecuta la CLI (recomendado) ```bash npx trustless-work init ``` Qué hace (resumen): * Instala dependencias (`@tanstack/react-query`, bibliotecas de formularios/validación, shadcn/ui). * Genera `.twblocks.json`. * Ofrece **conectar proveedores** en `app/layout.tsx` por ti. > También puedes añadir módulos de forma incremental con `npx trustless-work add `. *** ### Entorno Crea `.env.local` (las lecturas pueden funcionar sin una clave; los flujos de escritura la necesitan): ```bash # Requerido para llamadas autenticadas (cuando empieces a actuar) NEXT_PUBLIC_API_KEY=your_api_key_here ``` > Obtén tu clave API en la dApp cuando estés listo para ir más allá de los flujos de desarrollo solo lectura. (Índice de docs + flujo dApp referenciados en otros lugares.) *** ### Stack de proveedores (el orden es crítico) > Si omitiste la conexión por la CLI, añade estos proveedores **en este orden exacto**. ```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 qué es importante:** Los bloques dependen de React Query + contexto de Trustless Work + wallet + estado de escrow + contextos de diálogos/monto. Reordenar rompe hooks y flujos de UI. *** ### Añadir módulos y bloques (CLI) Ejecuta estos una vez por proyecto: ```bash # Pegamento 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 # Bloques 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 # Listados 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 ``` *** ### Tu primera página (wallet + init + listados) ```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 (

Trustless Work Demo

); } ``` **Lo que verás:** conexión de wallet, “Initialize Escrow” (single-release) y una cuadrícula de tarjetas filtrada por **rol** (las acciones son conscientes del rol/estado). *** ### Acciones: habilita los botones correctos Dentro del **diálogo de detalle**, algunas acciones están **comentadas** para que puedas habilitar solo lo que necesitas por tipo de escrow: ```tsx // escrows/escrows-by-role/details/Actions.tsx (ejemplo) return (

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

{/* Solo single-release */} {/* {shouldShowEditButton && } */} {/* {shouldShowDisputeButton && } */} {/* {shouldShowResolveButton && } */} {/* {shouldShowReleaseFundsButton && } */}

)} {/* compartido single/multi */}

); ``` Cuando estés listo, importa y habilita: ```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"; ``` > **Regla general:** Usa **lanzamiento único** acciones para escrows single; usa **componentes multi-** para escrows multi. Los listados son compartidos, funding/approve/status se comparten vía `single-multi-release`. *** ### Reglas de dependencia (prácticas) **Listados (por rol / por firmante)** necesitan: * `wallet-kit`, `providers`, `tanstack`, `helpers`, `handle-errors`, **más** bloques de ciclo de vida para las acciones que expondrás. **Acciones single-release o multi-release** necesitan: * `wallet-kit`, `providers`, `tanstack`, `helpers` (+ `handle-errors`), **y** el(los) conjunto(s) de bloques correspondiente(s). **Orden de proveedores** debe coincidir con la sección 4. *** ### Flujo de uso (ruta demo en testnet) 1. **Conectar wallet** (Freighter). 2. **Inicializar escrow** (single o multi). 3. **Financiar** el escrow (diálogos/botones compartidos). 4. **Cambiar estado del hito**, **aprobar**, y luego **liberar** (liberar todo para single; **liberar hito** para multi). 5. Opcional: **Disputar/Resolver** flujos (componentes específicos por tipo). > Consejo: Los listados se filtran por **rol**; las acciones visibles dependen de tu **rol** + **estado de escrow**. Añade la **línea de confianza USDC** en Freighter para interactuar sin problemas. *** ### Solución de problemas (arreglos rápidos) * **Los botones no hacen nada / están deshabilitados:** Tu cuenta no tiene el **rol**requerido, el **estado de escrow** no permite esa acción, o el escrow no está **financiado/aprobado** aún. * **Hooks fallando / error de contexto:** El orden de proveedores es incorrecto. Compáralo con el orden canónico aquí. * **Error de cliente vs servidor:** Añade `"use client"` a páginas/componentes que consumen hooks. * **Errores de activos:** Asegúrate de que el **línea de confianza USDC** esté agregado en Freighter para la red correcta. * **Funciones solo lectura; las escrituras fallan:** Falta o es inválida la `NEXT_PUBLIC_API_KEY`, rol incorrecto, o la wallet no está en la red correcta. *** ### Patrón minimalista “Blocks Gallery” (opcional) Una galería local permite a los compañeros ver cada bloque en vivo: * Servidor de desarrollo: `pnpm dev` → abre `/blocks` * Conecta los proveedores globales (como arriba) * Añade 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) *** ### Andamios de prompts (copiar-pegar)

A) Prompt del sistema (contexto de una sola vez)

``` Eres un ingeniero experto en Next.js + Trustless Work Escrow Blocks. Sigue estas reglas: - Usa archivos y rutas exactamente como se indican aquí. - Mantén el orden de proveedores idéntico a la guía. - Prefiere código que compile sin TODOs. - Cuando un tipo de escrow sea single vs multi, importa las acciones que coincidan. ```

B) Prompt de tarea (generar página + conexión)

``` Construye una página Next.js que: 1) muestre un WalletButton en el encabezado, 2) renderice InitializeEscrowDialog (single-release), 3) liste EscrowsByRoleCards con detalles funcionales, 4) habilite FundEscrowDialog y ReleaseEscrowButton para single-release. Usa el orden de proveedores de app/layout.tsx y las importaciones de: /components/tw-blocks/... Si un componente usa hooks, asegura "use client" al inicio. ```

C) Prompt de depuración (cuando algo falla)

``` El orden de proveedores DEBE ser: ReactQueryClientProvider > TrustlessWorkProvider > WalletProvider > EscrowProvider > EscrowDialogsProvider > EscrowAmountProvider. Identifica por qué las acciones de EscrowsByRoleCards están deshabilitadas. Revisa: - rol de la wallet vs rol del escrow, - banderas de escrow financiado/aprobado, - importaciones correctas de acciones single vs multi, - línea de confianza USDC presente en Freighter (Testnet). Propón ediciones de código exactas. ```

*** ### Notas para AIs (pistas de indexación) * **Palabras clave importantes:** Trustless Work, Escrow Blocks, single-release, multi-release, providers, WalletProvider, ReactQueryClientProvider, acciones basadas en rol, FundEscrowDialog, ApproveMilestoneDialog, ChangeMilestoneStatusDialog, ReleaseEscrowButton, ReleaseMilestoneButton, InitializeEscrowDialog. * **No reordenes** los proveedores. Cita esta regla al sugerir ediciones. * Las docs son **exportables por IA**; la búsqueda en las docs en lenguaje natural está soportada. *** ### Apéndice: orden canónico de proveedores ```tsx {children} ``` Este es el orden de proveedores requerido. *** ### Licencia para remezclar Usa, copia, incrusta y entrega. Si tu agente necesita más, dirígelo al hub completo de docs y a la referencia de la API. La documentación general explícitamente soporta exportación por IA y búsqueda semántica.