escrow

Documentation

Overview

Package escrow provides buyer-protection for service payments.

Flow:

1. Buyer calls service → funds moved: available → escrowed
2. Service delivers result → seller marks delivered
3. Buyer confirms → funds moved: buyer's escrowed → seller's available
4. Buyer disputes → funds moved: buyer's escrowed → buyer's available
5. Timeout → auto-released to seller

Index

• Constants
• Variables
• type CreateRequest
• type DisputeRequest
• type Escrow
  • func (e *Escrow) IsTerminal() bool
• type Handler
  • func NewHandler(service *Service) *Handler
  • func (h *Handler) ConfirmEscrow(c *gin.Context)
  • func (h *Handler) CreateEscrow(c *gin.Context)
  • func (h *Handler) DisputeEscrow(c *gin.Context)
  • func (h *Handler) GetEscrow(c *gin.Context)
  • func (h *Handler) ListEscrows(c *gin.Context)
  • func (h *Handler) MarkDelivered(c *gin.Context)
  • func (h *Handler) RegisterProtectedRoutes(r *gin.RouterGroup)
  • func (h *Handler) RegisterRoutes(r *gin.RouterGroup)
• type LedgerService
• type MemoryStore
  • func NewMemoryStore() *MemoryStore
  • func (m *MemoryStore) Create(ctx context.Context, escrow *Escrow) error
  • func (m *MemoryStore) Get(ctx context.Context, id string) (*Escrow, error)
  • func (m *MemoryStore) ListByAgent(ctx context.Context, agentAddr string, limit int) ([]*Escrow, error)
  • func (m *MemoryStore) ListExpired(ctx context.Context, before time.Time, limit int) ([]*Escrow, error)
  • func (m *MemoryStore) Update(ctx context.Context, escrow *Escrow) error
• type Service
  • func NewService(store Store, ledger LedgerService) *Service
  • func (s *Service) AutoRelease(ctx context.Context, escrow *Escrow) error
  • func (s *Service) Confirm(ctx context.Context, id, callerAddr string) (*Escrow, error)
  • func (s *Service) Create(ctx context.Context, req CreateRequest) (*Escrow, error)
  • func (s *Service) Dispute(ctx context.Context, id, callerAddr, reason string) (*Escrow, error)
  • func (s *Service) Get(ctx context.Context, id string) (*Escrow, error)
  • func (s *Service) ListByAgent(ctx context.Context, agentAddr string, limit int) ([]*Escrow, error)
  • func (s *Service) MarkDelivered(ctx context.Context, id, callerAddr string) (*Escrow, error)
  • func (s *Service) WithRecorder(r TransactionRecorder) *Service
• type Status
• type Store
• type Timer
  • func NewTimer(service *Service, store Store, logger *slog.Logger) *Timer
  • func (t *Timer) Start(ctx context.Context)
  • func (t *Timer) Stop()
• type TransactionRecorder

Constants

const DefaultAutoRelease = 5 * time.Minute

DefaultAutoRelease is the default time before auto-releasing to seller.

Variables

var (
	ErrEscrowNotFound  = errors.New("escrow not found")
	ErrInvalidStatus   = errors.New("invalid escrow status for this operation")
	ErrUnauthorized    = errors.New("not authorized for this escrow operation")
	ErrInvalidAmount   = errors.New("invalid amount")
	ErrAlreadyResolved = errors.New("escrow already resolved")
)

Types

type CreateRequest

type CreateRequest struct {
	BuyerAddr    string `json:"buyerAddr" binding:"required"`
	SellerAddr   string `json:"sellerAddr" binding:"required"`
	Amount       string `json:"amount" binding:"required"`
	ServiceID    string `json:"serviceId"`
	SessionKeyID string `json:"sessionKeyId"`
	AutoRelease  string `json:"autoRelease"` // Duration string, e.g. "5m", "1h"
}

CreateRequest contains the parameters for creating an escrow.

type DisputeRequest

type DisputeRequest struct {
	Reason string `json:"reason" binding:"required"`
}

DisputeRequest contains the parameters for disputing an escrow.

type Escrow

type Escrow struct {
	ID            string     `json:"id"`
	BuyerAddr     string     `json:"buyerAddr"`
	SellerAddr    string     `json:"sellerAddr"`
	Amount        string     `json:"amount"`
	ServiceID     string     `json:"serviceId,omitempty"`
	SessionKeyID  string     `json:"sessionKeyId,omitempty"`
	Status        Status     `json:"status"`
	AutoReleaseAt time.Time  `json:"autoReleaseAt"`
	DeliveredAt   *time.Time `json:"deliveredAt,omitempty"`
	ResolvedAt    *time.Time `json:"resolvedAt,omitempty"`
	DisputeReason string     `json:"disputeReason,omitempty"`
	Resolution    string     `json:"resolution,omitempty"`
	CreatedAt     time.Time  `json:"createdAt"`
	UpdatedAt     time.Time  `json:"updatedAt"`
}

Escrow represents a buyer-protection escrow record.

func (*Escrow) IsTerminal

func (e *Escrow) IsTerminal() bool

IsTerminal returns true if the escrow is in a final state.

type Handler

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

Handler provides HTTP endpoints for escrow operations.

func NewHandler

func NewHandler(service *Service) *Handler

NewHandler creates a new escrow handler.

func (*Handler) ConfirmEscrow

func (h *Handler) ConfirmEscrow(c *gin.Context)

ConfirmEscrow handles POST /v1/escrow/:id/confirm

func (*Handler) CreateEscrow

