Solana Pay: tudo o que você precisa saber

Solana Pay: como funciona

O Solana Pay oferece uma maneira diferente de os usuários interagirem com contratos inteligentes e transferirem tokens. Em vez de precisarem conectar uma carteira, eles podem visualizar e assinar uma transação por meio de um link. Isso elimina a barreira de precisar conectar sua carteira para interagir. Esse recurso pode ser usado tanto para pagamentos simples quanto para interações com aplicativos, permitindo processar solicitações de transação e de transferência.

O principal recurso do Solana Pay é a solicitação de transferência, uma solicitação não interativa para transferir SOL ou tokens SPL. É importante observar que nem todas as carteiras Solana aceitam esse formato, mas a maioria das carteiras populares aceita (Phantom, Solflare e Glow). Veja como é uma URL de solicitação de transferência do Solana Pay:

solana:<recipient>?amount=<amount>&spl-token=<spl-token>&reference=<reference>&label=<label>&message=<message>&memo=<memo>

Os parâmetros da URL são usados por uma carteira para compor diretamente uma transação. Neste guia, vamos nos concentrar nas solicitações de transferência, mas é importante observar que praticamente qualquer transação da Solana pode ser convertida em uma URL válida do Solana Pay.

Parâmetros

Agora, vamos analisar cada um dos parâmetros:

Destinatário:

Essa é a chave pública da pessoa para quem você está enviando SOL. Para transferências de tokens SPL, especifique o tipo de token no campo spl-token. A carteira usa essas informações para identificar a conta real da transferência.

Valor

A quantidade de SOL ou tokens que você está enviando. Se for menor que 1, deve haver um 0 antes do ponto decimal. Se nenhum valor for especificado, a carteira solicitará que você o insira. Ao transferir SOL, esse valor é expresso em SOL, não em lamports.

Token SPL

Esse campo opcional representa o endereço de mint de um determinado tipo de conta de token SPL. Se você não o incluir, a transação será apenas uma transferência normal de SOL.

Referência

Um identificador exclusivo codificado na transação. Ele é usado para ajudar a localizar transações específicas e verificar seus resultados.

Rótulo

Uma breve descrição da origem da solicitação de transferência. Pode ser uma loja ou um aplicativo. As carteiras exibem essa informação ao usuário para fornecer detalhes sobre a transação.

Mensagem

Uma URL codificada que armazena detalhes sobre o motivo da transferência. Ela pode incluir o que você está comprando, um ID de pedido ou uma observação simples. As carteiras também usam essa informação para fornecer mais contexto ao usuário.

Memorando

Uma observação incluída na transação de pagamento. Ela não deve conter informações privadas ou confidenciais, pois fica armazenada on-chain.

Esses detalhes oferecem controle total sobre sua transação e simplificam a interação entre sua carteira e o destinatário. Por segurança, os aplicativos só devem processar a transação depois que ela for confirmada on-chain.

Solana Pay: exemplos de URLs

Enviando 0,5 SOL:

solana:CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE?amount=0.5&label=Amazon&message=Thanks%20for%20shopping%20at%20Amazon&memo=ID321

Enviando 5 USDC:

solana:CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE?amount=5&spl-token=EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v

Solana Pay: implementação com Next.js

O que vamos desenvolver? Ao final deste tutorial, você terá um aplicativo web que cria um código QR do Solana Pay usando os dados inseridos pelos usuários (um endereço de carteira e uma quantidade de SOL). Esse aplicativo também mostrará o status do pagamento verificando o status da transação na blockchain.

Pré-requisitos

• Você precisa ter o Node.js instalado em sua máquina
• Tenha bons conhecimentos de React e TypeScript.
• Você precisará de uma carteira Solana para enviar e receber fundos.
• Você também precisará de uma chave de API da Helius para qualquer operação on-chain. Você pode obter gratuitamente uma chave de API da Helius usando apenas uma carteira em nosso portal para desenvolvedores.

Etapas

Siga estas etapas para usar o Solana Pay com Next.js.

Criar um aplicativo Next.js

Primeiro, verifique se o Node está instalado e crie o aplicativo Next.js. No terminal, digite o seguinte:

npx create-next-app@latest sol-pay-app

