project8: refactor test case using native anchor testing framework

since bankrun libraries are deprecated
TAKEAWAYS: try messing around the code and see what errors are

Author: Lewis

project-8-token-vesting/anchor/Anchor.toml

@@ -11,7 +11,7 @@ vesting = "GFdLg11UBR8ZeePW43ZyD1gY4z4UQ96LPa22YBgnn4z8"
 url = "https://api.apr.dev"
 
 [provider]
-cluster = "Localnet"
+cluster = "localnet"
 wallet = "~/.config/solana/id.json"
 
 [scripts]

project-8-token-vesting/anchor/package.json

@@ -2,12 +2,9 @@
   "name": "@token-vesting/anchor",
   "version": "0.0.1",
   "dependencies": {
-    "@coral-xyz/anchor": "^0.30.1",
-    "@solana/spl-token": "^0.4.8",
-    "@solana/web3.js": "1.94.0",
-    "anchor-bankrun": "^0.4.0",
-    "solana-bankrun": "^0.2.0",
-    "spl-token-bankrun": "0.2.5"
+    "@coral-xyz/anchor": "^0.31.1",
+    "@solana/spl-token": "^0.4.13",
+    "@solana/web3.js": "1.98.2"
   },
   "main": "./index.cjs",
   "module": "./index.js",

project-8-token-vesting/anchor/programs/vesting/Cargo.toml

@@ -17,6 +17,5 @@ default = []
 idl-build = ["anchor-lang/idl-build", "anchor-spl/idl-build"]
 
 [dependencies]
-anchor-lang = { version="0.30.1", features=["init-if-needed"] }
-anchor-spl = "0.30.1"
-solana-program = "1.18.17"
+anchor-lang = { version="0.31.1", features=["init-if-needed"] }
+anchor-spl = "0.31.1"

project-8-token-vesting/anchor/programs/vesting/src/lib.rs

@@ -87,6 +87,7 @@ pub mod vesting {
             signer_seeds
         );
         let decimals = ctx.accounts.mint.decimals;
+        // claimable_amount is i64
         token_interface::transfer_checked(cpi_context, claimable_amount as u64, decimals)?;
         employee_account.total_withdrawn += claimable_amount;
         Ok(())
@@ -115,6 +116,11 @@ pub struct CreateVestingAccount<'info> {
         seeds = [b"vesting_treasury", company_name.as_bytes()],
         bump
     )]
+    // treasury_token_account 是公司金库的 TokenAccount，它是由合约（PDA）控制的，
+    //  不是某个用户钱包的“关联账户”
+    // 是程序自定义的账户，而不是 SPL Token Associated Token Program 自动推导出来的账户。
+    // 金库账户不是“某个用户的钱包+mint”的标准组合，而是“公司+mint”的唯一账户，由合约自己管理,
+    //   所以它不能用 associated_token::xxx 这样的约束
     pub treasury_token_account: InterfaceAccount<'info, TokenAccount>,
     pub token_program: Interface<'info, TokenInterface>,
     pub system_program: Program<'info, System>,
@@ -124,7 +130,7 @@ pub struct CreateVestingAccount<'info> {
 pub struct CreateEmployeeAccount<'info> {
     #[account(mut)]
     pub owner: Signer<'info>,
-    pub beneficiary: SystemAccount<'info>,
+    pub beneficiary: SystemAccount<'info>, //why SystemAccount
     #[account(has_one = owner)]
     pub vesting_account: Account<'info, VestingAccount>,
     #[account(
@@ -147,6 +153,8 @@ pub struct ClaimTokens<'info> {
         mut,
         seeds = [b"employee_vesting", beneficiary.key().as_ref(), vesting_account.key().as_ref()],
         bump = employee_account.bump,
+        // 如果随便换名，则报：no field `beneficiary2` on type `anchor_lang::prelude::Account<'_, EmployeeAccount>`
+        // 这样可以防止恶意用户伪造账户，确保账户之间的归属关系正确
         has_one = beneficiary,
         has_one = vesting_account
     )]
@@ -158,9 +166,12 @@ pub struct ClaimTokens<'info> {
         has_one = treasury_token_account,
         has_one = mint
     )]
+    // 公司级别的 vesting 账户，记录公司、mint、金库等信息
     pub vesting_account: Account<'info, VestingAccount>,
+    // 代币的 mint 信息（即是哪种 SPL Token）
     pub mint: InterfaceAccount<'info, Mint>,
-    #[account(mut)]
+    #[account(mut)] // will change the token account's balance
+    // 公司金库的 token 账户，存放待发放的代币
     pub treasury_token_account: InterfaceAccount<'info, TokenAccount>,
     #[account(
         init_if_needed,
@@ -169,8 +180,13 @@ pub struct ClaimTokens<'info> {
         associated_token::authority = beneficiary,
         associated_token::token_program = token_program
     )]
