driver

type Action interface {
	Validate() error
}

type ActionDeserializer[TA TransferAction, IA IssueAction] interface {
	DeserializeActions(tr *TokenRequest) ([]IA, []TA, error)
}

type ActionMetadataEntry struct {
	ActionID         uint32            // Position in Actions slice
	IssueMetadata    *IssueMetadata    // Non-nil if this is an issue action
	TransferMetadata *TransferMetadata // Non-nil if this is a transfer action
}

type ActionSignature struct {
	ActionID  uint32
	Signature []byte
}

type ActionWithInputs interface {
	// NumInputs returns the number of inputs in the action
	NumInputs() int
	// GetInputs returns the identifiers of the inputs in the action.
	GetInputs() []*token.ID
	// GetSerializedInputs returns the serialized inputs of the action
	GetSerializedInputs() ([][]byte, error)
	// GetSerialNumbers returns the serial numbers of the inputs if this action supports graph hiding
	GetSerialNumbers() []string
	// IsGraphHiding returns true if the action is graph hiding
	IsGraphHiding() bool
	// GetMetadata returns the action's metadata
	GetMetadata() map[string][]byte
	// ExtraSigners returns the extra signers of the action
	ExtraSigners() []Identity
}

type AuditInfoProvider interface {
	// GetAuditInfo returns the audit information for the given identity, if available.
	GetAuditInfo(ctx context.Context, identity Identity) ([]byte, error)
}

type AuditMatcherProvider interface {
	MatcherDeserializer
	MatchIdentity(ctx context.Context, id Identity, ai []byte) error
	GetAuditInfo(ctx context.Context, id Identity, p AuditInfoProvider) ([]byte, error)
}

type AuditableIdentity struct {
	Identity  Identity
	AuditInfo []byte
}

type AuditorService interface {
	// AuditorCheck performs a comprehensive validation of a token request and its metadata.
	// It ensures that the transaction is well-formed and meets all auditing requirements
	// within the context of the provided anchor.
	AuditorCheck(ctx context.Context, request *TokenRequest, metadata *TokenRequestMetadata, anchor TokenRequestAnchor) error
}

type AuditorSignature struct {
	Identity  Identity
	Signature []byte
}

type AuditorWallet interface {
	Wallet

	// GetAuditorIdentity returns an auditor identity.
	// Depending on the underlying wallet implementation, this can be a long-term or ephemeral identity.
	GetAuditorIdentity() (Identity, error)
}

type Authorization interface {
	// IsMine determines if a given token belongs to a known owner wallet.
	// It returns the ID of the wallet (if any) and additional identifiers that may indicate ownership,
	// along with a boolean indicating if the token is indeed owned.
	IsMine(ctx context.Context, tok *token.Token) (walletID string, additionalOwners []string, mine bool)

	// AmIAnAuditor checks if the service has auditor privileges based on its configuration and identities.
	AmIAnAuditor() bool

	// Issued checks if a specific issuer, identified by their identity, was the one that issued the token.
	Issued(ctx context.Context, issuer Identity, tok *token.Token) bool

	// OwnerType determines the type of the token's owner and extracts the owner's raw identity.
	OwnerType(raw []byte) (IdentityType, []byte, error)
}

type CertificationClient interface {
	// IsCertified checks if a specific token identifier has already been certified.
	IsCertified(ctx context.Context, id *token.ID) bool
	// RequestCertification initiates the certification process for the given list of token identifiers.
	RequestCertification(ctx context.Context, ids ...*token.ID) error
}

type CertificationService interface {
	// NewCertificationRequest creates a serialized certification request for the specified token identifiers.
	NewCertificationRequest(ids []*token.ID) ([]byte, error)

	// Certify uses the provided certifier wallet and ledger representations to certify a list of token identifiers.
	// It takes as input the certification request and the raw token data as stored on the ledger.
	Certify(wallet CertifierWallet, ids []*token.ID, tokens [][]byte, request []byte) ([][]byte, error)

	// VerifyCertifications validates the provided certifications for a given list of token identifiers.
	// It returns the processed certifications if they are valid, or an error otherwise.
	VerifyCertifications(ids []*token.ID, certifications [][]byte) ([][]byte, error)
}

type CertificationStorage interface {
	// Exists checks if a certification exists for the specified token ID.
	Exists(ctx context.Context, id *token.ID) bool
	// Store saves the provided certifications for the given token IDs.
	Store(ctx context.Context, certifications map[*token.ID][]byte) error
}

type CertifierWallet interface {
	Wallet

	// GetCertifierIdentity returns a certifier identity.
	// Depending on the underlying wallet implementation, this can be a long-term or ephemeral identity.
	GetCertifierIdentity() (Identity, error)
}

