pool

由 doc2go 直接从当前 Go 源码与 doc comments 生成。

package pool

import "github.com/bsv8/go-bitfs/pool"

Package pool contains the generic 2-of-3 settlement primitives. It does not import BitFS quote or content types.

Index

Constants

const (
	KindPoolRefundPresignRequest  uint64 = 12
	KindPoolRefundPresignResponse uint64 = 13
	KindPoolFundingTxDelivery     uint64 = 14
)
const MajorVersion uint64 = 3
const MultisigProtocol = "bitfs.pool.v4"
const MultisigVersion uint64 = 4
const ProtocolFamily = "bitfs.pool.workflow.v3"

ProtocolFamily is the go-bitfs pool workflow protocol. It is deliberately separate from the MultisigPool library protocol embedded in OpeningProof.

Variables

var (
	ErrInvalidEvidence      = errors.New("invalid pool evidence")
	ErrPoolBusy             = errors.New("pool busy")
	ErrStalePaymentSequence = errors.New("stale payment sequence")
	ErrInsufficientBalance  = errors.New("insufficient pool balance")
	ErrNonFinalRejected     = errors.New("non-final pool rejected update")
	ErrFinalRejected        = errors.New("pool node rejected final transaction")
	ErrNotExpired           = errors.New("pool refund expiry has not been reached")
	ErrPoolStateUncertain   = errors.New("pool state requires external reconciliation")
)

Functions

func Build2of3LockingScript

func Build2of3LockingScript(pubkeys [][]byte) ([]byte, error)

func BuildPoolLock

func BuildPoolLock(roles mp.ArbitratedPoolRoles) ([]byte, error)

BuildPoolLock is the public role-explicit lock adapter. The argument order is permanently Buyer, Seller, Arbiter through the v4 role object.

func EncodeFundingTxDelivery

func EncodeFundingTxDelivery(delivery *FundingTxDelivery) ([]byte, error)

func EncodeOpeningProof

func EncodeOpeningProof(proof *OpeningProof) ([]byte, error)

func EncodePaymentUpdate

func EncodePaymentUpdate(update *PaymentUpdate) ([]byte, error)

func EncodeRefundPresignRequest

func EncodeRefundPresignRequest(request *RefundPresignRequest) ([]byte, error)

func EncodeRefundPresignResponse

func EncodeRefundPresignResponse(response *RefundPresignResponse) ([]byte, error)

func ValidateFundingTxDelivery

func ValidateFundingTxDelivery(delivery *FundingTxDelivery) error

func ValidateOpeningProof

func ValidateOpeningProof(proof *OpeningProof) error

func ValidatePaymentUpdate

func ValidatePaymentUpdate(update *PaymentUpdate) error

func ValidateRefundPresignRequest

func ValidateRefundPresignRequest(request *RefundPresignRequest) error

func ValidateRefundPresignResponse

func ValidateRefundPresignResponse(response *RefundPresignResponse) error

Types

type ArbiterPoolAdapter

type ArbiterPoolAdapter struct {
	*MultisigPoolEngine
	Key PrivateKeyProvider
}
func NewArbiterPoolAdapter
func NewArbiterPoolAdapter(engine *MultisigPoolEngine, key PrivateKeyProvider) *ArbiterPoolAdapter
func (*ArbiterPoolAdapter) SignArbiterPayment
func (adapter *ArbiterPoolAdapter) SignArbiterPayment(ctx context.Context, unsigned *UnsignedPayment, _ Signer) ([]byte, error)

type BSVTransactionIDCalculator

type BSVTransactionIDCalculator struct {
	Engine *MultisigPoolEngine
}

BSVTransactionIDCalculator adapts the synchronous reference engine to the context-aware opening workflow port. Production applications can replace it with a database-backed calculator or a node/SDK implementation.

func (BSVTransactionIDCalculator) TransactionID
func (calculator BSVTransactionIDCalculator) TransactionID(_ context.Context, rawTx []byte) (Hash32, error)

type BuyerOpeningPort

type BuyerOpeningPort struct {
	Store      OpeningProofStore
	Verifier   RefundTxSignatureVerifier
	Calculator TransactionIDCalculator
}

BuyerOpeningPort composes the small external capabilities needed by the buyer-side 002 workflow without forcing applications to create boilerplate forwarding types.