+    // 员工自己的 token 账户，用于接收领取到的代币。如果不存在会自动创建
     pub employee_token_account: InterfaceAccount<'info, TokenAccount>,
     pub token_program: Interface<'info, TokenInterface>,
+    /*
+    在 Anchor 里，如果你用 associated_token::mint = ... 和 associated_token::authority = ... 
+    这样的语法，Anchor 会自动帮你用这个程序去创建（如果不存在）或查找（如果已存在）这个账户
+     */
     pub associated_token_program: Program<'info, AssociatedToken>,
     pub system_program: Program<'info, System>,
 }

project-8-token-vesting/anchor/tests/bankrun.spec.ts

@@ -1,77 +1,52 @@
 // No imports needed: web3, anchor, pg and more are globally available
 import * as anchor from "@coral-xyz/anchor";
-import { BankrunProvider } from "anchor-bankrun";
-import { TOKEN_PROGRAM_ID } from "@solana/spl-token";
+import { ASSOCIATED_TOKEN_PROGRAM_ID, TOKEN_PROGRAM_ID } from "@solana/spl-token";
 import { BN, Program } from "@coral-xyz/anchor";
+import { createMint, getOrCreateAssociatedTokenAccount, mintTo } from "@solana/spl-token";
 
-import {
-  startAnchor,
-  Clock,
-  BanksClient,
-  ProgramTestContext,
-} from "solana-bankrun";
-
-import { createMint, mintTo } from "spl-token-bankrun";
-import { PublicKey, Keypair } from "@solana/web3.js";
-import NodeWallet from "@coral-xyz/anchor/dist/cjs/nodewallet";
+import { PublicKey, Keypair, Connection, LAMPORTS_PER_SOL } from "@solana/web3.js";
 
 import IDL from "../target/idl/vesting.json";
 import { Vesting } from "../target/types/vesting";
 import { SYSTEM_PROGRAM_ID } from "@coral-xyz/anchor/dist/cjs/native/system";
 
