Implantando programas

Este guia pressupõe conhecimento dos seguintes tópicos:

Loader-v3 e Loader-v4

Atualmente está ocorrendo uma transição do loader-v3 (subcomando program) para loader-v4 (subcomando program -v4), pois o loader-v3 está sendo descontinuado.

Para novas implantações, use solana program-v4 deploy em vez de solana program deploy.

Para migrar um programa existente (o que essencialmente é reimplantá-lo):

solana program migrate ./target/deploy/your_program-keypair.json

Preparação

Primeiro, o programa precisa ser compilado (compilado, vinculado, reduzido).

cargo +solana build --target sbpf-solana-solana --release

Esta etapa deve ser realizada antes de cada reimplantação/implantação.

Verifique se há fundos suficientes disponíveis na conta pagadora padrão proporcional ao tamanho do executável:

du -h ./target/deploy/your_program.so
solana balance

Além disso, cada programa tem uma conta de programa e um ID de programa, que é o endereço dessa conta de programa. O seguinte gera um keypair para a conta do programa:

solana-keygen new -o ./target/deploy/your_program-keypair.json

Isso deve ser realizado apenas uma vez por programa e será reutilizado para reimplantações do mesmo programa posteriormente.

A cadeia de ferramentas continha um atalho, no entanto, ele está sendo eliminado / descontinuado:

cargo-build-sbf

Implantação inicial

Agora o executável pode ser enviado para a conta do programa:

Loader-v3

O parâmetro é chamado program-id mesmo que espere o caminho do arquivo de um keypair:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json

Fazer upload de um executável diferente para a mesma conta de programa novamente irá sobrescrever / substituí-lo. No entanto, para reimplantações, apenas o ID do programa (pubkey do keypair do programa) é necessário, não o keypair inteiro, porque o assinante é o keypair da autoridade de atualização.

Loader-v3

Isso é exatamente igual à implantação inicial:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Se o executável antigo for menor que o novo, pode ser necessário aumentar a conta programdata primeiro:

solana program extend ./target/deploy/your_program.so <ADDITIONAL_BYTES>

Loader-v4

Observe que a implantação inicial usou program-keypair, enquanto a reimplantação usa program-id em vez disso:

solana program-v4 deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Priorizando um upload

Durante períodos de congestionamento, existem algumas flags adicionais que você pode usar para ajudar com a implantação do programa:

--with-compute-unit-price: Define o preço da unidade de computação para a transação, em incrementos de 0,000001 lamports (micro-lamports) por unidade de computação. Use a API de Taxa de Prioridade da Helius para obter uma estimativa da taxa de prioridade a ser definida.
--use-rpc: Envia transações de escrita para o RPC configurado em vez de TPUs do validador. Esta flag requer uma conexão RPC ponderada por stake como Helius ou Triton. Esta flag também pode ser configurada como padrão usando: solana config set --url <RPC_URL>.
--max-sign-attempts: Número máximo de tentativas para assinar ou reassinar transações após a expiração do blockhash. Se alguma transação enviada durante a implantação do programa ainda não estiver confirmada após a expiração do blockhash recente inicialmente escolhido, essas transações serão reassinadas com um novo blockhash recente e reenviadas. Use esta configuração para ajustar o número máximo de iterações de assinatura de transação. Cada blockhash é válido por cerca de 60 segundos, o que significa que usar o valor padrão de 5 levará ao envio de transações por pelo menos 5 minutos ou até que todas as transações sejam confirmadas, o que ocorrer primeiro.

Retomando um upload

É possível que um upload fique travado ou seja abortado.

Loader-v3

Se a implantação do programa falhar, haverá uma conta de buffer intermediária pendente que contém um saldo diferente de zero. Para recuperar esse saldo, você pode retomar uma implantação que falhou fornecendo o mesmo buffer intermediário para uma nova chamada a deploy.

Falhas na implantação exibirão uma mensagem de erro especificando a frase seed necessária para recuperar o keypair do buffer intermediário gerado:

