uma

package
v1.0.2 Latest Latest
Warning

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

 Go to latest Published: May 6, 2024 License: Apache-2.0 Imports: 20 Imported by: 1

Documentation

Index

Constants

View Source 
const MAJOR_VERSION = 1
View Source 
const MINOR_VERSION = 0

Variables

View Source 
var UmaProtocolVersion = fmt.Sprintf("%d.%d", MAJOR_VERSION, MINOR_VERSION)

Functions

func FetchPublicKeyForVasp 

func FetchPublicKeyForVasp(vaspDomain string, cache PublicKeyCache) (*protocol.PubKeyResponse, error)

FetchPublicKeyForVasp fetches the public key for another VASP.

If the public key is not in the cache, it will be fetched from the VASP's domain. The public key will be cached for future use.

NOTE: localhost domains will be fetched over HTTP for testing purposes, all other domains will be fetched over HTTPS.

Args: 

vaspDomain: the domain of the VASP.
cache: the PublicKeyCache cache to use. You can use the InMemoryPublicKeyCache struct, or implement your own persistent cache with any storage type.

func GenerateNonce 

func GenerateNonce() (*string, error)

func GetLnurlpResponse 

func GetLnurlpResponse(
	request protocol.LnurlpRequest,
	callback string,
	encodedMetadata string,
	minSendableSats int64,
	maxSendableSats int64,
	privateKeyBytes *[]byte,
	requiresTravelRuleInfo *bool,
	payerDataOptions *protocol.CounterPartyDataOptions,
	currencyOptions *[]protocol.Currency,
	receiverKycStatus *protocol.KycStatus,
	commentCharsAllowed *int,
	nostrPubkey *string,
) (*protocol.LnurlpResponse, error)

func GetPayReqResponse 

func GetPayReqResponse(
	request protocol.PayRequest,
	invoiceCreator InvoiceCreator,
	metadata string,
	receivingCurrencyCode *string,
	receivingCurrencyDecimals *int,
	conversionRate *float64,
	receiverFeesMillisats *int64,
	receiverChannelUtxos *[]string,
	receiverNodePubKey *string,
	utxoCallback *string,
	payeeData *protocol.PayeeData,
	receivingVaspPrivateKey *[]byte,
	payeeIdentifier *string,
	disposable *bool,
	successAction *map[string]string,
) (*protocol.PayReqResponse, error)

GetPayReqResponse Creates an uma pay request response with an encoded invoice.

Args: 

	query: the uma pay request.
	invoiceCreator: the object that will create the invoice.
	metadata: the metadata that will be added to the invoice's metadata hash field. Note that this should not include
	    the extra payer data. That will be appended automatically.
	receivingCurrencyCode: the code of the currency that the receiver will receive for this payment.
	receivingCurrencyDecimals: the number of decimal places in the specified currency. For example, USD has 2
		decimal places. This should align with the decimals field returned for the chosen currency in the LNURLP
		response.
	conversionRate: milli-satoshis per the smallest unit of the specified currency. This rate is committed to by the
    	receiving VASP until the invoice expires.
	receiverFeesMillisats: the fees charged (in millisats) by the receiving VASP to convert to the target currency.
	    This is separate from the conversion rate.
	receiverChannelUtxos: the list of UTXOs of the receiver's channels that might be used to fund the payment.
	receiverNodePubKey: If known, the public key of the receiver's node. If supported by the sending VASP's compliance provider,
        this will be used to pre-screen the receiver's UTXOs for compliance purposes.
	utxoCallback: the URL that the receiving VASP will call to send UTXOs of the channel that the receiver used to
    	receive the payment once it completes.
	payeeData: the payee data which was requested by the sender. Can be nil if no payee data was requested or is
		mandatory. The data provided does not need to include compliance data, as it will be added automatically.
	receivingVaspPrivateKey: the private key of the VASP that is receiving the payment. This will be used to sign the request.
	payeeIdentifier: the identifier of the receiver. For example, $bob@vasp2.com
	disposable: This field may be used by a WALLET to decide whether the initial LNURL link will be stored locally
		for later reuse or erased. If disposable is null, it should be interpreted as true, so if SERVICE intends
		its LNURL links to be stored it must return `disposable: false`. UMA should never return
		`disposable: false`. See LUD-11.
	successAction: an optional action that the wallet should take once the payment is complete. See LUD-09.

func GetPostTransactionCallback added in v1.0.0 

func GetPostTransactionCallback(
	utxos []protocol.UtxoWithAmount,
	vaspDomain string,
	signingPrivateKey []byte,
) (*protocol.PostTransactionCallback, error)

