driver

type Driver interface {
	// New returns a new network instance for the passed network and channel (if applicable)
	New(network, channel string) (Network, error)
}

type Envelope interface {
	// Bytes marshals the envelope to bytes
	Bytes() ([]byte, error)

	// FromBytes unmarshals the envelope from bytes
	FromBytes([]byte) error

	// TxID returns the ID of this envelope
	TxID() string

	// String returns the string representation of this envelope
	String() string
}

type FinalityListener interface {
	// OnStatus is called when the validation status of a transaction changes on the ledger.
	OnStatus(ctx context.Context, txID string, status int, message string, tokenRequestHash []byte)
	// OnError is called when the finality event cannot be delivered after all retries are exhausted
	OnError(ctx context.Context, txID string, err error)
}

type FinalityListenerManager interface {
	// AddFinalityListener registers a listener for transaction status for the passed transaction id.
	// If the status is already valid or invalid, the listener is called immediately.
	// When the listener is invoked, then it is also removed.
	AddFinalityListener(namespace string, txID string, listener FinalityListener) error
}

type Ledger interface {
	// Status returns the status of the transaction
	Status(id string) (ValidationCode, error)
	// GetTransactionStatus retrieves the current status and token request hash for a transaction.
	// Returns the validation status, token request hash, status message, and any error encountered.
	GetTransactionStatus(ctx context.Context, namespace, txID string) (status int, tokenRequestHash []byte, message string, err error)
	// GetStates returns the value corresponding to the given keys stored in the given namespace.
	GetStates(ctx context.Context, namespace string, keys ...string) ([][]byte, error)
	// TransferMetadataKey returns the transfer metadata key associated to the given key
	TransferMetadataKey(k string) (string, error)
}

type LocalMembership interface {
	// DefaultIdentity returns the default FSC node identity
	DefaultIdentity() view.Identity

	// AnonymousIdentity returns a fresh anonymous identity
	AnonymousIdentity() (view.Identity, error)
}

type Network interface {
	// Name returns the identifier of the network.
	Name() string

	// Channel returns the name of the channel or ledger partition, if applicable.
	Channel() string

	// Normalize populates default values in service options based on network configuration.
	Normalize(opt *token2.ServiceOptions) (*token2.ServiceOptions, error)

	// Connect initializes the connection to the backend for a specific namespace.
	Connect(ns string) ([]token2.ServiceOption, error)

	// Broadcast submits a transaction or data blob to the network's ordering service.
	Broadcast(ctx context.Context, blob any) error

	// NewEnvelope creates a new, empty transaction envelope specific to the backend.
	NewEnvelope() Envelope

	// RequestApproval requests an endorsement for a token request from the network's approval service.
	// metadata carries optional application-level key-value pairs forwarded to the approver.
	RequestApproval(context view.Context, tms *token2.ManagementService, requestRaw []byte, signer view.Identity, txID TxID, metadata TransientMap) (Envelope, error)

	// ComputeTxID calculates the ledger-specific transaction ID from an abstract TxID.
	ComputeTxID(id *TxID) string

	// FetchPublicParameters retrieves the latest cryptographic public parameters from the ledger.
	FetchPublicParameters(namespace string) ([]byte, error)

	// QueryTokens retrieves raw token data for the specified IDs from the ledger state.
	QueryTokens(ctx context.Context, namespace string, IDs []*token.ID) ([][]byte, error)

	// AreTokensSpent checks the spent status of multiple tokens on the distributed ledger.
	AreTokensSpent(ctx context.Context, namespace string, tokenIDs []*token.ID, meta []string) ([]bool, error)

	// LocalMembership returns the local membership service for managing node identities.
	LocalMembership() LocalMembership

	// AddFinalityListener registers a listener for transaction status for the passed transaction id.
	// If the status is already valid or invalid, the listener is called immediately.
	// When the listener is invoked, then it is also removed.
	AddFinalityListener(namespace string, txID string, listener FinalityListener) error

	// GetTransactionStatus retrieves the current status and token request hash for a transaction.
	// Returns the validation status, token request hash, status message, and any error encountered.
	GetTransactionStatus(ctx context.Context, namespace, txID string) (status int, tokenRequestHash []byte, message string, err error)

	// LookupTransferMetadataKey scans the ledger for metadata associated with a transfer action.
	LookupTransferMetadataKey(namespace string, key string, timeout time.Duration) ([]byte, error)

	// Ledger provides access to the underlying ledger service for direct state interaction.
	Ledger() (Ledger, error)
}

type SpentTokenQueryExecutor interface {
	QuerySpentTokens(ctx context.Context, namespace string, IDs []*token2.ID, meta []string) ([]bool, error)
}

type SpentTokenQueryExecutorProvider interface {
	GetSpentExecutor(network, channel string) (SpentTokenQueryExecutor, error)
}

type TokenQueryExecutor interface {
	QueryTokens(ctx context.Context, namespace string, IDs []*token2.ID) ([][]byte, error)
}

type TokenQueryExecutorProvider interface {
	GetExecutor(network, channel string) (TokenQueryExecutor, error)
}

type TransientMap = map[string][]byte

type TxID struct {
	// Nonce is a random value used to prevent replay attacks.
	Nonce []byte
	// Creator is the serialized identity of the entity that created the transaction.
	Creator []byte
}

type TxStatus = int

type ValidationCode = int