Documentação SolanaIntrodução

Guia de Início Rápido do Kora

Última Atualização: 31-10-2025

Fundamentos do Kora

Kora é um servidor JSON-RPC que fornece serviços de pagamento de taxas para transações Solana. Ele permite que os usuários paguem taxas de transação com tokens SPL em vez de SOL, proporcionando uma melhor experiência do usuário para aplicações onde os usuários podem não possuir SOL.

O Kora RPC valida solicitações de clientes com base em uma configuração (kora.toml) que define programas, carteiras, tokens, etc. permitidos. Uma vez validada, o servidor Kora assinará a transação e a enviará para a rede (ou retornará uma transação assinada serializada ao cliente).

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐

│   Client App    │───▶│   Kora RPC      │───▶│   Solana RPC    │

│                 │    │   Server        │    │                 │

└─────────────────┘    └─────────────────┘    └─────────────────┘

                              │

                              ▼

                       ┌──────────────────────┐

                       │   Kora Private Key   │

                       │ ( or Turnkey/Privy ) │

                       └──────────────────────┘

Este guia de início rápido iniciará um servidor Kora RPC local e demonstrará a integração do cliente para testar fluxos de trabalho de pagamento de taxas.

Requisitos

Instalar o Kora RPC

Instale o servidor Kora RPC globalmente:

cargo install kora-cli

Importante: O branch main do Kora é um branch de integração e pode conter alterações não lançadas ou em versão beta. Sempre use a tag de versão estável mais recente para produção e uso em tutoriais. Você pode encontrar a versão estável mais recente na página de lançamentos do Kora.

Criar Projeto

Clone o repositório, faça checkout da tag estável mais recente e navegue até o diretório de demonstração de início:

git clone https://github.com/solana-foundation/kora

cd kora

git checkout v2.0.5

cd examples/getting-started/demo

Estrutura do Projeto

A demonstração contém três componentes principais:

Diretório do Cliente (client/src/)

  • setup.ts - Configuração do ambiente local (cria keypairs e os grava em .env, distribui SOL por airdrop, inicializa token de teste)
  • quick-start.ts - Script de demonstração de início rápido mostrando como estabelecer uma conexão Kora e fazer uma chamada simples ao servidor Kora RPC
  • full-demo.ts - Script de demonstração completo demonstrando múltiplos métodos do Kora RPC

Diretório do Servidor (server/)

  • kora.toml - Configuração do Kora RPC definindo regras de validação, tokens permitidos e parâmetros de taxa
  • signers.toml - Configuração de signatários definindo os signatários para o servidor Kora

Configuração Compartilhada

  • .env - Variáveis de ambiente para keypairs e endereços (criar .env na raiz - demo/.env). As variáveis de ambiente serão criadas pelo script de configuração.

Configurar Ambiente

Primeiro, crie o .env para o seu ambiente:

# Create .env file (will be populated by setup script)

touch .env

Configurar Cliente

Instale as dependências do cliente:

# From project root (kora/)

cd examples/getting-started/demo/client

pnpm install --ignore-workspace # use --ignore-workspace to avoid pnpm workspace conflicts

Configurar Servidor Kora RPC

O servidor Kora requer configuração para especificar quais tokens podem ser usados para pagamento de taxas. Abra server/kora.toml e observe a seção de validação. Aqui podemos especificar vários parâmetros que serão validados antes de assinar uma transação:

  • max_allowed_lamports: taxa máxima de transação que você está disposto a pagar em nome do usuário
  • max_signatures: número máximo de assinaturas que uma transação pode ter
  • price_source: oráculo para determinar o preço do token ("Mock" ou "Jupiter")
  • allowed_programs: lista de permissões de IDs de programas que podem ser executados (por exemplo, System Program, Token Program)
  • allowed_tokens: lista de permissões de tokens que podem ser transferidos
  • allowed_spl_paid_tokens: array de endereços de mint que seu programa aceita como pagamento
  • disallowed_accounts: lista de bloqueio de contas não autorizadas a interagir com seu RPC Kora

Por enquanto, vamos manter os valores padrão--você pode voltar aqui e alterá-los mais tarde (para mais informações sobre as opções de configuração, consulte a documentação de Configuração do Kora).

Configurar Signatários

Abra server/signers.toml e observe a seção de signatários. Aqui podemos especificar quais signatários serão usados para assinar transações e (se estiver usando múltiplos signatários) uma estratégia para selecionar qual signatário usar. Por enquanto, vamos usar um único signatário com os valores padrão--você pode voltar aqui e alterá-los mais tarde (para mais informações sobre a configuração de signatários, consulte o Guia de Signatários).

Servidor de Teste

Abra três terminais e execute os seguintes comandos:

Terminal 1: Iniciar Validador de Teste Local

# From project root or anywhere

solana-test-validator -r