func (BuyerOpeningPort) LoadOpeningProof
func (port BuyerOpeningPort) LoadOpeningProof(ctx context.Context, spendTxID Hash32) (*OpeningProof, error)
func (BuyerOpeningPort) SaveOpeningProof
func (port BuyerOpeningPort) SaveOpeningProof(ctx context.Context, proof *OpeningProof) error
func (BuyerOpeningPort) TransactionID
func (port BuyerOpeningPort) TransactionID(ctx context.Context, rawTx []byte) (Hash32, error)
func (BuyerOpeningPort) VerifySellerRefundSignature
func (port BuyerOpeningPort) VerifySellerRefundSignature(ctx context.Context, request *RefundPresignRequest, signature []byte) error

type BuyerPoolAdapter

type BuyerPoolAdapter struct {
	*MultisigPoolEngine
	Key PrivateKeyProvider
}
func NewBuyerPoolAdapter
func NewBuyerPoolAdapter(engine *MultisigPoolEngine, key PrivateKeyProvider) *BuyerPoolAdapter
func (*BuyerPoolAdapter) BuildRefundPresignRequest
func (adapter *BuyerPoolAdapter) BuildRefundPresignRequest(ctx context.Context, input OpeningInput, _ Signer) (*RefundPresignRequest, error)
func (*BuyerPoolAdapter) SignBuyerPayment
func (adapter *BuyerPoolAdapter) SignBuyerPayment(ctx context.Context, unsigned *UnsignedPayment, _ Signer) ([]byte, error)

type BuyerPoolOpeningHooks

type BuyerPoolOpeningHooks interface {
	OpeningProofStore
	RefundTxSignatureVerifier
	TransactionIDCalculator
}

type BuyerPoolPort

type BuyerPoolPort interface {
	TransactionID([]byte) (Hash32, error)
	BuildRefundPresignRequest(context.Context, OpeningInput, Signer) (*RefundPresignRequest, error)
	BuildRefundSubmission(*OpeningProof) ([]byte, error)
	VerifyRefundExpired(*OpeningProof, time.Time) error
	VerifyOpening(*OpeningProof) error
	ParsePaymentState(context.Context, []byte, *OpeningProof) (*PaymentState, error)
	ParseUnsignedPayment(context.Context, []byte, *OpeningProof) (*UnsignedPayment, error)
	VerifyAcceptedPayment(*PaymentState, *OpeningProof) error
	VerifyBuyerPayment(*UnsignedPayment, []byte, *OpeningProof) error
	VerifyCompletedFinalPayment(*SignedPayment, *OpeningProof) error
	CheckPaymentCapacity(context.Context, PaymentUpdateInput) error
	BuildPaymentUpdate(context.Context, PaymentUpdateInput) (*UnsignedPayment, error)
	SignBuyerPayment(context.Context, *UnsignedPayment, Signer) ([]byte, error)
	BuildImmediateClose(context.Context, CloseInput) (*UnsignedPayment, []byte, error)
}

type CloseInput

type CloseInput struct {
	Opening              *OpeningProof
	Latest               *PaymentState
	SellerAmountAfterSat uint64
}
func CloneCloseInput
func CloneCloseInput(input CloseInput) CloseInput

type FileStore

type FileStore struct {
	// contains filtered or unexported fields
}

FileStore is a small durable reference implementation of the pool storage ports. It uses an advisory process lock and reloads the current snapshot for every operation, so cooperating Unix processes do not overwrite each other's updates. A transactional database is still preferable when the deployment needs indexed queries, crash-recovery guarantees beyond atomic rename, or an authoritative lock service.

Each mutation writes a complete snapshot through a temporary file and an atomic rename. Raw transactions, signatures and pending price commitments therefore survive a process restart without changing their protocol bytes.

func NewFileStore
func NewFileStore(path string, calculator TransactionIDCalculator) (*FileStore, error)

NewFileStore opens path and rehydrates all pool, payment and delivery-latch state. A missing file is treated as an empty store.

