What it solves, how it works, and how to integrate it into a CKB application
Imagine building an application on Nervos CKB where a user deposits an asset today but should not be able to spend it until a future date. The same requirement might arise in token vesting, a treasury release, or a payment-channel dispute period. The Cell exists, and someone may already be authorized to spend it. The missing piece is time: the transaction should not be valid yet.
CKB addresses this need through `since`, a small transaction-input field with an important purpose: expressing when an input is eligible to be committed. Once you understand that role, since becomes useful well beyond a simple timelock.
What is 'Since
`since` is an optional, consensus-enforced maturity condition on each CKB transaction input. When a transaction consumes an existing Cell, the network checks the input’s `since` value. If it specifies a condition that has not matured, the transaction cannot be committed—even when its other requirements are satisfied. A value of zero disables the `since` precondition.
It is useful to think of `since` as a “not before” rule, not as an instruction to execute a transaction on a schedule. Once the condition matures, someone must still construct, authorize, and submit the spending transaction.
A key distinction: `since` belongs to the spending transaction input, not to the existing Cell or the newly created output. Each input can carry its own condition.
What is Solves and Why CKB needs it.
The Cell Model changes state by consuming existing Cells and creating new ones. Lock scripts determine whether a spending transaction meets the rules protecting those Cells. Authorization and maturity, however, answer different questions: who is allowed to spend, and when is the spending transaction allowed to be committed?
Consider a vesting allocation owned by an employee, a treasury held until a governance deadline, or a payment-channel refund path that should become available only after a challenge period. Knowing the authorized party is not enough; the transaction also needs a maturity rule.
Rather than leaving every protocol to devise its own view of time, CKB defines `since` at the consensus layer. Because the field is per input, one transaction can combine Cells with different maturity requirements. All of those inputs must be mature for the transaction to be committed.
The features of Since.
1. Three measurement of maturity.
RFC 0017 provides three metrics. Block number expresses a particular height or number of blocks; epoch number expresses CKB’s epoch structure, including fractional positions; and timestamp expresses time in milliseconds using the blockchain’s consensus-defined timestamp rule. The metric should match the application’s intended behavior.
- Block number — suitable for rules defined by chain progression, such as a 100-block waiting period.
- Epoch number with fraction — suitable for rules naturally expressed in CKB epochs.
- Timestamp — suitable for user-facing deadlines and durations expressed in real-world time.
2. Absolute and relative conditions
Absolute `since` names a fixed maturity point. “Not before block 1,000,000” is absolute, regardless of when the Cell was created. Relative `since` defines a delay measured from the referenced Cell’s commitment: “wait 100 blocks after this Cell was committed.”
These meanings must not be confused. At chain height 25,000, absolute block 100 has already matured; relative block delay 100 is a different condition. Both modes are available for block, epoch, and timestamp metrics.
3. `since` is not a timer
A maturity condition does not count down inside the Cell, wake up a contract, or automatically broadcast a transaction. It is evaluated when a spending transaction is processed. The application—or another authorized actor—must still submit a valid transaction after maturity.
4. `since` is an encoded `u64`
The field is a 64-bit unsigned integer, but not all 64 bits represent time. Bit 63 selects relative versus absolute mode; bits 62–61 select the metric (block, epoch, or timestamp); bits 60–56 are reserved and must be zero; and the lower 56 bits hold the encoded value. The metric pattern `11` is invalid.
5. Timestamp maturity uses CKB consensus time
A device clock showing that a deadline has passed does not prove the transaction is mature. For timestamp-based `since`, CKB checks a consensus-derived median of the preceding 37 block timestamps. Accordingly, an application may show the user’s local time for convenience, but should use the chain’s maturity rule to determine whether spending is eligible.
How to integrate `since` into a CKB project
The implementation starts with an application rule, not a bit mask. The same sequence applies whether the client is written in Rust, TypeScript, another language, or built with a framework.
1. Define the rule. State the requirement precisely: a fixed date, a target block, or a duration after commitment.
2. Choose the mode and metric. Select absolute or relative, then block number, epoch, or timestamp.
3. Encode the value. Use RFC 0017’s 64-bit format. Validate the permitted range, flag combination, and reserved bits.
4. Commit the required spending policy to the Cell. If the delay must be mandatory, the lock must authenticate and enforce the intended policy, for example using lock arguments or Cell data.
5. Create and commit the protected Cell. Construct the creation transaction and confirm commitment. Relative conditions rely on the referenced Cell’s on-chain commitment point.
6. Construct the spending transaction. Reference the Cell’s OutPoint, set the encoded `since` on that input, construct outputs, and supply dependencies and witnesses.
7. Enforce the spending rules. The lock script verifies its authorization and policy requirements, including the prescribed mode, metric, and value. Where a script group includes multiple applicable inputs, validate each one.
8. Let consensus evaluate maturity. CKB checks whether each input’s `since` precondition is mature. The transaction can be committed only when all applicable consensus and script rules pass.
9. Test failure paths. Verify premature spending, wrong mode or metric, invalid bits, policy bypass with `since = 0`, unauthorized spending, and multiple-input behavior.
Trade-offs and design choices
-
Absolute versus relative — an absolute deadline is known in advance, but late Cell commitment shortens the effective holding period. Relative maturity preserves a commitment-based delay, while its exact target depends on when the Cell is committed.
-
Blocks versus wall-clock time — a block count is easy to use for protocol delays, but variable block production prevents it from guaranteeing an exact number of minutes.
-
Epoch versus timestamp — epochs align with CKB’s native progress model but are harder to present to ordinary users; timestamps communicate dates clearly but rely on consensus time, not a local device clock.
-
Consensus enforcement versus automation — consensus checks when spending is eligible, but it does not schedule or execute the transaction for the application.
-
Flexible encoding versus correctness — the compact format supports several time models, but developers must decode the flags and enforce the intended policy rather than compare raw `u64` values.
-
Per-input conditions versus transaction-wide maturity — independent inputs can express independent deadlines, but one immature input prevents commitment of the entire transaction.
Conclusion
`since` gives a CKB transaction input a consensus-level “not before” rule. Developers choose the appropriate time model, encode it correctly, and—when the application requires a mandatory lock—make the Cell’s script enforce that policy. CKB consensus determines whether the spending input has matured.
The practical takeaway is to separate three concerns: who may spend, what maturity policy the application requires, and whether the blockchain has reached that condition. Keeping those responsibilities distinct makes time-based CKB applications easier to reason about and safer to implement.