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 validation code of the transaction with the given ID.
	// If the transaction cannot be retrieved from the ledger, it returns Unknown
	// together with a non-nil error. Implementations are not required to agree on
	// whether a pending (not-yet-committed) transaction is reported as Unknown or
	// Invalid; callers should not rely on Unknown being returned without an error.
	Status(id string) (ValidationCode, error)
	// GetTransactionStatus retrieves the current status and token request hash for a transaction.
	// It returns the validation status, the token request hash stored for namespace (if any),
	// a human-readable status message, and any error encountered while contacting the ledger.
	// The token request hash is populated only when status is Valid; for any other status it is
	// nil. A Valid transaction with no token request hash recorded for namespace also yields a
	// nil hash, not an error.
	GetTransactionStatus(ctx context.Context, namespace, txID string) (status int, tokenRequestHash []byte, message string, err error)
	// GetStates returns the raw value stored at each of the given keys in the given namespace.
	// The returned slice has exactly one entry per requested key, in the same order; a key with
	// no corresponding state on the ledger yields a nil entry at that position rather than an
	// error. Implementations may disagree on the zero-keys case: some return (nil, nil), others
	// return an error, so callers should avoid invoking GetStates with no keys.
	GetStates(ctx context.Context, namespace string, keys ...string) ([][]byte, error)
	// TransferMetadataKey returns the ledger key associated to the given transfer metadata sub-key.
	// It is a pure key-derivation function backed by the network's key translator and does not
	// touch the ledger, so it does not indicate whether the resulting key actually exists.
	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)

	// SetupPublicParams submits new or updated public parameters for a namespace to the
	// network's endorsement service, mirroring RequestApproval. Unlike RequestApproval it
	// takes a TMSID rather than a *ManagementService, so it also works for first-time setup
	// of a namespace that has no public parameters yet.
	SetupPublicParams(context view.Context, tmsID token2.TMSID, publicParamsRaw []byte, signer view.Identity, txID TxID) (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