func (*FileStore) EnsurePoolHealthy
func (store *FileStore) EnsurePoolHealthy(ctx context.Context, spendTxID Hash32) error
func (*FileStore) Load
func (store *FileStore) Load(ctx context.Context, spendTxID Hash32) (*PendingRequest, error)
func (*FileStore) LoadAcceptedPayment
func (store *FileStore) LoadAcceptedPayment(ctx context.Context, spendTxID Hash32) (*PaymentState, error)
func (*FileStore) LoadOpeningProof
func (store *FileStore) LoadOpeningProof(ctx context.Context, spendTxID Hash32) (*OpeningProof, error)
func (*FileStore) LoadOpeningProofByFundingTxID
func (store *FileStore) LoadOpeningProofByFundingTxID(ctx context.Context, fundingTxID Hash32) (*OpeningProof, error)
func (*FileStore) MarkExternalStateUncertain
func (store *FileStore) MarkExternalStateUncertain(ctx context.Context, spendTxID, txID Hash32) error
func (*FileStore) ReconcileExternalState
func (store *FileStore) ReconcileExternalState(ctx context.Context, spendTxID Hash32, state *PaymentState) error
func (*FileStore) Release
func (store *FileStore) Release(ctx context.Context, spendTxID, requestHash Hash32) error
func (*FileStore) SaveAcceptedPayment
func (store *FileStore) SaveAcceptedPayment(ctx context.Context, state *PaymentState) error
func (*FileStore) SaveOpeningProof
func (store *FileStore) SaveOpeningProof(ctx context.Context, proof *OpeningProof) error
func (*FileStore) TryAcquire
func (store *FileStore) TryAcquire(ctx context.Context, request PendingRequest) (PendingAcquireResult, error)

type FundingTxDelivery

type FundingTxDelivery struct {
	Version   uint64
	FundingTx []byte
}
func CloneFundingTxDelivery
func CloneFundingTxDelivery(delivery *FundingTxDelivery) *FundingTxDelivery
func DecodeFundingTxDelivery
func DecodeFundingTxDelivery(data []byte) (*FundingTxDelivery, error)

type FundingTxVerifier

type FundingTxVerifier interface {
	VerifyFundingTx(context.Context, []byte, *OpeningProof) error
}

type Hash32

type Hash32 [sha256.Size]byte
func SpendTxID
func SpendTxID(ctx context.Context, proof *OpeningProof, calculator TransactionIDCalculator) (Hash32, error)

SpendTxID is the stable transaction anchor defined by 002: the canonical ID of the presigned RefundTx evidence bytes. BuildRefundSubmission later adds the separate signatures for actual broadcast, which may produce another transaction ID because unlocking data is part of the txid.

type MemoryStore

type MemoryStore struct {
	// contains filtered or unexported fields
}

MemoryStore is a concurrency-safe reference implementation of the pool persistence ports. It is useful for integration tests and small embedded deployments; replacing it does not change protocol semantics.

func NewMemoryStore
func NewMemoryStore(calculator TransactionIDCalculator) (*MemoryStore, error)
func (*MemoryStore) EnsurePoolHealthy
func (store *MemoryStore) EnsurePoolHealthy(_ context.Context, spendTxID Hash32) error
func (*MemoryStore) Load
func (store *MemoryStore) Load(_ context.Context, spendTxID Hash32) (*PendingRequest, error)
func (*MemoryStore) LoadAcceptedPayment
func (store *MemoryStore) LoadAcceptedPayment(_ context.Context, spendTxID Hash32) (*PaymentState, error)
func (*MemoryStore) LoadOpeningProof
func (store *MemoryStore) LoadOpeningProof(_ context.Context, spendTxID Hash32) (*OpeningProof, error)
func (*MemoryStore) LoadOpeningProofByFundingTxID
func (store *MemoryStore) LoadOpeningProofByFundingTxID(_ context.Context, fundingTxID Hash32) (*OpeningProof, error)
func (*MemoryStore) MarkExternalStateUncertain
func (store *MemoryStore) MarkExternalStateUncertain(_ context.Context, spendTxID, txID Hash32) error
func (*MemoryStore) ReconcileExternalState
func (store *MemoryStore) ReconcileExternalState(ctx context.Context, spendTxID Hash32, state *PaymentState) error
func (*MemoryStore) Release
func (store *MemoryStore) Release(_ context.Context, spendTxID, requestHash Hash32) error
func (*MemoryStore) SaveAcceptedPayment
func (store *MemoryStore) SaveAcceptedPayment(_ context.Context, state *PaymentState) error
func (*MemoryStore) SaveOpeningProof
func (store *MemoryStore) SaveOpeningProof(ctx context.Context, proof *OpeningProof) error
func (*MemoryStore) TryAcquire
func (store *MemoryStore) TryAcquire(_ context.Context, request PendingRequest) (PendingAcquireResult, error)

type MultisigPoolAdapter

type MultisigPoolAdapter struct {
	Engine     *MultisigPoolEngine
	ArbiterKey PrivateKeyProvider
}

MultisigPoolAdapter is the arbiter-facing capability. It contains no legacy role aliases and never constructs a replacement candidate transaction.