GetPostTransactionCallback Creates a signed post transaction callback.

Args: 

utxos: UTXOs of the channels of the VASP initiating the callback.
vaspDomain: the domain of the VASP initiating the callback.
signingPrivateKey: the private key of the VASP initiating the callback. This will be used to sign the request.

func GetPubKeyResponse added in v1.0.0 

func GetPubKeyResponse(
	signingCertChainPem string,
	encryptionCertChainPem string,
	expirationTimestamp *int64,
) (*protocol.PubKeyResponse, error)

GetPubKeyResponse Creates a public key response to be shared with the counterparty VASP.

Args: 

signingCertChainPem: The PEM-encoded certificate chain used to verify signatures from a VASP.
encryptionCertChainPem: The PEM-encoded certificate chain used to encrypt TR info sent to a VASP.
expirationTimestamp: Seconds since epoch at which these pub keys must be refreshed. It can be safely cached until this expiration (or forever if null).

func GetSignedLnurlpRequestUrl 

func GetSignedLnurlpRequestUrl(
	signingPrivateKey []byte,
	receiverAddress string,
	senderVaspDomain string,
	isSubjectToTravelRule bool,
	umaVersionOverride *string,
) (*url.URL, error)

GetSignedLnurlpRequestUrl Creates a signed uma request URL. Should only be used for UMA requests.

Args: 

signingPrivateKey: the private key of the VASP that is sending the payment. This will be used to sign the request.
receiverAddress: the address of the receiver of the payment (i.e. $bob@vasp2).
senderVaspDomain: the domain of the VASP that is sending the payment. It will be used by the receiver to fetch the public keys of the sender.
isSubjectToTravelRule: whether the sending VASP is a financial institution that requires travel rule information.
umaVersionOverride: the version of the UMA protocol to use. If not specified, the latest version will be used.

func GetSupportedMajorVersions 

func GetSupportedMajorVersions() []int

func GetSupportedMajorVersionsFromErrorResponseBody 

func GetSupportedMajorVersionsFromErrorResponseBody(errorResponseBody []byte) ([]int, error)

func GetUmaPayRequest added in v1.0.0 

func GetUmaPayRequest(
	amount int64,
	receiverEncryptionPubKey []byte,
	sendingVaspPrivateKey []byte,
	receivingCurrencyCode string,
	isAmountInReceivingCurrency bool,
	payerIdentifier string,
	umaMajorVersion int,
	payerName *string,
	payerEmail *string,
	trInfo *string,
	trInfoFormat *protocol.TravelRuleFormat,
	payerKycStatus protocol.KycStatus,
	payerUtxos *[]string,
	payerNodePubKey *string,
	utxoCallback string,
	requestedPayeeData *protocol.CounterPartyDataOptions,
	comment *string,
) (*protocol.PayRequest, error)

GetUmaPayRequest Creates a signed UMA pay request. For non-UMA LNURL requests, just construct a protocol.PayRequest directly.

Args: 

		amount: the amount of the payment in the smallest unit of the specified currency (i.e. cents for USD).
		receiverEncryptionPubKey: the public key of the receiver that will be used to encrypt the travel rule information.
		sendingVaspPrivateKey: the private key of the VASP that is sending the payment. This will be used to sign the request.
		receivingCurrencyCode: the code of the currency that the receiver will receive for this payment.
		isAmountInReceivingCurrency: whether the amount field is specified in the smallest unit of the receiving
			currency or in msats (if false).
		payerIdentifier: the identifier of the sender. For example, $alice@vasp1.com
		umaMajorVersion: the major version of UMA used for this request. If non-UMA, this version is still relevant
         for which LUD-21 spec to follow. For the older LUD-21 spec, this should be 0. For the newer LUD-21 spec,
         this should be 1.
		payerName: the name of the sender (optional).
		payerEmail: the email of the sender (optional).
		trInfo: the travel rule information. This will be encrypted before sending to the receiver.
		trInfoFormat: the standardized format of the travel rule information (e.g. IVMS). Null indicates raw json or a
			custom format, or no travel rule information.
		payerKycStatus: whether the sender is a KYC'd customer of the sending VASP.
		payerUtxos: the list of UTXOs of the sender's channels that might be used to fund the payment.
	 	payerNodePubKey: If known, the public key of the sender's node. If supported by the receiving VASP's compliance provider,
	        this will be used to pre-screen the sender's UTXOs for compliance purposes.
		utxoCallback: the URL that the receiver will call to send UTXOs of the channel that the receiver used to receive
			the payment once it completes.
		requestedPayeeData: the payer data options that the sender is requesting about the receiver.
		comment: a comment that the sender would like to include with the payment. This can only be included
	        if the receiver included the `commentAllowed` field in the lnurlp response. The length of
	        the comment must be less than or equal to the value of `commentAllowed`.

