Help us shape the future of Go! Take the 2026 Go Developer Survey

tempo

package
v0.1.0 Latest Latest
Warning

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

Go to latest
Published: May 2, 2026 License: MIT, Apache-2.0, MIT Imports: 17 Imported by: 0

Documentation

Overview

Package tempo contains the Tempo-specific charge method built on top of the generic pkg/client and pkg/server HTTP 402 flow, including request helpers, attribution utilities, and replay stores for single-process and Redis-backed deployments.

Index

Constants

View Source
const (
	// MethodName is the Tempo payment method token.
	MethodName = "tempo"
	// IntentCharge is the Tempo charge intent token.
	IntentCharge = "charge"
	// DefaultDecimals is the default TIP-20 decimal precision used for charges.
	DefaultDecimals = 6
	// DefaultGasLimit is the fallback gas limit when estimation is unavailable.
	DefaultGasLimit = uint64(1_000_000)
	// FeePayerWindow is the client-side validity window used for sponsored charges.
	FeePayerWindow = 25 * time.Second
	// ReplayKeyPrefix is the storage namespace for charge replay protection.
	ReplayKeyPrefix = "mppx:charge:"
	// TransferSelector is the TIP-20 transfer selector.
	TransferSelector = "a9059cbb"
	// TransferWithMemoSelector is the Tempo transfer-with-memo selector.
	TransferWithMemoSelector = "95777d59"
	// MainnetUSDCAddress is Circle's USDC contract on Tempo mainnet.
	MainnetUSDCAddress = "0x20C000000000000000000000b9537d11c60E8b50"
)

Variables

View Source
var (
	// TransferTopic is the TIP-20 Transfer event topic hash.
	TransferTopic = crypto.Keccak256Hash([]byte("Transfer(address,address,uint256)"))
	// TransferWithMemoTopic is the Tempo TransferWithMemo event topic hash.
	TransferWithMemoTopic = crypto.Keccak256Hash([]byte("TransferWithMemo(address,address,uint256,bytes32)"))
)
View Source
var ExpiringNonceKey = new(big.Int).Sub(new(big.Int).Lsh(big.NewInt(1), 256), big.NewInt(1))

ExpiringNonceKey is the reserved nonce key used for fee-payer transactions.

Functions

func ChargeProofStoreKey

func ChargeProofStoreKey(challengeID string) string

ChargeProofStoreKey normalizes a replay-protection key for a Tempo proof credential.

func ChargeSponsoredChallengeStoreKey

func ChargeSponsoredChallengeStoreKey(challengeID string) string

ChargeSponsoredChallengeStoreKey normalizes a replay-protection key for a sponsored Tempo challenge.

func ChargeStoreKey

func ChargeStoreKey(hash string) string

ChargeStoreKey normalizes a replay-protection key for a Tempo transaction hash.

func DefaultCurrencyForChain

func DefaultCurrencyForChain(chainID int64) string

DefaultCurrencyForChain returns the default stablecoin used for charges on a chain.

func DefaultRPCURLForChain

func DefaultRPCURLForChain(chainID int64) string

DefaultRPCURLForChain returns the canonical Tempo RPC URL for a chain ID.

func EncodeAttribution

func EncodeAttribution(serverID, clientID, challengeID string) string

EncodeAttribution builds the 32-byte Tempo attribution memo for a Challenge.

func EncodeTransfer

func EncodeTransfer(recipient string, amount *big.Int) string

EncodeTransfer builds TIP-20 transfer calldata for the supplied recipient and amount.

func EncodeTransferWithMemo

func EncodeTransferWithMemo(recipient string, amount *big.Int, memo string) (string, error)

EncodeTransferWithMemo builds Tempo transfer-with-memo calldata for the supplied values.

func InferChainIDFromRPCURL

func InferChainIDFromRPCURL(rpcURL string) int64

InferChainIDFromRPCURL maps known Tempo RPC URLs back to their chain IDs. It returns 0 when the URL does not match a known Tempo endpoint.

func IsAttributionMemo

func IsAttributionMemo(memo string) bool

IsAttributionMemo reports whether a memo uses the Tempo attribution layout.

func IsKnownChainID

func IsKnownChainID(chainID int64) bool

IsKnownChainID reports whether the chain ID maps to a built-in Tempo network.

func MatchTransferCalldata

func MatchTransferCalldata(dataHex string, request ChargeRequest, realm, challengeID string) bool

MatchTransferCalldata reports whether calldata satisfies the canonical Tempo charge transfer.

func ParseHexBigInt

func ParseHexBigInt(value string) (*big.Int, error)

ParseHexBigInt decodes a JSON-RPC hex integer into a big.Int.

func ParseHexUint64

func ParseHexUint64(value string) (uint64, error)

ParseHexUint64 decodes a JSON-RPC hex integer into uint64.

func ParseTopicAddress