func (*MultisigPoolAdapter) SignArbitrationCandidate
func (adapter *MultisigPoolAdapter) SignArbitrationCandidate(ctx context.Context, raw []byte, proof *OpeningProof, _ Signer) ([]byte, error)
func (*MultisigPoolAdapter) VerifyArbitrationCandidate
func (adapter *MultisigPoolAdapter) VerifyArbitrationCandidate(_ context.Context, raw []byte, proof *OpeningProof, terms *bitfs.ContentRequestTerms, sellerSig []byte) (*UnsignedPayment, error)
func (*MultisigPoolAdapter) VerifyOpening
func (adapter *MultisigPoolAdapter) VerifyOpening(proof *OpeningProof) error

type MultisigPoolEngine

type MultisigPoolEngine struct {
	// contains filtered or unexported fields
}
func NewMultisigPoolEngine
func NewMultisigPoolEngine(config MultisigPoolEngineConfig) (*MultisigPoolEngine, error)
func (*MultisigPoolEngine) BuildImmediateClose
func (engine *MultisigPoolEngine) BuildImmediateClose(_ context.Context, input CloseInput) (*UnsignedPayment, []byte, error)
func (*MultisigPoolEngine) BuildPaymentUpdate
func (engine *MultisigPoolEngine) BuildPaymentUpdate(ctx context.Context, input PaymentUpdateInput) (*UnsignedPayment, error)
func (*MultisigPoolEngine) BuildRefundSubmission
func (engine *MultisigPoolEngine) BuildRefundSubmission(proof *OpeningProof) ([]byte, error)
func (*MultisigPoolEngine) CheckPaymentCapacity
func (engine *MultisigPoolEngine) CheckPaymentCapacity(_ context.Context, input PaymentUpdateInput) error
func (*MultisigPoolEngine) FundingTxID
func (engine *MultisigPoolEngine) FundingTxID(rawTx []byte) (Hash32, error)
func (*MultisigPoolEngine) ParseFinalPaymentState
func (engine *MultisigPoolEngine) ParseFinalPaymentState(ctx context.Context, rawTx []byte, proof *OpeningProof) (*PaymentState, error)
func (*MultisigPoolEngine) ParsePaymentState
func (engine *MultisigPoolEngine) ParsePaymentState(_ context.Context, rawTx []byte, proof *OpeningProof) (*PaymentState, error)
func (*MultisigPoolEngine) ParseUnsignedPayment
func (engine *MultisigPoolEngine) ParseUnsignedPayment(_ context.Context, rawTx []byte, proof *OpeningProof) (*UnsignedPayment, error)
func (*MultisigPoolEngine) TransactionID
func (engine *MultisigPoolEngine) TransactionID(rawTx []byte) (Hash32, error)
func (*MultisigPoolEngine) VerifyAcceptedPayment
func (engine *MultisigPoolEngine) VerifyAcceptedPayment(state *PaymentState, proof *OpeningProof) error
func (*MultisigPoolEngine) VerifyArbitratedPayment
func (engine *MultisigPoolEngine) VerifyArbitratedPayment(state *PaymentState, proof *OpeningProof) error
func (*MultisigPoolEngine) VerifyBuyerPayment
func (engine *MultisigPoolEngine) VerifyBuyerPayment(unsigned *UnsignedPayment, sig []byte, proof *OpeningProof) error
func (*MultisigPoolEngine) VerifyCompletedFinalPayment
func (engine *MultisigPoolEngine) VerifyCompletedFinalPayment(payment *SignedPayment, proof *OpeningProof) error
func (*MultisigPoolEngine) VerifyFinalPayment
func (engine *MultisigPoolEngine) VerifyFinalPayment(state *PaymentState, proof *OpeningProof) error
func (*MultisigPoolEngine) VerifyFundingTx
func (engine *MultisigPoolEngine) VerifyFundingTx(_ context.Context, rawTx []byte, proof *OpeningProof) error
func (*MultisigPoolEngine) VerifyOpening
func (engine *MultisigPoolEngine) VerifyOpening(proof *OpeningProof) error
func (*MultisigPoolEngine) VerifyPoolParticipants
func (engine *MultisigPoolEngine) VerifyPoolParticipants(proof *OpeningProof, buyer, seller, arbiter []byte) error
func (*MultisigPoolEngine) VerifyRefundExpired
func (engine *MultisigPoolEngine) VerifyRefundExpired(proof *OpeningProof, now time.Time) error
func (*MultisigPoolEngine) VerifySellerPayment
func (engine *MultisigPoolEngine) VerifySellerPayment(unsigned *UnsignedPayment, sig []byte, proof *OpeningProof) error
func (*MultisigPoolEngine) VerifySellerRefundSignature
func (engine *MultisigPoolEngine) VerifySellerRefundSignature(_ context.Context, request *RefundPresignRequest, signature []byte) error

