SPI(Satoshi Payment Interface)是一个简单的余额查询/回收协议。SDK 固定使用
RFC 8949 deterministic CBOR,第三方服务只需要实现余额 Backend;金额在 Go 中是
uint64,在 TypeScript 中是 bigint。
当前仓库交付范围包括 SPI Wire、HTTP V0.1 签名外壳和固定 /spi/1.0.0 的正常
libp2p Stream 适配。/home/david/Workspaces/bitcoin-libp2p 负责通用 secp256k1 身份、
Noise、Yamux 和 transport,SPI 业务适配器由本仓库负责。
身份与业务分层:
- SPI payload 只包含业务字段,不携带公钥、签名、
session_id或过期时间。 - HTTP/HTTPS 使用
AuthenticatedEnvelope做每个 payload 的 secp256k1 签名和完整性保护。 - libp2p 连接身份由外部
bitcoin-libp2pNoise 已认证连接提供,本仓库的libp2padapter/只从该连接取得公钥并调用统一 SPI handler。 - HTTP 外壳不提供保密性,公网必须使用 HTTPS。
libp2p 的业务协议名固定为 /spi/1.0.0。具体 transport 由 bitcoin-libp2p 注入,
SPI 适配器只处理已认证连接上的业务 Stream。
目录:
protocol/:版本、Kind、named type 和稳定错误码。wire/:四种 SPI Wire 的严格编解码。wallet/:请求创建和响应 request_id 绑定。service/:统一服务入口、Backend 契约和测试内存实现。currency/:固定 network 注册及 BSV/BTC P2PKH 地址验证。httpauth/:HTTP AuthenticatedEnvelope、strict DER、low-S 和公钥 pin。libp2padapter/:Go/spi/1.0.0server/client Stream 适配器。typescript/:同义的satoshi-payment-interfaceESM/声明文件 SDK。
发布 / Release 0.1.0:
# Go
go get github.com/bsv8/SPI@v0.1.0
# TypeScript / npm
npm install satoshi-payment-interface@0.1.0Satoshi Payment Interface (SPI) 0.1.0 provides matching Go and TypeScript SDKs.
The npm registry does not allow spaces in package names, so the standalone package
uses the npm-compatible name satoshi-payment-interface while retaining the full
product name in documentation.
Go:
requestID, payload, err := wallet.NewInformationRequest()
response, err := wallet.ParseResponse(responsePayload, requestID)TypeScript:
const request = newInformationRequest()
const response = parseResponse(responsePayload, request.requestId)libp2p 适配器使用外部 bitcoin-libp2p 创建的已认证 Host/Connection:
server, err := libp2padapter.NewServer(h, backend, libp2padapter.Options{})
client, err := libp2padapter.NewClient(h, libp2padapter.Options{})
requestID, requestWire, err := wallet.NewInformationRequest()
responseWire, err := client.Call(ctx, remotePeerID, requestWire)
response, err := wallet.ParseResponse(responseWire, requestID)const server = await registerServer(node, backend)
const responseWire = await createClient().call(connection, request.wire)服务端从 Noise authenticated connection 取得 remote_public_key,执行
handleRequest 后返回响应;客户端在同一协议上发送一次请求并读取一次响应。
CDDL 负责 Wire/Envelope 的结构和 .cbor 子文档绑定;消息长度、数量和安全边界由
Go/TypeScript 共享常量及单元测试执行。CDDL 是协议说明,不替代运行时输入校验。
HTTP 请求/响应必须先由 httpauth.ParseAndVerify 验证;验证服务响应时传入预期服务
公钥。testdata/v1/ 是 Go 和 TypeScript 共用的固定向量,测试私钥明确为 TEST-ONLY。
验证:
go test ./...
cd typescript && npm test
cd .. && ./scripts/test-integration.sh