‍Em seguida, algumas perguntas serão exibidas. Selecione estas opções:

Depois que o aplicativo for criado, acesse o diretório com:

cd sol-pay-app

Dentro do diretório, inicie o aplicativo com:

npm run dev

Acesse http://localhost:3000/ para visualizar seu aplicativo.

Instalar pacotes

Este aplicativo precisará de dois pacotes: Solana web3.js e Solana Pay. Também usaremos um pacote chamado “react-qr-code” para gerar versões em código QR dos links de transação.

Para instalar esses pacotes, execute:

npm install @solana/pay @solana/web3.js bignumber.js react-qr-code --save

Criar um front-end

Crie um front-end para exibir o código QR do Solana Pay e permitir a edição do endereço que receberá o SOL e da quantidade de SOL. Por segurança, é recomendável executar toda a lógica no back-end, principalmente a definição dos valores e do destinatário.

No entanto, para manter tudo simples, também executaremos a lógica do aplicativo no front-end.

1. Acesse o diretório pages e abra o arquivo index.tsx. Esse arquivo representa sua página inicial. Substitua o código existente pelo seguinte:

export default function Home() {
  return (
    <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
      <h1 className="mb-6 text-3xl font-bold text-orange-700">
        Helius Solana Pay Demo
      </h1>
    </div>
  );
}

2. Adicione as importações no início da página.

// imports
import {Cluster,clusterApiUrl,Connection,PublicKey,Keypair} from "@solana/web3.js";
import { encodeURL, createQR,findReference, FindReferenceError, validateTransfer } from "@solana/pay";
import BigNumber from "bignumber.js";
import { useState } from "react";
import QRCode from "react-qr-code";

3. Crie uma variável para armazenar sua URL RPC da Helius. Se você pretende implantar esse aplicativo, use um arquivo ENV ou um proxy para ocultar sua chave de API.

// get a free Helius RPC at helius.dev
 const RPC="https://rpc.helius.xyz/?api-key="!

4. Crie um objeto Solana Connection com sua URL RPC da Helius:

console.log('Connecting to the Solana network\n');
const connection = new Connection(RPC, 'confirmed');

5. Em seguida, declararemos e inicializaremos as variáveis que serão usadas. Isso incluirá todas as variáveis necessárias na URL do Solana Pay. Você pode criar essas variáveis dentro da função Home().

// URL Variables
  const [address, setAddress] = useState("");
  const [recipient, setRecipient] = useState(
    new PublicKey("CckxW6C1CjsxYcXSiDbk7NYfPLhfqAm3kSB5LEZunnSE"));
  const [amount, setAmount] = useState(new BigNumber(1));
  const [message, setMessage] = useState("Helius Demo Order");
  const reference = new Keypair().publicKey;
  const label = "Helius Super Store";
  const memo = "Helius#4098";

  // for the QR code
  const [qrCodeValue, setQrCodeValue] = useState('');
  const [paymentStatus, setPaymentStatus] = useState('');

6. Agora, precisamos escrever uma função para criar o pagamento. Essa função usará as variáveis dos campos de entrada e criará uma URL codificada do Solana Pay com o método encodedURL. Depois, converteremos o objeto URL em uma string e a salvaremos para exibir o código QR posteriormente. Adicione o seguinte código abaixo das variáveis:

async function createPayment() {
    console.log("Creating a payment URL \n");
    setRecipient(new PublicKey(address));
    const url = encodeURL({
      recipient,
      amount,
      reference,
      label,
      message,
      memo,
    });

    setQrCodeValue(url.toString()); // convert URL object to string
    checkPayment();
  }

7. Depois que o pagamento for criado, apresentaremos o código QR ao usuário, que poderá escaneá-lo e realizar a transação. Para verificar se essa transação ocorreu e foi bem-sucedida, precisamos criar uma função que confira a transação de pagamento on-chain. Na função createPayment acima, você pode ver que chamamos essa função logo após criar a transação.

async function checkPayment() {
    // update payment status
    setPaymentStatus('pending');

		// search for transaction

		// validate transaction
}

Essa função terá duas partes: buscar a transação confirmada e validar a transação.