type MultisigPoolEngineConfig

type MultisigPoolEngineConfig struct {
	BuyerPubKey   []byte
	SellerPubKey  []byte
	ArbiterPubKey []byte
	BlockHeight   func() uint32
}

type NonFinalPoolBackend

type NonFinalPoolBackend interface {
	SubmitUpdate(context.Context, []byte) (*UpdateAcceptance, error)
	SubmitFinal(context.Context, []byte) (Hash32, error)
}

NonFinalPoolBackend is the narrow boundary for a concrete BSV node/RPC client. SubmitUpdate must return only after the node has accepted rawTx as the current non-final spend; SubmitFinal must return only after final acceptance. A JSON-RPC, gRPC or vendor SDK client can implement this port without being coupled to seller or buyer workflow code.

type NonFinalPoolNode

type NonFinalPoolNode interface {
	SubmitUpdate(context.Context, []byte) (*UpdateAcceptance, error)
	SubmitFinal(context.Context, []byte) (Hash32, error)
}

type OpeningByFundingStore

type OpeningByFundingStore interface {
	LoadOpeningProofByFundingTxID(context.Context, Hash32) (*OpeningProof, error)
}

OpeningByFundingStore supplies the opening proof needed to verify a raw payment before it reaches a node adapter.

type OpeningInput

type OpeningInput struct {
	FundingTx            []byte
	PoolOutputIndex      uint32
	ExpiryLockTime       uint32
	MinerFeeRateSatPerKB uint64
	SellerPubKey         []byte
	ArbiterPubKey        []byte
}

OpeningInput contains generic pool construction data only.

func CloneOpeningInput
func CloneOpeningInput(input OpeningInput) OpeningInput

type OpeningProof

type OpeningProof struct {
	Version               uint64
	MultisigProtocol      string
	MultisigVersion       uint64
	RefundTx              []byte
	SpendTxID             []byte
	FundingTxID           []byte
	PoolOutputIndex       uint32
	PoolOutputSatoshis    uint64
	PoolLockingScript     []byte
	BuyerPubKey           []byte
	SellerPubKey          []byte
	ArbiterPubKey         []byte
	MinerFeeRateSatPerKB  uint64
	BuyerRefundSignature  []byte
	SellerRefundSignature []byte
	FundingTx             []byte
}
func BuyerAcceptRefundPresign
func BuyerAcceptRefundPresign(ctx context.Context, request *RefundPresignRequest, response *RefundPresignResponse, fundingTx []byte, hooks BuyerPoolOpeningHooks) (*OpeningProof, error)

BuyerAcceptRefundPresign verifies and persists the complete proof before the caller is allowed to reveal FundingTx to the seller.

func CloneOpeningProof
func CloneOpeningProof(proof *OpeningProof) *OpeningProof
func DecodeOpeningProof
func DecodeOpeningProof(data []byte) (*OpeningProof, error)
func SellerAcceptFundingTx
func SellerAcceptFundingTx(ctx context.Context, delivery *FundingTxDelivery, hooks SellerPoolOpeningHooks) (*OpeningProof, error)

SellerAcceptFundingTx verifies the funding transaction against the retained refund proof, persists it, then submits it. A submit retry is safe when the node treats transaction IDs idempotently.

type OpeningProofStore

type OpeningProofStore interface {
	SaveOpeningProof(context.Context, *OpeningProof) error
	LoadOpeningProof(context.Context, Hash32) (*OpeningProof, error)
}

type ParticipantVerifier

type ParticipantVerifier interface {
	VerifyPoolParticipants(*OpeningProof, []byte, []byte, []byte) error
}

type PaymentState

type PaymentState struct {
	SpendTxID                   Hash32
	RawTx                       []byte
	PaymentSequence             uint32
	BuyerAmountSat              uint64
	SellerAmountSat             uint64
	ArbiterAmountSat            uint64
	PaymentAuthorizationHash    Hash32
	BuyerTransactionSignature   []byte
	SellerTransactionSignature  []byte
	ArbiterTransactionSignature []byte
	PoolOutputSatoshis          uint64
	PoolLockingScript           []byte
}

PaymentState only represents a fully merged transaction accepted by a node. Detached signatures are kept explicitly when a workflow needs to carry them across an API boundary, but RawTx is never a single-signature or unsigned transaction.

