wallet.go

/*
Copyright IBM Corp. All Rights Reserved.

SPDX-License-Identifier: Apache-2.0
*/

package driver

import (
	"context"

	"github.com/hyperledger-labs/fabric-smart-client/platform/view/view"
	"github.com/hyperledger-labs/fabric-token-sdk/token/token"
)

// Identity represents a generic identity
type Identity = view.Identity

// IdentityProvider manages identity-related concepts like signature signers, verifiers, audit information, and so on.
//
//go:generate counterfeiter -o mock/ip.go -fake-name IdentityProvider . IdentityProvider
type IdentityProvider interface {
	// RegisterRecipientData stores the passed recipient data
	RegisterRecipientData(ctx context.Context, data *RecipientData) error

	// GetAuditInfo returns the audit information associated to the passed identity, nil otherwise
	GetAuditInfo(ctx context.Context, identity Identity) ([]byte, error)

	// GetSigner returns a Signer for passed identity.
	GetSigner(ctx context.Context, identity Identity) (Signer, error)

	// RegisterSigner registers a Signer and a Verifier for passed identity.
	RegisterSigner(ctx context.Context, identity Identity, signer Signer, verifier Verifier, signerInfo []byte, ephemeral bool) error

	// AreMe returns the hashes of the passed identities that have a signer registered before
	AreMe(ctx context.Context, identities ...Identity) []string

	// IsMe returns true if a signer was ever registered for the passed identity
	IsMe(ctx context.Context, party Identity) bool

	// GetEnrollmentID extracts the enrollment ID from the passed audit info
	GetEnrollmentID(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

	// GetRevocationHandler extracts the revocation handler from the passed audit info
	GetRevocationHandler(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

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

	// Bind binds longTerm to the passed ephemeral identities.
	Bind(ctx context.Context, longTerm Identity, ephemeralIdentities ...Identity) error

	// RegisterRecipientIdentity register the passed identity as a third-party recipient identity.
	RegisterRecipientIdentity(ctx context.Context, id Identity) error
}

// RecipientData contains information about the identity of a token owner
type RecipientData struct {
	// Identity is the identity of the token owner
	Identity Identity
	// AuditInfo contains private information Identity
	AuditInfo []byte
	// TokenMetadata contains public information related to the token to be assigned to this Recipient.
	TokenMetadata []byte
	// TokenMetadataAuditInfo contains private information TokenMetadata
	TokenMetadataAuditInfo []byte
}

// ListTokensOptions contains options that can be used to list tokens from a wallet
type ListTokensOptions struct {
	// TokenType is the type of token to list
	TokenType token.Type
	// Context is used to track the operation
	Context context.Context
}

// Wallet models a generic wallet
//
//go:generate counterfeiter -o mock/w.go -fake-name Wallet . Wallet
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)
}

// OwnerWallet models the wallet of a token recipient.
//
//go:generate counterfeiter -o mock/ow.go -fake-name OwnerWallet . OwnerWallet
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(opts *ListTokensOptions) (*token.UnspentTokens, error)

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

	// Balance returns the sun of the amounts, with 64 bits of precision, of the tokens with type and EID equal to those passed as arguments.
	Balance(ctx context.Context, opts *ListTokensOptions) (uint64, 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
}

// IssuerWallet models the wallet of an issuer
//
//go:generate counterfeiter -o mock/iw.go -fake-name IssuerWallet . IssuerWallet
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)
}

// AuditorWallet models the wallet of an auditor
//
//go:generate counterfeiter -o mock/aw.go -fake-name AuditorWallet . AuditorWallet
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)
}

// CertifierWallet models the wallet of a certifier
//
//go:generate counterfeiter -o mock/cw.go -fake-name CertifierWallet . CertifierWallet
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)
}

// IdentityConfiguration contains configuration-related information of an identity
type IdentityConfiguration struct {
	ID     string
	Type   string
	URL    string
	Config []byte
	Raw    []byte
}

// WalletLookupID defines the type of identifiers that can be used to retrieve a given wallet.
// It can be a string, as the name of the wallet, or an identity contained in that wallet.
// Ultimately, it is the token driver to decide which types are allowed.
type WalletLookupID = any

// IdentityType identifies the type of identity
type IdentityType = string

// Authorization defines method to check the relation between a token
// and wallets (owner, auditor, etc.)
//
//go:generate counterfeiter -o mock/authorization.go -fake-name Authorization . Authorization
type Authorization interface {
	// IsMine returns true if the passed token is owned by an owner wallet.
	// It returns the ID of the owner wallet (walletID) and any additional owner identifier (additionalOwners), if supported.
	// It is possible that walletID is empty additionalOwners is not.
	// If walletID is not empty, this means that the corresponding wallet can spend the token directly.
	// If walletID is empty, then additionalOwners must cooperate in some way in order to spend the token.
	IsMine(ctx context.Context, tok *token.Token) (walletID string, additionalOwners []string, mine bool)
	// AmIAnAuditor return true if the passed TMS contains an auditor wallet for any of the auditor identities
	// defined in the public parameters of the passed TMS.
	AmIAnAuditor() bool
	// Issued returns true if the passed issuer issued the passed token
	Issued(ctx context.Context, issuer Identity, tok *token.Token) bool
	// OwnerType returns the type of owner (e.g. 'idemix' or 'htlc') and the identity bytes
	OwnerType(raw []byte) (IdentityType, []byte, error)
}

