From ec86ff8fb361938667eac80b4f1d6937634676f4 Mon Sep 17 00:00:00 2001 From: Jon Cinque Date: Mon, 1 Nov 2021 21:41:49 +0100 Subject: [PATCH] docs: Update language around immutable programs (#21116) --- docs/src/developing/on-chain-programs/deploying.md | 10 +++++++--- docs/src/developing/programming-model/accounts.md | 8 +++++--- .../programming-model/calling-between-programs.md | 6 ++++-- 3 files changed, 16 insertions(+), 8 deletions(-) diff --git a/docs/src/developing/on-chain-programs/deploying.md b/docs/src/developing/on-chain-programs/deploying.md index 7d938265db..767d6d114b 100644 --- a/docs/src/developing/on-chain-programs/deploying.md +++ b/docs/src/developing/on-chain-programs/deploying.md @@ -11,9 +11,13 @@ clients via a _program ID_. The program ID is an _address_ specified when deploying and is used to reference the program in subsequent transactions. Upon a successful deployment the account that holds the program is marked -executable and its account data become permanently immutable. If any changes -are required to the program (features, patches, etc...) the new program must be -deployed to a new program ID. +executable. If the program is marked "final", its account data become permanently +immutable. If any changes are required to the finalized program (features, patches, +etc...) the new program must be deployed to a new program ID. + +If a program is upgradeable, the account that holds the program is marked +executable, but it is possible to redeploy a new shared object to the same +program ID, provided that the program's upgrade authority signs the transaction. The Solana command line interface supports deploying programs, for more information see the [`deploy`](cli/usage.md#deploy-program) command line usage diff --git a/docs/src/developing/programming-model/accounts.md b/docs/src/developing/programming-model/accounts.md index 2c60c6373a..bc05d32f8d 100644 --- a/docs/src/developing/programming-model/accounts.md +++ b/docs/src/developing/programming-model/accounts.md @@ -47,9 +47,11 @@ instruction's [program id](transactions.md#program-id). Accounts are marked as executable during a successful program deployment process by the loader that owns the account. When a program is deployed to the execution engine (BPF deployment), the loader determines that the bytecode in the account's data is valid. -If so, the loader -permanently marks the program account as executable. Once executable, the -runtime enforces that the account's data (the program) is immutable. +If so, the loader permanently marks the program account as executable. + +If a program is marked as final (non-upgradeable), the runtime enforces that the +account's data (the program) is immutable. Through the upgradeable loader, it is +possible to upload a totally new program to an existing program address. ## Creating diff --git a/docs/src/developing/programming-model/calling-between-programs.md b/docs/src/developing/programming-model/calling-between-programs.md index d53d6cced4..96a41764b4 100644 --- a/docs/src/developing/programming-model/calling-between-programs.md +++ b/docs/src/developing/programming-model/calling-between-programs.md @@ -84,8 +84,10 @@ signers and writable accounts. For example, if the instruction the caller is processing contains a signer or writable account, then the caller can invoke an instruction that also contains that signer and/or writable account. -This privilege extension relies on the fact that programs are immutable. In the -case of the `acme` program, the runtime can safely treat the transaction's +This privilege extension relies on the fact that programs are immutable, except +during the special case of program upgrades. + +In the case of the `acme` program, the runtime can safely treat the transaction's signature as a signature of a `token` instruction. When the runtime sees the `token` instruction references `alice_pubkey`, it looks up the key in the `acme` instruction to see if that key corresponds to a signed account. In this case, it