Timelocks

[schoen]

Add some material on how relative timelocks using block distance work

[imaginator]

you need to link these into the menu

[schoen]

@imaginator I updated this and the other PR to replace them with versions that are linked into the menu

[imaginator]

as with my other comments... "```rust" will make the code easier to read.

[apoelstra]

Overall 7b7e489 looks good. It is missing two things:

• It should clarify that the inequality for locktimes is a "less than or equal to blockheight" check. So if your locktime implies age 0, it can be included in any block (including the same block as the one that created your output). If your output is confirmed in block 10000 with a relative locktime of 100 blocks, then it can be included in block 10100 and will be relayed by mempools when the chain is at block 10099. (This "off-by-one" behavior is 99% of the reason people check the docs for locktimes and it should really be prominent.)
• Also, unfortunately for your goal of understanding and documenting everything, there are two kinds of locktimes: height based and height based. For relative locktimes, these are distinguished by a bit in the sequence number and indicate whether the units are blocks or 512-second intervals. The former we refer to by "distance" and the latter by "duration", though these are both nonstandard terms that we made up to distinguish this. If your sequence number is distance-based the "duration" that Simplicity sees will be 0, and vice-versa. If you attempt to lower-bound both of them above 0 your coins will be unspendable. In Miniscript this caused us a lot of grief; see https://blog.blockstream.com/dont-mix-your-timelocks/

[apoelstra]

On Bitcoin standard advice is to never use time-based, only use block-based timelocks, because they're easier to reason about, less miner-gamable, and give you a longer range.

Unfortunately on Liquid we inherited Bitcoin's "up to 65535 blocks or up to 65535 512-second intervals" limits. But with blocks coming 1 minute rather than every 10 minutes, this means that block-based relative timelocks are limited to roughly 45 days. If you need a longer timelock you're forced to use time-based ones, which will get you a bit over a year. If you need longer than that you have to use absolute, rather than relative, timelocks.

[schoen]

I'm planning to talk this over with @apoelstra tomorrow and then make some edits based on my deepened understanding of this topic.

[imaginator]

I'd recommend not tying Timelock documentation to referencing the Liquid network - timelocks behave in a similar way on non-liquid bitcoin systems. You just need to point out the 65k limit on Liquid.

[schoen]

This turned out to be complicated on several grounds (including bugs we discovered in timelock jets). My preference would be to work this out with @apoelstra when he's back because there are many fine details, including the jet deprecation, to get right.

If we do find some people getting stuck with timelock issues, I think @delta1 understands this enough that we could probably work out a minimum viable version.