> 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/sdk-blocks-de-escrow/introducao.md).

# Introdução

{% hint style="info" %}
Quer personalizar os blocos?

Edite os componentes gerados como quiser.
{% endhint %}

***

### O que você recebe

* Blocos de UI (cards/tabelas/diálogos/formulários) para listar e gerenciar escrowes
* Providers para configuração da API, contexto de carteira, diálogos e valores
* Hooks do TanStack Query para buscar e mutar escrowes
* Helpers do wallet-kit e utilitários de tratamento de erros

### Links

{% embed url="<https://blocks.trustlesswork.com>" %}

{% embed url="<https://github.com/Trustless-Work/react-library-trustless-work-blocks>" %}

{% embed url="<https://www.npmjs.com/package/@trustless-work/blocks>" %}

### Listar todos os blocos disponíveis

Use o CLI para imprimir todos os blocos disponíveis:

{% code title="CLI" %}

```sh
npx trustless-work list
```

{% endcode %}

Esta é a maneira mais rápida de descobrir os caminhos das pastas para `npx trustless-work add ...`.

### API de Contexto

A API de contexto é um armazenamento global de escrowes. Ela é usada para armazenar os escrowes que são buscados da API. Também é usada para armazenar o escrow selecionado.

{% hint style="info" %}
Você não precisa usar essa abordagem de contexto.

Você pode usar Redux, Zustand ou qualquer outra coisa.\
Apenas certifique-se de que os dados do escrow alvo estejam disponíveis para cada hook de endpoint.
{% endhint %}

#### Como o contexto é usado pelos hooks de endpoint

Ao implementar os endpoints, precisamos passar os dados de um escrow específico para cada endpoint. Mas como fazemos isso? Nossa biblioteca fornece um contexto chamado `EscrowContext`, que inclui alguns utilitários muito importantes. Entre eles estão`selectedEscrow`e `setSelectedEscrow`, que nos permitem fazer o seguinte:

#### `selectedEscrow`

Atualmente, `selectedEscrow` mantém um escrow específico ao 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 seletor de alteração de status do milestone, os `milestoneIndex` valores são carregados com base no escrow atualmente selecionado. Portanto, se`setSelectedEscrow` estiver indefinido, eles não serão carregados.

{% code title="useChangeMilestoneStatus.ts" overflow="wrap" %}

```ts
const { selectedEscrow } = useEscrowContext();

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

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

{% endcode %}

#### `setSelectedEscrow`

`setSelectedEscrow` armazena o escrow selecionado no contexto.

Outros hooks e blocos de UI podem então ler `selectedEscrow` para obter `contractId`, papéis, etc.\
Exemplo: a visualização de cards armazena o escrow selecionado antes de abrir o diálogo de detalhes.

{% code title="EscrowsCards.tsx" overflow="wrap" %}

```ts
const { setSelectedEscrow } = useEscrowContext();

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

{% endcode %}

#### `updateEscrow`

Nossa `updateEscrow` função atualiza o selectedEscrow existente no contexto. É útil para atualizar uma flag ou outros campos. Por exemplo, usamos para atualizar o status do escrow após uma mutação de alteração de status do milestone.

{% code title="useChangeMilestoneStatus.ts" overflow="wrap" %}

```ts
const { selectedEscrow, updateEscrow } = useEscrowContext();

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

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

  // Atualiza o escrow selecionado 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;
    }),
  });
}
```

{% endcode %}

### Instalar blocos por caminho de pasta

Você pode instalar pastas inteiras (e todos os blocos filhos) com um comando.

#### Instalar um diretório pai

```sh
npx trustless-work add escrows
```

Instala todos os blocos de escrow.

#### Instalar uma subpasta específica

```sh
npx trustless-work add escrows/single-release
```

Instala apenas os blocos de escrow single-release.

{% hint style="success" %}
Quanto mais profundo o caminho da pasta, mais específica será a instalação.

Comece amplo (`escrows`), depois afine conforme necessário (`escrows/single-release/...`).
{% endhint %}

[Guia de Instalação](https://blocks.trustlesswork.com/get-started/installation)


---

# 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/sdk-blocks-de-escrow/introducao.md?ask=<question>
```

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.