Documentation
¶
Overview ¶
Package protocol 是仓库唯一的共享基础层：强类型值、显式外部事实 Facts、 受约束 Signer 端口、typed ID、固定签名域与统一错误模型。它不依赖任何 领域包或角色包，也不做存储、网络、时钟或节点副作用。
Index ¶
- Constants
- Variables
- func IsCode(err error, code ErrorCode) bool
- func ParseCompressedPubKey(raw []byte) (*ec.PublicKey, error)
- func SignWireDocument(ctx context.Context, signer Signer, wireVersion, wireKind uint64, ...) ([]byte, error)
- func ValidateCompressedPubKey(raw []byte) error
- func ValidatePublicKey(key PublicKey) error
- func VerifyDigestSignature(publicKey PublicKey, digest Digest32, signature []byte) error
- func VerifyMessageSignature(publicKey, payload, signature []byte) error
- func VerifyWireDocument(publicKey []byte, wireVersion, wireKind uint64, documentCBOR, signature []byte) error
- func WireSignatureInput(wireVersion, wireKind uint64, documentCBOR []byte) ([]byte, error)
- func Wrap(err error, op string, code ErrorCode, kind uint16, field string) error
- func WrapClassified(err error, op string, kind uint16, field string) error
- type ArbitrationClaimID
- type BlockHeight
- type ContentPayloadsID
- type ContentRetrievalRequestID
- type Digest32
- type Error
- type ErrorCode
- type Facts
- func (f Facts) CheckRefundMatured(lockTime RefundLockTime) error
- func (f Facts) CheckRefundNotExpired(lockTime RefundLockTime) error
- func (f Facts) ClassifyRefundGate(lockTime RefundLockTime) (matured bool, err error)
- func (f Facts) RefundMatured(lockTime RefundLockTime) (bool, error)
- func (f Facts) RequireBlockHeight() (BlockHeight, error)
- func (f Facts) RequireNow() (time.Time, error)
- type FileQuoteTermsID
- type Hash32
- type PaymentAuthorizationID
- type PaymentSequence
- type PrivateKeySigner
- type PublicKey
- type RefundLockTime
- type RetrievalNonce
- type Satoshis
- type SatoshisPerKilobyte
- type Signer
- type SigningPurpose
- type SigningRequest
Constants ¶
const ProtocolFamily = "bitfs.protocol.v1"
ProtocolFamily 是外部协议族/manifest 标识字符串：wire 报文本身不携带族 名称，版本真值仍只有 WireVersion。仓库内其他位置的族名称一律引用本常量。
const RefundTimestampThreshold = refundlock.TimestampThreshold
RefundTimestampThreshold 引用内部包的唯一定界常量，避免第二份真值。
const WireSignatureDomain = "bitfs/wire-signature"
WireSignatureDomain 是统一普通消息签名上下文的固定域分隔字符串。
const WireVersion uint64 = 1
WireVersion 是 BitFS 对外暴露的唯一协议版本。所有完整 wire 报文都以 [WireVersion, wire_kind, ...] 开头；认证子文档不再重复携带版本与 Kind。 任何改变 wire shape、签名对象、ID 算法、交易重建或验收语义的修改都必须 提升该值；依赖库修复且协议可观察结果完全不变时不提升。
Variables ¶
var ( // ErrValueLength 标记字节宽度不等于类型固定宽度的输入。 ErrValueLength = errors.New("value length does not match the fixed width") // ErrZeroValue 标记进入编码、存储或网络路径的全零哨兵值。 ErrZeroValue = errors.New("all-zero value is rejected") // ErrNilInput 标记公开 API 收到 nil 指针或 nil 切片。 ErrNilInput = errors.New("required input is nil") )
var ErrFactsMissing = errors.New("required explicit facts are missing or zero")
ErrFactsMissing 标记当前操作所需的显式事实缺失（零值时间或零高度）。
var ErrHighSSignature = errors.New("high-S signature is rejected; only low-S DER is canonical")
ErrHighSSignature 标记一个 S > N/2 的可延展（high-S）签名。协议只接受 low-S DER：low-S 消除 ECDSA 的对称 high-S 可延展形式，但不承诺不同签名 调用产生逐字节相同的 DER——不同 nonce 仍可给出多份合法 low-S 签名。 exact Artifact 的幂等依赖"首次成功后持久化并原样重放"，而不是签名复现。
ErrSignerUnavailable 表示 Signer 托管方（HSM/KMS/远程服务）暂时无法完成 本次密钥操作。SDK 不做本地降级；应用按自身策略对同一 prepared 输入重试。
var ErrZeroIdentifier = errors.New("all-zero identifier is rejected")
ErrZeroIdentifier 标记进入编码、存储或网络路径的全零哨兵 ID。
Functions ¶
func IsCode ¶
IsCode 报告错误链的最外层稳定分类是否等于 code：errors.As 只命中链上 第一个（最外层）*Error，本函数不继续向内层搜索，不要误读为全链扫描。 调用方按稳定 Code 分支用它或 CodeOf；包装层一律经 WrapClassified 保留 底层分类，因此最外层判断即等价于业务语义。
func ParseCompressedPubKey ¶
ParseCompressedPubKey 解析一个协议身份密钥字节并返回底层 EC 公钥（SDK 引擎内部使用）。Protocol identity fields carry only the canonical 33-byte compressed secp256k1 form; accepting an equivalent uncompressed encoding would change signed wire bytes.
func SignWireDocument ¶
func SignWireDocument(ctx context.Context, signer Signer, wireVersion, wireKind uint64, documentCBOR []byte) ([]byte, error)
SignWireDocument 用受约束 Signer 签署普通 wire 报文：SDK 固定构造 WireSignatureDigest(1, kind, exact document)，Signer 只对该摘要执行密钥 操作；签名返回后 SDK 用 Signer 固定公钥立即自验（DER、low-S、验签）， 失败即拒绝。ctx 只用于取消远程签名；私钥/托管细节绝不进入 CBOR、报文、 日志或持久化结构。
func ValidateCompressedPubKey ¶
ValidateCompressedPubKey validates a protocol identity public key and rejects non-canonical or uncompressed representations.
func ValidatePublicKey ¶
ValidatePublicKey 校验强类型公钥输入：nil 切片、错误长度与全零哨兵都拒绝。
func VerifyDigestSignature ¶
VerifyDigestSignature 是协议固定的摘要级验证入口：直接对 SDK 已构造的 32 字节摘要解析 DER、强制 low-S 并做 ECDSA 验证。交易签名自验与 Signer 返回值检查都使用它；调用方不能替换验证器。
func VerifyMessageSignature ¶
VerifyMessageSignature 是协议固定的普通消息签名验证入口：对 payload 做一次 SHA-256，解析 DER，强制 low-S，再做 ECDSA 验证。所有跨包验证路径都必须经 过本函数或 VerifyWireDocument，禁止绕过 low-S 检查。
func VerifyWireDocument ¶
func VerifyWireDocument(publicKey []byte, wireVersion, wireKind uint64, documentCBOR, signature []byte) error
VerifyWireDocument 验证普通 wire 报文签名：用相同外层版本、Kind 与 exact 认证文档重建唯一 WireSignatureInput，做一次 SHA-256 后走统一 low-S 验签。
func WireSignatureInput ¶
WireSignatureInput 把外层版本、wire Kind 与 exact 认证文档打包成唯一的 普通消息签名预映像：
deterministic-CBOR(["bitfs/wire-signature", wire_version, wire_kind, document_cbor])
结果不是 wire 字段，也不持久化为第二份业务文档；它只把外层上下文和 exact document_cbor 作为一个整体纳入签名输入，绝不解码并重新编码业务字段。 documentCBOR 必须是已经过对应 Kind 严格 decoder 验证的 exact 字节。
func WrapClassified ¶
WrapClassified 是"保分类"包装：错误链上已有稳定分类（CodeOf 命中）时原样 透传该分类，绝不覆盖；链上没有任何分类时才落到 CodeInvalidEvidence。
它专用于包装可能携带多种分类的底层门禁结果（如退款门禁会返回 expired/ not_matured/invalid_evidence）：调用方只补充 Op/Kind/Field 上下文，不得把 "事实缺失（invalid_evidence）"误报成"expired/not_matured"这类协议状态结论， 否则应用按稳定 Code 分支时会得到错误的语义。需要附加消息时必须用 %w 保持 错误链（errors.Is(ErrFactsMissing) 等哨兵判断不能断）。
Types ¶
type ArbitrationClaimID ¶
type ArbitrationClaimID [32]byte
ArbitrationClaimID = SHA-256(exact arbitration_claim_cbor)，Kind 8 文档 ID， 同时路由 Kind 9 回执与 Kind 10 取件请求。
func NewArbitrationClaimID ¶
func NewArbitrationClaimID(raw []byte) (ArbitrationClaimID, error)
NewArbitrationClaimID 从精确 32 字节构造 ID；拒绝其他长度与全零哨兵。
func ParseArbitrationClaimID ¶
func ParseArbitrationClaimID(text string) (ArbitrationClaimID, error)
ParseArbitrationClaimID 解析带 ac_ 前缀的文本 ID。
func (ArbitrationClaimID) Bytes ¶
func (id ArbitrationClaimID) Bytes() []byte
Bytes 返回内部字节的副本；调用方修改副本不会影响本 ID。
func (ArbitrationClaimID) IsZero ¶
func (id ArbitrationClaimID) IsZero() bool
IsZero 报告该 ID 是否为全零哨兵；哨兵绝不允许上线。
func (ArbitrationClaimID) MarshalText ¶
func (id ArbitrationClaimID) MarshalText() ([]byte, error)
MarshalText 实现 encoding.TextMarshaler：输出带 ac_ 前缀的小写 hex。
func (ArbitrationClaimID) String ¶
func (id ArbitrationClaimID) String() string
String 返回带稳定类型前缀 ac_ 的小写 hex 文本；仅用于 SDK/存储/日志层。
func (*ArbitrationClaimID) UnmarshalText ¶
func (id *ArbitrationClaimID) UnmarshalText(text []byte) error
UnmarshalText 实现 encoding.TextMarshaler 的解码侧：只接受 ac_ 前缀。
type BlockHeight ¶
type BlockHeight uint32
BlockHeight 是调用方作为显式事实传入的区块高度；0 表示"未提供"， 需要高度判断的操作必须拒绝零值。
type ContentPayloadsID ¶
type ContentPayloadsID [32]byte
ContentPayloadsID = SHA-256(exact content_payloads_cbor)，Kind 11 available 分支绑定的 payload 集合 ID。它不替代 payment authorization 中逐块的 content hashes。
func NewContentPayloadsID ¶
func NewContentPayloadsID(raw []byte) (ContentPayloadsID, error)
NewContentPayloadsID 从精确 32 字节构造 ID；拒绝其他长度与全零哨兵。
func ParseContentPayloadsID ¶
func ParseContentPayloadsID(text string) (ContentPayloadsID, error)
ParseContentPayloadsID 解析带 cp_ 前缀的文本 ID。
func (ContentPayloadsID) Bytes ¶
func (id ContentPayloadsID) Bytes() []byte
Bytes 返回内部字节的副本；调用方修改副本不会影响本 ID。
func (ContentPayloadsID) IsZero ¶
func (id ContentPayloadsID) IsZero() bool
IsZero 报告该 ID 是否为全零哨兵；哨兵绝不允许上线。
func (ContentPayloadsID) MarshalText ¶
func (id ContentPayloadsID) MarshalText() ([]byte, error)
MarshalText 实现 encoding.TextMarshaler：输出带 cp_ 前缀的小写 hex。
func (ContentPayloadsID) String ¶
func (id ContentPayloadsID) String() string
String 返回带稳定类型前缀 cp_ 的小写 hex 文本；仅用于 SDK/存储/日志层。
func (*ContentPayloadsID) UnmarshalText ¶
func (id *ContentPayloadsID) UnmarshalText(text []byte) error
UnmarshalText 实现 encoding.TextMarshaler 的解码侧：只接受 cp_ 前缀。
type ContentRetrievalRequestID ¶
type ContentRetrievalRequestID [32]byte
ContentRetrievalRequestID = SHA-256(exact content_retrieval_request_cbor)， Kind 10 文档 ID，绑定 Kind 11 的两种分支响应。
func NewContentRetrievalRequestID ¶
func NewContentRetrievalRequestID(raw []byte) (ContentRetrievalRequestID, error)
NewContentRetrievalRequestID 从精确 32 字节构造 ID；拒绝其他长度与全零哨兵。
func ParseContentRetrievalRequestID ¶
func ParseContentRetrievalRequestID(text string) (ContentRetrievalRequestID, error)
ParseContentRetrievalRequestID 解析带 cr_ 前缀的文本 ID。
func (ContentRetrievalRequestID) Bytes ¶
func (id ContentRetrievalRequestID) Bytes() []byte
Bytes 返回内部字节的副本；调用方修改副本不会影响本 ID。
func (ContentRetrievalRequestID) IsZero ¶
func (id ContentRetrievalRequestID) IsZero() bool
IsZero 报告该 ID 是否为全零哨兵；哨兵绝不允许上线。
func (ContentRetrievalRequestID) MarshalText ¶
func (id ContentRetrievalRequestID) MarshalText() ([]byte, error)
MarshalText 实现 encoding.TextMarshaler：输出带 cr_ 前缀的小写 hex。
func (ContentRetrievalRequestID) String ¶
func (id ContentRetrievalRequestID) String() string
String 返回带稳定类型前缀 cr_ 的小写 hex 文本；仅用于 SDK/存储/日志层。
func (*ContentRetrievalRequestID) UnmarshalText ¶
func (id *ContentRetrievalRequestID) UnmarshalText(text []byte) error
UnmarshalText 实现 encoding.TextMarshaler 的解码侧：只接受 cr_ 前缀。
type Digest32 ¶
type Digest32 [32]byte
Digest32 是 SDK 构造好的 32 字节签名摘要：普通消息为 SHA-256(exact WireSignatureInput)，交易签名为固定 sighash digest。Signer 只接触本值。
func NewDigest32 ¶
NewDigest32 从精确 32 字节构造 Digest32；拒绝其他长度与全零哨兵。
func WireSignatureDigest ¶
WireSignatureDigest 构造普通消息签名的唯一 32 字节摘要： SHA-256(WireSignatureInput(wireVersion, wireKind, documentCBOR))。 SDK 是 digest 的唯一构造者；Signer 只接触本返回值。
type Error ¶
type Error struct {
// Op 是产生错误的 SDK 操作名（如 "buyer.AcceptQuote"），仅用于开发诊断。
Op string
// Code 是稳定错误分类；应用分支只看它。
Code ErrorCode
// Kind 是相关的 wire Kind（1..11）；无关联时为 0。
Kind uint16
// Field 是安全的相关字段/子文档路径名；可为空。
Field string
// Cause 是底层原因；可为 nil。errors.Is 穿透本链。
Cause error
}
Error 是全仓统一的结构化错误：Op 描述操作路径，Code 用于稳定分支， Kind 标注相关 wire Kind（0 表示无），Field 只携带安全的字段路径名， Cause 保留底层原因供 errors.Is/As 追溯。错误字段绝不回显私钥、完整 payload、签名 preimage、raw transaction 或多租户存在性信息。
type ErrorCode ¶
type ErrorCode string
ErrorCode 是仓库唯一稳定的错误分类。应用只能依据 Code/类型做分支， 绝不能匹配错误文本（英文或中文）。
const ( // CodeMalformedWire 表示报文结构、数组形状或字段宽度畸形。 CodeMalformedWire ErrorCode = "malformed_wire" // CodeNonCanonical 表示结构合法但编码不是 deterministic CBOR。 CodeNonCanonical ErrorCode = "non_canonical" // CodeUnsupportedVersion 表示 wire version 不是 1。 CodeUnsupportedVersion ErrorCode = "unsupported_version" // CodeUnsupportedKind 表示 Kind 不在 1..11 或与路由声明不一致。 CodeUnsupportedKind ErrorCode = "unsupported_kind" // CodeInvalidSignature 表示普通消息签名或交易签名验证失败（含 // 畸形 DER、high-S、空签名、公钥不匹配）。 CodeInvalidSignature ErrorCode = "invalid_signature" // CodeInvalidEvidence 表示密码学/证据链/业务约束拒绝：哈希不匹配、 // 池绑定失败、金额守恒破坏等。 CodeInvalidEvidence ErrorCode = "invalid_evidence" CodeUnauthorized ErrorCode = "unauthorized" // CodeExpired 表示报价过期、交付截止已过或退款锁定已到期。 CodeExpired ErrorCode = "expired" // CodeNotMatured 表示退款锁定尚未到期（正向操作被拒）。 CodeNotMatured ErrorCode = "not_matured" // CodeStateConflict 表示序号陈旧、checkpoint 与证据错配等本地状态冲突。 CodeStateConflict ErrorCode = "state_conflict" // CodeInsufficientBalance 表示付款超出资金池余额或容量。 CodeInsufficientBalance ErrorCode = "insufficient_balance" // CodeCanceled 表示调用方 context 取消或超时。 CodeCanceled ErrorCode = "canceled" CodeSignerUnavailable ErrorCode = "signer_unavailable" )
type Facts ¶
type Facts struct {
// Now 是本操作唯一使用的时间事实（UTC）；时间无关操作不读取它。
Now time.Time
// BlockHeight 是本操作唯一使用的高度事实；仅当退款锁定为区块高时读取。
BlockHeight BlockHeight
}
Facts 是调用方作为显式外部事实传入的观测值：影响协议过期、deadline 与 refund lock 判断的时间，以及区块高度。SDK 不读取系统时钟，也不查询节点； 应用负责同时读取并记录 Now/BlockHeight 的来源与观测时刻。
SDK 只校验当前操作实际需要的字段：仅验证 Quote 的操作不应强迫应用查询 区块高度；height 锁定的退款判断只要求 BlockHeight，timestamp 锁定只要求 Now。需要哪个事实由当前操作的协议分支决定。
func (Facts) CheckRefundMatured ¶
func (f Facts) CheckRefundMatured(lockTime RefundLockTime) error
CheckRefundMatured 是成熟门禁：refund 尚未到期时返回 CodeNotMatured； 已到期返回 nil（可执行退款）；事实缺失时返回 invalid_evidence。
func (Facts) CheckRefundNotExpired ¶
func (f Facts) CheckRefundNotExpired(lockTime RefundLockTime) error
CheckRefundNotExpired 是正向操作门禁：refund 已到期时返回 CodeExpired， 未到期返回 nil；事实缺失时返回 invalid_evidence。只读取锁定类型对应的 那一份事实。
func (Facts) ClassifyRefundGate ¶
func (f Facts) ClassifyRefundGate(lockTime RefundLockTime) (matured bool, err error)
ClassifyRefundGate 把 RefundMatured 的错误归类为稳定的门禁分类：
- 事实缺失（ErrFactsMissing）→ invalid_evidence（应用没有提供本操作所需 的显式事实，属于输入问题而不是协议状态问题）；
- 其余错误原样透传。
成功时 matured 指示锁定是否已到期，由调用方映射为 expired/not_matured。
func (Facts) RefundMatured ¶
func (f Facts) RefundMatured(lockTime RefundLockTime) (bool, error)
RefundMatured 按锁定的实际类型只读取需要的那一份事实：height 锁定与 f.BlockHeight 比较，timestamp 锁定与 f.Now 比较。matured 为 true 表示 锁定已到期可执行退款。
func (Facts) RequireBlockHeight ¶
func (f Facts) RequireBlockHeight() (BlockHeight, error)
RequireBlockHeight 返回高度事实；零值直接拒绝，绝不猜测高度。
type FileQuoteTermsID ¶
type FileQuoteTermsID [32]byte
FileQuoteTermsID = SHA-256(exact file_quote_terms_cbor)，Kind 1 文档 ID。
func NewFileQuoteTermsID ¶
func NewFileQuoteTermsID(raw []byte) (FileQuoteTermsID, error)
NewFileQuoteTermsID 从精确 32 字节构造 ID；拒绝其他长度与全零哨兵。
func ParseFileQuoteTermsID ¶
func ParseFileQuoteTermsID(text string) (FileQuoteTermsID, error)
ParseFileQuoteTermsID 解析带 fq_ 前缀的文本 ID。
func (FileQuoteTermsID) Bytes ¶
func (id FileQuoteTermsID) Bytes() []byte
Bytes 返回内部字节的副本；调用方修改副本不会影响本 ID。
func (FileQuoteTermsID) IsZero ¶
func (id FileQuoteTermsID) IsZero() bool
IsZero 报告该 ID 是否为全零哨兵；哨兵绝不允许上线。
func (FileQuoteTermsID) MarshalText ¶
func (id FileQuoteTermsID) MarshalText() ([]byte, error)
MarshalText 实现 encoding.TextMarshaler：输出带 fq_ 前缀的小写 hex。
func (FileQuoteTermsID) String ¶
func (id FileQuoteTermsID) String() string
String 返回带稳定类型前缀 fq_ 的小写 hex 文本；仅用于 SDK/存储/日志层。
func (*FileQuoteTermsID) UnmarshalText ¶
func (id *FileQuoteTermsID) UnmarshalText(text []byte) error
UnmarshalText 实现 encoding.TextMarshaler 的解码侧：只接受 fq_ 前缀的 64 位小写/大写 hex，全零哨兵拒绝。
type Hash32 ¶
type Hash32 [32]byte
Hash32 是固定 32 字节的通用哈希值（例如资金交易 TxID）。
type PaymentAuthorizationID ¶
type PaymentAuthorizationID [32]byte
PaymentAuthorizationID = SHA-256(exact payment_authorization_cbor)，Kind 5 文档 ID，也是 Kind 6/7 的内容寻址键。
func NewPaymentAuthorizationID ¶
func NewPaymentAuthorizationID(raw []byte) (PaymentAuthorizationID, error)
NewPaymentAuthorizationID 从精确 32 字节构造 ID；拒绝其他长度与全零哨兵。
func ParsePaymentAuthorizationID ¶
func ParsePaymentAuthorizationID(text string) (PaymentAuthorizationID, error)
ParsePaymentAuthorizationID 解析带 pa_ 前缀的文本 ID。
func (PaymentAuthorizationID) Bytes ¶
func (id PaymentAuthorizationID) Bytes() []byte
Bytes 返回内部字节的副本；调用方修改副本不会影响本 ID。
func (PaymentAuthorizationID) IsZero ¶
func (id PaymentAuthorizationID) IsZero() bool
IsZero 报告该 ID 是否为全零哨兵；哨兵绝不允许上线。
func (PaymentAuthorizationID) MarshalText ¶
func (id PaymentAuthorizationID) MarshalText() ([]byte, error)
MarshalText 实现 encoding.TextMarshaler：输出带 pa_ 前缀的小写 hex。
func (PaymentAuthorizationID) String ¶
func (id PaymentAuthorizationID) String() string
String 返回带稳定类型前缀 pa_ 的小写 hex 文本；仅用于 SDK/存储/日志层。
func (*PaymentAuthorizationID) UnmarshalText ¶
func (id *PaymentAuthorizationID) UnmarshalText(text []byte) error
UnmarshalText 实现 encoding.TextMarshaler 的解码侧：只接受 pa_ 前缀。
type PaymentSequence ¶
type PaymentSequence uint32
PaymentSequence 是资金池付款状态链上的序号（1..4294967294）； 4294967295 保留给最终关闭。
type PrivateKeySigner ¶
type PrivateKeySigner struct {
// contains filtered or unexported fields
}
PrivateKeySigner 是官方 BSV *ec.PrivateKey 的唯一本地 Signer 适配器： 直接私钥只能通过它进入 Workflow，绝不存在"Workflow 同时接受 Signer 和 私钥"的第二条路径。私钥不外泄：本类型不暴露任何读取私钥的方法，签名 请求原文（digest）与返回值也绝不进入错误、日志、wire 或 checkpoint。
func NewPrivateKeySigner ¶
func NewPrivateKeySigner(privateKey *ec.PrivateKey) (*PrivateKeySigner, error)
NewPrivateKeySigner 校验并封装一把软件私钥；nil 与无法派生压缩公钥的 输入直接拒绝。
func (*PrivateKeySigner) PublicKey ¶
func (s *PrivateKeySigner) PublicKey() PublicKey
PublicKey 返回构造时固定下来的压缩公钥；生命周期内不变。
func (*PrivateKeySigner) Sign ¶
func (s *PrivateKeySigner) Sign(_ context.Context, request SigningRequest) ([]byte, error)
Sign 对 SDK 给出的 32 字节 digest 执行 secp256k1 签名并返回 low-S DER （不带交易 sighash flag）。本适配器是纯本地计算，不消耗 context； nil context 原样接受且绝不替换为 context.Background()。
type PublicKey ¶
type PublicKey [33]byte
PublicKey 是 33 字节压缩 secp256k1 角色公钥的强类型值。
func ParsePublicKey ¶
ParsePublicKey 解析协议身份公钥并返回强类型 PublicKey。协议身份字段只 接受 canonical 33 字节压缩 secp256k1 形式；接受等价非压缩编码会改变签名 的 wire 字节。
func PublicKeyFromBytes ¶
PublicKeyFromBytes 解析并校验压缩公钥有效性后返回强类型公钥；拒绝非 canonical 压缩编码、错误长度与全零哨兵。
type RefundLockTime ¶
type RefundLockTime uint32
RefundLockTime 是退款交易 nLockTime 原始值：低于 TimestampThreshold 为 区块高锁定，否则为 UTC 时间戳锁定（解释规则由协议固定）。
func (RefundLockTime) UsesBlockHeight ¶
func (t RefundLockTime) UsesBlockHeight() bool
UsesBlockHeight 报告该锁定值是否按区块高解释。
type RetrievalNonce ¶
type RetrievalNonce [32]byte
RetrievalNonce 是 Kind 10 取回请求的 32 字节重放键。默认入口由 SDK 用 crypto/rand 生成；显式 nonce 入口只服务测试与恢复路径。
func GenerateRetrievalNonce ¶
func GenerateRetrievalNonce() (RetrievalNonce, error)
GenerateRetrievalNonce 用 crypto/rand 生成安全随机 nonce；SDK 默认入口 使用它，应用不需要也不应该自造弱随机源。
func NewRetrievalNonce ¶
func NewRetrievalNonce(raw []byte) (RetrievalNonce, error)
NewRetrievalNonce 从精确 32 字节构造 RetrievalNonce；拒绝其他长度与 全零哨兵。
type Signer ¶
type Signer interface {
// PublicKey 返回本 Signer 的固定压缩公钥；Workflow 构造时固定并验证它，
// 生命周期内不得变化。
PublicKey() PublicKey
// Sign 对 request.Digest 做 secp256k1 签名，返回不带 sighash flag 的
// DER 字节。context 只用于取消远程签名或长计算；实现遇到托管故障时
// 返回错误（可包装 ErrSignerUnavailable），绝不能返回空签名或部分结果。
Sign(ctx context.Context, request SigningRequest) ([]byte, error)
}
Signer 是 SDK 唯一的密钥操作端口：固定公钥 + 对给定 digest 的 secp256k1 签名。Signer 不能提供自定义 hash、preimage、sighash、Verifier、CBOR encoder、价格规则或角色判断；所有验签固定在 SDK 内部执行。
func BindSigner ¶
BindSigner 冻结并校验一个 Signer 的当前公钥，返回生命周期内公钥不变的 绑定视图。nil 或无效公钥直接拒绝。角色 Workflow 必须经它进入签名能力。
type SigningPurpose ¶
type SigningPurpose uint8
SigningPurpose 标记一次签名请求的业务目的，只供 HSM/KMS 策略审计； 它不进入也不替代任何既定签名预映像。
const ( // PurposeWireMessage 是普通 wire 报文签名：Digest = SHA-256(exact // WireSignatureInput)，WireKind 携带 1..11。 PurposeWireMessage SigningPurpose = 1 // PurposeTransaction 是 MultisigPool 交易签名：Digest 为固定 ForkID|All // sighash digest，WireKind 固定为 0；sighash flag 由 pool 装配时添加， // Signer 不能选择 flag。 PurposeTransaction SigningPurpose = 2 )
func (SigningPurpose) String ¶
func (p SigningPurpose) String() string
String 返回 purpose 的稳定诊断名称；不进入 wire 或日志策略之外的场景。
type SigningRequest ¶
type SigningRequest struct {
// Purpose 声明业务目的（wire_message / transaction）；仅供密钥托管侧审计。
Purpose SigningPurpose
// WireKind 是普通 wire 签名的 Kind（1..11）；交易签名为 0。
WireKind uint16
// Digest 是 SDK 构造好的 32 字节签名摘要；Signer 绝不能自行哈希。
Digest Digest32
}
SigningRequest 描述一次受约束的密钥操作：SDK 已经构造好唯一 digest， Signer 只对该 32 字节摘要执行 secp256k1 签名，返回不带交易 sighash flag 的 low-S DER。私钥、seed、WIF、助记词和签名请求原文不得进入错误、日志、 wire 或 checkpoint。
Source Files