Add docs for migrating a program to two token programs

Author: joncinque

docs/src/token-2022/onchain.md

@@ -230,6 +230,250 @@ do more work.
 
 ## Part II: Support Mixed Token Programs: trading a Token for a Token-2022
 
+In Part I, we looked at the minimal amount of work to support Token-2022 in your
+program. This work won't cover all cases, however. Specifically, in the token-swap
+program, most instructions involve multiple token types. If those token types are
+from different token programs, then our current implementation will fail.
+
+For example, if you want to swap tokens from the Token program for tokens from
+the Token-2022 program, then your program's instruction must provide each token
+program, so that your program may invoke them.
+
+Let's go through the steps to support both token programs in the same instruction.
+
+### Step 1: Update all instruction interfaces
+
+The first step is to update all instruction interfaces to accept a token program
+for each token type used in the program.
+
+For example, here is the previous definition for the `Swap` instruction:
+
+```rust
+///   Swap the tokens in the pool.
+///
+///   0. `[]` Token-swap
+///   1. `[]` swap authority
+///   2. `[]` user transfer authority
+///   3. `[writable]` token_(A|B) SOURCE Account, amount is transferable by user transfer authority,
+///   4. `[writable]` token_(A|B) Base Account to swap INTO.  Must be the SOURCE token.
+///   5. `[writable]` token_(A|B) Base Account to swap FROM.  Must be the DESTINATION token.
+///   6. `[writable]` token_(A|B) DESTINATION Account assigned to USER as the owner.
+///   7. `[writable]` Pool token mint, to generate trading fees
+///   8. `[writable]` Fee account, to receive trading fees
+///   9. `[]` Token program id
+///   10. `[optional, writable]` Host fee account to receive additional trading fees
+Swap {
+    pub amount_in: u64,
+    pub minimum_amount_out: u64
+}
+```
+
+`Swap` contains 3 different token types: token A, token B, and the pool token. Let's
+add a separate token program for each, transforming the instruction into:
+
+```rust
+///   Swap the tokens in the pool.
+///
+///   0. `[]` Token-swap
+///   1. `[]` swap authority
+///   2. `[]` user transfer authority
+///   3. `[writable]` token_(A|B) SOURCE Account, amount is transferable by user transfer authority,
+///   4. `[writable]` token_(A|B) Base Account to swap INTO.  Must be the SOURCE token.
+///   5. `[writable]` token_(A|B) Base Account to swap FROM.  Must be the DESTINATION token.
+///   6. `[writable]` token_(A|B) DESTINATION Account assigned to USER as the owner.
+///   7. `[writable]` Pool token mint, to generate trading fees
+///   8. `[writable]` Fee account, to receive trading fees
+///   9. `[]` Token (A|B) SOURCE program id
+///   10. `[]` Token (A|B) DESTINATION program id
+///   11. `[]` Pool Token program id
+///   12. `[optional, writable]` Host fee account to receive additional trading fees
+Swap {
+    pub amount_in: u64,
+    pub minimum_amount_out: u64
+}
+```
+
+Note the clarification on `9.`, and the new inputs of `10.` and `11.`.
+
+All of these additional accounts may make you wonder: how big will transactions
+get with these new accounts? If you are using both Token and Token-2022,
+the additional Token-2022 program will take up space in the transaction,
+32 bytes for the pubkey, and 1 byte for its index.
+
+On the flip side, if you're only using one token program at once, you will only
+incur 1 byte of overhead because of the deduplication of accounts in the Solana
+transaction format.
+
+Also note that some instructions will remain unchanged. For example, here is the
+`Initialize` instruction:
+
+```rust
+///   Initializes a new swap
+///
+///   0. `[writable, signer]` New Token-swap to create.
+///   1. `[]` swap authority derived from `create_program_address(&[Token-swap account])`
+///   2. `[]` token_a Account. Must be non zero, owned by swap authority.
+///   3. `[]` token_b Account. Must be non zero, owned by swap authority.
+///   4. `[writable]` Pool Token Mint. Must be empty, owned by swap authority.
+///   5. `[]` Pool Token Account to deposit trading and withdraw fees.
+///   Must be empty, not owned by swap authority
+///   6. `[writable]` Pool Token Account to deposit the initial pool token
+///   supply.  Must be empty, not owned by swap authority.
+///   7. `[]` Token program id
+Initialize { ... } // details omitted
+```
+
+Although we pass in token A and token B accounts, we don't actually need to invoke
+their respective token programs. We do, however, mint new pool tokens, so we must
+pass in the token program for the pool token mint.
+
+This step is mostly churn since interfaces must be updated. Don't worry if some
+tests fail after this step. We'll fix them in the next step.
+
+### Step 2: Update instruction processors
+
+If your instruction processor is expecting accounts after the added token programs,
+you may see some test failures.
+
+Specifically, in the token-swap example, the `Swap` instruction is expecting
+an optional account at the end, which has been clobbered by the added token
+programs.
+
+For this step, we'll simply pull out all of the new provided accounts. For example,
+in the `Swap` instruction processor, we'll go from:
+
+```rust
+let account_info_iter = &mut accounts.iter();
+let swap_info = next_account_info(account_info_iter)?;
+let authority_info = next_account_info(account_info_iter)?;
+let user_transfer_authority_info = next_account_info(account_info_iter)?;                     let source_info = next_account_info(account_info_iter)?;
+let swap_source_info = next_account_info(account_info_iter)?;
+let swap_destination_info = next_account_info(account_info_iter)?;
+let destination_info = next_account_info(account_info_iter)?;                                 let pool_mint_info = next_account_info(account_info_iter)?;                                   let pool_fee_account_info = next_account_info(account_info_iter)?;
+let token_program_info = next_account_info(account_info_iter)?;                       
+```
+
+To:
+
+```rust
+let account_info_iter = &mut accounts.iter();
+let swap_info = next_account_info(account_info_iter)?;
+let authority_info = next_account_info(account_info_iter)?;
+let user_transfer_authority_info = next_account_info(account_info_iter)?;
+let source_info = next_account_info(account_info_iter)?;
+let swap_source_info = next_account_info(account_info_iter)?;
+let swap_destination_info = next_account_info(account_info_iter)?;
+let destination_info = next_account_info(account_info_iter)?;
+let pool_mint_info = next_account_info(account_info_iter)?;
+let pool_fee_account_info = next_account_info(account_info_iter)?;
+let source_token_program_info = next_account_info(account_info_iter)?;
+let destination_token_program_info = next_account_info(account_info_iter)?;
+let pool_token_program_info = next_account_info(account_info_iter)?;
+```
+
+For now, just use one of those. For example, we'll just use `pool_token_program_info`
+everywhere. In the next step, we'll add some tests which will properly fail since
+we're always using the same token program.
+
+Once again, all of your tests should pass! But not for long.
+
+### Step 3: Write tests using multiple token programs at once
+
+In the spirit of test-driven development, let's start by writing some failing
+tests.
+
+Previously, our `test_case`s defined only provided one program id. Now it's
+time to mix them up and add more cases. For full coverage, we could do all
+permutations of different programs, but let's go with:
+
+* all mints belong to Token
+* all mints belong to Token-2022
+* the pool mint belongs to Token, but token A and B belong to Token-2022
+* the pool mint belongs to Token-2022, but token A and B are mixed
+
+Let's update test cases to pass in three different program ids, and then use them
+in the tests. For example, that means transforming:
+
+```rust
+#[test_case(spl_token::id(); "token")]
+#[test_case(spl_token_2022::id(); "token-2022")]
+fn test_initialize(token_program_id: Pubkey) {
+```
+
+Into:
+
+```rust
+#[test_case(spl_token::id(), spl_token::id(), spl_token::id(); "all-token")]
+#[test_case(spl_token_2022::id(), spl_token_2022::id(), spl_token_2022::id(); "all-token-2022")]
+#[test_case(spl_token::id(), spl_token_2022::id(), spl_token_2022::id(); "mixed-pool-token")]
+#[test_case(spl_token_2022::id(), spl_token_2022::id(), spl_token::id(); "mixed-pool-token-2022")]
+fn test_initialize(pool_token_program_id: Pubkey, token_a_program_id: Pubkey, token_b_program_id: Pubkey) {
+    ...
+}
+```
+
+This step may also involve churn, but take your time to go through it carefully,
+and you'll have failing tests for the `mixed-pool-token` and `mixed-pool-token-2022`
+test cases.
+
+### Step 4: Use appropriate token program in your processor
+
+Let's fix the failing tests! The errors come up because we're trying to operate
+on tokens with the wrong program in a "mixed" Token and Token-2022 environment.
+
+We need to properly use all of the `pool_token_program_info` / `token_a_program_info`
+variables that we extracted in Step 2.
+
+In the token-swap example, we'll check anywhere we filled in `pool_token_program_info`
+by default, and instead choose the correct program info. For example, when
+transferring the source tokens in `process_swap`, we currently have:
+
+```rust
+Self::token_transfer(
+    swap_info.key,
+    pool_token_program_info.clone(),
+    source_info.clone(),
+    swap_source_info.clone(),
+    user_transfer_authority_info.clone(),
+    token_swap.bump_seed(),
+    to_u64(result.source_amount_swapped)?,
+)?;
+```
+
+Let's use the correct token program, making this:
+
+```rust
+Self::token_transfer(
+    swap_info.key,
+    source_token_program_info.clone(),
+    source_info.clone(),
+    swap_source_info.clone(),
+    user_transfer_authority_info.clone(),
+    token_swap.bump_seed(),
+    to_u64(result.source_amount_swapped)?,
+)?;
+```
+
+While going through this, if you notice any owner checks for a token account or mint
+in the form of:
+
+```rust
+if token_account_info.owner != &spl_token::id() { ... }
+```
+
+You'll need to update to a new owner check from `spl_token_2022`:
+
+```rust
+if spl_token_2022::check_spl_token_program_account(token_account_info.owner).is_err() { ... }
+```
+
+In this step, because of all the test cases in token-swap, we also have to update
+the expected error due to mismatched owner token programs.
+
+It's tedious, but at this point, we have updated our program to use both Token
+and Token-2022 simultaneously. Congratulations! You're ready to be part of the
+next stage of DeFi on Solana.
+
 ## Part III: Support Specific Extensions
 
 ### Update from `transfer` to `transfer_checked`