role

package
v0.14.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 7, 2026 License: Apache-2.0 Imports: 19 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	CacheLevelOpts = metrics.GaugeOpts{
		Name:       "recipient_data_cache_level",
		Help:       "Level of the wallet recipient data cache",
		LabelNames: []string{"network", "channel", "namespace"},
	}
)

Functions

This section is empty.

Types

type AnonymousOwnerWallet 

type AnonymousOwnerWallet struct {
	*LongTermOwnerWallet
	Logger          logging.Logger
	Deserializer    Deserializer
	IdentitySupport IdentitySupport
	IdentityCache   *RecipientDataCache
}

AnonymousOwnerWallet represents an owner wallet that uses ephemeral pseudonyms for privacy. It embeds a LongTermOwnerWallet for shared functionality and adds a cache and registry interactions to produce and manage anonymous recipient identities.

func NewAnonymousOwnerWallet 

func NewAnonymousOwnerWallet(
	logger logging.Logger,
	IdentityProvider IdentityProvider,
	TokenVault OwnerTokenVault,
	Deserializer Deserializer,
	identitySupport IdentitySupport,
	id idriver.WalletID,
	identityInfo idriver.IdentityInfo,
	cacheSize int,
	metricsProvider metrics.Provider,
) (*AnonymousOwnerWallet, error)

NewAnonymousOwnerWallet creates an AnonymousOwnerWallet. It initializes a RecipientDataCache (used to cache pseudonyms/recipient data) and stores references to the identity provider, vault, deserializer and wallet registry used to validate and register pseudonyms.

func (*AnonymousOwnerWallet) Contains 

func (w *AnonymousOwnerWallet) Contains(ctx context.Context, identity Identity) bool

Contains reports whether the provided identity is bound to this anonymous owner wallet according to the wallet registry.

func (*AnonymousOwnerWallet) ContainsToken 

func (w *AnonymousOwnerWallet) ContainsToken(ctx context.Context, token *token.UnspentToken) bool

ContainsToken returns true if the token is owned by an identity bound to this anonymous owner wallet.

func (*AnonymousOwnerWallet) GetRecipientData 

func (w *AnonymousOwnerWallet) GetRecipientData(ctx context.Context) (*driver.RecipientData, error)

GetRecipientData returns recipient data (identity + audit info) from the identity cache.

func (*AnonymousOwnerWallet) GetRecipientIdentity 

func (w *AnonymousOwnerWallet) GetRecipientIdentity(ctx context.Context) (Identity, error)

GetRecipientIdentity returns the current recipient identity (pseudonym) from the cache, creating a new one if necessary.

func (*AnonymousOwnerWallet) GetSigner 

func (w *AnonymousOwnerWallet) GetSigner(ctx context.Context, identity Identity) (Signer, error)

GetSigner returns a signer for the provided identity if it is bound to this anonymous owner wallet; otherwise an error is returned.

func (*AnonymousOwnerWallet) RegisterRecipient 

func (w *AnonymousOwnerWallet) RegisterRecipient(ctx context.Context, data *driver.RecipientData) error

RegisterRecipient validates and registers the provided recipient data (verifier and audit info) into the identity provider and wallet registry.

type AuditorWallet 

type AuditorWallet struct {
	WalletID string

	Identity Identity
	Signer   Signer
}

AuditorWallet represents a wallet that holds a single auditor identity. Auditor wallets are used to perform audit-related operations and to validate whether a given identity belongs to the auditor.

func NewAuditorWallet 

func NewAuditorWallet(walletID string, identity Identity, signer Signer) *AuditorWallet

NewAuditorWallet creates a new AuditorWallet bound to a single auditor identity. The wallet uses the provided IdentityProvider to obtain signers and audit information for the auditor identity.

func (*AuditorWallet) Contains 

func (w *AuditorWallet) Contains(ctx context.Context, identity Identity) bool

Contains reports whether the given identity belongs to this auditor wallet. The context is accepted for API consistency and future use.

func (*AuditorWallet) ContainsToken 

func (w *AuditorWallet) ContainsToken(ctx context.Context, token *token.UnspentToken) bool