func GetVaspDomainFromUmaAddress 

func GetVaspDomainFromUmaAddress(umaAddress string) (string, error)

GetVaspDomainFromUmaAddress Gets the domain of the VASP from an uma address.

func IsUmaLnurlpQuery 

func IsUmaLnurlpQuery(url url.URL) bool

IsUmaLnurlpQuery Checks if the given URL is a valid UMA request. If this returns false, You should try to process the request as a regular LNURLp request to fall back to LNURL-PAY.

func IsVersionSupported 

func IsVersionSupported(version string) bool

func ParseLnurlpRequest 

func ParseLnurlpRequest(url url.URL) (*protocol.LnurlpRequest, error)

ParseLnurlpRequest Parse Parses the message into an LnurlpRequest object. Args: 

url: the full URL of the uma request.

func ParseLnurlpResponse 

func ParseLnurlpResponse(bytes []byte) (*protocol.LnurlpResponse, error)

func ParsePayReqResponse 

func ParsePayReqResponse(bytes []byte) (*protocol.PayReqResponse, error)

ParsePayReqResponse Parses the uma pay request response from a raw response body.

func ParsePayRequest 

func ParsePayRequest(bytes []byte) (*protocol.PayRequest, error)

func ParsePostTransactionCallback added in v1.0.0 

func ParsePostTransactionCallback(bytes []byte) (*protocol.PostTransactionCallback, error)

func SelectHighestSupportedVersion 

func SelectHighestSupportedVersion(otherVaspSupportedMajorVersions []int) *string

func SelectLowerVersion 

func SelectLowerVersion(version1String string, version2String string) (*string, error)

func VerifyPayReqResponseSignature added in v1.0.0 

func VerifyPayReqResponseSignature(
	response *protocol.PayReqResponse,
	otherVaspPubKeyResponse protocol.PubKeyResponse,
	nonceCache NonceCache,
	payerIdentifier string,
	payeeIdentifier string,
) error

VerifyPayReqResponseSignature Verifies the signature on an uma pay request response based on the public key of the VASP making the request.

Args: 

response: the signed response to verify.
otherVaspPubKeyResponse: the PubKeyResponse of the VASP making this request.
nonceCache: the NonceCache cache to use to prevent replay attacks.
payerIdentifier: the identifier of the sender. For example, $alice@vasp1.com
payeeIdentifier: the identifier of the receiver. For example, $bob@vasp2.com

func VerifyPayReqSignature 

func VerifyPayReqSignature(query *protocol.PayRequest, otherVaspPubKeyResponse protocol.PubKeyResponse, nonceCache NonceCache) error

VerifyPayReqSignature Verifies the signature on an uma pay request based on the public key of the VASP making the request.

Args: 

query: the signed query to verify.
otherVaspPubKeyResponse: the PubKeyResponse of the VASP making this request.
nonceCache: the NonceCache cache to use to prevent replay attacks.

func VerifyPostTransactionCallbackSignature added in v1.0.0 

func VerifyPostTransactionCallbackSignature(
	callback *protocol.PostTransactionCallback,
	otherVaspPubKeyResponse protocol.PubKeyResponse,
	nonceCache NonceCache,
) error

VerifyPostTransactionCallbackSignature Verifies the signature on a post transaction callback based on the public key of the counterparty VASP.

Args: 

callback: the signed callback to verify.
otherVaspPubKeyResponse: the PubKeyResponse of the VASP making this request.
nonceCache: the NonceCache cache to use to prevent replay attacks.

func VerifyUmaLnurlpQuerySignature 

func VerifyUmaLnurlpQuerySignature(query protocol.UmaLnurlpRequest, otherVaspPubKeyResponse protocol.PubKeyResponse, nonceCache NonceCache) error

VerifyUmaLnurlpQuerySignature Verifies the signature on an uma Lnurlp query based on the public key of the VASP making the request.

Args: 

query: the signed query to verify.
otherVaspPubKeyResponse: the PubKeyResponse of the VASP making this request in bytes.
nonceCache: the NonceCache cache to use to prevent replay attacks.

func VerifyUmaLnurlpResponseSignature 

