How a subscription works

Checking amendment… Ready

A standing debit: the subscriber authorises the payee to pull up to Amount each Frequency period. Missed full periods accrue. Each Claim takes one period. Leftover of a started period is forfeited if you skip it. Three transactions: Set, Claim, Cancel.

Lab accounts

Each wallet is funded 100 XRP from genesis. Re-run setup if the ledger was wiped.

Subscriber

Subscription account. Pays. Signs Set and Cancel.

Not set

Bal - Obj -

Payee

Destination. The only account that may Claim.

Not set

Bal - Obj -

Token issuer

Issues RLUSD for the IOU path. Unused on XRP.

Not set

Bal - Obj -

Baseline

No subscription. Ordinary Payment for contrast.

Not set

Bal - Obj -

Subscriber signs SubscriptionSet with no SubscriptionID. The ledger creates the object and returns the id in metadata.

Asset XRP or IOU. Locked at create. Later claims must match. Amount Max the payee can pull each period. Frequency (Seconds) Length of one billing period. Must be > 0. Not a cooldown between claims: after a period is fully drained (or forfeited), the next period’s Amount becomes available. Immutable after create.

Start (Seconds) Delay before the first claim. 0 = after the next close. 12s demos too-soon. Expiration (Seconds) Optional end. Leave blank for none. Must be after Start. Then anyone may delete.

Subscriber signs SubscriptionSet with the existing SubscriptionID. Only Amount (same asset) and Expiration may change.

Asset Filled from the looked-up subscription. Change it to test a wrong-asset update. New amount New per-period cap. If lower than remaining Balance, Balance is cut to match. Expiration (Seconds) Leave blank to keep the current expiry. Seconds from now; must be after the next claim.

Payee signs SubscriptionClaim. Amount must be the same asset and ≤ remaining Balance. Partial claims leave the period open; draining Balance starts the next period. Catch-up is one period per Claim, not one Claim per ledger. Forfeit applies only when now ≥ NextClaimTime + Frequency and Balance < Amount.

Asset Filled from the looked-up subscription. Change it to test a wrong-asset claim. Claim amount How much to pull now. Cannot exceed remaining Balance.

Wait seconds until submit

Looks up NextClaimTime when a subscription is loaded. Ledgers close on the node timer. This is wall time, not a ledger count.

Signs SubscriptionCancel. Subscriber or payee may delete a live object. Reserve returns to the subscriber.

Signed by Either party may delete while it is live. After expiry, anyone may.

Two live walkthroughs on this fork. Each step submits for real. Activity keeps every fork result; Result shows only the last response. The XRP and IOU runs are a partial-drain demo: they do not show catch-up or expiry-delete.

Catch-up (manual)

Set Amount 5, Frequency 10s, no start delay.
Claim 1 (leave Balance 4). A partial does not close the period.
Wait more than one Frequency.
Claim 5: leftover 4 of the started period is forfeited; this Claim takes a fresh Amount and drains it.
Wait several more periods without claiming (or wait Frequency after each drain).
Claim 5, 5, 5… one period each time. Several Claims in one ledger only if those periods have already accrued. Claiming 4 against Amount 5 leaves Balance 1 and the next 4 is tecINSUFFICIENT_FUNDS.

Worked numbers with Amount = 5: partial 1 then four idle Claims of 5 is 21, not 25. Missing 4 is the forfeited leftover of the started period.

Expiration (manual)

Set with Expiration a few seconds out → Claim after that time → object deleted, subscriber reserve returned. That is one last pull, then gone. It is not “expired objects cannot be claimed”.

Current subscription No subscription loaded

SubscriptionID	-
Subscriber	-
Payee	-
Amount	-
Balance	-
Frequency	-
NextClaimTime	-
Expiration	-
Create Sequence	-
Parent close	-

No subscription loaded yet. Submit Set, or paste an id.

Unsigned

tx_json before submit

No TxnSignature. Fields above rewrite this payload.

{ }

Subscriber SubscriptionSet 10 XRP

Result

Latest fork response only.

{ }

Activity

Every submission, with the fork result. Kept in this browser. Drag the bottom edge to expand.

Notes from the live fork

· Official GitHub draft · · Defs snapshot
The proposal opened from this page is our revised XLS for this fork. GitHub master still says SendMax, stores StartTime/Data on the object, and Frequency ≥ 3600. This node does none of those.
Type codes 109 / 110 / 111, subscription object 146, from live server_definitions.
network_id is 0: omit NetworkID.
This node closes ledgers on a backend timer. Claim waits on NextClaimTime in seconds, not a number of ledgers.
Create without StartTime is claimable after the next close. Use Start +12s to demo tecTOO_SOON, then wait that many seconds before submit.
Partial claim lowers Balance; draining it rolls NextClaimTime by Frequency and resets Balance.
Subscriber Claim → tecNO_PERMISSION. Payee == subscriber → temDST_IS_SRC.
Accruing, not a rate limit. Frequency is the period length. You may submit several successful Claims in the same ledger if each one finishes a period (drain or forfeit). tecTOO_SOON only means now < NextClaimTime.
Catch-up. If the payee does not claim for N untouched periods, they may claim up to N times, each time taking up to Amount. Periods do not stack into one Claim.
Forfeit (partial only). If a period was partly claimed (Balance < Amount) and the payee waits until now ≥ NextClaimTime + Frequency, that leftover is discarded, NextClaimTime advances by one Frequency, Balance resets to Amount. Full unused periods are not forfeited by waiting.
Expiration. A successful Claim with now ≥ Expiration deletes the object and returns the subscriber’s reserve. That is one last pull, then gone. It is not “expired objects cannot be claimed”.
Worked numbers (Amount = 5). Partial 1 then four idle Claims of 5 is 21, not 25. Missing 4 is the forfeited leftover of the started period. Do not mix a cap of 5 with claims of 4: a partial does not close the period, so the next 4 finds Balance 1 and returns tecINSUFFICIENT_FUNDS (paid 5, not 17). Eight Claims in one ledger can be tesSUCCESS when each Claim fully drains a period that has already accrued. After 129 untouched periods idle, 25 Claims of 5 is the catch-up, not a bug.

How a subscription works

Set

Claim

Cancel

Lab accounts

XRP path

IOU path

Catch-up (manual)

Expiration (manual)

tx_json before submit