ContainsToken returns true if the supplied unspent token is owned by the auditor identity associated with this wallet.

func (*AuditorWallet) GetAuditorIdentity 

func (w *AuditorWallet) GetAuditorIdentity() (Identity, error)

GetAuditorIdentity returns the underlying auditor identity for this wallet. It never fails in the current implementation.

func (*AuditorWallet) GetSigner 

func (w *AuditorWallet) GetSigner(ctx context.Context, identity Identity) (Signer, error)

GetSigner returns a signer for the given identity if the identity belongs to this wallet; otherwise it returns an error.

func (*AuditorWallet) ID 

func (w *AuditorWallet) ID() string

ID returns the wallet identifier.

type CertifierWallet 

type CertifierWallet struct {
	WalletID string
	Identity Identity
	Signer   Signer
}

CertifierWallet represents a wallet bounded to a single certifier identity. It provides access to a signer and exposes whether a given identity is the certifier for this wallet.

func NewCertifierWallet 

func NewCertifierWallet(walletID string, identity Identity, signer Signer) *CertifierWallet

NewCertifierWallet creates a new CertifierWallet for the provided certifier identity.

func (*CertifierWallet) Contains 

func (w *CertifierWallet) Contains(ctx context.Context, identity Identity) bool

Contains reports whether the given identity belongs to the certifier identity for this wallet.

func (*CertifierWallet) ContainsToken 

func (w *CertifierWallet) ContainsToken(ctx context.Context, token *token.UnspentToken) bool

ContainsToken returns true if the token is owned by the certifier identity associated with this wallet.

func (*CertifierWallet) GetCertifierIdentity 

func (w *CertifierWallet) GetCertifierIdentity() (Identity, error)

GetCertifierIdentity returns the certifier identity this wallet manages.

func (*CertifierWallet) GetSigner 

func (w *CertifierWallet) GetSigner(ctx context.Context, identity Identity) (Signer, error)

GetSigner returns a signer for the certifier identity if it belongs to this wallet. Returns an error otherwise.

func (*CertifierWallet) ID 

func (w *CertifierWallet) ID() string

ID returns the certifier wallet identifier.

type DefaultFactory 

type DefaultFactory struct {
	Logger               logging.Logger
	IdentityProvider     IdentityProvider
	TokenVault           TokenVault
	WalletsConfiguration WalletsConfiguration
	Deserializer         Deserializer
	MetricsProvider      metrics.Provider
}

DefaultFactory creates wallets for the default role.

func NewDefaultFactory 

func NewDefaultFactory(
	logger logging.Logger,
	identityProvider driver.IdentityProvider,
	tokenVault TokenVault,
	walletsConfiguration WalletsConfiguration,
	deserializer Deserializer,
	metricsProvider metrics.Provider,
) *DefaultFactory

NewDefaultFactory creates a new DefaultFactory.

func (*DefaultFactory) NewWallet 

func (w *DefaultFactory) NewWallet(ctx context.Context, id idriver.WalletID, role idriver.IdentityRoleType, wr IdentitySupport, info idriver.IdentityInfo) (driver.Wallet, error)

type Deserializer 

type Deserializer = driver.Deserializer

type Identity 

type Identity = driver.Identity

Identity represents a generic identity. It is modeled as a byte slice.

type IdentityProvider 

type IdentityProvider = driver.IdentityProvider

IdentityProvider is a type alias for IdentityProvider. It exposes identity-related operations that wallets need (signers, verifiers, audit info, registry operations, etc.). Using a type alias keeps the code shorter while preserving the underlying interface contract.

type IdentitySupport 

type IdentitySupport interface {
	BindIdentity(ctx context.Context, identity driver.Identity, eID string, wID idriver.WalletID, meta any) error
	ContainsIdentity(ctx context.Context, i driver.Identity, id string) bool
}

type IssuerTokenVault 

type IssuerTokenVault interface {
	ListHistoryIssuedTokens(context.Context) (*token.IssuedTokens, error)
}

IssuerTokenVault provides a minimal view of a vault used by issuer wallets: the ability to list history of issued tokens. This is different from the owner vault in that it exposes issued token history instead of unspent token queries.