func (h *Handler) CreateEscrow(c *gin.Context)

CreateEscrow handles POST /v1/escrow

func (*Handler) DisputeEscrow

func (h *Handler) DisputeEscrow(c *gin.Context)

DisputeEscrow handles POST /v1/escrow/:id/dispute

func (*Handler) GetEscrow

func (h *Handler) GetEscrow(c *gin.Context)

GetEscrow handles GET /v1/escrow/:id

func (*Handler) ListEscrows

func (h *Handler) ListEscrows(c *gin.Context)

ListEscrows handles GET /v1/agents/:address/escrows

func (*Handler) MarkDelivered

func (h *Handler) MarkDelivered(c *gin.Context)

MarkDelivered handles POST /v1/escrow/:id/deliver

func (*Handler) RegisterProtectedRoutes

func (h *Handler) RegisterProtectedRoutes(r *gin.RouterGroup)

RegisterProtectedRoutes sets up protected (auth-required) escrow routes.

func (*Handler) RegisterRoutes

func (h *Handler) RegisterRoutes(r *gin.RouterGroup)

RegisterRoutes sets up public (read-only) escrow routes.

type LedgerService

type LedgerService interface {
	EscrowLock(ctx context.Context, agentAddr, amount, reference string) error
	ReleaseEscrow(ctx context.Context, buyerAddr, sellerAddr, amount, reference string) error
	RefundEscrow(ctx context.Context, agentAddr, amount, reference string) error
}

LedgerService abstracts ledger operations so escrow doesn't import ledger.

type MemoryStore

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

MemoryStore is an in-memory escrow store for demo/development mode.

func NewMemoryStore

func NewMemoryStore() *MemoryStore

NewMemoryStore creates a new in-memory escrow store.

func (*MemoryStore) Create

func (m *MemoryStore) Create(ctx context.Context, escrow *Escrow) error

func (*MemoryStore) Get

func (m *MemoryStore) Get(ctx context.Context, id string) (*Escrow, error)

func (*MemoryStore) ListByAgent

func (m *MemoryStore) ListByAgent(ctx context.Context, agentAddr string, limit int) ([]*Escrow, error)

func (*MemoryStore) ListExpired

func (m *MemoryStore) ListExpired(ctx context.Context, before time.Time, limit int) ([]*Escrow, error)

func (*MemoryStore) Update

func (m *MemoryStore) Update(ctx context.Context, escrow *Escrow) error

type Service

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

Service implements escrow business logic.

func NewService

func NewService(store Store, ledger LedgerService) *Service

NewService creates a new escrow service.

func (*Service) AutoRelease

func (s *Service) AutoRelease(ctx context.Context, escrow *Escrow) error

AutoRelease releases expired escrows to the seller.

func (*Service) Confirm

func (s *Service) Confirm(ctx context.Context, id, callerAddr string) (*Escrow, error)

Confirm releases escrowed funds to the seller.

func (*Service) Create

func (s *Service) Create(ctx context.Context, req CreateRequest) (*Escrow, error)

Create creates a new escrow and locks buyer funds.

func (*Service) Dispute

func (s *Service) Dispute(ctx context.Context, id, callerAddr, reason string) (*Escrow, error)

Dispute refunds escrowed funds to the buyer.

func (*Service) Get

func (s *Service) Get(ctx context.Context, id string) (*Escrow, error)

Get returns an escrow by ID.

func (*Service) ListByAgent

func (s *Service) ListByAgent(ctx context.Context, agentAddr string, limit int) ([]*Escrow, error)

ListByAgent returns escrows involving an agent (as buyer or seller).

func (*Service) MarkDelivered

func (s *Service) MarkDelivered(ctx context.Context, id, callerAddr string) (*Escrow, error)

MarkDelivered marks the escrow as delivered by the seller.

func (*Service) WithRecorder

func (s *Service) WithRecorder(r TransactionRecorder) *Service

WithRecorder adds a transaction recorder for reputation integration.

type Status

type Status string

Status represents the state of an escrow.

const (
	StatusPending   Status = "pending"   // Created, funds locked
	StatusDelivered Status = "delivered" // Seller marked service as delivered
	StatusReleased  Status = "released"  // Buyer confirmed, funds sent to seller
	StatusDisputed  Status = "disputed"  // Buyer disputed, funds returned
	StatusRefunded  Status = "refunded"  // Dispute resolved with refund
	StatusExpired   Status = "expired"   // Auto-released after timeout
)

type Store

type Store interface {
	Create(ctx context.Context, escrow *Escrow) error
	Get(ctx context.Context, id string) (*Escrow, error)
	Update(ctx context.Context, escrow *Escrow) error
	ListByAgent(ctx context.Context, agentAddr string, limit int) ([]*Escrow, error)
	ListExpired(ctx context.Context, before time.Time, limit int) ([]*Escrow, error)
}

Store persists escrow data.

type Timer

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

Timer periodically checks for expired escrows and auto-releases them.

func NewTimer

func NewTimer(service *Service, store Store, logger *slog.Logger) *Timer

NewTimer creates a new escrow auto-release timer.

func (*Timer) Start

func (t *Timer) Start(ctx context.Context)

Start begins the auto-release loop. Call in a goroutine.

func (*Timer) Stop

func (t *Timer) Stop()

Stop signals the timer to stop.

type TransactionRecorder

type TransactionRecorder interface {
	RecordTransaction(ctx context.Context, txHash, from, to, amount, serviceID, status string) error
}

TransactionRecorder records transactions for reputation tracking.