==================================================================================
Recover the intermediate account's ephemeral keypair file with
`solana-keygen recover` and the following 12-word seed phrase:
==================================================================================
valley flat great hockey share token excess clever benefit traffic avocado athlete
==================================================================================
To resume a deploy, pass the recovered keypair as
the [BUFFER_SIGNER] to `solana program deploy` or `solana program write-buffer'.
Or to recover the account's lamports, pass it as the
[BUFFER_ACCOUNT_ADDRESS] argument to `solana program drain`.
==================================================================================

Para recuperar o keypair:

solana-keygen recover -o ./target/deploy/buffer-keypair.json

Quando solicitado, insira a frase seed de 12 palavras.

Em seguida, emita um novo comando deploy e especifique o buffer:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --buffer ./target/deploy/buffer-keypair.json

Loader-v4

É possível retomar um upload a partir de um deslocamento de bytes específico:

solana program deploy ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json --start-offset <BYTES_UPLOADED_SO_FAR>

Finalização

Esta é uma ação irreversível.

Um programa pode se tornar imutável removendo sua autoridade de atualização.

Loader-v3

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --final

Loader-v4

solana program finalize --program-id ./target/deploy/your_program-keypair.json

Em vez de sobrescrever programas, também é possível oferecer aos usuários a escolha de qual versão de um programa eles desejam usar, construindo uma lista encadeada de programas finalizados:

solana program finalize --program-id ./target/deploy/your_program-keypair.json --next-version ../your_newer_program/target/deploy/your_newer_program-keypair.json

Fechamento

Para programas implantados sob o loader-v3, apenas sua conta programdata, as contas de buffer e os fundos bloqueados nelas podem ser recuperados. A conta do programa junto com o ID do programa e os fundos bloqueados especificamente na conta do programa estão presos.

Programas implantados sob o loader-v4 podem ser fechados com sua conta de programa, seu ID de programa e seus fundos bloqueados, todos se tornando disponíveis para outros usos novamente.

Loader-v3

Esta é uma ação irreversível para programas implantados usando o loader-v3.

Observe que uma vez que um programa é fechado, seu ID de programa não pode ser reutilizado. Tentar implantar um programa com um ID de programa previamente fechado resultará em um erro. Se você precisar reimplantar um programa após fechá-lo, você deve gerar um novo arquivo de keypair do programa.

Para fechar uma única conta programdata:

solana program close ./target/deploy/your_program-keypair.json

Para fechar todas as contas de buffer associadas à autoridade atual:

solana program close --buffers

Loader-v4

solana program-v4 close --program-id ./target/deploy/your_program-keypair.json

Inspecionando Metadados

O subcomando show lista os metadados de um programa.

Um exemplo de saída se parece com:

Program Id: 3KS2k14CmtnuVv2fvYcvdrNgC94Y11WETBpMUGgXyWZL
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: EHsACWBhgmw8iq5dmUZzTA1esRqcTognhKNHUkPi4q4g
Authority: FwoGJNUaJN2zfVEex9BB11Dqb3NJKy3e9oY3KTh9XzCU
Last Deployed In Slot: 63890568
Data Length: 5216 (0x1460) bytes

Program Id é o endereço que pode ser referenciado no campo program_id de uma instrução ao invocar um programa.
Owner: O loader com o qual este programa foi implantado.
ProgramData Address é a conta programdata associada à conta do programa que contém o executável do programa (apenas loader-v3).
Status: retracted, deployed ou finalized (apenas loader-v4).
Authority é a autoridade de atualização do programa.
Last Deployed In Slot é o slot no qual o programa foi implantado pela última vez.
Data Length é o tamanho do espaço reservado para implantações. O espaço real usado pelo programa atualmente implantado pode ser menor.

Loader-v3

Para visualizar um programa específico:

solana program show ./target/deploy/your_program-keypair.json

Para visualizar a lista de programas implantados com a autoridade padrão:

solana program show --programs

Para mostrar todas as contas de buffer independentemente da autoridade:

solana program show --buffers --all

Para especificar uma autoridade diferente:

solana program show --programs --buffer-authority ~/.config/solana/authority-keypair.json
solana program show --buffers --buffer-authority ~/.config/solana/authority-keypair.json

Loader-v4

Para visualizar um programa específico:

solana program-v4 show --program-id ./target/deploy/your_program-keypair.json

Para visualizar a lista de programas implantados com a autoridade padrão:

solana program-v4 show --all

Para visualizar a lista de programas implantados com uma autoridade específica:

solana program-v4 show --authority ~/.config/solana/authority-keypair.json

Baixando o executável

Às vezes é útil baixar e comparar um programa para garantir que ele contenha um executável conhecido. O arquivo baixado pode ser truncado, transformado em hash e comparado com o hash do arquivo do programa original.

Loader-v3

solana program dump ./target/deploy/your_program-keypair.json ./target/deploy/your_program.so

Loader-v4

solana program download ./target/deploy/your_program.so --program-id ./target/deploy/your_program-keypair.json

Avançado: transferência de autoridade

O direito de alterar um determinado programa pertence à sua autoridade. Esta autoridade pode ser transferida para outro keypair sem alterar o keypair do programa, para que o ID do programa permaneça o mesmo. Além disso, uma única autoridade pode controlar vários program accounts.

Se não for explicitamente especificado durante a implantação inicial, então o keypair padrão é usado como autoridade. É por isso que reimplantar um programa nos passos acima não exigiu que uma autoridade fosse explicitamente especificada.

Uma autoridade explícita é útil para assinatura offline e programas governados por múltiplas entidades.

Primeiro, um keypair para a autoridade deve ser gerado:

solana-keygen new -o ~/.config/solana/authority-keypair.json

Loader-v3

A autoridade pode ser especificada durante a implantação:

solana program deploy ./target/deploy/your_program.so --upgrade-authority ~/.config/solana/authority-keypair.json

Ou após a implantação e usando o keypair padrão como a autoridade atual:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --new-upgrade-authority ~/.config/solana/authority-keypair.json

Ou após a implantação e especificando a autoridade atual:

solana program set-upgrade-authority ./target/deploy/your_program-keypair.json --upgrade-authority ~/.config/solana/authority-keypair.json --new-upgrade-authority ~/.config/solana/new_authority-keypair.json

Loader-v4

A autoridade pode ser especificada durante a implantação:

solana program-v4 deploy ./target/deploy/your_program.so --program-keypair ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json

Ou após a implantação e usando o keypair padrão como a autoridade atual:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --new-authority ~/.config/solana/authority-keypair.json

Ou após a implantação e especificando a autoridade atual:

solana program-v4 transfer-authority --program-id ./target/deploy/your_program-keypair.json --authority ~/.config/solana/authority-keypair.json --new-authority ~/.config/solana/new_authority-keypair.json

Avançado: Reimplantação em duas etapas usando um Buffer

Em vez de fazer o upload diretamente para o program account, o executável pode ser carregado primeiro em uma conta de buffer intermediária e depois transferido para o program account em uma segunda etapa (a reimplantação/implantação real). Isso é útil para assinatura offline e programas governados por múltiplas entidades, como uma votação de DAO para escolher ou rejeitar um executável carregado antes da reimplantação real.

Lembre-se que usar contas de buffer praticamente dobra os fundos necessários durante o processo de upload, pois duas contas estão mantendo um executável cada, simultaneamente.

Primeiro, um keypair para a conta de buffer deve ser criado:

solana-keygen new -o ~/.config/solana/buffer-keypair.json

A conta de buffer pode ser reutilizada para diferentes uploads e não está vinculada a nenhum program account específico.

Loader-v3

solana program write-buffer ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Loader-v4

solana program-v4 deploy ./target/deploy/your_program.so --buffer ~/.config/solana/buffer-keypair.json
solana program-v4 deploy --program-id ./target/deploy/your_program-keypair.json --buffer ~/.config/solana/buffer-keypair.json

Avançado: Assinatura Offline

Alguns modelos de segurança exigem separar o processo de assinatura da transmissão da transação, de modo que as chaves de assinatura possam estar completamente desconectadas de qualquer rede, também conhecido como assinatura offline.

Observe que apenas as reimplantações podem ser realizadas no modo offline. A implantação inicial do programa deve ser realizada a partir de uma máquina online, e apenas as reimplantações subsequentes do programa podem aproveitar a assinatura offline.

Uma configuração típica consistiria em dois assinantes diferentes:

assinante online (pagador de taxas e autoridade da conta de buffer)
assinante offline (autoridade do program account)

O processo geral é uma reimplantação em duas etapas com alguns extras:

(online) criar um novo programa
(online) transferir a autoridade para o assinante offline
(online) criar buffer e fazer upload de um executável para ele
(opcional) verificar o conteúdo do buffer na blockchain
(offline) assinar uma transação para reimplantar o programa usando o buffer --blockhash <VALUE> --sign-only
(online) usar esta assinatura para transmitir a transação de reimplantação --blockhash <VALUE> --signer <OFFLINE_SIGNER_PUBKEY>:<OFFLINE_SIGNER_SIGNATURE>

Procure um blockhash recente e cole-o para gerar a assinatura de transação offline. O blockhash expira após aproximadamente 60 segundos. Se você não conseguir a tempo - basta obter outro hash novo e repetir até ter sucesso, ou considere usar nonces de transação duráveis.

Índice