func ClonePaymentState
func ClonePaymentState(state *PaymentState) *PaymentState

type PaymentUpdate

type PaymentUpdate struct {
	Version                   uint64
	PaymentAuthorizationHash  []byte
	UnsignedStateTxRaw        []byte
	BuyerTransactionSignature []byte
}

PaymentUpdate is the v3 005 transport container. It carries an unsigned state transaction and a detached Buyer signature; it never carries a partially unlocked transaction.

func ClonePaymentUpdate
func ClonePaymentUpdate(update *PaymentUpdate) *PaymentUpdate
func DecodePaymentUpdate
func DecodePaymentUpdate(data []byte) (*PaymentUpdate, error)

type PaymentUpdateInput

type PaymentUpdateInput struct {
	Opening              *OpeningProof
	Previous             *PaymentState
	PaymentSequenceAfter uint32
	SellerAmountAfterSat uint64
}
func ClonePaymentUpdateInput
func ClonePaymentUpdateInput(input PaymentUpdateInput) PaymentUpdateInput

type PendingAcquireResult

type PendingAcquireResult uint8
const (
	PendingAcquired    PendingAcquireResult = 1
	PendingAlreadyHeld PendingAcquireResult = 2
	PendingConflict    PendingAcquireResult = 3
)

type PendingOpeningProofStore

type PendingOpeningProofStore interface {
	SaveOpeningProof(context.Context, *OpeningProof) error
	LoadOpeningProofByFundingTxID(context.Context, Hash32) (*OpeningProof, error)
}

type PendingRequest

type PendingRequest struct {
	SpendTxID               Hash32
	BasePaymentSequence     uint32
	ContentRequestHash      Hash32
	ExpectedSellerAmountSat uint64
}

type PendingRequestStore

type PendingRequestStore interface {
	TryAcquire(context.Context, PendingRequest) (PendingAcquireResult, error)
	Load(context.Context, Hash32) (*PendingRequest, error)
	Release(context.Context, Hash32, Hash32) error
}

type PoolNodeVerifierPort

type PoolNodeVerifierPort interface {
	FundingTxID([]byte) (Hash32, error)
	TransactionID([]byte) (Hash32, error)
	BuildRefundSubmission(*OpeningProof) ([]byte, error)
	VerifyRefundExpired(*OpeningProof, time.Time) error
	ParsePaymentState(context.Context, []byte, *OpeningProof) (*PaymentState, error)
	ParseUnsignedPayment(context.Context, []byte, *OpeningProof) (*UnsignedPayment, error)
	ParseFinalPaymentState(context.Context, []byte, *OpeningProof) (*PaymentState, error)
	VerifyAcceptedPayment(*PaymentState, *OpeningProof) error
	VerifyArbitratedPayment(*PaymentState, *OpeningProof) error
	VerifyCompletedFinalPayment(*SignedPayment, *OpeningProof) error
}

type PoolRefundSigner

type PoolRefundSigner struct{ Adapter *SellerPoolAdapter }
func (PoolRefundSigner) SignRefundTx
func (adapter PoolRefundSigner) SignRefundTx(ctx context.Context, request *RefundPresignRequest) ([]byte, error)

type PoolStore

type PoolStore interface {
	OpeningProofStore
	LoadOpeningProofByFundingTxID(context.Context, Hash32) (*OpeningProof, error)
	SaveAcceptedPayment(context.Context, *PaymentState) error
	LoadAcceptedPayment(context.Context, Hash32) (*PaymentState, error)
	EnsurePoolHealthy(context.Context, Hash32) error
	MarkExternalStateUncertain(context.Context, Hash32, Hash32) error
	ReconcileExternalState(context.Context, Hash32, *PaymentState) error
}

type PrivateKeyProvider

type PrivateKeyProvider interface {
	PrivateKey(context.Context) (*ec.PrivateKey, error)
}

PrivateKeyProvider is intentionally narrower than the workflow Signer: MultisigPool must receive the actual private key so it can calculate its canonical sighash and detached signature.

type Reference

type Reference struct {
	SpendTxID           Hash32
	BasePaymentSequence uint32
}

type RefundPresignRequest

type RefundPresignRequest struct {
	Version              uint64
	MultisigProtocol     string
	MultisigVersion      uint64
	RefundTx             []byte
	FundingTxID          []byte
	PoolOutputIndex      uint32
	PoolOutputSatoshis   uint64
	PoolLockingScript    []byte
	BuyerPubKey          []byte
	SellerPubKey         []byte
	ArbiterPubKey        []byte
	MinerFeeRateSatPerKB uint64
	BuyerRefundSignature []byte
}
func CloneRefundPresignRequest
func CloneRefundPresignRequest(request *RefundPresignRequest) *RefundPresignRequest
func DecodeRefundPresignRequest
func DecodeRefundPresignRequest(data []byte) (*RefundPresignRequest, error)

