# Stellar Wallet Kit - Integração rápida

## **Construindo um Sistema de Gerenciamento de Carteiras Stellar**

Este guia irá orientá-lo na criação de um sistema completo de gerenciamento de carteiras para integração com a blockchain Stellar em sua aplicação React/Next.js. O sistema fornece conexão segura de carteira, desconexão e gerenciamento de estado com persistência.

### **Visão geral**

O sistema consiste em três componentes principais:

1. **Provedor de Carteira** - Gerenciamento de estado global para informações da carteira
2. **Hook de Carteira** - Lógica de negócio para operações da carteira
3. **Configuração do Kit de Carteiras** - Configuração de integração com a blockchain Stellar

### **Passo 1: Instalar Dependências**

Primeiro, instale o pacote necessário Stellar Wallet Kit:

```bash
npm install @creit.tech/stellar-wallets-kit
```

### **Passo 2: Configure o Stellar Wallet Kit**

Crie um arquivo de configuração que configure o Stellar Wallet Kit com suporte para múltiplos tipos de carteira:

```tsx
import {
  StellarWalletsKit,
  WalletNetwork,
  FREIGHTER_ID,
  AlbedoModule,
  FreighterModule,
} from "@creit.tech/stellar-wallets-kit";

/**
 * Configuração principal para o Stellar Wallet Kit
 * Este kit suporta múltiplos tipos de carteira incluindo Freighter e Albedo
 * Configure para TESTNET durante o desenvolvimento e MAINNET para produção
 */
export const kit: StellarWalletsKit = new StellarWalletsKit({
  network: WalletNetwork.TESTNET,
  selectedWalletId: FREIGHTER_ID,
  modules: [new FreighterModule(), new AlbedoModule()],
});

/**
 * Interface para parâmetros de assinatura de transação
 */
interface signTransactionProps {
  unsignedTransaction: string;
  address: string;
}

/**
 * Assine uma transação Stellar usando a carteira conectada
 * Esta função lida com o processo de assinatura e retorna a transação assinada
 * 
 * @param unsignedTransaction - A string XDR da transação não assinada
 * @param address - O endereço da carteira que irá assinar a transação
 * @returns Promise<string> - O XDR da transação assinada
 */
export const signTransaction = async ({
  unsignedTransaction,
  address,
}: signTransactionProps): Promise<string> => {
  const { signedTxXdr } = await kit.signTransaction(unsignedTransaction, {
    address,
    networkPassphrase: WalletNetwork.TESTNET,
  });

  return signedTxXdr;
};
```

### **Passo 3: Crie o Provedor de Contexto da Carteira**

O Wallet Provider gerencia o estado global da carteira e persiste informações no localStorage para uma melhor experiência do usuário

```tsx
"use client";

import {
  createContext,
  useContext,
  useState,
  useEffect,
  ReactNode,
} from "react";

/**
 * Definição de tipo para o contexto da carteira
 * Contém endereço da carteira, nome e funções para gerenciar o estado da carteira
 */
type WalletContextType = {
  walletAddress: string | null;
  walletName: string | null;
  setWalletInfo: (address: string, name: string) => void;
  clearWalletInfo: () => void;
};

/**
 * Crie o contexto React para gerenciamento do estado da carteira
 */
const WalletContext = createContext<WalletContextType | undefined>(undefined);

/**
 * Componente Wallet Provider que envolve a aplicação
 * Gerencia o estado da carteira e fornece informações da carteira aos componentes filhos
 * Carrega automaticamente informações salvas da carteira do localStorage na inicialização
 */
export const WalletProvider = ({ children }: { children: ReactNode }) => {
  const [walletAddress, setWalletAddress] = useState<string | null>(null);
  const [walletName, setWalletName] = useState<string | null>(null);

  /**
   * Carregar informações salvas da carteira do localStorage quando o componente monta
   * Isso garante que o estado da carteira persista entre sessões do navegador
   */
  useEffect(() => {
    const storedAddress = localStorage.getItem("walletAddress");
    const storedName = localStorage.getItem("walletName");

    if (storedAddress) setWalletAddress(storedAddress);
    if (storedName) setWalletName(storedName);
  }, []);

  /**
   * Defina informações da carteira e salve-as no localStorage
   * Esta função é chamada quando uma carteira é conectada com sucesso
   * 
   * @param address - O endereço público da carteira
   * @param name - O nome/identificador da carteira (por exemplo, "Freighter", "Albedo")
   */
  const setWalletInfo = (address: string, name: string) => {
    setWalletAddress(address);
    setWalletName(name);
    localStorage.setItem("walletAddress", address);
    localStorage.setItem("walletName", name);
  };

  /**
   * Limpar informações da carteira e removê-las do localStorage
   * Esta função é chamada ao desconectar uma carteira
   */
  const clearWalletInfo = () => {
    setWalletAddress(null);
    setWalletName(null);
    localStorage.removeItem("walletAddress");
    localStorage.removeItem("walletName");
  };

  return (
    <WalletContext.Provider
      value={{ walletAddress, walletName, setWalletInfo, clearWalletInfo }}
    >
      {children}
    </WalletContext.Provider>
  );
};

/**
 * Hook personalizado para acessar o contexto da carteira
 * Fornece estado da carteira e funções para os componentes
 * Lança um erro se usado fora do WalletProvider
 */
export const useWalletContext = () => {
  const context = useContext(WalletContext);
  if (!context) {
    throw new Error("useWalletContext must be used within WalletProvider");
  }
  return context;
};
```

### **Passo 4: Crie o Hook da Carteira**

O hook da carteira encapsula toda a lógica de negócio para operações da carteira, fornecendo uma interface limpa para os componentes:

