Module dev_p4.erl

The HyperBEAM core payment ledger.

Description

This module allows the operator to specify another device that can act as a pricing mechanism for transactions on the node, as well as orchestrating a payment ledger to calculate whether the node should fulfil services for users.

The device requires the following node message settings in order to function:

• p4_pricing-device: The device that will estimate the cost of a request.
• p4_ledger-device: The device that will act as a payment ledger.

The pricing device should implement the following keys:

<code>GET /estimate?type=pre|post&body=[...]&request=RequestMessage</code><code>GET /price?type=pre|post&body=[...]&request=RequestMessage</code>

The body key is used to pass either the request or response messages to the device. The type key is used to specify whether the inquiry is for a request (pre) or a response (post) object. Requests carry lists of messages that will be executed, while responses carry the results of the execution. The price key may return infinity if the node will not serve a user under any circumstances. Else, the value returned by the price key will be passed to the ledger device as the amount key.

A ledger device should implement the following keys:

<code>POST /credit?message=PaymentMessage&request=RequestMessage</code><code>POST /charge?amount=PriceMessage&request=RequestMessage</code><code>GET /balance?request=RequestMessage</code>

The type key is optional and defaults to pre. If type is set to post, the charge must be applied to the ledger, whereas the pre type is used to check whether the charge would succeed before execution.

Function Index

balance/3	Get the balance of a user in the ledger.
faff_test/0*	Simple test of p4's capabilities with the faff@1.0 device.
hyper_token_ledger/0*
hyper_token_ledger_test_/0*	Ensure that Lua scripts can be used as pricing and ledger devices.
is_chargable_req/2*	The node operator may elect to make certain routes non-chargable, using the routes syntax also used to declare routes in router@1.0.
non_chargable_route_test/0*	Test that a non-chargable route is not charged for.
request/3	Estimate the cost of a transaction and decide whether to proceed with a request.
response/3	Postprocess the request after it has been fulfilled.
test_opts/1*
test_opts/2*
test_opts/3*

Function Details

balance/3

balance(X1, Req, NodeMsg) -> any()

Get the balance of a user in the ledger.

faff_test/0 *

faff_test() -> any()

Simple test of p4's capabilities with the faff@1.0 device.

hyper_token_ledger/0 *

hyper_token_ledger() -> any()

hyper_token_ledger_test_/0 *

hyper_token_ledger_test_() -> any()

Ensure that Lua scripts can be used as pricing and ledger devices. Our scripts come in two components: 1. A process script which is executed as a persistent local-process on the node, and which maintains the state of the ledger. This process runs hyper-token.lua as its base, then adds the logic of hyper-token-p4.lua to it. This secondary script implements the charge function that p4@1.0 will call to charge a user's account. 2. A client script, which is executed as a p4@1.0 ledger device, which uses ~push@1.0 to send requests to the ledger process.

is_chargable_req/2 *

is_chargable_req(Req, NodeMsg) -> any()

The node operator may elect to make certain routes non-chargable, using the routes syntax also used to declare routes in router@1.0.

non_chargable_route_test/0 *

non_chargable_route_test() -> any()

Test that a non-chargable route is not charged for.

request/3

request(State, Raw, NodeMsg) -> any()

Estimate the cost of a transaction and decide whether to proceed with a request. The default behavior if pricing-device or p4_balances are not set is to proceed, so it is important that a user initialize them.

response/3

response(State, RawResponse, NodeMsg) -> any()

Postprocess the request after it has been fulfilled.

test_opts/1 *

test_opts(Opts) -> any()

test_opts/2 *

test_opts(Opts, PricingDev) -> any()

test_opts/3 *

test_opts(Opts, PricingDev, LedgerDev) -> any()