func VerifyUmaLnurlpResponseSignature(response protocol.UmaLnurlpResponse, otherVaspPubKeyResponse protocol.PubKeyResponse, nonceCache NonceCache) error

VerifyUmaLnurlpResponseSignature Verifies the signature on an uma Lnurlp response based on the public key of the VASP making the request.

Args: 

response: the signed response to verify.
otherVaspPubKeyResponse: the PubKeyResponse of the VASP making this request in bytes.
nonceCache: the NonceCache cache to use to prevent replay attacks.

Types

type InMemoryNonceCache added in v0.6.2 

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

InMemoryNonceCache is an in-memory implementation of NonceCache. It is not recommended to use this in production, as it will not persist across restarts. You likely want to implement your own NonceCache that persists to a database of some sort.

func NewInMemoryNonceCache added in v0.6.2 

func NewInMemoryNonceCache(oldestValidTimestamp time.Time) *InMemoryNonceCache

func (*InMemoryNonceCache) CheckAndSaveNonce added in v0.6.2 

func (c *InMemoryNonceCache) CheckAndSaveNonce(nonce string, timestamp time.Time) error

func (*InMemoryNonceCache) PurgeNoncesOlderThan added in v0.6.2 

func (c *InMemoryNonceCache) PurgeNoncesOlderThan(timestamp time.Time)

type InMemoryPublicKeyCache 

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

func NewInMemoryPublicKeyCache 

func NewInMemoryPublicKeyCache() *InMemoryPublicKeyCache

func (*InMemoryPublicKeyCache) AddPublicKeyForVasp 

func (c *InMemoryPublicKeyCache) AddPublicKeyForVasp(vaspDomain string, pubKey *protocol.PubKeyResponse)

func (*InMemoryPublicKeyCache) Clear 

func (c *InMemoryPublicKeyCache) Clear()

func (*InMemoryPublicKeyCache) FetchPublicKeyForVasp 

func (c *InMemoryPublicKeyCache) FetchPublicKeyForVasp(vaspDomain string) *protocol.PubKeyResponse

func (*InMemoryPublicKeyCache) RemovePublicKeyForVasp 

func (c *InMemoryPublicKeyCache) RemovePublicKeyForVasp(vaspDomain string)

type InvoiceCreator added in v1.0.0 

type InvoiceCreator interface {
	CreateInvoice(amountMsats int64, metadata string) (*string, error)
}

type NonceCache added in v0.6.2 

type NonceCache interface {
	// CheckAndSaveNonce checks if the given nonce has been used before, and if not, saves it and returns nil.
	// If the nonce has been used before, or if timestamp is too old, returns an error.
	CheckAndSaveNonce(nonce string, timestamp time.Time) error

	// PurgeNoncesOlderThan purges all nonces older than the given timestamp.
	// This allows the cache to be pruned periodically while still preventing replay attacks by holding onto an earliest
	// timestamp that is still valid.
	PurgeNoncesOlderThan(timestamp time.Time)
}

NonceCache is an interface for a caching of nonces used in signatures. This is used to prevent replay attacks.

Implementations of this interface should be thread-safe.

type ParsedVersion 

type ParsedVersion struct {
	Major int
	Minor int
}

func GetHighestSupportedVersionForMajorVersion 

func GetHighestSupportedVersionForMajorVersion(majorVersion int) *ParsedVersion

func ParseVersion 

func ParseVersion(version string) (*ParsedVersion, error)

func (*ParsedVersion) String 

func (v *ParsedVersion) String() string

type PublicKeyCache 

type PublicKeyCache interface {
	// FetchPublicKeyForVasp fetches the public key entry for a VASP if in the cache, otherwise returns nil.
	FetchPublicKeyForVasp(vaspDomain string) *protocol.PubKeyResponse

	// AddPublicKeyForVasp adds a public key entry for a VASP to the cache.
	AddPublicKeyForVasp(vaspDomain string, pubKey *protocol.PubKeyResponse)

	// RemovePublicKeyForVasp removes a public key for a VASP from the cache.
	RemovePublicKeyForVasp(vaspDomain string)

	// Clear clears the cache.
	Clear()
}

PublicKeyCache is an interface for a cache of public keys for other VASPs.

Implementations of this interface should be thread-safe.

type UnsupportedVersionError 

type UnsupportedVersionError struct {
	UnsupportedVersion     string `json:"unsupportedVersion"`
	SupportedMajorVersions []int  `json:"supportedMajorVersions"`
}

func (UnsupportedVersionError) Error 

func (e UnsupportedVersionError) Error() string

Source Files

View all Source files

Directories

Path Synopsis

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.