type Configuration interface {
	// ID returns the unique identifier of the TMS to which this configuration applies.
	ID() TMSID

	// IsSet checks if a specific configuration key is defined.
	IsSet(key string) bool

	// UnmarshalKey decodes the configuration value associated with a key into a provided struct or interface.
	// The key is typically relative to the TMS configuration block.
	UnmarshalKey(key string, rawVal any) error

	// GetString retrieves the value for a key as a string.
	GetString(key string) string

	// GetBool retrieves the value for a key as a boolean.
	GetBool(key string) bool

	// TranslatePath converts a relative configuration path into an absolute file system path.
	TranslatePath(path string) string
}

type Deserializer interface {
	// GetOwnerVerifier returns a signature verifier for a given owner identity.
	GetOwnerVerifier(ctx context.Context, id Identity) (Verifier, error)

	// GetIssuerVerifier returns a signature verifier for a given issuer identity.
	GetIssuerVerifier(ctx context.Context, id Identity) (Verifier, error)

	// GetAuditorVerifier returns a signature verifier for a given auditor identity.
	GetAuditorVerifier(ctx context.Context, id Identity) (Verifier, error)

	// Recipients extracts all recipient identities from a given serialized identity.
	Recipients(raw Identity) ([]Identity, error)

	// GetAuditInfoMatcher provides an identity matcher for a given identity and its audit metadata.
	GetAuditInfoMatcher(ctx context.Context, owner Identity, auditInfo []byte) (Matcher, error)

	// MatchIdentity checks if a specific identity corresponds to the provided audit data.
	MatchIdentity(ctx context.Context, id Identity, ai []byte) error

	// GetAuditInfo retrieves the audit information for a specific identity using an AuditInfoProvider.
	GetAuditInfo(ctx context.Context, id Identity, p AuditInfoProvider) ([]byte, error)
}

type Driver interface {
	PPReader
	// NewTokenService returns a new TokenManagerService instance.
	NewTokenService(tmsID TMSID, publicParams []byte) (TokenManagerService, error)
}

type Extras = map[string][]byte

type FullIdentity interface {
	SigningIdentity
	Verifier
}

type GetStateFnc = func(id token.ID) ([]byte, error)

type Identity = view.Identity

type IdentityConfiguration struct {
	// ID is the unique identifier for this identity configuration.
	ID string
	// Type is the type of the identity (e.g., "bccsp", "idemix").
	Type string
	// URL is the location of the identity's credential material (e.g., path to MSP folder).
	URL string
	// Config contains driver-specific configuration options in encoded format.
	Config []byte
	// Raw contains the raw identity material if already loaded.
	Raw []byte
}