//go:generate counterfeiter -o mock/ws.go -fake-name WalletService . WalletService

// WalletService models the wallet service that handles issuer, owner, auditor, and certifier wallets
type WalletService interface {
	// RegisterRecipientIdentity registers the passed recipient identity together with the associated audit information
	RegisterRecipientIdentity(ctx context.Context, data *RecipientData) error

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

	// GetEnrollmentID extracts the enrollment id from the passed audit information
	GetEnrollmentID(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

	// GetRevocationHandle extracts the revocation handler from the passed audit information
	GetRevocationHandle(ctx context.Context, identity Identity, auditInfo []byte) (string, error)

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

	// Wallet returns the wallet bound to the passed identity, if any is available
	Wallet(ctx context.Context, identity Identity) Wallet

	// RegisterOwnerIdentity registers an owner long-term identity
	RegisterOwnerIdentity(ctx context.Context, config IdentityConfiguration) error

	// RegisterIssuerIdentity registers an issuer long-term wallet
	RegisterIssuerIdentity(ctx context.Context, config IdentityConfiguration) error

	// OwnerWalletIDs returns the list of owner wallet identifiers
	OwnerWalletIDs(ctx context.Context) ([]string, error)

	// OwnerWallet returns an instance of the OwnerWallet interface bound to the passed id.
	// The id can be: the wallet identifier or a unique id of a view identity belonging to the wallet.
	OwnerWallet(ctx context.Context, id WalletLookupID) (OwnerWallet, error)

	// IssuerWallet returns an instance of the IssuerWallet interface bound to the passed id.
	// The id can be: the wallet identifier or a unique id of a view identity belonging to the wallet.
	IssuerWallet(ctx context.Context, id WalletLookupID) (IssuerWallet, error)

	// AuditorWallet returns an instance of the AuditorWallet interface bound to the passed id.
	// The id can be: the wallet identifier or a unique id of a view identity belonging to the wallet.
	AuditorWallet(ctx context.Context, id WalletLookupID) (AuditorWallet, error)

	// CertifierWallet returns an instance of the CertifierWallet interface bound to the passed id.
	// The id can be: the wallet identifier or a unique id of a view identity belonging to the wallet.
	CertifierWallet(ctx context.Context, id WalletLookupID) (CertifierWallet, error)

	// SpendIDs returns the spend ids for the passed token ids
	SpendIDs(ids ...*token.ID) ([]string, error)
}

//go:generate counterfeiter -o mock/wallet_service_factory.go -fake-name WalletServiceFactory . WalletServiceFactory
type WalletServiceFactory interface {
	PPReader
	// NewWalletService returns an instance of the WalletService interface for the passed arguments
	NewWalletService(tmsConfig Configuration, params PublicParameters) (WalletService, error)
}

// Matcher models a matcher that can be used to match identities
//
//go:generate counterfeiter -o mock/matcher.go -fake-name Matcher . Matcher
type Matcher interface {
	// Match returns true if the passed identity matches this matcher
	Match(ctx context.Context, identity []byte) error
}

// AuditInfoProvider models a provider of audit information
//
//go:generate counterfeiter -o mock/audit_info_provider.go -fake-name AuditInfoProvider . AuditInfoProvider
type AuditInfoProvider interface {
	// GetAuditInfo returns the audit information for the given identity, if available.
	GetAuditInfo(ctx context.Context, identity Identity) ([]byte, error)
}

// Deserializer models the deserializer of owner, issuer, and auditor identities to
// get signature verifiers
//
//go:generate counterfeiter -o mock/deserializer.go -fake-name Deserializer . Deserializer
type Deserializer interface {
	// GetOwnerVerifier returns the verifier associated to the passed owner identity
	GetOwnerVerifier(ctx context.Context, id Identity) (Verifier, error)
	// GetIssuerVerifier returns the verifier associated to the passed issuer identity
	GetIssuerVerifier(ctx context.Context, id Identity) (Verifier, error)
	// GetAuditorVerifier returns the verifier associated to the passed auditor identity
	GetAuditorVerifier(ctx context.Context, id Identity) (Verifier, error)
	// Recipients returns the recipient identities from the given serialized representation
	Recipients(raw Identity) ([]Identity, error)
	// GetAuditInfoMatcher returns an identity matcher for the passed identity and audit data
	GetAuditInfoMatcher(ctx context.Context, owner Identity, auditInfo []byte) (Matcher, error)
	// MatchIdentity returns nil if the given identity matches the given audit information.
	// An error otherwise.
	MatchIdentity(ctx context.Context, id Identity, ai []byte) error
	// GetAuditInfo returns the audit information for the passed identity
	GetAuditInfo(ctx context.Context, id Identity, p AuditInfoProvider) ([]byte, error)
}