```tsx
import { kit } from "@/config/wallet-kit";
import { useWalletContext } from "@/providers/wallet.provider";
import { ISupportedWallet } from "@creit.tech/stellar-wallets-kit";

/**
 * Hook personalizado que fornece funcionalidade de conexão e desconexão de carteira
 * Integra-se com o Stellar Wallet Kit e gerencia o estado da carteira através do contexto
 */
export const useWallet = () => {
  // Obtenha funções de gerenciamento de carteira a partir do contexto
  const { setWalletInfo, clearWalletInfo } = useWalletContext();

  /**
   * Conectar a uma carteira Stellar usando o Wallet Kit
   * Abre um modal para seleção da carteira e lida com o processo de conexão
   * Define automaticamente as informações da carteira no contexto após conexão bem-sucedida
   */
  const connectWallet = async () => {
    await kit.openModal({
      modalTitle: "Conecte-se à sua carteira favorita",
      onWalletSelected: async (option: ISupportedWallet) => {
        // Defina a carteira selecionada como a carteira ativa
        kit.setWallet(option.id);

        // Obtenha o endereço e o nome da carteira
        const { address } = await kit.getAddress();
        const { name } = option;

        // Armazene informações da carteira no contexto e no localStorage
        setWalletInfo(address, name);
      },
    });
  };

  /**
   * Desconectar da carteira atual
   * Remove informações da carteira do contexto e do localStorage
   * Desconecta a carteira do Stellar Wallet Kit
   */
  const disconnectWallet = async () => {
    await kit.disconnect();
    clearWalletInfo();
  };

  /**
   * Lidar com a conexão da carteira com tratamento de erros
   * Envolve a função connectWallet em um bloco try-catch para melhor gerenciamento de erros
   */
  const handleConnect = async () => {
    try {
      await connectWallet();
    } catch (error) {
      console.error("Erro ao conectar a carteira:", error);
      // Você pode adicionar tratamento de erro adicional aqui, como mostrar notificações ao usuário
    }
  };

  /**
   * Lidar com a desconexão da carteira com tratamento de erros
   * Envolve a função disconnectWallet em um bloco try-catch para melhor gerenciamento de erros
   */
  const handleDisconnect = async () => {
    try {
      await disconnectWallet();
    } catch (error) {
      console.error("Erro ao desconectar a carteira:", error);
      // Você pode adicionar tratamento de erro adicional aqui, como mostrar notificações ao usuário
    }
  };

  return {
    connectWallet,
    disconnectWallet,
    handleConnect,
    handleDisconnect,
  };
};
```

### **Passo 5: Integre o Provider em Sua App**

Envolva sua aplicação com o WalletProvider para habilitar o gerenciamento de estado da carteira por toda a sua app:

```tsx
import { WalletProvider } from "@/providers/wallet.provider";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <WalletProvider>
          {children}
        </WalletProvider>
      </body>
    </html>
  );
}
```

### **Passo 6: Use o Hook da Carteira em Componentes**

Agora você pode usar a funcionalidade da carteira em qualquer componente. Aqui está um exemplo de um botão de conexão de carteira:

```tsx
import { useWallet } from "@/hooks/wallet.hook";
import { useWalletContext } from "@/providers/wallet.provider";

/**
 * Componente de botão de conexão/desconexão de carteira
 * Mostra diferentes estados com base no status de conexão da carteira
 */
export const WalletButton = () => {
  const { handleConnect, handleDisconnect } = useWallet();
  const { walletAddress, walletName } = useWalletContext();

  // Se a carteira estiver conectada, mostrar opção de desconectar
  if (walletAddress) {
    return (
      <div className="flex items-center gap-4">
        <div className="text-sm">
          <p className="font-medium">Conectado: {walletName}</p>
          <p className="text-gray-500">{walletAddress}</p>
        </div>
        <button 
          onClick={handleDisconnect}
          className="px-4 py-2 bg-red-500 text-white rounded hover:bg-red-600"
        >
          Desconectar
        </button>
      </div>
    );
  }

  // Se a carteira não estiver conectada, mostrar opção de conectar
  return (
    <button 
      onClick={handleConnect}
      className="px-4 py-2 bg-blue-500 text-white rounded hover:bg-blue-600"
    >
      Conectar Carteira
    </button>
  );
};
```

### **Principais Recursos e Benefícios**

#### **Persistência de Estado**

* As informações da carteira são automaticamente salvas no localStorage
* Os usuários não precisam reconectar sua carteira toda vez que visitam sua app
* Experiência do usuário sem atrito entre sessões do navegador

#### **Suporte a Múltiplas Carteiras**

* Suporta múltiplos tipos de carteiras Stellar (Freighter, Albedo, etc.)
* Fácil adicionar novos módulos de carteira conforme eles se tornem disponíveis
* Os usuários podem escolher sua carteira preferida

#### **Tratamento de Erros**

* Tratamento de erros abrangente para operações de carteira
* Alternativas elegantes quando as operações de carteira falham
* Fácil de estender com notificações de erro personalizadas

#### **Segurança de Tipos**

* Suporte completo a TypeScript com definições de tipo apropriadas
* Suporte a IntelliSense para melhor experiência de desenvolvimento
* Verificação de erros em tempo de compilação para operações da carteira

#### **Arquitetura Baseada em Contexto**

* Separação limpa de responsabilidades entre gerenciamento de estado e lógica de negócio
* Fácil acesso ao estado da carteira a partir de qualquer componente
* Gerenciamento centralizado do estado da carteira

### **Opções de Configuração**

#### **Seleção de Rede**

* **TESTNET**: Use durante desenvolvimento e testes
* **MAINNET**: Use para aplicações de produção


---

# Agent Instructions: 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/introducao/developer-resources/stellar-wallet-kit-integracao-rapida.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.