type IssuerWallet 

type IssuerWallet struct {
	Logger     logging.Logger
	TokenVault IssuerTokenVault
	WalletID   string
	Identity   Identity
	Signer     Signer
}

IssuerWallet represents a wallet that manages a single issuer identity. Issuer wallets can enumerate tokens that were issued by the wallet's identity and obtain signers to sign issuance transactions.

func NewIssuerWallet 

func NewIssuerWallet(
	logger logging.Logger,
	tokenVault IssuerTokenVault,
	id string,
	identity Identity,
	signer Signer,
) *IssuerWallet

NewIssuerWallet constructs an IssuerWallet bound to the given issuer identity and backed by the provided token vault and identity provider.

func (*IssuerWallet) Contains 

func (w *IssuerWallet) Contains(_ context.Context, identity Identity) bool

Contains reports whether the given identity belongs to this issuer wallet. The context parameter is provided for API compatibility.

func (*IssuerWallet) ContainsToken 

func (w *IssuerWallet) ContainsToken(ctx context.Context, token *token.UnspentToken) bool

ContainsToken returns true if the provided token is issued to an identity managed by this issuer wallet.

func (*IssuerWallet) GetIssuerIdentity 

func (w *IssuerWallet) GetIssuerIdentity(tokenType token.Type) (Identity, error)

GetIssuerIdentity returns the issuer identity for the requested token type. In this simple wallet the issuer identity does not vary by token type and is returned directly.

func (*IssuerWallet) GetSigner 

func (w *IssuerWallet) GetSigner(ctx context.Context, identity Identity) (Signer, error)

GetSigner returns a signer for the given identity if it belongs to this issuer wallet; otherwise an error is returned.

func (*IssuerWallet) HistoryTokens 

func (w *IssuerWallet) HistoryTokens(ctx context.Context, opts *driver.ListTokensOptions) (*token.IssuedTokens, error)

HistoryTokens returns the history of tokens issued by this wallet that match the provided listing options. It filters by token type and verifies that tokens belong to this wallet's issuer identity.

func (*IssuerWallet) ID 

func (w *IssuerWallet) ID() string

ID returns the issuer wallet identifier.

type LocalMembership 

type LocalMembership interface {
	DefaultNetworkIdentity() driver.Identity
	IsMe(ctx context.Context, id driver.Identity) bool
	GetIdentityInfo(ctx context.Context, label string, auditInfo []byte) (idriver.IdentityInfo, error)
	GetIdentifier(ctx context.Context, id driver.Identity) (string, error)
	GetDefaultIdentifier() string
	RegisterIdentity(ctx context.Context, config driver.IdentityConfiguration) error
	IDs() ([]string, error)
	Close()
}

LocalMembership abstracts the local identity/membership service used by a Role. The Role relies on this interface to lookup identities, identifiers and to register identities. The concrete implementation is provided by the local membership/identity provider and a counterfeiter-generated fake exists under `mock` for unit tests.

type LongTermOwnerWallet 

type LongTermOwnerWallet struct {
	IdentityProvider  IdentityProvider
	TokenVault        OwnerTokenVault
	WalletID          idriver.WalletID
	OwnerIdentityInfo idriver.IdentityInfo
	OwnerIdentity     Identity
	OwnerAuditInfo    []byte
}

LongTermOwnerWallet is the representation of a wallet that holds a long-term owner identity (potentially a real, non-pseudonymous identity). It provides methods to list tokens, check balances, and obtain recipient data and signers. The wallet binds to an identity.Info which can produce pseudonyms or other identities when required.

func NewLongTermOwnerWallet 

func NewLongTermOwnerWallet(
	ctx context.Context,
	IdentityProvider IdentityProvider,
	TokenVault OwnerTokenVault,
	id idriver.WalletID,
	identityInfo idriver.IdentityInfo,
) (*LongTermOwnerWallet, error)

NewLongTermOwnerWallet constructs a LongTermOwnerWallet by resolving the provided identity.Info into an actual Identity and its audit info.

