📓Blocos de Caução

Um conjunto pronto para produção de blocos React para integrar os fluxos de custódia (escrow) e resolução de disputas da Trustless Work.

Você gostaria de personalizar os blocos? Você pode fazer isso editando os blocos como achar melhor.

---

O que você recebe

• Blocos de UI (cards/tabelas/diálogos/formulários) para listar e gerenciar custódias

• Providers para configuração de API, contexto de carteira, diálogos e valores

• Hooks do TanStack Query para buscar e mutar custódias

• Helpers do wallet-kit e utilitários de tratamento de erros

Links

Trustless Work | Blocksblocks.trustlesswork.com

https://github.com/Trustless-Work/react-library-trustless-work-blocksgithub.com

https://www.npmjs.com/package/@trustless-work/blockswww.npmjs.com

Listar todos os blocos disponíveis#

Com o CLI você pode listar todos os blocos disponíveis:

npx trustless-work list

O comando init irá:

• Mostrar todos os blocos disponíveis.

Context API#

A context API é um armazenamento global de custódias. Ela é usada para armazenar as custódias que são buscadas da API. Também é usada para armazenar a custódia selecionada.

Importante

Se você não quiser usar nossa abordagem para recuperar os dados da custódia, você é totalmente livre para alterá-la. Pode usar Redux, Zustand ou qualquer outra solução. No entanto, é importante garantir que a custódia desejada seja passada para o endpoint.

Entendendo como o contexto funciona nos endpoints de custódia.#

Ao implementar os endpoints, precisamos passar os dados de uma custódia específica para cada endpoint. Mas como fazemos isso? Nossa biblioteca fornece um contexto chamado EscrowContext, que inclui algumas utilidades muito importantes. Entre elas estãoselectedEscrowe setSelectedEscrow, que nos permitem fazer o seguinte:

Uso de selectedEscrow#

Atualmente, selectedEscrow mantém uma custódia específica para a qual estamos apontando. Com isso, todos os hooks de endpoint interagem com esse estado para extrair dados dele, como contractId, papéis, etc. Por exemplo, no select de alteração de status de marco (change status), os milestoneIndex valores são carregados com base na custódia atualmente selecionada. Portanto, sesetSelectedEscrow estiver indefinido, eles não serão carregados.

/useChangeMilestoneStatus.ts

const { selectedEscrow } = useEscrowContext();

const handleSubmit = form.handleSubmit(async (payload) => {             
  /**
   * Cria o payload final para a mutação de mudança de status do marco
   *
   * @param payload - O payload do formulário
   * @returns O payload final para a mutação de mudança de status do marco
  */
  const finalPayload: ChangeMilestoneStatusPayload = {
    contractId: selectedEscrow?.contractId || '', // contractId da selectedEscrow
    milestoneIndex: payload.milestoneIndex,
    newStatus: payload.status,
    newEvidence: payload.evidence || undefined,
    serviceProvider: walletAddress || '',
  };

  /**
   * Chama a mutação de mudança de status do marco
   *
   * @param payload - O payload final para a mutação de mudança de status do marco
   * @param type - O tipo da custódia
   * @param address - O endereço da custódia
  */
  await changeMilestoneStatus.mutateAsync({
    payload: finalPayload,
    type: selectedEscrow?.type || 'multi-release',
    address: walletAddress || '',
  });
}

Uso de setSelectedEscrow#

A função setSelectedEscrow salva a custódia selecionada no contexto, para que todos os hooks de endpoint interajam com esse estado para extrair dados dele, como contractId, papéis, etc. Por exemplo, nos cards de custódias por signatário salvamos a custódia selecionada no contexto, para que possamos usá-la no diálogo de detalhes.

/EscrowsCards.tsx

const { setSelectedEscrow } = useEscrowContext();

const onCardClick = (escrow: Escrow) => {
  setSelectedEscrow(escrow);
  dialogStates.second.setIsOpen(true);
};

Uso de updateEscrow#

Nossa updateEscrow função atualiza a selectedEscrow existente no contexto. É útil para atualizar uma flag ou outros campos. Por exemplo, a usamos para atualizar o status da custódia depois de uma mutação de mudança de status do marco.

/useChangeMilestoneStatus.ts

const { selectedEscrow, updateEscrow } = useEscrowContext();

const handleSubmit = form.handleSubmit(async (payload) => { 
  /**
    * Chama a mutação de mudança de status do marco
    *
    * @param payload - O payload final para a mutação de mudança de status do marco
    * @param type - O tipo da custódia
    * @param address - O endereço da custódia
  */
  await changeMilestoneStatus.mutateAsync({
    payload: finalPayload,
    type: selectedEscrow?.type || "multi-release", // tipo da selectedEscrow
    address: walletAddress || "",
  });

  toast.success("Status do marco atualizado com sucesso");

  // Atualiza a custódia selecionada no contexto com o novo status e evidência
  updateEscrow({
    ...selectedEscrow,
    milestones: selectedEscrow?.milestones.map((milestone, index) => {
      if (index === Number(payload.milestoneIndex)) {
        return {
          ...milestone,
          status: payload.status,
          evidence: payload.evidence || undefined,
        };
      }
      return milestone;
    }),
  });
}

Instalação baseada no caminho da pasta#

Se você precisa de todos os blocos filhos, pode instalá-los apontando para o diretório pai, assim não precisará instalá-los um por um.

npx trustless-work escrows // ou outro diretório de blocos do pai

Instalar Diretório Pai

npx trustless-work add escrows

Instala TODOS os blocos de custódia

Instalar Subpasta Específica

npx trustless-work add escrows/single-release

Instala apenas os blocos de custódia single-release

💡 Dica Pro: Instalação Hierárquica

Quanto mais profundo você for na estrutura de pastas, mais específicos os blocos se tornam. Comece pelos diretórios pai para funcionalidade abrangente e depois aprofunde-se nos componentes específicos conforme necessário.

Guia de Instalação