+// Original method is using bankrun libraries, but since it has been deprecated,
+// I refactored using native anchor testing framework
+
 describe("Vesting Smart Contract Tests", () => {
   const companyName = "Company";
   let beneficiary: Keypair;
   let vestingAccountKey: PublicKey;
   let treasuryTokenAccount: PublicKey;
   let employeeAccount: PublicKey;
-  let provider: BankrunProvider;
+  let provider: anchor.AnchorProvider;
   let program: Program<Vesting>;
-  let banksClient: BanksClient;
   let employer: Keypair;
+  let payer: Keypair;
   let mint: PublicKey;
-  let beneficiaryProvider: BankrunProvider;
-  let program2: Program<Vesting>;
-  let context: ProgramTestContext;
+  // let beneficiaryProvider: anchor.AnchorProvider;
+  // let program2: Program<Vesting>;
+  const MY_DECIMALS = 2;
 
   beforeAll(async () => {
     beneficiary = new anchor.web3.Keypair();
 
-    // set up bankrun
-    context = await startAnchor(
-      "",
-      [{ name: "vesting", programId: new PublicKey(IDL.address) }],
-      [
-        {
-          address: beneficiary.publicKey,
-          info: {
-            lamports: 1_000_000_000,
-            data: Buffer.alloc(0),
-            owner: SYSTEM_PROGRAM_ID,
-            executable: false,
-          },
-        },
-      ]
-    );
-    provider = new BankrunProvider(context);
-
+    provider = anchor.AnchorProvider.env();
+    // rent is needed when claiming tokens for creating employee_token_acount
+    await provider.connection.requestAirdrop(beneficiary.publicKey,
+      1 * LAMPORTS_PER_SOL);
     anchor.setProvider(provider);
+    program = anchor.workspace.Vesting as Program<Vesting>;
+    console.log("program id:", program.programId.toString(),
+      ",beneficiary:", beneficiary.publicKey.toString());
 
-    program = new Program<Vesting>(IDL as Vesting, provider);
-
-    banksClient = context.banksClient;
-
-    employer = provider.wallet.payer;
+    employer = (provider.wallet as anchor.Wallet).payer;
+    payer = employer;
 
     // Create a new mint
-    // @ts-ignore
-    mint = await createMint(banksClient, employer, employer.publicKey, null, 2);
-
-    // Generate a new keypair for the beneficiary
-    beneficiaryProvider = new BankrunProvider(context);
-    beneficiaryProvider.wallet = new NodeWallet(beneficiary);
-
-    program2 = new Program<Vesting>(IDL as Vesting, beneficiaryProvider);
+    mint = await createMint(provider.connection, payer,
+      payer.publicKey, null, MY_DECIMALS);
+    console.log("Mint address:", mint.toBase58(), "payer:", payer.publicKey.toString());
 
     // Derive PDAs
     [vestingAccountKey] = PublicKey.findProgramAddressSync(
@@ -118,13 +93,22 @@ describe("Vesting Smart Contract Tests", () => {
 
   it("should fund the treasury token account", async () => {
     const amount = 10_000 * 10 ** 9;
+
+    // 创建 employer 的 ATA（关联账户）
+    // const employerTokenAccount = await getOrCreateAssociatedTokenAccount(
+    //   provider.connection,
+    //   payer,
+    //   mint,
+    //   payer.publicKey
+    // );
+
+    // 给 treasuryTokenAccount 铸币
     const mintTx = await mintTo(
-      // @ts-ignores
-      banksClient,
-      employer,
+      provider.connection,
+      payer,
       mint,
       treasuryTokenAccount,
-      employer,
+      payer, // mint authority/signer
       amount
     );
 
@@ -139,34 +123,75 @@ describe("Vesting Smart Contract Tests", () => {
         vestingAccount: vestingAccountKey,
       })
       .rpc({ commitment: "confirmed", skipPreflight: true });
+      //skipPreflight: 适合你确信交易不会失败，或者预检经常报奇怪的错误但实际能成功时
 
     console.log("Create Employee Account Transaction Signature:", tx2);
     console.log("Employee account", employeeAccount.toBase58());
   });
 
   it("should claim tokens", async () => {
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-
-    const currentClock = await banksClient.getClock();
-    context.setClock(
-      new Clock(
-        currentClock.slot,
-        currentClock.epochStartTimestamp,
-        currentClock.epoch,
-        currentClock.leaderScheduleEpoch,
-        1000n
-      )
-    );
-
-    console.log("Employee account", employeeAccount.toBase58());
-
-    const tx3 = await program2.methods
+    //await new Promise((resolve) => setTimeout(resolve, 1000));
+
+    // author says: the signer for this instruction is goint to be the beneficiary and not the employer
+    /*
+      The following is what I found by trial and error:
+
+      1. If not perform beneficiary airdrop，report:(won't be printed without try/catch)：
+      Error:  SendTransactionError: Simulation failed.
+    Message: Transaction simulation failed: Error processing Instruction 0: custom program error: 0x1.
+    Logs:
+    [
+      "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA consumed 1595 of 181545 compute units",
+      "Program return: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA pQAAAAAAAAA=",
+      "Program TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA success",
+      "Program 11111111111111111111111111111111 invoke [3]",
+      "Transfer: insufficient lamports 0, need 2039280",
+      "Program 11111111111111111111111111111111 failed: custom program error: 0x1"
+
+      2. unknown signer: xxx When only commenting out the line
+        // beneficiary: beneficiary.publicKey,
+
+      3. when commenting out the line,report:
+          Missing signature for public key xxx（beneficiary's key)
+          Solana 要求：只要合约指令声明了某个账户为 signer，交易就必须用对应私钥签名
+        // .signers([beneficiary])
+        
+      4. 除了tokenProgram, beneficiary，其他字段似乎都可注释掉，用例可过
+        如果仅注释了tokenProgram，则会报错：
+          Reached maximum depth for account resolution. Unresolved accounts: `employeeTokenAccount
+        原因（copilot gives)： 它是 SPL Token 程序的地址，不是 PDA，也不是可以自动推导的账户，
+          但它的 presence 让 Anchor 能正确识别和推导后续的 token 相关账户（比如 employeeTokenAccount
+      
+      5. 同时注释掉beneficiary和signers，报错：
+        AnchorError caused by account: employee_account. Error Code: 
+          AccountNotInitialized. Error Number: 3012. Error Message: 
+          The program expected this account to be already initialize
+      6. 既然第5点报employee_acount 未初使化，则尝试在同时注释它俩时，添加employeeAccount: 报：
+      AnchorError caused by account: employee_account. Error Code: ConstraintSeeds. 
+      Error Number: 2006. Error Message: A seeds constraint was violated.
+        Program log: Left:
+        Program log: BJRNd9PYp6oJNkioxJAdoZgNgt4TnNqGbKd6KuQVw9TS
+        Program log: Right:
+        Program log: 6xyHAzfxnWrjqK7zXTrTc9uw5zMh47Yr4VLFqYAu6mP
+        以上这个报错在 .anchor/ 中没找到相关日志,但错误描述是在anchor 源码中的
+    */
+   try {
+    const tx3 = await program.methods
       .claimTokens(companyName)
       .accounts({
+        beneficiary: beneficiary.publicKey,
+        //employeeAccount: employeeAccount, // pda 帐户可自动推导
+        //vestingAccount: vestingAccountKey,
+        //mint,
+        //treasuryTokenAccount: treasuryTokenAccount,
+        //employeeTokenAccount: employeeTokenAccountPda,
         tokenProgram: TOKEN_PROGRAM_ID,
+        //associatedTokenProgram: ASSOCIATED_TOKEN_PROGRAM_ID,
       })
+      .signers([beneficiary])
       .rpc({ commitment: "confirmed" });
-
-    console.log("Claim Tokens transaction signature", tx3);
+    } catch (err) {
+      throw err;
+    }
   });
 });