type RefundPresignResponse

type RefundPresignResponse struct {
	Version               uint64
	SellerRefundSignature []byte
}
func CloneRefundPresignResponse
func CloneRefundPresignResponse(response *RefundPresignResponse) *RefundPresignResponse
func DecodeRefundPresignResponse
func DecodeRefundPresignResponse(data []byte) (*RefundPresignResponse, error)
func SellerPresignRefund
func SellerPresignRefund(ctx context.Context, request *RefundPresignRequest, hooks SellerPoolOpeningHooks) (*RefundPresignResponse, error)

SellerPresignRefund signs and durably records the refund evidence before returning. FundingTx is intentionally not required at this stage.

type RefundTxSignatureVerifier

type RefundTxSignatureVerifier interface {
	VerifySellerRefundSignature(context.Context, *RefundPresignRequest, []byte) error
}

type RefundTxSigner

type RefundTxSigner interface {
	SignRefundTx(context.Context, *RefundPresignRequest) ([]byte, error)
}

type SellerOpeningPort

type SellerOpeningPort struct {
	Store            PendingOpeningProofStore
	RefundSigner     RefundTxSigner
	Calculator       TransactionIDCalculator
	FundingVerifier  FundingTxVerifier
	FundingSubmitter TransactionSubmitter
}

SellerOpeningPort composes the external capabilities required by the seller-side 002 workflow. The submitter is deliberately separate from the non-final payment node: funding submission and payment-pool replacement are different state transitions.

func (SellerOpeningPort) LoadOpeningProofByFundingTxID
func (port SellerOpeningPort) LoadOpeningProofByFundingTxID(ctx context.Context, fundingTxID Hash32) (*OpeningProof, error)
func (SellerOpeningPort) SaveOpeningProof
func (port SellerOpeningPort) SaveOpeningProof(ctx context.Context, proof *OpeningProof) error
func (SellerOpeningPort) SignRefundTx
func (port SellerOpeningPort) SignRefundTx(ctx context.Context, request *RefundPresignRequest) ([]byte, error)
func (SellerOpeningPort) SubmitTransaction
func (port SellerOpeningPort) SubmitTransaction(ctx context.Context, rawTx []byte) (Hash32, error)
func (SellerOpeningPort) TransactionID
func (port SellerOpeningPort) TransactionID(ctx context.Context, rawTx []byte) (Hash32, error)
func (SellerOpeningPort) VerifyFundingTx
func (port SellerOpeningPort) VerifyFundingTx(ctx context.Context, fundingTx []byte, proof *OpeningProof) error

type SellerPoolAdapter

type SellerPoolAdapter struct {
	*MultisigPoolEngine
	Key PrivateKeyProvider
}
func NewSellerPoolAdapter
func NewSellerPoolAdapter(engine *MultisigPoolEngine, key PrivateKeyProvider) *SellerPoolAdapter
func (*SellerPoolAdapter) MergeBuyerSellerPayment
func (adapter *SellerPoolAdapter) MergeBuyerSellerPayment(unsigned *UnsignedPayment, buyerSig, sellerSig []byte) (*SignedPayment, error)
func (*SellerPoolAdapter) MergeSellerArbiterPayment
func (adapter *SellerPoolAdapter) MergeSellerArbiterPayment(unsigned *UnsignedPayment, sellerSig, arbiterSig []byte) (*SignedPayment, error)
func (*SellerPoolAdapter) SignImmediateClose
func (adapter *SellerPoolAdapter) SignImmediateClose(ctx context.Context, unsigned *UnsignedPayment, buyerSig []byte, _ Signer) (*SignedPayment, error)
func (*SellerPoolAdapter) SignSellerArbitrationCandidate
func (adapter *SellerPoolAdapter) SignSellerArbitrationCandidate(ctx context.Context, unsigned *UnsignedPayment, _ Signer) ([]byte, error)
func (*SellerPoolAdapter) SignSellerPayment
func (adapter *SellerPoolAdapter) SignSellerPayment(ctx context.Context, unsigned *UnsignedPayment, _ Signer) ([]byte, error)
func (*SellerPoolAdapter) VerifyBuyerPayment
func (adapter *SellerPoolAdapter) VerifyBuyerPayment(unsigned *UnsignedPayment, sig []byte, proof *OpeningProof) error
func (*SellerPoolAdapter) VerifySellerPayment
func (adapter *SellerPoolAdapter) VerifySellerPayment(unsigned *UnsignedPayment, sig []byte, proof *OpeningProof) error