func (*LongTermOwnerWallet) Balance 

func (w *LongTermOwnerWallet) Balance(ctx context.Context, opts *driver.ListTokensOptions) (*big.Int, error)

Balance returns the on-chain balance for the wallet for the given token type in the listing options. The result is returned as a *big.Int to support arbitrary precision and prevent overflow.

func (*LongTermOwnerWallet) Contains 

func (w *LongTermOwnerWallet) Contains(ctx context.Context, identity Identity) bool

Contains reports whether the provided identity is the long-term owner identity bound to this wallet.

func (*LongTermOwnerWallet) ContainsToken 

func (w *LongTermOwnerWallet) ContainsToken(ctx context.Context, token *token.UnspentToken) bool

ContainsToken returns true if the token is owned by the long-term owner identity managed by this wallet.

func (*LongTermOwnerWallet) EnrollmentID 

func (w *LongTermOwnerWallet) EnrollmentID() string

EnrollmentID returns the enrollment id associated with the underlying identity info.

func (*LongTermOwnerWallet) GetAuditInfo 

func (w *LongTermOwnerWallet) GetAuditInfo(ctx context.Context, id Identity) ([]byte, error)

GetAuditInfo delegates to the identity provider to fetch audit info for the supplied identity.

func (*LongTermOwnerWallet) GetRecipientData 

func (w *LongTermOwnerWallet) GetRecipientData(context.Context) (*driver.RecipientData, error)

GetRecipientData returns the recipient data (identity + audit info) associated with the long-term owner identity.

func (*LongTermOwnerWallet) GetRecipientIdentity 

func (w *LongTermOwnerWallet) GetRecipientIdentity(context.Context) (Identity, error)

GetRecipientIdentity returns the owner identity used as a recipient in transfer operations.

func (*LongTermOwnerWallet) GetSigner 

func (w *LongTermOwnerWallet) GetSigner(ctx context.Context, identity Identity) (Signer, error)

GetSigner returns a signer for the provided identity if it belongs to this long-term owner wallet; otherwise an error is returned.

func (*LongTermOwnerWallet) GetTokenMetadata 

func (w *LongTermOwnerWallet) GetTokenMetadata(id Identity) ([]byte, error)

GetTokenMetadata returns associated token metadata for the given owner identity. Not implemented in the current wallet and returns nil.

func (*LongTermOwnerWallet) GetTokenMetadataAuditInfo 

func (w *LongTermOwnerWallet) GetTokenMetadataAuditInfo(id Identity) ([]byte, error)

GetTokenMetadataAuditInfo returns audit info for token metadata. Not implemented in the current wallet and returns nil.

func (*LongTermOwnerWallet) ID 

func (w *LongTermOwnerWallet) ID() string

ID returns the wallet identifier for the long-term owner wallet.

func (*LongTermOwnerWallet) ListTokens 

func (w *LongTermOwnerWallet) ListTokens(ctx context.Context, opts *driver.ListTokensOptions) (*token.UnspentTokens, error)

ListTokens returns all unspent tokens for the wallet matching the provided listing options.

func (*LongTermOwnerWallet) ListTokensIterator 

func (w *LongTermOwnerWallet) ListTokensIterator(ctx context.Context, opts *driver.ListTokensOptions) (driver.UnspentTokensIterator, error)

ListTokensIterator returns an iterator to scan unspent tokens instead of materializing them in memory.

func (*LongTermOwnerWallet) RegisterRecipient 

func (w *LongTermOwnerWallet) RegisterRecipient(ctx context.Context, data *driver.RecipientData) error

RegisterRecipient registers recipient data (identity + audit info). The long-term owner wallet currently has a no-op implementation here and returns nil. The TODO indicates where custom logic would be added.

func (*LongTermOwnerWallet) Remote 

func (w *LongTermOwnerWallet) Remote() bool

Remote reports whether the underlying identity info is remote.

type Metrics 

type Metrics struct {
	CacheLevelGauge metrics.Gauge
}

Metrics contains the metrics for this package

func NewMetrics 

func NewMetrics(p metrics.Provider) *Metrics