Terminal 2: Inicializar Ambiente

# From ./client directory

pnpm init-env

Este script irá:

  • Gerar keypairs e salvá-los em .env
  • Enviar SOL via airdrop para contas de teste
  • Criar e inicializar um token USDC local
  • Financiar contas de teste com tokens

Importante: Certifique-se de copiar a chave pública do novo token USDC de teste do seu .env e atualizar o allowed_tokens e allowed_spl_paid_tokens em ./server/kora.toml.

allowed_tokens = [

    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env

]

allowed_spl_paid_tokens = [

    "YOUR_USDC_LOCAL_PUBLICK_KEY"    # Update this based on the USDC_LOCAL_KEY public key comment in your .env

]

Terminal 3: Inicializar ATAs de Pagamento (Opcional)

Para receber pagamentos, você precisará inicializar Associated Token Accounts (ATAs) para seus tokens de pagamento. Você pode fazer isso executando o seguinte comando:

# From ./server directory

kora rpc initialize-atas --signers-config signers.toml

Este comando irá:

  • Ler seu endereço de pagamento de kora.toml (ou se você não especificou um endereço de pagamento, todos os signatários listados em signers.toml)
  • Criar ATAs para todos os tokens listados em allowed_spl_paid_tokens
  • Ignorar quaisquer ATAs que já existam
  • Você pode opcionalmente especificar um pagador de taxa personalizado para geração de ATA usando a flag fee_payer_key.

Terminal 4: Iniciar Servidor RPC Kora

# From ./server directory

kora rpc start --signers-config signers.toml

Nota: Para implantações em produção usando price_source = "Jupiter", você deve definir a variável de ambiente JUPITER_API_KEY. O servidor falhará ao iniciar sem ela:

JUPITER_API_KEY=your_api_key kora rpc start --signers-config signers.toml

O servidor lê a configuração de kora.toml e signers.toml e usa variáveis de ambiente do arquivo compartilhado .env. Se você estiver usando uma estrutura de pastas diferente da especificada aqui, pode ser necessário usar --config para especificar a localização de kora.toml e --signers-config para especificar o diretório de sua configuração de signatários:

kora rpc --config path/to/kora.toml start --signers-config path/to/signers.toml

Você pode acessar kora rpc -h para obter ajuda sobre as opções do servidor RPC.

Terminal 5: Executar Demonstração do Cliente

# From ./client directory

pnpm start

Você deverá ver uma saída semelhante a:

Kora Config: {

  fee_payer: 'Df2UmGQH86TBDsub7XZoSAo7KZa1ZJZr2w1PL1APUjjU',

  validation_config: {

    max_allowed_lamports: 1000000,

    max_signatures: 10,

    allowed_programs: [

      '11111111111111111111111111111111',

      'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA',

      'ATokenGPvbdGVxr1b2hvZbsiqW5xWH25efTNsLJA8knL',

      'AddressLookupTab1e1111111111111111111111111',

      'ComputeBudget11111111111111111111111111111111'

    ],

    allowed_tokens: [

      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'

    ],

    allowed_spl_paid_tokens: [

      'usdCAEFbouFGxdkbHCRtMTcN7DJHd3aCmP9vqjLgmAp'

    ],

    disallowed_accounts: [],

    price_source: 'Mock',

    fee_payer_policy: {...},

    price: { type: 'margin', margin: 0 }

  },

  enabled_methods: { ... }

 }

}

Blockhash:  C8W8d5w2H4jKXyFg5CEBoiaPvEpJ1am7xLxZ3fym4a2g

Isso confirma que seu servidor Kora está em execução e configurado corretamente!

Próximos Passos

Assim que você tiver a configuração básica funcionando, confira a demonstração completa do fluxo Kora:

→ Fluxo Completo de Transação Sem Gas do Kora

explore métodos RPC adicionais do Kora:

  • estimateTransactionFee - Calcular taxas para transações
  • getPayerSigner - Obter o signatário pagador e o destino de pagamento
  • getSupportedTokens - Retorna um array de tokens de pagamento suportados
  • signTransaction - Assinar condicionalmente transações quando as taxas são cobertas
  • transferTransaction - Criar transações de transferência de SOL ou tokens SPL (assinadas pelo pagador de taxas do Kora)
  • signAndSendTransaction - Assina condicionalmente uma transação com o pagador de taxas do Kora e a envia para o RPC Solana configurado
  • getPaymentInstruction - Obter uma instrução de pagamento para uma transação

Tem dúvidas? Faça perguntas no Solana Stack Exchange com uma tag Kora.

Is this page helpful?

Anterior

Instalação

Próximo

Documentação de Operadores Kora

Índice

Editar Página

Gerenciado por

© 2026 Fundação Solana.
Todos os direitos reservados.
Solana
Conecte-se
  • Blog