type SellerPoolOpeningHooks

type SellerPoolOpeningHooks interface {
	PendingOpeningProofStore
	RefundTxSigner
	TransactionIDCalculator
	FundingTxVerifier
	TransactionSubmitter
}

type SellerPoolPort

type SellerPoolPort interface {
	TransactionID([]byte) (Hash32, error)
	FundingTxID([]byte) (Hash32, error)
	BuildRefundSubmission(*OpeningProof) ([]byte, error)
	VerifyOpening(*OpeningProof) error
	ParsePaymentState(context.Context, []byte, *OpeningProof) (*PaymentState, error)
	ParseUnsignedPayment(context.Context, []byte, *OpeningProof) (*UnsignedPayment, error)
	VerifyAcceptedPayment(*PaymentState, *OpeningProof) error
	VerifyArbitratedPayment(*PaymentState, *OpeningProof) error
	VerifyBuyerPayment(*UnsignedPayment, []byte, *OpeningProof) error
	VerifySellerPayment(*UnsignedPayment, []byte, *OpeningProof) error
	CheckPaymentCapacity(context.Context, PaymentUpdateInput) error
	BuildPaymentUpdate(context.Context, PaymentUpdateInput) (*UnsignedPayment, error)
	SignSellerArbitrationCandidate(context.Context, *UnsignedPayment, Signer) ([]byte, error)
	SignSellerPayment(context.Context, *UnsignedPayment, Signer) ([]byte, error)
	MergeBuyerSellerPayment(*UnsignedPayment, []byte, []byte) (*SignedPayment, error)
	MergeSellerArbiterPayment(*UnsignedPayment, []byte, []byte) (*SignedPayment, error)
	SignImmediateClose(context.Context, *UnsignedPayment, []byte, Signer) (*SignedPayment, error)
}

type SignatureVerifier

type SignatureVerifier interface {
	Verify(pubkey, payload, signature []byte) error
}

type SignedPayment

type SignedPayment struct {
	State PaymentState
	RawTx []byte
}
func CloneSignedPayment
func CloneSignedPayment(payment *SignedPayment) *SignedPayment

type Signer

type Signer interface {
	PublicKey(context.Context) ([]byte, error)
	Sign(context.Context, []byte) ([]byte, error)
}

type TransactionIDCalculator

type TransactionIDCalculator interface {
	TransactionID(context.Context, []byte) (Hash32, error)
}

type TransactionSubmitter

type TransactionSubmitter interface {
	SubmitTransaction(context.Context, []byte) (Hash32, error)
}

type UnsignedPayment

type UnsignedPayment struct {
	SpendTxID          Hash32
	RawTx              []byte
	PaymentSequence    uint32
	BuyerAmountSat     uint64
	SellerAmountSat    uint64
	ArbiterAmountSat   uint64
	PoolOutputSatoshis uint64
	PoolLockingScript  []byte
}

UnsignedPayment is the only transaction object accepted by single-sign methods. It contains no unlocking script and no embedded signature.

type UpdateAcceptance

type UpdateAcceptance struct {
	TxID            Hash32
	SpendTxID       Hash32
	PaymentSequence uint32
}

type VerifiedNonFinalPoolNode

type VerifiedNonFinalPoolNode struct {
	// contains filtered or unexported fields
}

VerifiedNonFinalPoolNode is the production-side adapter between workflow code and a concrete node client. It verifies the exact input, outputs, buyer authorization and final signature set available in rawTx before forwarding it, then verifies that the backend response describes the same accepted transaction and sequence.

func NewVerifiedNonFinalPoolNode
func NewVerifiedNonFinalPoolNode(engine PoolNodeVerifierPort, openings OpeningByFundingStore, backend NonFinalPoolBackend) (*VerifiedNonFinalPoolNode, error)
func (*VerifiedNonFinalPoolNode) SubmitFinal
func (node *VerifiedNonFinalPoolNode) SubmitFinal(ctx context.Context, rawTx []byte) (Hash32, error)
func (*VerifiedNonFinalPoolNode) SubmitUpdate
func (node *VerifiedNonFinalPoolNode) SubmitUpdate(ctx context.Context, rawTx []byte) (*UpdateAcceptance, error)