NewMetrics instantiate the metrics for this package

type OwnerTokenVault 

type OwnerTokenVault interface {
	UnspentTokensIteratorBy(ctx context.Context, id string, tokenType token.Type) (UnspentTokensIterator, error)
	Balance(ctx context.Context, id string, tokenType token.Type) (*big.Int, error)
}

OwnerTokenVault provides the minimal token-vault operations needed by owner wallets: the ability to iterate unspent tokens for a given owner (by id) and to query the balance for a specific token type. Implementations are expected to return an UnspentTokensIterator that can be consumed by the wallet logic.

type RecipientDataBackendFunc 

type RecipientDataBackendFunc func(ctx context.Context) (*driver.RecipientData, error)

type RecipientDataCache 

type RecipientDataCache struct {
	Logger logging.Logger
	// contains filtered or unexported fields
}

func NewRecipientDataCache 

func NewRecipientDataCache(Logger logging.Logger, backed RecipientDataBackendFunc, size int, metrics *Metrics) *RecipientDataCache

func (*RecipientDataCache) RecipientData 

func (c *RecipientDataCache) RecipientData(ctx context.Context) (*driver.RecipientData, error)

type Registry 

type Registry struct {
	Logger  logging.Logger
	Role    idriver.Role
	Storage idriver.WalletStoreService

	WalletFactory WalletFactory
	WalletMu      sync.RWMutex
	Wallets       map[string]driver.Wallet
}

Registry manages wallets whose long-term identities have a given role.

Concurrency and invariants:

  • The Wallets map MUST only be accessed while holding WalletMu. Use WalletMu.RLock()/RUnlock() for short read-only access and WalletMu.Lock()/Unlock() for modifications. Methods in this file follow the pattern of taking short RLocks for map reads and never holding locks while calling out to external services (identity provider, storage, wallet factory) to avoid blocking and potential deadlocks.

func NewRegistry 

func NewRegistry(logger logging.Logger, role idriver.Role, storage idriver.WalletStoreService, walletFactory WalletFactory) *Registry

NewRegistry returns a new registry for the passed parameters. A registry is bound to a given role, and it is persistent.

func (*Registry) BindIdentity 

func (r *Registry) BindIdentity(ctx context.Context, identity driver.Identity, eID string, wID idriver.WalletID, meta any) error

BindIdentity binds the passed identity to the passed wallet identifier. Additional metadata can be bound to the identity.

func (*Registry) ContainsIdentity 

func (r *Registry) ContainsIdentity(ctx context.Context, identity driver.Identity, wID string) bool

ContainsIdentity returns true if the passed identity belongs to the passed wallet, false otherwise

func (*Registry) Done 

func (r *Registry) Done() error

Done releases all the resources allocated by this service.

func (*Registry) GetIdentityMetadata 

func (r *Registry) GetIdentityMetadata(ctx context.Context, identity driver.Identity, wID string, meta any) error

GetIdentityMetadata loads metadata bound to the passed identity into the passed meta argument

func (*Registry) GetWalletID 

func (r *Registry) GetWalletID(ctx context.Context, identity driver.Identity) (string, error)

GetWalletID returns the wallet identifier bound to the passed identity

func (*Registry) Lookup 

func (r *Registry) Lookup(ctx context.Context, id driver.WalletLookupID) (driver.Wallet, idriver.IdentityInfo, idriver.WalletID, error)

Lookup searches the wallet corresponding to the passed id. If a wallet is found, Lookup returns the wallet and its identifier. If no wallet is found, Lookup returns the identity info and a potential wallet identifier for the passed id, if anything is found

The lookup strategy is multi-step: 1. Ask the role provider to MapToIdentity (identity, walletID). If that errors, fall back to toViewIdentity/GetWalletID. 2. Check the in-memory cache (r.Wallets) for wallet entries. Map reads are protected by WalletMu.RLock for a short duration. 3. If cache misses, try to resolve identity -> wallet id using storage/role and finally call role.GetIdentityInfo for any discovered wallet identifiers.

Note: Lookup only takes short RLocks for map reads and does not hold the lock while calling external services.

