transfer

type CacheMetrics struct {
	// PutsTotal counts Put calls by result: "ok" or "full".
	PutsTotal *prometheus.CounterVec

	// GetsTotal counts GetAndDelete calls by result: "ok", "not_found", or "expired".
	GetsTotal *prometheus.CounterVec
}

type CompletedTransfer struct {
	ContractID      string `json:"contract_id"`
	Kind            string `json:"kind"`   // "direct" | "offer"
	Status          string `json:"status"` // "completed"
	FromPartyID     string `json:"from_party_id"`
	ToPartyID       string `json:"to_party_id"`
	Amount          string `json:"amount"`
	InstrumentAdmin string `json:"instrument_admin"`
	InstrumentID    string `json:"instrument_id"`
	Timestamp       string `json:"timestamp"`       // RFC3339
	TxID            string `json:"tx_id,omitempty"` // ledger update id
	Symbol          string `json:"symbol,omitempty"`
	Decimals        int    `json:"decimals,omitempty"`
	Name            string `json:"name,omitempty"`
	ContractAddress string `json:"contract_address,omitempty"`
}

type CompletedTransfersList struct {
	Items   []CompletedTransfer `json:"items"`
	Total   int64               `json:"total"`
	Page    int                 `json:"page"`
	Limit   int                 `json:"limit"`
	HasMore bool                `json:"has_more"`
}

type CustodialTransferRequest struct {
	ToPartyID       string `json:"to_party_id"`      // Recipient Canton party id (<hint>::<fingerprint>)
	Amount          string `json:"amount"`           // Token amount (decimal string)
	Token           string `json:"token"`            // Token symbol
	ValiditySeconds int64  `json:"validity_seconds"` // Offer validity window in seconds; must be > 0
}

type ExecuteRequest struct {
	TransferID string `json:"transfer_id"`
	Signature  string `json:"signature"` // hex-encoded DER signature
	SignedBy   string `json:"signed_by"` // Canton multihash fingerprint
}

type ExecuteResponse struct {
	Status string `json:"status"` // "completed"
}

type IncomingTransfer struct {
	ContractID      string `json:"contract_id"`
	SenderPartyID   string `json:"sender_party_id"`
	ReceiverPartyID string `json:"receiver_party_id"`
	Amount          string `json:"amount"`
	InstrumentAdmin string `json:"instrument_admin"`
	InstrumentID    string `json:"instrument_id"`
	Symbol          string `json:"symbol,omitempty"`
	Decimals        int    `json:"decimals,omitempty"`
	Name            string `json:"name,omitempty"`
	ContractAddress string `json:"contract_address,omitempty"`
}

type IncomingTransfersList struct {
	Items   []IncomingTransfer `json:"items"`
	Total   int64              `json:"total"`
	Page    int                `json:"page"`
	Limit   int                `json:"limit"`
	HasMore bool               `json:"has_more"`
}

type IndexerReader interface {
	GetTransfers(
		ctx context.Context, partyID string, query indexer.TransferQuery, p indexer.Pagination,
	) (*indexer.Page[indexer.Transfer], error)
	// GetTransfer returns a single transfer by its contract id (used to validate a
	// claim-back request directly, without scanning a party's transfer list).
	GetTransfer(ctx context.Context, contractID string) (*indexer.Transfer, error)
}

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

type OutgoingTransfer struct {
	ContractID      string `json:"contract_id"`
	SenderPartyID   string `json:"sender_party_id"`
	ReceiverPartyID string `json:"receiver_party_id"`
	Amount          string `json:"amount"`
	InstrumentAdmin string `json:"instrument_admin"`
	InstrumentID    string `json:"instrument_id"`
	Status          string `json:"status"`
	CreatedAt       string `json:"created_at"`           // RFC3339; ledger effective time of the offer's creation
	ExpiresAt       string `json:"expires_at,omitempty"` // RFC3339; omitted when the offer never expires
	Symbol          string `json:"symbol,omitempty"`
	Decimals        int    `json:"decimals,omitempty"`
	Name            string `json:"name,omitempty"`
	ContractAddress string `json:"contract_address,omitempty"`
}

