使用 createAction() 创建你的第一笔 BSV 交易：入门指南

一句话理解

createAction() 是通过钱包创建一笔交易动作的高级接口：你告诉钱包要创建哪些 inputs 和 outputs，钱包帮你补齐签名、费用、找零和处理流程。

它是新手写第一笔 BSV 交易时最重要的方法，因为它把“交易构造”包装成一个应用动作。

什么是 action

在 SDK 的语境里，action 可以理解为一次有意义的钱包操作。它不只是“转账”，也可以是发布数据、创建某个可花费输出、花掉一个已有输出、为应用协议写入状态。

也就是说，应用不是直接对钱包说：“请给我一串私钥签名后的原始交易字节。”而是说：“我要创建一个动作：描述是这个，输出是这些，需要花掉这些输入，处理选项是这些。”钱包再根据这些信息创建交易。

createAction 的核心参数

官方钱包参考中，createAction() 接收 CreateActionArgs。核心字段可以简化理解为：

TypeScript

2 description: string

3 inputBEEF?: string

4 inputs?: Array<...>

5 outputs?: Array<...>

6 lockTime?: number

7 version?: number

8 labels?: string[]

9 options?: {

10 signAndProcess?: boolean

11 acceptDelayedBroadcast?: boolean

12 returnTXIDOnly?: boolean

13 noSend?: boolean

14 sendWith?: string[]

15 randomizeOutputs?: boolean

16 }

17}

入门阶段最常用的是 description 和 outputs。

description：给用户和钱包看的操作说明。不要写成无意义的字符串，真实应用应该让用户知道这次操作大概在做什么。
outputs：描述这笔交易要创建的新输出。每个 output 通常包括金额、locking script 和输出说明。
inputs：用于指定要花掉哪些已有输出。第一笔简单交易通常可以先不手动指定 inputs，由钱包自动选择。
options：控制是否签名和处理、是否只返回 txid、是否不广播等行为。新手阶段不要随意修改，先理解默认流程。

创建 OP_RETURN 数据输出

官方第一笔交易教程用 Script.fromASM() 构造一个 OP_RETURN 数据输出，示例思路如下。

TypeScript

1import { WalletClient, Script } from '@bsv/sdk'

3async function createSimpleTransaction() {

4 const wallet = new WalletClient('auto', 'localhost')

6 const response = await wallet.createAction({

7 description: 'My first BSV transaction',

8 outputs: [{

9 satoshis: 100,

10 lockingScript: Script

11 .fromASM(`OP_RETURN ${Buffer.from('Hello BSV!').toString('hex')}`)

12 .toHex(),

13 outputDescription: 'My first data output'

14 }]

15 })

17 console.log(response)

18 return response

19}

21createSimpleTransaction().catch(console.error)

这段代码里有几个关键点：

WalletClient 负责连接钱包。
Script.fromASM() 把可读的 ASM 脚本转成 SDK 能使用的脚本对象。
Buffer.from('Hello BSV!').toString('hex') 把文本编码成十六进制数据。
lockingScript 是输出上的脚本。这里使用 OP_RETURN，表示这是数据输出，而不是普通收款地址输出。
createAction() 返回的结果里可能包含 txid，也可能包含更多交易处理信息，取决于钱包和选项。

createAction 帮你做了什么

如果你没有手动指定 inputs，钱包会尝试从可用 UTXO 中选择足够的输入。
如果目标输出金额加手续费小于输入总额，钱包会创建找零输出。
如果需要签名，钱包会用自己的密钥管理体系完成签名，而不是把私钥交给应用。
如果默认处理流程包含广播，钱包或相关服务会尝试把交易送入网络。
如果处理失败，应用需要读取错误或状态，而不是假设调用成功就等于交易已经被矿工接受。

在 BSV 技术栈里的位置

BSV 应用中的很多用户操作都可以抽象为 action。

发布一条内容，可以是一个数据输出。
创建一张凭证，可以是带协议字段和签名的数据输出。
转移某个 token，可以是花掉旧 token UTXO，再创建新 token UTXO。
更新业务状态，可以是一笔记录新状态的交易。

createAction() 的价值是让应用用同一种接口描述这些动作。底层仍然是交易，但上层可以更接近业务语言。

什么时候不该只依赖 createAction

createAction() 很适合第一笔交易和许多钱包驱动的应用场景，但它不是学习的终点。

如果你要理解签名哈希、手动手续费、复杂输入输出、交易链、批量交易或低层广播，就需要进入第 8 阶段，学习手动构造交易。
如果你要做协议级工具、钱包后端或交易处理服务，也不能只停留在高级接口。

正确顺序是：先用 createAction() 跑通真实交易，再回头拆开每一层。

新手常见误解

createAction() 不是“写数据库”。它创建的是比特币交易动作，交易能否被接受还取决于网络和矿工策略。
outputs 不是随便填的数组。每个 output 的 locking script 决定它未来能否被花费，或它是不是数据输出。
description 不是装饰字段。真实钱包会用它帮助用户理解授权内容。
自动签名不等于无授权。钱包可以要求用户确认，也可以根据权限策略拒绝操作。
返回 txid 不等于你已经完成应用状态管理。应用还要考虑广播状态、确认、索引和后续查询。

参考来源

First Transaction tutorial: https://bsv-blockchain.github.io/ts-sdk/tutorials/first-transaction/
Wallet reference: https://bsv-blockchain.github.io/ts-sdk/reference/wallet/
Wallet Integration concept: https://bsv-blockchain.github.io/ts-sdk/concepts/wallet-integration/