func ParseTopicAddress(topic string) string

ParseTopicAddress extracts the address stored in an indexed log topic.

func ProofSource

func ProofSource(chainID int64, address common.Address) string

ProofSource formats the canonical did:pkh source used by Tempo proof credentials.

func ProofTypedDataHash

func ProofTypedDataHash(chainID int64, challengeID, realm string) (common.Hash, error)

ProofTypedDataHash returns the EIP-712 digest for a Tempo proof credential.

func RPCURLForChain

func RPCURLForChain(chainID int64) (string, error)

RPCURLForChain returns the canonical Tempo RPC URL for a known chain ID. Chain ID 0 falls back to mainnet defaults.

func VerifyAttributionChallenge

func VerifyAttributionChallenge(memo, challengeID string) bool

VerifyAttributionChallenge reports whether a memo matches a specific Challenge ID.

func VerifyAttributionServer

func VerifyAttributionServer(memo, serverID string) bool

VerifyAttributionServer reports whether a memo matches the Challenge realm fingerprint.

Types

type ChargeCredentialPayload

type ChargeCredentialPayload struct {
	// Type selects the payload variant.
	Type CredentialType
	// Hash stores the submitted transaction hash for push flows.
	Hash string
	// Signature stores the raw transaction or proof signature.
	Signature string
}

ChargeCredentialPayload is the Tempo-specific payload carried by a Credential.

func ParseChargeCredentialPayload

func ParseChargeCredentialPayload(input map[string]any) (ChargeCredentialPayload, error)

ParseChargeCredentialPayload parses a generic payload map into a Tempo payload.

func (ChargeCredentialPayload) Map

func (p ChargeCredentialPayload) Map() map[string]any

Map converts a Tempo payload back into the generic Credential payload shape.

type ChargeMode

type ChargeMode string

ChargeMode declares which Tempo credential flow a challenge accepts.

const (
	// ChargeModePull allows clients to return a signed transaction credential.
	ChargeModePull ChargeMode = "pull"
	// ChargeModePush allows clients to broadcast first and return a hash credential.
	ChargeModePush ChargeMode = "push"
)

type ChargeRequest

type ChargeRequest struct {
	// Amount is the canonical base-unit amount.
	Amount string
	// Currency is the token contract address.
	Currency string
	// Recipient is the primary payee address.
	Recipient string
	// Description is a human-readable challenge description.
	Description string
	// ExternalID is application metadata echoed into receipts.
	ExternalID string
	// MethodDetails stores Tempo-specific extensions for the charge.
	MethodDetails MethodDetails
}

ChargeRequest is the canonical Tempo request shape embedded in a Challenge.

func NormalizeChargeRequest

func NormalizeChargeRequest(params ChargeRequestParams) (ChargeRequest, error)

NormalizeChargeRequest validates request parameters and produces the canonical Tempo shape.

func ParseChargeRequest

func ParseChargeRequest(input map[string]any) (ChargeRequest, error)

ParseChargeRequest parses a generic request map into the canonical Tempo shape.

func (ChargeRequest) Allows

func (r ChargeRequest) Allows(credentialType CredentialType) bool

Allows reports whether the request accepts the supplied credential type.

func (ChargeRequest) Map

func (r ChargeRequest) Map() map[string]any

Map converts a ChargeRequest into the generic request map embedded in a Challenge.

type ChargeRequestParams

type ChargeRequestParams struct {
	// Amount is the human-readable decimal amount.
	Amount string
	// Currency is the token contract address.
	Currency string
	// Recipient is the primary payee address.
	Recipient string
	// Decimals controls how Amount values are converted to base units.
	Decimals int
	// Description is copied into the challenge for display.
	Description string
	// ExternalID is opaque application metadata echoed into receipts.
	ExternalID string
	// ChainID binds the charge to a specific Tempo chain when set.
	ChainID int64
	// FeePayer enables the sponsored transaction flow.
	FeePayer bool
	// FeePayerURL points at a remote fee-payer signer.
	FeePayerURL string
	// Memo overrides the default attribution memo for the primary transfer.
	Memo string
	// Splits lists any additional transfers included in the charge.
	Splits []SplitParams
	// SupportedModes restricts which credential submission modes are allowed.
	SupportedModes []ChargeMode
}

ChargeRequestParams are the human-friendly inputs used to build a ChargeRequest.

type CredentialType

type CredentialType string

CredentialType identifies the Tempo credential payload shape.

const (
	// CredentialTypeTransaction carries a signed Tempo transaction.
	CredentialTypeTransaction CredentialType = "transaction"
	// CredentialTypeHash carries a submitted Tempo transaction hash.
	CredentialTypeHash CredentialType = "hash"
	// CredentialTypeProof carries a zero-amount proof signature.
	CredentialTypeProof CredentialType = "proof"
)

type MemoryStore

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

MemoryStore is the default in-process replay-protection store.