type OutgoingTransfersList struct {
	Items   []OutgoingTransfer `json:"items"`
	Total   int64              `json:"total"`
	Page    int                `json:"page"`
	Limit   int                `json:"limit"`
	HasMore bool               `json:"has_more"`
}

type PartyRegistry interface {
	PartyExists(ctx context.Context, partyID string) (bool, error)
}

type PrepareAcceptRequest struct {
	InstrumentAdmin string `json:"instrument_admin"` // Canton party ID of the instrument admin
}

type PrepareRequest struct {
	To              string `json:"to,omitempty"`          // Recipient EVM address (0x...) of a registered user
	ToPartyID       string `json:"to_party_id,omitempty"` // Recipient Canton party id (<hint>::<fingerprint>)
	Amount          string `json:"amount"`                // Token amount (decimal string)
	Token           string `json:"token"`                 // "DEMO" or "PROMPT"
	ValiditySeconds int64  `json:"validity_seconds"`      // Offer validity window in seconds; must be > 0
}

type PrepareResponse struct {
	TransferID      string `json:"transfer_id"`
	TransactionHash string `json:"transaction_hash"` // hex-encoded hash to sign
	PartyID         string `json:"party_id"`
	ExpiresAt       string `json:"expires_at"` // RFC3339
}

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

type Service interface {
	Prepare(ctx context.Context, senderEVMAddr string, req *PrepareRequest) (*PrepareResponse, error)
	Execute(ctx context.Context, senderEVMAddr string, req *ExecuteRequest) (*ExecuteResponse, error)

	// SendCustodial performs a single-call, server-signed transfer for a custodial
	// user to an arbitrary recipient party id (the middleware holds the user's
	// Canton key, so there is no client prepare/execute round-trip).
	SendCustodial(ctx context.Context, senderEVMAddr string, req *CustodialTransferRequest) (*ExecuteResponse, error)

	// ListIncoming returns one page of pending inbound TransferOffer details for the
	// user with the given EVM address. This call is unauthenticated — anyone can
	// query any address's pending offers; the response is intentionally minimized
	// (party IDs truncated) to keep that from leaking counterparties.
	ListIncoming(ctx context.Context, evmAddr string, p indexer.Pagination) (*IncomingTransfersList, error)
	// ListOutgoing returns one page of the user's outbound transfers filtered
	// by status (pending / expired / completed / canceled / rejected / all).
	// Like ListIncoming it is unauthenticated and truncates party IDs.
	ListOutgoing(ctx context.Context, evmAddr string, status string, p indexer.Pagination) (*OutgoingTransfersList, error)
	// ListCompleted returns one page of the user's settled transfers across all
	// tokens (TokenTransferEvents and accepted TransferOffers), newest first.
	ListCompleted(ctx context.Context, evmAddr string, p indexer.Pagination) (*CompletedTransfersList, error)
	// PrepareAccept builds a Canton transaction for accepting an inbound offer.
	PrepareAccept(
		ctx context.Context, evmAddr, contractID string, req *PrepareAcceptRequest,
	) (*PrepareResponse, error)
	// ExecuteAccept completes a previously prepared accept using the client's DER signature.
	ExecuteAccept(ctx context.Context, evmAddr string, req *ExecuteRequest) (*ExecuteResponse, error)
	// PrepareWithdraw builds a Canton transaction for a non-custodial sender to claim
	// back (withdraw) a pending/expired offer they sent. Complete it via Execute.
	PrepareWithdraw(ctx context.Context, evmAddr, contractID string) (*PrepareResponse, error)
	// WithdrawCustodial claims back a pending/expired offer for a custodial sender in a
	// single server-signed call.
	WithdrawCustodial(ctx context.Context, evmAddr, contractID string) (*ExecuteResponse, error)
}

type TransferCache interface {
	Put(transfer *token.PreparedTransfer) error
	GetAndDelete(transferID string) (*token.PreparedTransfer, error)
}

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

type UserStore interface {
	GetUserByEVMAddress(ctx context.Context, evmAddress string) (*user.User, error)
	GetUserByCantonPartyID(ctx context.Context, partyID string) (*user.User, error)
}