Como o usuário interagirá com a transação em outro dispositivo, não há como saber exatamente quando ela ocorreu. Em vez disso, verificaremos repetidamente se uma transação com a referência correspondente ocorreu e qual é o status dela. Isso é feito com o método findReference do Solana Pay.

// search for transaction
console.log('Searching for the payment\n');
    let signatureInfo;
  
    const {signature} = await new Promise((resolve, reject) => {
      
        const interval = setInterval(async () => {
            console.count('Checking for transaction...'+reference);
            try {
                signatureInfo = await findReference(connection, reference, { finality: 'confirmed' });
                console.log('\n Signature: ', signatureInfo.signature,signatureInfo);
                clearInterval(interval);
                resolve(signatureInfo);
            } catch (error: any) {
                if (!(error instanceof FindReferenceError)) {
                    console.error(error);
                    clearInterval(interval);
                    reject(error);
                }
            }
        }, 250);
    });
	// Update payment status
  setPaymentStatus('confirmed');

Depois que a transação for encontrada, precisamos confirmar se tudo ocorreu corretamente nela.

Isso inclui verificar se o destinatário correto recebeu os tokens e se a quantidade correta de tokens foi enviada. Para isso, usaremos o método validateTransfer do Solana Pay:

//validate transaction
    console.log('Validating the payment\n');
    try {
      await validateTransfer(connection, signature, { recipient: recipient, amount });

      // Update payment status
      setPaymentStatus('validated');
      console.log('Payment validated');
      return true;
      
  } catch (error) {
      console.error('Payment failed', error);
      return false;
  }

8. A etapa final do processo será adicionar o TSX para configurar a interface. Usaremos Tailwind para estilizar os elementos. A interface incluirá um título, dois campos de entrada para o endereço do destinatário e a quantidade de SOL, um botão e um código QR do Solana Pay. O código QR do Solana Pay será substituído pelo texto “Pagamento validado” assim que o pagamento for validado. O botão chamará o método createPayment.

//validate transaction
return (
    <div className="flex flex-col items-center justify-center min-h-screen bg-gray-100">
      <h1 className="mb-6 text-3xl font-bold text-orange-700">
        Helius Solana Pay Demo
      </h1>
      <div className="w-full max-w-md p-6 mx-auto bg-white rounded-xl shadow-md">
        <div className="mb-4">
          <label className="block mb-2 text-sm font-medium text-gray-700">
            Address:
          </label>
          <input
            type="text"
            onChange={(e) => setAddress(e.target.value)}
            className="w-full px-3 py-2 text-sm leading-tight text-gray-700 border rounded shadow appearance-none focus:outline-none focus:shadow-outline"
          />
        </div>
        <div className="mb-4">
          <label className="block mb-2 text-sm font-medium text-gray-700">
            Amount:
          </label>
          <input
            type="number"
            onChange={(e) => setAmount(new BigNumber(e.target.value))}
            className="w-full px-3 py-2 text-sm leading-tight text-gray-700 border rounded shadow appearance-none focus:outline-none focus:shadow-outline"
          />
        </div>
        <div className="flex justify-center items-center">
        <button
          className="px-4 py-2 font-bold text-white bg-blue-500 rounded hover:bg-blue-700"
          onClick={createPayment}
        >
          Create QR Code
        </button>
        </div>
        
        <div>
        {paymentStatus === 'validated' ? <p className="mt-4 text-green-500 text-center">Payment Validated</p> : <div className="flex justify-center mt-4">
          {qrCodeValue && }
        </div>}
      </div>
      </div>
      
    </div>
  );

‍Depois de concluir todas essas etapas, você terá um aplicativo com esta aparência e comportamento:

Solana Pay: criando experiências simples

Seja para fazer um pagamento ou configurar uma transação, o sistema de codificação do Solana Pay oferece uma experiência simples tanto para usuários quanto para aplicativos. Espero que este guia seja uma ferramenta completa para entender e implementar o Solana Pay, tornando suas interações com a blockchain Solana mais simples e eficientes. Se precisar de ajuda, fique à vontade para entrar no Discord da Helius ou falar conosco pelo Twitter.

• Encontre o código completo que deve estar no arquivo index.tsx
• Saiba mais sobre o Solana Pay
• Consulte a documentação do Solana Pay

‍

‍

‍