func (*Registry) RegisterIdentity 

func (r *Registry) RegisterIdentity(ctx context.Context, config driver.IdentityConfiguration) error

func (*Registry) RegisterWallet 

func (r *Registry) RegisterWallet(ctx context.Context, id string, w driver.Wallet) error

RegisterWallet binds the passed wallet to the passed id

func (*Registry) WalletByID 

func (r *Registry) WalletByID(ctx context.Context, role idriver.IdentityRoleType, id driver.WalletLookupID) (driver.Wallet, error)

func (*Registry) WalletIDs 

func (r *Registry) WalletIDs(ctx context.Context) ([]string, error)

WalletIDs returns the list of wallet identifiers

type Role 

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

Role models a role whose identities are anonymous. A Role delegates identity resolution to the LocalMembership implementation. It exposes mapping helpers that accept either a string identifier, a driver.Identity or raw []byte and returns either a long-term identity (driver.Identity) and/or an identifier string used by the token subsystem.

func NewRole 

func NewRole(
	logger logging.Logger,
	roleID idriver.IdentityRoleType,
	networkID string,
	nodeIdentity driver.Identity,
	localMembership LocalMembership,
) *Role

func (*Role) Done 

func (r *Role) Done() error

Done releases all the resources allocated by this service.

func (*Role) GetIdentityInfo 

func (r *Role) GetIdentityInfo(ctx context.Context, id string) (idriver.IdentityInfo, error)

GetIdentityInfo returns the identity information for the given identity identifier. It simply forwards the call to the LocalMembership and annotates any returned error with the network context for easier diagnosis.

func (*Role) ID 

func (r *Role) ID() idriver.IdentityRoleType

ID returns the role identifier (RoleType) for this Role instance.

func (*Role) IdentityIDs 

func (r *Role) IdentityIDs() ([]string, error)

IdentityIDs returns the identifiers known to this Role (delegates to LocalMembership.IDs).

func (*Role) MapToIdentity 

func (r *Role) MapToIdentity(ctx context.Context, v driver.WalletLookupID) (driver.Identity, string, error)

MapToIdentity returns the identity for the given WalletLookupID argument. The WalletLookupID can be a string (label), []byte or driver.Identity. The method dispatches to helper functions that implement the mapping logic.

func (*Role) RegisterIdentity 

func (r *Role) RegisterIdentity(ctx context.Context, config driver.IdentityConfiguration) error

RegisterIdentity registers the given identity via the LocalMembership service.

type Roles 

type Roles map[driver.IdentityRoleType]driver.Role

Roles is a map of Role, one for each identity role

func NewRoles 

func NewRoles() Roles

NewRoles returns a new Roles maps

func (Roles) Register 

func (m Roles) Register(usage driver.IdentityRoleType, role driver.Role)

Register associates an instance of Role to a given identifier

func (Roles) Registries 

func (m Roles) Registries(logger logging.Logger, storage driver.WalletStoreService, walletFactory WalletFactory) map[driver.IdentityRoleType]*Registry

type Signer 

type Signer = driver.Signer

Signer is an interface which wraps the Sign method.

type TokenVault 

type TokenVault interface {
	UnspentTokensIteratorBy(ctx context.Context, id string, tokenType token.Type) (driver.UnspentTokensIterator, error)
	ListHistoryIssuedTokens(ctx context.Context) (*token.IssuedTokens, error)
	Balance(ctx context.Context, id string, tokenType token.Type) (*big.Int, error)
}

type UnspentTokensIterator 

type UnspentTokensIterator = driver.UnspentTokensIterator

UnspentTokensIterator defines an iterator over unspent tokens

type WalletFactory 

type WalletFactory interface {
	NewWallet(ctx context.Context, id idriver.WalletID, role idriver.IdentityRoleType, is IdentitySupport, info idriver.IdentityInfo) (driver.Wallet, error)
}

type WalletsConfiguration 

type WalletsConfiguration interface {
	CacheSizeForOwnerID(id string) int
}

Source Files

View all Source files

Directories

Path Synopsis
Code generated by counterfeiter.
 Code generated by counterfeiter.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.