func NewMemoryStore

func NewMemoryStore() *MemoryStore

NewMemoryStore constructs an in-memory replay-protection store.

func (*MemoryStore) Delete

func (s *MemoryStore) Delete(_ context.Context, key string) error

Delete removes a replay-protection value.

func (*MemoryStore) Get

func (s *MemoryStore) Get(_ context.Context, key string) (string, bool, error)

Get loads a replay-protection value.

func (*MemoryStore) Put

func (s *MemoryStore) Put(_ context.Context, key, value string) error

Put stores a replay-protection value, replacing any existing entry.

func (*MemoryStore) PutIfAbsent

func (s *MemoryStore) PutIfAbsent(_ context.Context, key, value string) (bool, error)

PutIfAbsent stores a replay-protection value only when the key is unused.

type MethodDetails

type MethodDetails struct {
	// ChainID binds the charge to a specific Tempo chain when present.
	ChainID *int64
	// FeePayer enables the sponsored transaction flow.
	FeePayer bool
	// FeePayerURL points at a remote fee-payer signer.
	FeePayerURL string
	// Memo overrides the default attribution memo for the primary transfer.
	Memo string
	// Splits lists any additional transfers included in the charge.
	Splits []Split
	// SupportedModes restricts which credential submission modes are allowed.
	SupportedModes []ChargeMode
}

MethodDetails holds Tempo-specific request fields nested under methodDetails.

type RPCClient

type RPCClient interface {
	GetChainID(ctx context.Context) (uint64, error)
	GetTransactionCount(ctx context.Context, address string) (uint64, error)
	SendRawTransaction(ctx context.Context, serializedTx string) (string, error)
	SendRequest(ctx context.Context, method string, params ...interface{}) (*temporpc.JSONRPCResponse, error)
}

RPCClient is the subset of Tempo JSON-RPC used by the charge flow.

func NewRPCClient

func NewRPCClient(rpcURL string) RPCClient

NewRPCClient constructs a Tempo JSON-RPC client.

type RedisStore

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

RedisStore implements Store with Redis commands.

func NewRedisStore

func NewRedisStore(client redis.Cmdable, ttl time.Duration) *RedisStore

NewRedisStore constructs a Redis-backed replay-protection store.

When ttl is zero, stored values do not expire automatically. PutIfAbsent always keeps replay-protection keys persistent so used payment proofs and hashes cannot become valid again after a TTL window.

func (*RedisStore) Delete

func (s *RedisStore) Delete(ctx context.Context, key string) error

Delete removes a replay-protection value.

func (*RedisStore) Get

func (s *RedisStore) Get(ctx context.Context, key string) (string, bool, error)

Get loads a replay-protection value.

func (*RedisStore) Put

func (s *RedisStore) Put(ctx context.Context, key, value string) error

Put stores a replay-protection value, replacing any existing entry.

func (*RedisStore) PutIfAbsent

func (s *RedisStore) PutIfAbsent(ctx context.Context, key, value string) (bool, error)

PutIfAbsent stores a replay-protection value only when the key is unused.

type Split

type Split struct {
	// Amount is the base-unit amount routed to this split recipient.
	Amount string
	// Memo is an optional split-specific Tempo memo.
	Memo string
	// Recipient is the split recipient address.
	Recipient string
}

Split is a canonical additional transfer nested under methodDetails.splits.

type SplitParams

type SplitParams struct {
	// Amount is the human-readable amount routed to this split recipient.
	Amount string
	// Memo is an optional split-specific Tempo memo.
	Memo string
	// Recipient is the split recipient address.
	Recipient string
}

SplitParams are the human-friendly inputs used to build a canonical Split.

type Store

type Store interface {
	// Get loads a replay-protection value.
	Get(ctx context.Context, key string) (value string, ok bool, err error)
	// Put stores a replay-protection value, replacing any existing entry.
	Put(ctx context.Context, key, value string) error
	// PutIfAbsent stores a replay-protection value only when the key is unused.
	PutIfAbsent(ctx context.Context, key, value string) (bool, error)
	// Delete removes a replay-protection value.
	Delete(ctx context.Context, key string) error
}

Store is the minimal replay-protection contract used by the Tempo charge verifier.

Unlike the verifier-specific helpers elsewhere in this package, Store stays close to common key-value backends so in-memory, Redis, and SQL-backed implementations can all satisfy the same interface. Implementations must not allow PutIfAbsent replay keys to become reusable after later expiry.

Directories

Path Synopsis
Package chargeclient contains the Tempo charge client method for creating Payment Credentials that satisfy Tempo HTTP 402 Challenges.
Package chargeclient contains the Tempo charge client method for creating Payment Credentials that satisfy Tempo HTTP 402 Challenges.
Package chargeserver contains the Tempo charge server method and verifier.
Package chargeserver contains the Tempo charge server method and verifier.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL