Implantando programas

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

• Modelo de conta Solana
• Programas Solana em geral
• Desenvolvendo programas Solana personalizados

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

$ 
solana-keygen newCopy

Isto cria um keypair em ~/.config/solana/id.json por padrão.

cargo-build-sbf

Implantação inicial

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

Escolha em qual cluster Solana implementar. Use o comando solana config get para verificar a sua configuração atual:

$ 
solana config get
Copy
[show output]

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

$ 
solana config set --url mainnet-beta
Copy
$ 
solana config set --url devnet
Copy
$ 
solana config set --url localhost
Copy
$ 
solana config set --url testnet
Copy
$ 
solana config set --url "https://your-rpc-url.com"Copy

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

Reimplantação

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

Para devnet ou localhost, financie a sua carteira usando o comando solana airdrop:

$ 
solana airdrop 2
Copy
[show output]

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

$ 
solana balance
Copy
[show output]

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

Para compilar um programa, use o comando cargo build-sbf:

$ 
cargo build-sbfCopy

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.

Para recuperar o keypair:

Compile o seu programa usando o comando cargo build-sbf:

$ 
cargo build-sbfCopy

Isto cria dois ficheiros importantes em target/deploy/:

1. hello_world-keypair.json: Um ficheiro de keypair cuja chave pública será usada como o seu ID de programa
2. hello_world.so: O executável do programa compilado

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.

$ 
wc -c < ./target/deploy/hello_world.so
Copy
[show output]

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

$ 
solana rent 18504
Copy
[show output]

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:

Use o comando solana program deploy para implementar o seu programa:

$ 
solana program deploy ./target/deploy/hello_world.so
Copy
[show output]

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

$ 
solana program deploy ./target/deploy/hello_world.so --program-id ./custom-keypair.jsonCopy

Pode gerar novos keypairs usando o comando solana-keygen:

$ 
solana-keygen new -o ./custom-keypair.jsonCopy

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

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

Atualize o seu programa usando o mesmo comando solana program deploy:

1. Faça alterações no código do seu programa
2. Recompile o seu programa: cargo build-sbf
3. Implemente a atualização:

$ 
solana program deploy ./target/deploy/hello_world.so
Copy
[show output]

Inspecionando Metadados

O subcomando show lista os metadados de um programa.

Um exemplo de saída se parece com:

$ 
solana program extend 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE 1000
Copy
[show output]

• 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 verificar os metadados do seu programa, use o comando solana program show:

$ 
solana program show 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpECopy

Para mostrar todas as contas de buffer independentemente da autoridade:

solana program show --buffers --all

$ solana program show 7283x8k8fyBcfaFLyPsxbd2VV1AMmZFP7FNoyTXVKJw7
Program Id: 7283x8k8fyBcfaFLyPsxbd2VV1AMmZFP7FNoyTXVKJw7
Owner: BPFLoaderUpgradeab1e11111111111111111111111
ProgramData Address: Gqn7YQVCP8NtYV1qkEqR4Udhj8EJ3fkikvS7HskCNQ7c
Authority: 5kh6HxYZiAebF8HWLsUWod2EaQQ6iWHpHYCz8UcmFbM1
Last Deployed In Slot: 6573
Data Length: 18504 (0x4848) bytes
Balance: 0.12999192 SOL

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.

Para transferir a autoridade do programa para uma conta diferente, use o comando solana program set-upgrade-authority:

$ 
solana program set-upgrade-authority 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE --new-upgrade-authority ./new-authority-keypair.jsonCopy

Primeiro, um keypair para a autoridade deve ser gerado:

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

Para tornar o seu programa imutável, use o comando solana program set-upgrade-authority com a flag --final para remover a autoridade do programa:

$ 
solana program set-upgrade-authority 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE --final
Copy
[show output]

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:

Para fechar o seu programa e recuperar o SOL alocado à conta do programa, use o comando solana program close:

$ 
solana program close 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE --bypass-warning
Copy
[show output]

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

$ 
solana program show --programsCopy

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

Program Id                                       | Slot       | Authority                                      | Balance
-------------------------------------------------|------------|------------------------------------------------|-------------
7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE     | 249885434  | 5kh6HxYZiAebF8HWLsUWod2EaQQ6iWHpHYCz8UcmFbM1   | 0.12999192
3KSGCk4m5hqJkTjPHBXUCPcqMwJnK3VmkqEsFUKKGJPK     | 249883212  | 5kh6HxYZiAebF8HWLsUWod2EaQQ6iWHpHYCz8UcmFbM1   | 0.28654328

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

Para descarregar um programa implementado, use o comando solana program dump:

$ 
solana program dump 7NxQjW8H8hVcqBKgXbVDWqGQCovHbqDW9p1SJJwUyTpE ./downloaded_program.so
Copy
[show output]

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.

$ 
solana program deploy ./target/deploy/hello_world.so \
    --with-compute-unit-price 10000 \
    --max-sign-attempts 10 \
    --use-rpcCopy

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

• --with-compute-unit-price: Define a taxa de prioridade em micro-lamports (0,000001 SOL) por unidade de computação. Consulte a API de Taxa de Prioridade Helius para taxas atuais. Uma taxa de prioridade é uma taxa adicional paga ao líder atual para priorizar a sua transação.
• --max-sign-attempts: Número de vezes para tentar novamente com um novo blockhash se as transações expirarem. (Padrão: 5)
• --use-rpc: Envia transações para o RPC configurado. Esta flag requer uma conexão RPC ponderada por stake de fornecedores como Triton ou Helius.