Referência da API Solana Privacy Rings

A API Solana Privacy Rings consulta o indexador de privacidade. Ela retorna o estado criptografado e metadados públicos das transações. Sua carteira descriptografa os payloads para ler saldos e históricos privados. Consulte a visão geral de privacidade para entender os conceitos e o SDK para conhecer os fluxos de depósito, transferência e saque.

Saldos públicos e privados

Um saldo privado é armazenado em UTXOs (saídas de transação não gastas). Uma UTXO não é uma conta da Solana.

	Saldo público	Saldo privado
Saldo	Lamports em uma conta da Solana ou o `amount` em uma conta de token SPL	A soma das UTXOs não gastas de um ativo
Visibilidade	Público on-chain	Criptografado on-chain
Descobrir contas de token ou saídas	`getTokenAccountsByOwner` retorna as contas de token SPL pertencentes a um endereço	`getEncryptedUtxosByTags` retorna as saídas criptografadas correspondentes a tags de visualização ou a um anel
Consultar um saldo	`getBalance` para SOL; `getTokenAccountBalance` para uma conta de token SPL	Sua carteira descriptografa as saídas, verifica quais não foram gastas e soma os valores de cada ativo

Consulte Estado privado e UTXOs para saber como os saldos privados são armazenados e gastos.

Endpoint e autenticação

Envie uma solicitação JSON-RPC 2.0 para o caminho do método com sua chave de API da Helius:

curl --request POST \
  --url "https://devnet.helius-rpc.com/v1/spr/getUserRecords?api-key=YOUR_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "getUserRecords",
    "params": {
      "owners": ["11111111111111111111111111111111"]
    }
  }'

O method deve corresponder ao segmento final do caminho da URL. Os caminhos dos métodos aceitam uma única solicitação; lotes, campos method duplicados e divergências entre caminho e corpo retornam HTTP 400 antes da execução. Para desenvolvimento local, use http://127.0.0.1:8784/{method} após iniciar a stack local.

Métodos

getEncryptedUtxosByTags

Descubra saídas criptografadas por tags de visualização ou anel.

getShieldedTransactionsByTags

Consulte o histórico de transações protegidas por tags de visualização ou anel.

getShieldedTransactionsBySignature

Recupere eventos protegidos de uma transação da Solana.

getShieldedTransactionsByNullifiers

Encontre as transações que gastaram os anuladores fornecidos.

getMerkleProofs

Obtenha provas de inclusão para compromissos da árvore de estado.

getNonInclusionProofs

Obtenha provas de não inclusão para valores de anuladores.

getNullifierQueueElements

Leia anuladores enfileirados em ordem sequencial.

getUserRecords

Consulte registros públicos de endereços protegidos.

Paginação

getEncryptedUtxosByTags, getShieldedTransactionsByTags e getShieldedTransactionsByNullifiers retornam uma página em result:

{
  "jsonrpc": "2.0",
  "id": "1",
  "result": {
    "context": { "slot": 4242, "blockTime": 1730000000 },
    "data": [],
    "paginationToken": null
  }
}

data agrupa os resultados por transação da Solana, ordenados por slot e assinatura em ordem crescente. O método de UTXOs criptografadas usa um array outputs em cada grupo; os métodos de histórico de transações usam um array events.
limit conta as transações da Solana, de 1 a 1.000, e o valor padrão é 1.000. As saídas ou os eventos correspondentes de uma transação permanecem juntos em uma única página.
Reenvie um paginationToken não nulo sem alterações, com as mesmas tags ou anuladores, o mesmo anel e os mesmos filtros de slot. Continue até que o token da resposta seja null.
filters.slot aceita os limites gt, gte, lt e lte. Os limites fornecidos são combinados com AND. Depois que uma leitura sem limite máximo alcançar um token nulo, salve o context.slot dessa página e retome mais tarde com filters.slot.gt definido como esse valor. Uma leitura limitada por lt ou lte abrange apenas os slots até esse limite; retome a partir do limite, não de context.slot.
Defina minContextSlot para exigir um slot mínimo persistido pelo indexador. O indexador também exige o slot do seu paginationToken e de qualquer filtro gt ou gte. Se ele estiver atrasado em relação a qualquer um deles, retornará o erro -32016 com error.data.contextSlot; tente novamente depois que ele se atualizar.

As respostas de histórico também podem incluir outputTreeId, o ID mais recente de uma árvore de estado não pausada. Ele será omitido quando estiver indisponível. As saídas individuais identificam suas próprias árvores com outputContext.treeId. getNullifierQueueElements usa paginação baseada em sequência; consulte a página do método.

Codificação dos dados

Valor	Codificação
Chaves públicas, hashes, compromissos, tags de visualização, anuladores	Strings Base58 que representam 32 bytes
Assinaturas de transações da Solana	Strings Base58 que representam 64 bytes
Payloads de texto cifrado, `txViewingPk`, `salt`, `viewingPubkey` do registro	Strings Base64
`context.slot`	Slot mais alto da Solana persistido pelo indexador
`context.blockTime`	Horário do bloco como timestamp Unix em segundos

Erros

Verifique o campo error do JSON-RPC antes de ler result, inclusive quando o status HTTP for 200.

Código	Significado
`-32600`	A validação da solicitação falhou, um registro não foi encontrado, uma raiz de prova indexada está desatualizada ou o histórico solicitado começa antes do histórico indexado. Um corpo de solicitação ilegível também retorna `-32600` com HTTP 400. Leia `message` para identificar a causa.
`-32601`	Método desconhecido ou o caminho de um método rejeitou a solicitação antes da execução. Rejeições de caminho usam HTTP 400.
`-32602`	Não foi possível analisar os parâmetros, por exemplo, devido a uma codificação de chave inválida ou a um limite fora do intervalo permitido.
`-32603`	Erro interno do servidor.
`-32016`	O indexador ainda não alcançou `minContextSlot`, o slot do token de paginação ou um filtro de slot `gt`/`gte`.

HTTP 429 indica limitação de taxa; consulte os limites de taxa. Consulte autenticação para configurar a chave de API.

Primeiros passos

Negociação

Envio de transações

Gerenciamento de contas

API Solana Privacy Rings

Saldos públicos e privados

Endpoint e autenticação

Métodos

getEncryptedUtxosByTags

getShieldedTransactionsByTags

getShieldedTransactionsBySignature

getShieldedTransactionsByNullifiers

getMerkleProofs

getNonInclusionProofs

getNullifierQueueElements

getUserRecords

Paginação

Codificação dos dados

Erros

​Saldos públicos e privados

​Endpoint e autenticação

​Métodos

getEncryptedUtxosByTags

getShieldedTransactionsByTags

getShieldedTransactionsBySignature

getShieldedTransactionsByNullifiers

getMerkleProofs

getNonInclusionProofs

getNullifierQueueElements

getUserRecords

​Paginação

​Codificação dos dados

​Erros

Saldos públicos e privados

Endpoint e autenticação

Métodos

Paginação

Codificação dos dados

Erros