文章目录
- Solana开发之Anchor框架
- 一、什么是Anchor
- 二、安装和使用
- 1. 安装rust
- 2. 安装Solana
- 下载预构建的二进制文件
- 3. 使用 Anchor 版本管理器 (avm) 进行安装(推荐)
- 四、Anchor 核心原理
- Anchor 程序由三部分组成
- 程序的 ID 从哪里来
- 五、初始化项目、build项目、运行测试用例
- 初始化项目
- build项目
- 测试用例编写
- 用例demo
- 运行测试用例
- 六、本地构建和部署
- 七、使用Anchor与 Solana 区块链进行交互
- 使用场景
- Anchor on the front-end
- 【推荐】如何使用 Kinobi 创建 Anchor 程序客户端
- 参考
Solana开发之Anchor框架
大多数 Rust 开发使用的是 Anchor 框架。Anchor 文档指出,开发人员只需要熟悉 Rust 的基础知识(即 Rust Book 的前九章)。
一、什么是Anchor
官网:https://www.anchor-lang.com/
Anchor 是一个功能强大的框架,旨在快速构建安全的 Solana 程序。它通过减少诸如账户(反)序列化和指令数据等领域的样板文件、进行必要的安全检查、自动生成客户端库以及提供广泛的测试环境来简化开发流程。
Anchor 是 Solana 的 Sealevel 运行时的框架,提供了几种方便的开发人员工具来编写智能合约。
二、安装和使用
1. 安装rust
https://www.rust-lang.org/tools/install
在 Rust 开发环境中,所有工具都安装在 ~/.cargo/bin
目录中,您可以在这里找到包括 rustc
、cargo
和 rustup
在内的 Rust 工具链。
Rust 开发者通常会将该目录加入 PATH
环境变量中。在安装过程中,rustup 会尝试配置 PATH。 由于不同平台、命令行 Shell 之间存在差异,rustup 中也可能存在 Bug,因此在终端重启或用户重新登录之前,rustup 对 PATH 的修改可能不会生效,甚至完全无效。
如果安装后在终端尝试执行 rustc --version
失败,那么,以上内容就是最可能的原因。
2. 安装Solana
https://docs.solanalabs.com/cli/install
linux、macos:
sh -c "$(curl -sSfL https://release.solana.com/v1.18.17/install)"
Windows:
cmd /c "curl https://release.solana.com/v1.18.17/solana-install-init-x86_64-pc-windows-msvc.exe --output C:\solana-install-tmp\solana-install-init.exe --create-dirs"
复制并粘贴以下命令,然后按 Enter 键安装最新版本的 Solana。如果您看到系统弹出安全窗口,请选择允许程序运行。
C:\solana-install-tmp\solana-install-init.exe v1.18.17
通过运行以下命令确认 solana 您已安装所需的版本:
solana --version
After a successful install, solana-install update may be used to easily update the Solana software to a newer version at any time.
安装成功后, solana-install update
可用于随时轻松地将 Solana 软件更新到更新版本。
安装使用稳定版本:
sh -c "$(curl -sSfL https://release.solana.com/stable/install)"
使用官方安装命令安装 Solana CLI 工具套件:您可以 stable 替换为与所需版本的软件版本匹配的版本标记(即 v1.18.1 ),或使用以下三个符号通道名称之一: stable 、 beta 或 edge 。
报错:# solana-test-validator
Aborted (core dumped)
尝试运行 solana-test-validator --log
以查看此类输出。您的错误可能依赖于您没有的 CPU AVX2 指令。
# solana-test-validator --log
[2024-07-09T15:55:05.254090404Z INFO solana_test_validator] solana-validator 1.17.25 (src:d0ed878d; feat:3580551090, client:SolanaLabs)
[2024-07-09T15:55:05.254140535Z INFO solana_test_validator] Starting validator with: ArgsOs {inner: ["solana-test-validator","--log",],}
[2024-07-09T15:55:05.254172296Z WARN solana_perf] CUDA is disabled
[2024-07-09T15:55:05.254196077Z INFO solana_perf] AVX detected
[2024-07-09T15:55:05.254203279Z ERROR solana_perf] Incompatible CPU detected: missing AVX2 support. Please build from source on the target
Aborted (core dumped)
下载预构建的二进制文件
如果您不想使用 solana-install 来管理安装,可以手动下载并安装二进制文件。
通过导航到 https://github.com/solana-labs/solana/releases/latest
下载二进制文件,下载 solana-release-x86_64-unknown-linux-gnu.tar.bz2
tar jxf solana-release-x86_64-unknown-linux-gnu.tar.bz2
cd solana-release/
export PATH=$PWD/bin:$PATH
因为
release.solana.com
不太好访问,这里我直接git上自己下载,解压安装。
3. 使用 Anchor 版本管理器 (avm) 进行安装(推荐)
Anchor 版本管理器是用于使用 anchor-cli 多个版本的工具。它需要与从源代码构建相同的依赖关系。如果已安装 NPM 包,建议您卸载它。
使用 Cargo 安装 avm 。请注意,如果您安装了二进制文件,这将替换您的 anchor 二进制文件。
#sudo apt-get install build-essential
cargo install --git https://github.com/coral-xyz/anchor avm --locked --force
使用 avm 安装最新版本的 CLI,然后将其设置为要使用的版本。
avm install latest
avm use latest
验证安装。
anchor --version
最新的默认是0.30.1,我暂时安装使用用anchor 0.29.0,
avm install 0.29.0
avm use 0.29.0
添加 你的安装到bin中
export PATH=/root/.avm/bin:$PATH
四、Anchor 核心原理
Anchor 程序由三部分组成
Anchor 程序由三部分组成: program
模块、标有 #[derive(Accounts)]
的 Accounts
结构和 declare_id
宏。
declare_id!
宏的作用是在 Rust 代码中声明 Solana 程序的唯一标识符(ID)。
这个 ID 在 Solana 网络中是唯一的,用于标识和定位这个程序。它类似于在以太坊中合约的地址。
启动新的 Anchor 项目时,你将看到以下内容:
// use this import to gain access to common anchor features
use anchor_lang::prelude::*;// declare an id for your program
declare_id!("Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS");// write your business logic here
#[program]
mod hello_anchor {use super::*;pub fn initialize(_ctx: Context<Initialize>) -> Result<()> {Ok(())}
}// validate incoming accounts here
#[derive(Accounts)]
pub struct Initialize {}
-
use anchor_lang::prelude:😗;
这个导入语句引入了 Anchor 框架中常用的特性和类型,例如 Context、Accounts 等。 -
declare_id!("Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS");
这个宏声明了当前 Solana 程序的唯一标识符(ID)。
这个 ID 在 Solana 网络中是唯一的,用于标识和定位这个程序。 -
#[program]
这个属性宏标记了一个 Rust 模块作为 Solana 程序的入口点。 -
mod hello_anchor { … }
这个模块包含了程序的业务逻辑实现。 -
#[derive(Accounts)]
这个属性宏自动为 Initialize 结构体生成一些样板代码,用于验证账户。
这段代码定义了一个基本的 Solana 程序,包含了程序 ID 的声明和一个简单的初始化函数。Anchor 框架通过提供各种宏和结构体,大大简化了 Solana 程序的开发过程,使开发者能够更专注于业务逻辑的实现。
程序的 ID 从哪里来
declare_id!
宏的作用是在 Rust 代码中声明 Solana 程序的唯一标识符(ID)。
这个 ID 在 Solana 网络中是唯一的,用于标识和定位这个程序。它类似于在以太坊中合约的地址。
那么这个 ID 是从哪里来的呢?有几种方式可以获得程序的 ID:
- 手动生成:
你可以手动生成一个 32 字节的随机 Pubkey 作为程序的 ID。这种方式适用于开发和测试阶段。
在示例代码中,“Fg6PaFpoGXkYsidMpWTK6W2BeZ7FEfcYkg476zPFsLnS” 就是一个手动生成的 Pubkey 字符串。
-
使用 Anchor 的 CLI 工具生成:
Anchor 提供了一个命令行工具,可以帮助你在部署程序时自动生成程序 ID。
当你运行anchor build
命令时,Anchor 会为你的程序生成一个唯一的 ID,并将其写入到 Anchor 项目的配置文件中。 -
从 Anchor 项目的配置文件读取:
如果你的 Solana 程序是使用 Anchor 框架开发的,那么在项目的配置文件(如 Cargo.toml 或 anchor.toml)中会有程序 ID 的定义。
你可以直接从这个配置文件中读取程序 ID,并在代码中使用declare_id!
宏进行声明。
程序 ID 的作用都是为了在 Solana 网络中唯一标识你的 Solana 程序。在部署和调用程序时,需要使用这个 ID 来定位和执行程序。
declare_id!
宏设置了程序的公钥。对于本地开发,使用anchor init
命令设置程序将在target/deploy
目录中生成一个密钥对,并填充此宏。
五、初始化项目、build项目、运行测试用例
初始化项目
要初始化一个新项目,只需运行:
anchor init <new-workspace-name>
这将创建一个新的Anchor工作区,以下是文件夹中的一些重要文件:
.anchor
文件夹:它包括最新的程序日志和用于测试的本地账本- 文件夹
app
:一个空文件夹,则可用于保存前端 programs
文件夹:此文件夹包含您的程序。它可以包含多个,但最初只包含与 同名的程序。该程序已包含一个lib.rs
包含一些示例代码的文件。
programs 文件夹下,你将看到一个src
目录。它包含lib.rs
。- 文件夹
tests
:包含 E2E 测试的文件夹。它已经包含一个文件,用于测试 中的示例代码。 programs/ migrations
文件夹:在此文件夹中,可以保存程序的部署和迁移脚本。- 文件
Anchor.toml
:此文件为程序配置工作区范围的设置。- 您的程序在 localnet 上的地址 ( [programs.localnet] )
- 一个注册表,你的程序可以被推送到 ( [registry] )
- 可用于测试的提供程序 ( [provider] )
- Anchor 执行脚本 ( [scripts] )。 test 脚本在运行
anchor test
时运行。您可以使用anchor run <script_name>
运行自己的脚本。
build项目
要编译这个程序,我们可以运行 Anchor build 命令:
anchor build
生成完成后,您应该会看到一个名为 target 的新文件夹。
IDL 位于 target/idl/xxx.json
, IDL 与 Solidity 中的 ABI(或 GraphQL 中的查询定义)非常相似,我们将在 JavaScript 测试和前端以类似的方式使用它们,通过 RPC 与我们的 Solana 程序进行通信。
测试用例编写
使用 Anchor 调用 Solana 程序, 我们通常需要两件主要事情:
- Provider - 是 Provider 与 Solana 网络连接的抽象,通常由 Connection, Wallet, and a preflight commitment组成。
在测试中,Anchor 框架将基于环境 ( anchor.Provider.env()
) 为我们创建提供者,但在客户端上,我们需要使用用户的 Solana 钱包自己构建提供者。
- program - 这是一个 program 抽象,它结合了 Provider 、 idl 和 ( programID 在构建程序时生成),并允许我们针对我们的程序调用 RPC 方法。
同样,与 Provider 一样,Anchor 提供了一种方便的访问方式 program ,但是在构建前端时,我们需要自己构建它 provider 。
一旦我们有了这两样东西,我们就可以开始在程序中调用函数了。例如,在我们的程序中,我们有一个 initialize 函数。在我们的测试中,您将看到我们可以直接使用以下方法 program.rpc.functionName 调用该函数:
const tx = await program.rpc.initialize();
这是一种非常常见的模式,您在使用 Anchor 时会经常使用,一旦您掌握了了解其工作原理的窍门,就可以非常轻松地连接到 Solana 程序并与之交互。
用例demo
测试用例:
- 定义了一个名为 “Test mint” 的测试用例。
- 为一个新的 wallet 账户进行空投,获得 1 SOL。
- 创建一个新的 asset 账户。
- 调用 MyNFT 合约的
mint
指令,传入相关的账户信息。 - 使用
fetchAssetV1
和fetchCollectionV1
获取刚刚创建的资产和集合信息,并打印出来。
实战demo:
import * as anchor from "@coral-xyz/anchor";
import { Program } from "@coral-xyz/anchor";
import { Mynft } from "../target/types/mynft";
import { createUmi } from "@metaplex-foundation/umi-bundle-defaults";
import {defaultPublicKey,generateSigner,signerIdentity,sol,publicKey,
} from "@metaplex-foundation/umi";
import { toWeb3JsKeypair } from "@metaplex-foundation/umi-web3js-adapters";
import {createCollectionV1,fetchAssetV1,fetchCollectionV1,MPL_CORE_PROGRAM_ID,
} from "@metaplex-foundation/mpl-core";const beneficiary = publicKey("4k7LBNMW3J6gMvEZMy77vZar8h3h3a9Moc8F4xxxxx");describe("mynft", () => {// Configure the client to use the local cluster.anchor.setProvider(anchor.AnchorProvider.env());const program = anchor.workspace.Mynft as Program<Mynft>;const umi = createUmi(anchor.AnchorProvider.env().connection);const payer = generateSigner(umi);umi.use(signerIdentity(payer));const collection = generateSigner(umi);const authority = generateSigner(umi);before(async () => {await umi.rpc.airdrop(payer.publicKey, sol(1));createCollectionV1(umi, {collection,name: "Mynft",uri: "http://mynft.org",updateAuthority: authority.publicKey,}).sendAndConfirm(umi);});it("Test mint", async () => {const wallet = generateSigner(umi);await umi.rpc.airdrop(wallet.publicKey, sol(1.0));const asset = generateSigner(umi);const tx = await program.methods.mint().accounts({coreAsset: asset.publicKey,coreCollection: collection.publicKey,authoriy: authority.publicKey,wallet: wallet.publicKey,beneficiary,mplCore: MPL_CORE_PROGRAM_ID,systemProgram: defaultPublicKey(),}).signers([toWeb3JsKeypair(wallet),toWeb3JsKeypair(asset),toWeb3JsKeypair(authority),]).rpc();const assetInfo = await fetchAssetV1(umi, asset.publicKey);console.log(assetInfo);const collectionInfo = await fetchCollectionV1(umi, collection.publicKey);console.log(collectionInfo);});
});
其中: …/target/types/mynft 为anchor build时候根据idl自动为你生成的typescript文件方便您调用合约方法。
在项目根目录下,运行 anchor test
命令。这会执行 tests
目录下所有的测试用例,包括这个 “Test mint” 用例。
如果你只想运行这个特定的测试用例,可以在 anchor test
命令后添加 -f "Test mint"
参数,这样只会运行名为 “Test mint” 的测试用例。
运行测试用例
现在,我们可以通过运行 test 来测试程序:
anchor test
六、本地构建和部署
官方文档:https://solana.com/developers/guides/getstarted/setup-local-development
参考URL: https://guides.quicknode.com/guides/solana-development/getting-started/start-a-solana-local-validator
参考URL: https://dev.to/edge-and-node/the-complete-guide-to-full-stack-solana-development-with-react-anchor-rust-and-phantom-3291
本地开发环境可以为开发人员提供更受控和高效的开发环境。
首先,我们要确保 Solana 工具套件正确配置为本地开发(Local development)。
运行solana config set --url localhost
命令,确保所有配置指向本地主机 URL。
还要确保你有一个本地密钥对(key pair)以与 Solana 进行交互。你必须拥有一个带有 SOL 余额的 Solana 钱包才能使用 Solana CLI 部署程序。
运行solana address
命令检查是否已经有本地密钥对。
如果遇到错误,请运行命令:
solana-keygen new -o /root/.config/solana/id.json
solana config set --keypair /root/.config/solana/id.json
solana config get
将在默认情况下在~/.config/solana/id.json
路径创建一个新的文件系统钱包。它还会提供一个可用于恢复公钥和私钥的恢复短语。建议保存此密钥对,即使它是在本地使用。
还要注意,如果你已经在默认位置保存了文件系统钱包,solana-keygen new
命令将不覆盖它,除非使用**–force**命令指定。
接下来,我们要确保我们的 Anchor.toml 文件正确指向本地主机。
...
[programs.localnet]
hello-world = "EJTW6qsbfya86xeLRQpKLM8qhn11cJXmU35QbJwE11R8"
...
[provider]
cluster = "Localnet"
wallet = '~config/solana/id.json'
配置项目的程序id,如这里的"EJTW6qsbfya86xeLRQpKLM8qhn11cJXmU35QbJwE11R8"
程序 ID 是公开的。但它的密钥对存储在 target/deploy 文件夹中。它遵循基于程序名称的特定命名约定。例如,如果程序名为 hello_world,Anchor 将在 target/deploy/hello-world-keypair.json 中寻找密钥对。
如果在部署过程中找不到该文件,Anchor 将生成一个新的密钥对,这将生成新的程序 ID。
因此,在第一次部署后更新程序 ID 至关重要。hello-world-keypair.json 文件用作程序所有权的证明。如果密钥对泄露,恶意行为者可以对程序进行未经授权的更改。
通过 [provider],我们告诉 Anchor 使用 本地主机 和指定的钱包来支付存储和交易费用。
确保 [provider] 部分的 cluster 参数设置为 “Localnet”。这表示你是在本地运行 Solana 节点进行部署和测试。
Solana CLI 自带一个测试验证器 。运行 solana-test-validator
命令 将在你的工作站上启动一个功能齐全的单节点集群。这对许多原因都很有益,例如没有 RPC 速率限制、没有空投限制、直接在链上部署程序、从文件加载账户以及从公共集群克隆账户。测试验证器必须在单独的打开的终端窗口中运行,并保持运行,以使本地主机集群保持在线并可供交互。
在启动 solana-test-validator 时,你可以使用参数来指定 RPC 服务监听的 IP 地址。
例如,如果你想让 RPC 服务监听在 0.0.0.0 上,而不是默认的 127.0.0.1,可以使用以下命令:
solana-test-validator --bind-address 0.0.0.0 --rpc-port 8899
现在,我们可以成功运行 anchor deploy
来将程序部署到我们的本地ledger。传输到本地 ledger 的任何数据都将保存在当前工作目录中生成的 test-ledger 文件夹中。建议将此文件夹添加到你的 .gitignore 文件中,以避免将此文件夹提交到你的存储库中。此外,退出本地 ledger(即在终端中按下 Ctrl + C)不会删除发送到集群的任何数据。您可以
solana-test-validator --reset
这将清空本地数据目录并重新初始化节点。
Solana Explorer
开发者还可以将 Solana Explorer 配置为他们的本地ledger。转到 Solana Explorer。在导航栏中,单击当前集群状态的绿色按钮:
这将打开一个侧边栏,允许你选择一个集群。单击 Custom RPC URL。这应该自动填充为 http://localhost:8899 。如果没有,请填写,以便将区块浏览器指向你的机器的 8899 端口:
配置本地区块链浏览器有几个非常重要原因:
- 它允许开发者实时检查本地ledger上的交易,就像他们通常在分析 devnet 或 mainnet 的区块浏览器上所具有的功能
- 更容易可视化账户、代币和程序的状态,就像它们在实时集群上运行一样
- 它提供了有关错误和交易失败的详细信息
- 它提供了一致的开发体验,因为它是一个熟悉的界面
solana balance
solana address
solana airdrop 100
从你提供的 solana config get
输出结果来看,你的 Solana 客户端配置指向的是 Solana 主网,而不是本地测试网。
使用 solana config set --url http://localhost:8899
命令将 RPC URL 设置为本地测试节点的地址。
使用 solana config get
命令再次检查配置,确认 RPC URL 已经正确设置。
netstat -an |findstr 8899
TCP 127.0.0.1:54115 127.0.0.1:8899 TIME_WAIT
七、使用Anchor与 Solana 区块链进行交互
使用场景
在 Node.js 环境下使用 Anchor 来与 Solana 区块链进行交互是非常常见的场景。
-
测试环境
在开发和测试阶段,你可以使用 anchor.setProvider(anchor.AnchorProvider.env()) 来连接到本地的 Solana 开发集群。这样可以快速进行开发和测试。 -
生产环境
当你准备将应用部署到生产环境时,你可以配置 Anchor 客户端连接到 Solana 主网。
如果你的项目中涉及到通过 IDL 和合约进行交互,我建议你优先考虑使用 Anchor,它可以为你提供更加完整和高效的开发体验。
Anchor on the front-end
官方ts文档:https://coral-xyz.github.io/anchor/ts/index.html
参考原文链接:https://creatorsdao.github.io/solana-co-learn/Solana-Co-Learn/module5/anchor-on-the-front-end/anchor-into-typescript/
Program 对象提供了一个自定义的 API,通过结合程序 IDL 和 Provider 来与特定程序进行交互。
创建 Program 对象,我们需要以下内容:
- Connection - 集群连接
- Wallet - 用于支付和签署交易的默认密钥对
- Provider - 将 Connection 和 Wallet 封装到一个 Solana 集群中
- IDL - 表示程序结构的文件
Provider 对象代表了两个主要部分的结合:
- Connection - 连接到 Solana 集群(例如 localhost、devnet、mainnet)
- Wallet - 用于支付和签署交易的指定地址
Provider 就能够代表 Wallet 向 Solana 区块链发送交易,并在发送的交易中加入钱包的签名。
创建一个 Program 对象,代表了以下两个事物的组合:
- IDL:展示了程序的结构。
- Provider:负责与集群建立连接并签署 Wallet 的 Connection。
你需要导入程序的 IDL,并明确指定programId,这个programId通常会包含在IDL中,当然也可以单独声明。
【推荐】如何使用 Kinobi 创建 Anchor 程序客户端
原文链接: https://learnblockchain.cn/article/8639
为测试验证,暂时不需要。
参考
[推荐]指南:用 Anchor 构建 Solana 程序
参考URL: https://learnblockchain.cn/article/7386