common

func AuditableRecipients ¶ added in v0.17.0

func AuditableRecipients(
	ctx context.Context,
	deserializer driver.Deserializer,
	walletService driver.WalletService,
	owner driver.Identity,
) ([]*driver.AuditableIdentity, error)

AuditableRecipients expands an output owner into the receivers to record in the action metadata, one entry per recipient with its own audit info.

A plain identity expands to itself, so this is a no-op for the common case. A composite owner (a policy or multisig identity) expands to its members: the auditing side rebuilds recipients from the ledger output and matches them positionally against this list, so recording the composite owner as a single receiver makes every composite recipient fail that match.

func AuditingSignaturesValidate ¶

func AuditingSignaturesValidate[P driver.PublicParameters, T driver.Input, TA driver.TransferAction, IA driver.IssueAction, DS driver.Deserializer](c context.Context, ctx *Context[P, T, TA, IA, DS]) error

AuditingSignaturesValidate validates the auditor signatures in the token request.

Auditor Signature Model:

The current implementation follows a 1-of-N auditor signature policy:

• If auditors are configured in the public parameters, at least one valid auditor signature must be present in the token request.
• Multiple auditor public keys may be configured (e.g., during key rotation).
• The validator verifies that each provided auditor signature corresponds to a configured auditor and that the signature is valid.
• The validator does NOT enforce N-of-N semantics.
• The validator does NOT enforce per-entity auditor checks.
• All configured auditor public keys are treated as belonging to a single logical auditor entity.

This behavior matches the semantics implemented by current token drivers.

func ExtractTokenIDsAndCheckDuplicates ¶

func ExtractTokenIDsAndCheckDuplicates(
	metadata *driver.TokenRequestMetadata,
	anchor driver.TokenRequestAnchor,
) ([]*token.ID, error)

ExtractTokenIDsAndCheckDuplicates extracts all token IDs from both transfer and issue actions in the metadata and checks for duplicates. Returns the list of unique token IDs or an error if duplicates are found.

This function is used by auditors to ensure that no token is spent multiple times within a single transaction.

func IsAnyNil ¶

func IsAnyNil[T any](args ...*T) bool

IsAnyNil returns true if any of the passed arguments is nil.

func IssueApplicationDataValidate ¶

func IssueApplicationDataValidate[P driver.PublicParameters, T driver.Input, TA driver.TransferAction, IA driver.IssueAction, DS driver.Deserializer](c context.Context, ctx *Context[P, T, TA, IA, DS]) error

IssueApplicationDataValidate accepts any metadata in the "pub" namespace. This gives the user of Panurus the option to attach public data to the token transaction.

func RetrieveAuditTokens ¶

func RetrieveAuditTokens(
	ctx context.Context,
	logger logging.Logger,
	queryEngine driver.QueryEngine,
	tokenIDs []*token.ID,
	anchor driver.TokenRequestAnchor,
	numRetries int,
	retryDelay time.Duration,
) (map[string]*token.Token, error)

RetrieveAuditTokens retrieves audit tokens from the query engine for the given token IDs and builds a map for efficient lookup. Returns the token map or an error if retrieval fails.

The returned map uses token ID pointers as keys, allowing callers to efficiently look up tokens by their ID during validation.

This function always returns a non-nil map (possibly empty) to ensure validation logic can distinguish between "no tokens requested" and "tokens not found".

numRetries and retryDelay control the tolerance for the pending-transaction read-timing race (see DefaultAuditTokensNumRetries / DefaultAuditTokensRetryDelay). A numRetries <= 0 is clamped to a single attempt.

func SelectIssuerForRedeem ¶

func SelectIssuerForRedeem(issuers []driver.Identity, opts *driver.TransferOptions) (driver.Identity, error)

SelectIssuerForRedeem returns the issuer's public key to use for a redeem. If opts specify an FSC issuer identity, then we expect to find in the opts also the public key to add in the transfer action. Otherwise, the first public key in the public params is used.

func TransferApplicationDataValidate ¶

func TransferApplicationDataValidate[P driver.PublicParameters, T driver.Input, TA driver.TransferAction, IA driver.IssueAction, DS driver.Deserializer](c context.Context, ctx *Context[P, T, TA, IA, DS]) error

TransferApplicationDataValidate accepts any metadata in the "pub" namespace. This gives the user of Panurus the option to attach public data to the token transaction.

func ValidateIssueActionTokenTypes ¶

func ValidateIssueActionTokenTypes(
	metadata *driver.IssueMetadata,
	auditTokens map[string]*token.Token,
) error

ValidateIssueActionTokenTypes ensures all inputs and outputs in an issue action have the same token type. It also validates that input tokens exist in the auditTokens map.

For issue actions with inputs (token upgrades/conversions), this validates that: - All input tokens exist in the audit token map - All inputs have the same token type - All outputs have the same token type as the inputs

This ensures token type consistency within an issue action.

func ValidateStructure ¶

func ValidateStructure(
	tokenRequest *driver.TokenRequest,
	tokenRequestMetadata *driver.TokenRequestMetadata,
	txID driver.TokenRequestAnchor,
) error

ValidateStructure ensures complete structural correspondence between TokenRequest and TokenRequestMetadata. It validates that: - Action counts match between request and metadata - Each action has corresponding metadata with correct type - ActionIDs are sequential and match their position - Action types align with metadata types (no mixed metadata)

This validation ensures that the request and metadata are structurally consistent before performing deeper semantic validation.

func ValidateTransferActionTokenTypes ¶

func ValidateTransferActionTokenTypes(
	metadata *driver.TransferMetadata,
	auditTokens map[string]*token.Token,
	validateValueSum bool,
	precision uint64,
) error

ValidateTransferActionTokenTypes ensures all inputs and outputs in a transfer action have the same token type. It also validates that input tokens exist in the auditTokens map.

When validateValueSum is true (for privacy-preserving tokens like zkatdlog), this also validates that the sum of input values equals the sum of output values using the provided precision.

For transfer actions, this validates that: - auditTokens map is non-empty (required for validation) - All input tokens exist in the audit token map - All inputs have the same token type - All outputs have the same token type as the inputs - (Optional) Sum of input values equals sum of output values

This ensures token type consistency and value conservation within a transfer action.