type IdentityProvider interface {
	// RegisterRecipientData stores information about a token recipient, including their identity and audit metadata.
	RegisterRecipientData(ctx context.Context, data *RecipientData) error

	// GetAuditInfo retrieves the audit data associated with a specific identity.
	GetAuditInfo(ctx context.Context, identity Identity) ([]byte, error)

	// GetSigner returns a cryptographic signer for a given identity, enabling signature generation.
	GetSigner(ctx context.Context, identity Identity) (Signer, error)

	// RegisterSigner registers a pair of signer and verifier for a specific identity,
	// along with additional identity information.
	RegisterSigner(ctx context.Context, identity Identity, signer Signer, verifier Verifier, signerInfo []byte, ephemeral bool) error

	// AreMe checks a list of identities and returns those that have signers registered with this provider.
	AreMe(ctx context.Context, identities ...Identity) []string

	// IsMe returns true if a signer has been registered for the specified identity.
	IsMe(ctx context.Context, party Identity) bool

	// GetEnrollmentID extracts the enrollment identifier from the provided audit information for a specific identity.
	GetEnrollmentID(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

	// GetRevocationHandler extracts the revocation handler from the provided audit information for a specific identity.
	GetRevocationHandler(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

	// GetEIDAndRH returns both the enrollment ID and the revocation handle associated with a specific identity and its audit data.
	GetEIDAndRH(ctx context.Context, identity Identity, auditInfo []byte) (string, string, error)

	// Bind associates a long-term identity with one or more ephemeral (short-term) identities.
	Bind(ctx context.Context, longTerm Identity, ephemeralIdentities ...Identity) error

	// RegisterRecipientIdentity registers a third-party recipient's identity without requiring audit information initially.
	RegisterRecipientIdentity(ctx context.Context, id Identity) error
}

type IdentityType = int32

type IdentityTypeString = string

type Input interface {
	// GetOwner returns the cryptographic owner of the token.
	GetOwner() []byte
}

type IssueAction interface {
	Action
	ActionWithInputs
	// Serialize converts the action into its serialized byte representation.
	Serialize() ([]byte, error)
	// NumOutputs returns the total number of tokens created by this issuance.
	NumOutputs() int
	// GetSerializedOutputs retrieves the serialized representation of each created token.
	GetSerializedOutputs() ([][]byte, error)
	// GetOutputs returns the list of created tokens as Output interfaces.
	GetOutputs() []Output
	// IsAnonymous indicates whether the issuer's identity is hidden.
	IsAnonymous() bool
	// GetIssuer returns the identifier of the party that issued the tokens.
	GetIssuer() []byte
	// GetMetadata returns any additional driver-specific metadata associated with the issuance.
	GetMetadata() map[string][]byte
	// IsGraphHiding indicates whether the link between inputs and outputs is obfuscated.
	IsGraphHiding() bool
	// ExtraSigners returns any additional identities that must sign this action.
	ExtraSigners() []Identity
}

type IssueInputMetadata struct {
	TokenID *token.ID
}

type IssueMetadata struct {
	// Issuer is the identity of the issuer
	Issuer  AuditableIdentity
	Inputs  []*IssueInputMetadata
	Outputs []*IssueOutputMetadata
	// ExtraSigners is the list of extra identities that are not part of the issue action per se
	// but needs to sign the request
	ExtraSigners []AuditableIdentity
}

type IssueOptions struct {
	// Attributes is a container of generic options that might be driver specific
	Attributes map[string]any
	// TokensUpgradeRequest is a request to upgrade tokens
	TokensUpgradeRequest *TokenUpgradeRequest
	// Wallet is the wallet that should be used to issue the tokens.
	Wallet IssuerWallet
}

type IssueOutputMetadata struct {
	OutputMetadata []byte
	// OutputAuditInfo, for each output owner we have audit info
	OutputAuditInfo []byte
	// Receivers, for each output we have a receiver
	Receivers []*AuditableIdentity
}

type IssueService interface {
	// Issue generates an IssuerAction for the issuance of tokens of the specified type.
	// It takes the identity of the issuer, the token type, and a list of values and their respective owners.
	// Optional configuration can be provided through IssueOptions.
	// The method returns:
	// - An IssueAction, which captures the issuance details for the ledger.
	// - IssueMetadata, containing additional information about the issuance for the requester.
	// - An error if the issuance generation fails.
	Issue(ctx context.Context, issuerIdentity Identity, tokenType token.Type, values []uint64, owners [][]byte, opts *IssueOptions) (IssueAction, *IssueMetadata, error)

	// VerifyIssue validates the well-formedness and correctness of an IssueAction.
	// It checks the action against the provided metadata to ensure that the issuance is valid
	// according to the driver's rules.
	VerifyIssue(ctx context.Context, ia IssueAction, metadata []*IssueOutputMetadata) error

	// DeserializeIssueAction reconstructs an IssueAction from its serialized byte representation.
	DeserializeIssueAction(raw []byte) (IssueAction, error)
}

type IssuerWallet interface {
	Wallet

	// GetIssuerIdentity returns an issuer identity for the passed token type.
	// Depending on the underlying wallet implementation, this can be a long-term or ephemeral identity.
	GetIssuerIdentity(tokenType token.Type) (Identity, error)

	// HistoryTokens returns the list of tokens issued by this wallet filtered using the passed options.
	HistoryTokens(ctx context.Context, opts *ListTokensOptions) (*token.IssuedTokens, error)
}

type Ledger interface {
	// GetState returns the value for the given key
	GetState(id token.ID) ([]byte, error)
}

type LedgerToken interface {
	GetOwner() []byte
}

type LedgerTokensIterator = iterators.Iterator[*token.LedgerToken]

type ListTokensOptions struct {
	// TokenType is the type of token to list
	TokenType token.Type
}

type Matcher interface {
	// Match returns true if the passed identity matches this matcher
	Match(ctx context.Context, identity []byte) error
}

type MatcherDeserializer interface {
	GetAuditInfoMatcher(ctx context.Context, owner Identity, auditInfo []byte) (Matcher, error)
}

type MetadataDeserializer[M any] interface {
	DeserializeMetadata([]byte) (M, error)
}

type Output interface {
	// Serialize converts the output into its serialized byte representation.
	Serialize() ([]byte, error)
	// IsRedeem indicates whether the output is being redeemed (burned) rather than assigned to an owner.
	IsRedeem() bool
	// GetOwner returns the cryptographic owner assigned to the created token.
	GetOwner() []byte
}

type OwnerWallet interface {
	Wallet

	// GetRecipientIdentity returns a recipient identity.
	// Depending on the underlying wallet implementation, this can be a long-term or ephemeral identity.
	// Using the returned identity as an index, one can retrieve the following information:
	// - Identity audit info via GetAuditInfo;
	// - TokenMetadata via GetTokenMetadata;
	// - TokenIdentityMetadata via GetTokenMetadataAuditInfo.
	GetRecipientIdentity(ctx context.Context) (Identity, error)

	// GetRecipientData returns a recipient data struct, it does not include the token metadata audit info
	GetRecipientData(ctx context.Context) (*RecipientData, error)

	// GetAuditInfo returns auditing information for the passed identity
	GetAuditInfo(ctx context.Context, id Identity) ([]byte, error)

	// GetTokenMetadata returns the public information related to the token to be assigned to passed recipient identity.
	GetTokenMetadata(id Identity) ([]byte, error)

	// GetTokenMetadataAuditInfo returns private information about the token metadata assigned to the passed recipient identity.
	GetTokenMetadataAuditInfo(id Identity) ([]byte, error)

	// ListTokens returns the list of unspent tokens owned by this wallet filtered using the passed options.
	ListTokens(ctx context.Context, opts *ListTokensOptions) (*token.UnspentTokens, error)

	// ListTokensIterator returns an iterator of unspent tokens owned by this wallet filtered using the passed options.
	ListTokensIterator(ctx context.Context, opts *ListTokensOptions) (UnspentTokensIterator, error)

	// Balance returns the sum of the amounts of the tokens with type and EID equal to those passed as arguments.
	// The result is returned as a *big.Int to support arbitrary precision and prevent overflow.
	Balance(ctx context.Context, opts *ListTokensOptions) (*big.Int, error)

	// EnrollmentID returns the enrollment ID of the owner wallet
	EnrollmentID() string

	// RegisterRecipient register the passed recipient data.
	// The data is passed as pointer to allow the underlying token driver to modify them if needed.
	RegisterRecipient(ctx context.Context, data *RecipientData) error

	// Remote returns true if this wallet is verify only, meaning that the corresponding secret key is external to this wallet
	Remote() bool
}

type PPHash []byte

type PPMFactory interface {
	PPReader
	// NewPublicParametersManager returns a new PublicParametersManager instance from the passed public parameters
	NewPublicParametersManager(pp PublicParameters) (PublicParamsManager, error)
}

type PPReader interface {
	// PublicParametersFromBytes unmarshals the bytes to a PublicParameters instance.
	PublicParametersFromBytes(params []byte) (PublicParameters, error)
}

type PublicParameters interface {
	// TokenDriverName returns the unique name of the token driver.
	TokenDriverName() TokenDriverName
	// TokenDriverVersion returns the version of the token driver for which these parameters are valid.
	TokenDriverVersion() TokenDriverVersion
	// TokenDataHiding indicates whether token values and types are hidden (obfuscated).
	TokenDataHiding() bool
	// GraphHiding indicates whether the transaction graph (linkage between tokens) is hidden.
	GraphHiding() bool
	// MaxTokenValue returns the maximum value any single token can have.
	MaxTokenValue() uint64
	// CertificationDriver returns the identifier of the certification driver, if any.
	CertificationDriver() string
	// Auditors returns the list of identities authorized to audit transactions.
	Auditors() []Identity
	// Issuers returns the list of identities authorized to issue tokens.
	Issuers() []Identity
	// Precision returns the numeric precision used for token values.
	Precision() uint64
	// String provides a human-readable representation of the public parameters.
	String() string
	// Serialize converts the public parameters into their byte representation.
	Serialize() ([]byte, error)
	// Validate checks if the public parameters are internally consistent and valid.
	Validate() error
	// Extras provides access to additional, driver-specific parameters.
	Extras() Extras
}

type PublicParamsFetcher interface {
	// Fetch fetches the public parameters from a repository.
	Fetch() ([]byte, error)
}

type PublicParamsManager interface {
	// PublicParameters returns the current set of public parameters.
	PublicParameters() PublicParameters
	// NewCertifierKeyPair generates a new public-private key pair for a certifier, if supported by the driver.
	NewCertifierKeyPair() ([]byte, []byte, error)
	// PublicParamsHash returns a unique hash of the serialized public parameters.
	PublicParamsHash() PPHash
}

type QueryCallback2Func func(*token.ID, string, []byte, []byte) error

type QueryCallbackFunc func(*token.ID, []byte) error

type QueryEngine interface {
	// IsPending checks if the transaction associated with the given token ID is still pending.
	IsPending(ctx context.Context, id *token.ID) (bool, error)
	// GetStatus returns the execution status of a specific transaction.
	GetStatus(ctx context.Context, txID string) (TxStatus, string, error)
	// IsMine checks if a specific token is owned by any wallet known to the service.
	IsMine(ctx context.Context, id *token.ID) (bool, error)
	// UnspentTokensIterator returns an iterator to traverse all unspent tokens on the ledger.
	UnspentTokensIterator(ctx context.Context) (UnspentTokensIterator, error)
	// UnspentLedgerTokensIteratorBy returns an iterator to traverse all unspent ledger tokens.
	UnspentLedgerTokensIteratorBy(ctx context.Context) (LedgerTokensIterator, error)
	// UnspentTokensIteratorBy returns an iterator over unspent tokens owned by a specific wallet and optionally filtered by token type.
	UnspentTokensIteratorBy(ctx context.Context, walletID string, tokenType token.Type) (UnspentTokensIterator, error)
	// ListUnspentTokens returns a comprehensive list of all unspent tokens.
	ListUnspentTokens(ctx context.Context) (*token.UnspentTokens, error)
	// ListAuditTokens returns the audited token data for the specified token IDs.
	// The result is in order of ids meaning that the first token correspond to the first id and so on.
	ListAuditTokens(ctx context.Context, ids ...*token.ID) ([]*token.Token, error)
	// ListHistoryIssuedTokens returns a list of all tokens issued by the service.
	ListHistoryIssuedTokens(ctx context.Context) (*token.IssuedTokens, error)
	// PublicParams returns the serialized public parameters used by the driver.
	PublicParams(ctx context.Context) ([]byte, error)
	// GetTokenMetadata retrieves the private information (metadata) for the given token IDs.
	GetTokenMetadata(ctx context.Context, ids []*token.ID) ([][]byte, error)
	// GetTokenOutputs retrieves the raw token outputs as stored on the ledger for the specified token IDs.
	GetTokenOutputs(ctx context.Context, ids []*token.ID, callback QueryCallbackFunc) error
	// GetTokenOutputsAndMeta retrieves both the raw token outputs and their metadata for the specified token IDs.
	GetTokenOutputsAndMeta(ctx context.Context, ids []*token.ID) ([][]byte, [][]byte, []token.Format, error)
	// GetTokens returns the de-obfuscated token data for the specified token IDs.
	GetTokens(ctx context.Context, inputs ...*token.ID) ([]*token.Token, error)
	// WhoDeletedTokens identifies which transaction deleted the specified tokens.
	WhoDeletedTokens(ctx context.Context, inputs ...*token.ID) ([]string, []bool, error)
	// Balance calculates the total value of unspent tokens of a specific type owned by a wallet.
	// The result is returned as a *big.Int to support arbitrary precision and prevent overflow.
	Balance(ctx context.Context, id string, tokenType token.Type) (*big.Int, error)
}

type RecipientData struct {
	// Identity is the owner's cryptographic identity.
	Identity Identity
	// AuditInfo contains private metadata used for auditing the owner's identity.
	AuditInfo []byte
	// TokenMetadata contains public information about the token being assigned to this recipient.
	TokenMetadata []byte
	// TokenMetadataAuditInfo contains private metadata used for auditing the token metadata.
	TokenMetadataAuditInfo []byte
}

type RecipientExtractor interface {
	Recipients(id Identity) ([]Identity, error)
}

type RequestSignature struct {
	Action  *ActionSignature
	Auditor *AuditorSignature
}

type ServiceOptions struct {
	// Network is the name of the network
	Network string
	// Channel is the name of the channel, if meaningful for the underlying backend
	Channel string
	// Namespace is the namespace of the token
	Namespace string
	// PublicParamsFetcher is used to fetch the public parameters
	PublicParamsFetcher PublicParamsFetcher
	// PublicParams contains the public params to use to instantiate the driver
	PublicParams []byte
	// Params is used to store any application specific parameter
	Params map[string]any
}

type SetupAction interface {
	// GetSetupParameters returns the serialized public parameters from the setup action.
	GetSetupParameters() ([]byte, error)
}

type SignatureProvider interface {
	// HasBeenSignedBy returns true and the verified signature if the provider contains a valid signature for the passed identity and verifier
	HasBeenSignedBy(c context.Context, id Identity, verifier Verifier) ([]byte, error)
	// Signatures returns the signatures inside this provider
	Signatures() [][]byte
}

type Signer interface {
	// Sign signs the provided message and returns the resulting signature.
	Sign(message []byte) ([]byte, error)
}

type SigningIdentity interface {
	// Sign signs the provided message bytes and returns the resulting signature.
	Sign(raw []byte) ([]byte, error)

	// Serialize converts the signing identity into its byte representation.
	Serialize() ([]byte, error)
}

type SpendableTokensIterator = iterators.Iterator[*token.UnspentTokenInWallet]

type TMSID struct {
	Network   string
	Channel   string
	Namespace string
}

type TokenAndMetadataDeserializer[T any, M any] interface {
	TokenDeserializer[T]
	MetadataDeserializer[M]
}

type TokenCertificationStorage interface {
	GetCertifications(ctx context.Context, ids []*token.ID) ([][]byte, error)
}

type TokenDeserializer[T any] interface {
	DeserializeToken([]byte) (T, error)
}

type TokenDriverName string

type TokenDriverVersion uint32

type TokenManagerService interface {
	// IssueService returns an instance of the IssueService interface, which manages the issuance of new tokens.
	IssueService() IssueService
	// TransferService returns an instance of the TransferService interface, which handles the transfer of token ownership.
	TransferService() TransferService
	// TokensService returns an instance of the TokensService interface, providing general token management utilities.
	TokensService() TokensService
	// TokensUpgradeService returns an instance of the TokensUpgradeService interface, enabling token upgrades.
	TokensUpgradeService() TokensUpgradeService
	// AuditorService returns an instance of the AuditorService interface, facilitating token auditing capabilities.
	AuditorService() AuditorService
	// CertificationService returns an instance of the CertificationService interface, managing token certifications.
	CertificationService() CertificationService
	// Deserializer returns an instance of the Deserializer interface, which deserializes identities to obtain signature verifiers.
	Deserializer() Deserializer
	// IdentityProvider returns an instance of the IdentityProvider interface, managing identities and their associated information.
	IdentityProvider() IdentityProvider
	// Validator returns an instance of the Validator interface, which provides mechanisms for validating token transactions.
	Validator() (Validator, error)
	// PublicParamsManager returns an instance of the PublicParamsManager interface, managing the driver's public parameters.
	PublicParamsManager() PublicParamsManager
	// Configuration returns an instance of the Configuration interface, providing access to driver-specific configuration.
	Configuration() Configuration
	// WalletService returns an instance of the WalletService interface, which manages issuer, owner, auditor, and certifier wallets.
	WalletService() WalletService
	// Authorization returns an instance of the Authorization interface, used to check the relationship between tokens and wallets.
	Authorization() Authorization
	// Done releases all the resources allocated by this service, ensuring a clean shutdown.
	Done() error
}

type TokenManagerServiceProvider interface {
	// GetTokenManagerService returns a TokenManagerService instance for the passed parameters
	// If a TokenManagerService is not available, it creates one.
	GetTokenManagerService(opts ServiceOptions) (TokenManagerService, error)

	// Update uses the given options to update the public parameters of a given TMS.
	// If the public parameters in the options are identical to those in the current TMS, then nothing happens.
	// If a TMS does not exist for the given options, one is created with the given public parameters.
	Update(options ServiceOptions) error
}

type TokenOutput []byte

type TokenOutputMetadata []byte

type TokenRequest struct {
	// Version specifies the protocol version for this token request.
	// Defaults to ProtocolV1 (structured format) for new requests.
	// The asn1 tag with "-" means this field is never included in ASN.1 marshaling,
	// ensuring consistent signature verification.
	Version    uint32
	Actions    []*TypedAction // Unified slice of all actions
	Signatures []*RequestSignature
}

type TokenRequestAnchor string

type TokenRequestMetadata struct {
	// Actions contains metadata for all actions in the corresponding TokenRequest.
	Actions []*ActionMetadataEntry
	// Application allows for attaching arbitrary application-level metadata to the token request.
	Application map[string][]byte
}

type TokenUpgradeRequest struct {
	// Challenge is a challenge to be solved by the prover
	Challenge TokensUpgradeChallenge
	// Tokens is a list of tokens to be converted
	Tokens []token.LedgerToken
	// Proof is a proof that the prover has solved the challenge
	Proof TokensUpgradeProof
}

type TokenVault interface {
	IsPending(ctx context.Context, id *token.ID) (bool, error)
	GetTokenOutputsAndMeta(ctx context.Context, ids []*token.ID) ([][]byte, [][]byte, []token.Format, error)
	GetTokenOutputs(ctx context.Context, ids []*token.ID, callback QueryCallbackFunc) error
	UnspentTokensIteratorBy(ctx context.Context, id string, tokenType token.Type) (UnspentTokensIterator, error)
	ListHistoryIssuedTokens(ctx context.Context) (*token.IssuedTokens, error)
	PublicParams(ctx context.Context) ([]byte, error)
	Balance(ctx context.Context, id string, tokenType token.Type) (*big.Int, error)
}

type TokensService interface {
	// SupportedTokenFormats returns the list of token formats supported by the driver.
	SupportedTokenFormats() []token.Format

	// Deobfuscate decodes a token output and its metadata to reveal its underlying details.
	// It returns the de-obfuscated token, the identity of its issuer (if applicable),
	// the list of its recipients, and its format.
	Deobfuscate(ctx context.Context, output TokenOutput, outputMetadata TokenOutputMetadata) (*token.Token, Identity, []Identity, token.Format, error)

	// Recipients extracts the recipient identities from a given token output.
	Recipients(output TokenOutput) ([]Identity, error)
}

type TokensUpgradeChallenge = []byte

type TokensUpgradeProof = []byte

type TokensUpgradeService interface {
	// NewUpgradeChallenge generates a new upgrade challenge that the issuer
	// provides to the client to ensure the integrity of the upgrade process.
	NewUpgradeChallenge() (TokensUpgradeChallenge, error)

	// GenUpgradeProof generates a proof of the validity of the tokens to be upgraded,
	// based on the provided challenge and ledger tokens.
	GenUpgradeProof(ctx context.Context, ch TokensUpgradeChallenge, tokens []token.LedgerToken, witness TokensUpgradeWitness) (TokensUpgradeProof, error)

	// CheckUpgradeProof verifies the provided upgrade proof against the challenge
	// and the tokens to ensure the upgrade is valid and authorized.
	CheckUpgradeProof(ctx context.Context, ch TokensUpgradeChallenge, proof TokensUpgradeProof, tokens []token.LedgerToken) (bool, error)
}

type TokensUpgradeWitness = []byte

type TransferAction interface {
	Action
	ActionWithInputs
	// Serialize converts the action into its serialized byte representation.
	Serialize() ([]byte, error)
	// NumOutputs returns the total number of tokens created by this transfer.
	NumOutputs() int
	// GetSerializedOutputs retrieves the serialized representation of each created token.
	GetSerializedOutputs() ([][]byte, error)
	// GetOutputs returns the list of created tokens as Output interfaces.
	GetOutputs() []Output
	// IsRedeemAt checks if a specific output, by its index, is a redeem output.
	IsRedeemAt(index int) bool
	// SerializeOutputAt returns the serialized representation of a specific output.
	SerializeOutputAt(index int) ([]byte, error)
	// IsGraphHiding indicates whether the link between inputs and outputs is obfuscated.
	IsGraphHiding() bool
	// GetMetadata returns any additional driver-specific metadata associated with the transfer.
	GetMetadata() map[string][]byte
	// GetIssuer returns the identity of the issuer in cases where the transfer includes redemption.
	GetIssuer() Identity
}

type TransferInputMetadata struct {
	TokenID *token.ID
	Senders []*AuditableIdentity
}

type TransferMetadata struct {
	Inputs  []*TransferInputMetadata
	Outputs []*TransferOutputMetadata
	// ExtraSigners is the list of extra identities that are not part of the transfer action per se
	// but needs to sign the request
	ExtraSigners []AuditableIdentity
	// Issuer contains the identity of the issuer to sign the transfer action
	Issuer AuditableIdentity
}

type TransferOptions struct {
	// Attributes is a container of generic options that might be driver specific
	Attributes map[string]any
}

type TransferOutputMetadata struct {
	OutputMetadata []byte
	// OutputAuditInfo, for each output owner we have audit info
	OutputAuditInfo []byte
	// Receivers is the list of receivers
	Receivers []*AuditableIdentity
}

type TransferService interface {
	// Transfer generates a TransferAction to transfer the specified tokens.
	// It uses the provided wallet and anchor, along with a list of token identifiers and target outputs.
	// Additional options can be provided through TransferOptions.
	// The method returns:
	// - A TransferAction, which encodes the transfer details for the ledger.
	// - TransferMetadata, containing additional information for the requester.
	// - An error if the transfer generation fails.
	Transfer(ctx context.Context, anchor TokenRequestAnchor, wallet OwnerWallet, ids []*token2.ID, outputs []*token2.Token, opts *TransferOptions) (TransferAction, *TransferMetadata, error)

	// VerifyTransfer validates the well-formedness and correctness of a TransferAction.
	// It ensures that the transfer adheres to the driver's rules and correctly spends its inputs
	// to produce its outputs.
	VerifyTransfer(ctx context.Context, tr TransferAction, outputMetadata []*TransferOutputMetadata) error

	// DeserializeTransferAction reconstructs a TransferAction from its serialized byte representation.
	DeserializeTransferAction(raw []byte) (TransferAction, error)
}

type TxStatus = int

type TypedAction struct {
	Type request.ActionType // ACTION_TYPE_ISSUE or ACTION_TYPE_TRANSFER
	Raw  []byte             // Serialized action data
}

type UnspentTokensIterator = iterators.Iterator[*token.UnspentToken]

type UnsupportedTokensIterator = iterators.Iterator[*token.LedgerToken]

type ValidationAttributeID = string

type ValidationAttributes = map[ValidationAttributeID][]byte

type Validator interface {
	// UnmarshalActions reconstructs the individual actions (issue, transfer, etc.)
	// from their serialized representation in a token request.
	UnmarshalActions(raw []byte) ([]any, error)

	// VerifyTokenRequestFromRaw validates a marshalled token request against the provided ledger state and anchor.
	// It performs a comprehensive check of all actions and signatures within the request.
	// It returns:
	// - The list of unmarshalled actions.
	// - A map of validation attributes (driver-specific) containing additional details about the request.
	// - An error if the validation fails.
	VerifyTokenRequestFromRaw(ctx context.Context, getState GetStateFnc, anchor TokenRequestAnchor, raw []byte) ([]any, ValidationAttributes, error)

	// SetMinProtocolVersion configures the minimum protocol version that this validator will accept.
	// Token requests with a protocol version below this minimum will be rejected during validation.
	// Setting this to 0 (default) accepts all protocol versions.
	// This is useful for enforcing protocol upgrades across a network.
	SetMinProtocolVersion(version uint32)
}

type ValidatorDriver interface {
	PPReader
	// NewValidator returns a new Validator instance from the passed public parameters
	NewValidator(pp PublicParameters) (Validator, error)
}

type ValidatorLedger interface {
	GetState(id token.ID) ([]byte, error)
}

type Vault interface {
	// QueryEngine returns an instance of the QueryEngine interface for querying the ledger.
	QueryEngine() QueryEngine
	// CertificationStorage returns an instance of the CertificationStorage interface for managing token certifications.
	CertificationStorage() CertificationStorage
}

type Verifier interface {
	// Verify checks the signature against the provided message and returns nil if valid.
	Verify(message, sigma []byte) error
}

type VerifierDeserializer interface {
	DeserializeVerifier(ctx context.Context, id Identity) (Verifier, error)
}

type Wallet interface {
	// ID returns the ID of this wallet
	ID() string

	// Contains returns true if the passed identity belongs to this wallet
	Contains(ctx context.Context, identity Identity) bool

	// ContainsToken returns true if the passed token is owned by this wallet
	ContainsToken(ctx context.Context, token *token.UnspentToken) bool

	// GetSigner returns the Signer bound to the passed identity
	GetSigner(ctx context.Context, identity Identity) (Signer, error)
}

type WalletLookupID = any

type WalletService interface {
	// RegisterRecipientIdentity registers a recipient identity and its audit data.
	RegisterRecipientIdentity(ctx context.Context, data *RecipientData) error

	// GetAuditInfo retrieves the audit data associated with a specific identity.
	GetAuditInfo(ctx context.Context, id Identity) ([]byte, error)

	// GetEnrollmentID extracts the enrollment identifier from audit data for a given identity.
	GetEnrollmentID(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

	// GetRevocationHandle extracts the revocation handler from audit data for a given identity.
	GetRevocationHandle(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

	// GetEIDAndRH returns both the enrollment ID and the revocation handle for a given identity and audit data.
	GetEIDAndRH(ctx context.Context, identity Identity, auditInfo []byte) (string, string, error)

	// Wallet returns a generic wallet interface associated with the specified identity, if any.
	Wallet(ctx context.Context, identity Identity) Wallet

	// RegisterOwnerIdentity registers a long-term owner identity using the provided configuration.
	RegisterOwnerIdentity(ctx context.Context, config IdentityConfiguration) error

	// RegisterIssuerIdentity registers a long-term issuer identity using the provided configuration.
	RegisterIssuerIdentity(ctx context.Context, config IdentityConfiguration) error

	// OwnerWalletIDs returns a list of identifiers for all known owner wallets.
	OwnerWalletIDs(ctx context.Context) ([]string, error)

	// OwnerWallet retrieves an OwnerWallet instance based on its identifier or an identity belonging to it.
	OwnerWallet(ctx context.Context, id WalletLookupID) (OwnerWallet, error)

	// IssuerWallet retrieves an IssuerWallet instance based on its identifier or an identity belonging to it.
	IssuerWallet(ctx context.Context, id WalletLookupID) (IssuerWallet, error)

	// AuditorWallet retrieves an AuditorWallet instance based on its identifier or an identity belonging to it.
	AuditorWallet(ctx context.Context, id WalletLookupID) (AuditorWallet, error)

	// CertifierWallet retrieves a CertifierWallet instance based on its identifier or an identity belonging to it.
	CertifierWallet(ctx context.Context, id WalletLookupID) (CertifierWallet, error)

	// SpendIDs returns unique identifiers representing the potential spending of the specified token IDs.
	SpendIDs(ids ...*token.ID) ([]string, error)

	// Done releases all the resources allocated by this service.
	Done() error
}

type WalletServiceFactory interface {
	PPReader
	// NewWalletService returns an instance of the WalletService interface for the passed arguments
	NewWalletService(tmsConfig Configuration, params PublicParameters) (WalletService, error)
}