walt/tables/channels

channels

one payment channel per provider. many calls, few settlements.

definition

voucher = sign(walt_key, [channel, cumulative_amount, nonce])

require cumulative_amount > channel.watermark
channel.watermark = cumulative_amount

what it is

paying for every call with its own transfer is slow and wasteful when calls are small. for a provider walt uses often, it opens a channel: usdc is deposited once, and each call is paid with a signed voucher instead of a transfer.

a voucher states the total paid so far in that channel, not the price of one call. each new voucher is larger than the last. the provider can claim on chain at any time by presenting the newest one, and the program moves the channel's watermark up to that total.

only walt's key can sign a voucher that raises the total. a facilitator can close a channel at the current watermark but cannot send the funds anywhere else. when a channel closes, whatever was deposited and never claimed leaves the channel and is burned as coin.

what moves the watermark

instructionsignereffect
open_channelwaltdeposit usdc, watermark starts at zero
claim_channelprovider or facilitator present newest voucher, watermark rises to its total
close_channelwalt or facilitatorpay out up to the watermark, burn the rest as coin

notes

the watermark is the only number about a channel that lives on chain. the vouchers themselves stay between walt and the provider until one is claimed.

a ticket paid through a channel still gets its own receipt. the receipt names the voucher's nonce in place of a settlement signature.

figure

the parts of a channel. the filled part can only grow.

columns

columntypemeaning
providerpubkeywho the channel pays
depositedu64usdc placed in the channel
watermarku64highest total claimed so far
nonceu64nonce of the newest claimed voucher
callsu64calls paid through the channel
statusu80 open, 1 closed
walt/tables/channels: the settled amount on chain only rises.