Scheduled transfers
A scheduled transfer is a series of payments set up by a single transaction. The payer signs once, and the chain makes every payment when it falls due: a salary, a subscription, an allowance or the vesting of a grant. It can pay ZBC or any token.
Setting up a schedule
A ScheduledTransfer (type 29) has a 47-byte body that states:
| Field | Meaning |
|---|---|
| token id | the asset to pay; 0 means ZBC |
| amount | the amount of each payment |
| interval | the time between two payments, in seconds |
| number of payments | from 1 to 520 |
| cliff | an optional delay before the first payment |
| funding mode | 0 for vesting, 1 for pull (see below) |
| cancel policy | revocable or irrevocable |
| end time | optional |
The fee is paid once, when the schedule is created. Payments then follow the interval; each falls due by the previous block's timestamp, so a producer cannot stamp its block ahead of time to pull a payment into it.
Two funding modes
- Vesting (mode 0): the whole total is locked when the schedule is created and released one payment at a time. The recipient knows the money is really there.
- Pull (mode 1): nothing is locked. Each payment is taken from the payer's balance when it falls due. After four missed payments in a row, the schedule cancels itself.
Vesting payments pass through the recipient's split policy, like any incoming credit; pull payments do not (see split and transact policies).
Cancelling and redirecting
- CancelSchedule (type 30) ends a schedule. The payer may cancel it only if it is revocable. The recipient may cancel it at any time, which is how a recipient declines a schedule. When a vesting schedule is cancelled, whatever is still locked returns to the payer.
- ReassignSchedule (type 31) lets the recipient redirect the future payments to another address.
A transact policy is checked only against the recipient named in the ScheduledTransfer itself, so its later payments still reach a recipient that opts out of payments afterwards.
What a schedule does not do
A schedule does not hunt for a cheap moment on the network: its fee is paid at creation, and its payments follow the interval its payer set. Nor does it trade: it pays the asset it names, and converting one asset into another is the work of swap offers and markets and orders.
Other tools cover other shapes of payment. For money that should vest continuously, minute by minute, see liquid payments (streams). For a single payment released at a future block height or when an event is confirmed, see triggers and attestations.
If a scheduled token expires, the units still locked in a vesting schedule count for the schedule's owner when the token's ZBC backing is shared out (see token upkeep (persistence)).