Update documentation using deterministic generation by rustyrussell · Pull Request #8557 · ElementsProject/lightning

rustyrussell · 2025-09-19T00:42:24Z

~~Depends on #8556~~ Merged!

Now we do major surgery on autogenerate-rpc-examples.py. Finally we run it to produce the canned blocks and wallet for future runs, and re-enable it in CI.

ShahanaFarooqui

@rustyrussell The changes in ./tests/autogenerate-rpc-examples.py look good at first glance, but I am unable to test them locally due to missing test data files:

./tests/data/autogenerate-bitcoin-blocks.json
./tests/data/autogenerate-bitcoind-wallet.dat

Could you please add these files or provide instructions on how to generate them for local testing?

ShahanaFarooqui · 2025-10-07T22:14:36Z

Now uv run make update-doc-examples is throwing error:

15:12:18 - ERROR - Error in setting up nodes: txid f160d78f39a5ccb96c1439333787b98f1a37c1bb3765b34c74047c8895f4e397 not found
15:12:18 - ERROR - txid f160d78f39a5ccb96c1439333787b98f1a37c1bb3765b34c74047c8895f4e397 not found
Traceback (most recent call last):
  File "/home/shahana/workspace/lightning/tests/autogenerate-rpc-examples.py", line 1443, in test_generate_examples
    l1, l2, l3, l4, l5, l6, c12, c23, c25 = setup_test_nodes(node_factory, bitcoind, regenerate_blockchain)
                                            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/shahana/workspace/lightning/tests/autogenerate-rpc-examples.py", line 331, in setup_test_nodes
    c12, c12res = l1.fundchannel(l2, FUND_CHANNEL_AMOUNT_SAT)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/shahana/workspace/lightning/contrib/pyln-testing/pyln/testing/utils.py", line 1194, in fundchannel
    assert False, f"txid {res['txid']} not found"
           ^^^^^
AssertionError: txid f160d78f39a5ccb96c1439333787b98f1a37c1bb3765b34c74047c8895f4e397 not found

And uv run make update-doc-examples-newchain is throwing:

15:10:44 - ERROR - Error in generating transactions examples: RPC call failed: method: fetchbip353, payload: {'address': 'send.some@satsto.me'}, error: {'code': -32700, 'data': None, 'message': 'failed to fetch payment instructions: HrnResolutionError("Multiple TXT records existed for the HRN, which is invalid")'}
15:10:44 - ERROR - RPC call failed: method: fetchbip353, payload: {'address': 'send.some@satsto.me'}, error: {'code': -32700, 'data': None, 'message': 'failed to fetch payment instructions: HrnResolutionError("Multiple TXT records existed for the HRN, which is invalid")'}
Traceback (most recent call last):
  File "/home/shahana/workspace/lightning/tests/autogenerate-rpc-examples.py", line 1444, in test_generate_examples
    c23_2, c23res2, c34_2, inv_l11, inv_l21, inv_l22, inv_l31, inv_l32, inv_l34 = generate_transactions_examples(l1, l2, l3, l4, l5, c25, bitcoind)
                                                                                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/shahana/workspace/lightning/tests/autogenerate-rpc-examples.py", line 463, in generate_transactions_examples
    update_example(node=l1, method='fetchbip353', params={'address': 'send.some@satsto.me'}, description=['Example of fetching BIP-353 payment details.'])
  File "/home/shahana/workspace/lightning/tests/autogenerate-rpc-examples.py", line 260, in update_example
    response = node.rpc.call(method, params)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/shahana/workspace/lightning/contrib/pyln-testing/pyln/testing/utils.py", line 811, in call
    res = LightningRpc.call(self, method, payload, cmdprefix, filter)
          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "/home/shahana/workspace/lightning/contrib/pyln-client/pyln/client/lightning.py", line 428, in call
    raise RpcError(method, payload, resp['error'])
pyln.client.lightning.RpcError: RPC call failed: method: fetchbip353, payload: {'address': 'send.some@satsto.me'}, error: {'code': -32700, 'data': None, 'message': 'failed to fetch payment instructions: HrnResolutionError("Multiple TXT records existed for the HRN, which is invalid")'}

Unless REGENERATE_BLOCKCHAIN is true, in which case we make them. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

This makes our transaction generation (nlocktime) consistent, as well as our htlcs for payment. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

Move the elements config writing into an ElementsD.set_port() override. This makes many of our information outputs consistent. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

1. Don't mangle bookkeeper events. 2. Use l3, not l1, for listtransactions: it's more stable. 3. Use l2, not l1, for listpeerchannels and listchannels. 3. Use l2, not l2, for listfunds. (l1 has a lot of variation). Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

And hand in CLN_NEXT_VERSION to replace the version string. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

…rsion

…s_settled, wait_for_wallet_txs

… request in Rewriter

…smtool getsecret`

…ithdraw examples

…stabilise the response And flake fixes

…wProxy mocks These tests built their RawProxy against a hardcoded bitcoin.conf in the node's datadir. That only worked on liquid-regtest by accident: BitcoinD.__init__ used to write bitcoin.conf even when the node was actually an ElementsD. Now that config writing is deferred to set_port() and ElementsD only writes elements.conf, the mocks found no config and no .cookie, so their RPC calls failed and bcli's getblock timed out, leaving lightningd stuck during restart. Use bitcoind.conf_file, which points at the config the running daemon actually uses (elements.conf on liquid-regtest, bitcoin.conf on egtest).

…s own binaries

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

rustyrussell

Ack 00dc521

ShahanaFarooqui

Ack 00dc521

madelinevibes

ack 00dc521

nGoline · 2026-07-14T01:27:00Z

+      - name: Debug check-doc-examples inputs
+        run: |
+          echo "== lightning-hsmtool =="
+          which lightning-hsmtool || echo "NOT ON PATH"
+          find . -name "lightning-hsmtool*" -not -path "./.git/*" 2>/dev/null
+
+          echo "== autogenerate-bitcoind-wallet.dat =="
+          ls -la tests/data/autogenerate-bitcoind-wallet.dat 2>&1
+
+          echo "== autogenerate-bitcoin-blocks.json =="
+          ls -la tests/data/autogenerate-bitcoin-blocks.json 2>&1
+          echo "-- number of blocks --"
+          python3 -c "import json; print(len(json.load(open('tests/data/autogenerate-bitcoin-blocks.json'))))" 2>&1
+          echo "-- first 300 chars --"
+          head -c 300 tests/data/autogenerate-bitcoin-blocks.json
+          echo ""
+
+          echo "== environment fingerprint =="
+          # Determinism discriminators: HAVE_USDT toggles tracing, which
+          # must not perturb the deterministic RNG stream.
+          grep -E 'HAVE_USDT|HAVE_SQLITE3' config.vars || true
+          bitcoind --version | head -1 || true
+          dpkg -l systemtap-sdt-dev 2>/dev/null | tail -1 || true
+


Don't forget to remove this debug scaffolding.

nGoline · 2026-07-14T01:29:51Z

                 executable=None,
                 bad_notifications=False,
                 old_hsmsecret=None,
+                 no_entropy=False,


The naming seems backwards. no_entropy=True actually enables the deterministic entropy seed (CLN_DEV_ENTROPY_SEED), so the name reads as the opposite of what it does. Consider deterministic_entropy= or entropy_seed=, or even add a docstring line here clarifying "no real entropy -> use a fixed dev seed."

nGoline · 2026-07-14T01:31:44Z

+        if no_entropy:
+            self.daemon.env["CLN_DEV_ENTROPY_SEED"] = str(node_id)


Looking at the behaviour makes it clear the variable does the opposite.

nGoline · 2026-07-14T01:33:08Z

+        if base_port:
+            port = base_port + node_id * 2 - 1
+            grpc_port = base_port + node_id * 2


With base_port set, port/grpc_port are computed deterministically and intentionally not added to reserved_ports (line 1876). That's fine for a single serial doc-gen run, but a collision here surfaces as a confusing bind error instead of a clean reservation retry. Worth a one-line comment stating the assumption (single serial run over a fixed range).

nGoline · 2026-07-14T01:33:20Z

+        if not base_port:
+            self.reserved_ports.append(port)


base_port ports aren't reserved or collision-checked.

nGoline · 2026-07-14T01:35:09Z

 bool randbytes_overridden(void)
 {
 	return dev_seed != 0;
 }


Pre-existing, but flagging since determinism is the whole point of this PR: randbytes_overridden() keys off dev_seed != 0, and the basename change alters the siphash24 input. If the hash ever lands on exactly 0, the override silently disables and output becomes non-deterministic rather than erroring. A dedicated dev_overridden bool would be more robust than sentinel-zero.

nGoline · 2026-07-14T01:37:14Z

+	/* Hash only the basename: binaries still get distinct seeds, but
+	* the stream no longer depends on the checkout path. Plugins and
+	* subdaemons are exec'd with absolute paths: hash only the basename,
+	* so the stream doesn't depend on where the source tree lives */


nit: the comment says "hash only the basename" twice (lines 59 and 61–62 restate it), and lines 60/62 are indented one space short of the block (\t* vs \t *).

rustyrussell added this to the v25.12 milestone Sep 19, 2025

rustyrussell requested a review from cdecker as a code owner September 19, 2025 00:42

ShahanaFarooqui reviewed Oct 2, 2025

View reviewed changes

rustyrussell force-pushed the guilt/fix-doc-gen branch from 9fc3b5e to c455c51 Compare October 7, 2025 05:44

madelinevibes assigned ShahanaFarooqui and unassigned ShahanaFarooqui Oct 10, 2025

rustyrussell modified the milestones: v25.12, v26.03 Nov 13, 2025

sangbida modified the milestones: v26.04, 26.06 Mar 18, 2026

madelinevibes added the PLEASE clear CI 🫠 label May 4, 2026

madelinevibes modified the milestones: v26.06, v26.09 May 6, 2026

madelinevibes requested a review from ShahanaFarooqui June 17, 2026 06:07

madelinevibes assigned ShahanaFarooqui Jun 17, 2026

madelinevibes added the Status::Ready for Review The work has been completed and is now awaiting evaluation or approval. label Jun 17, 2026

madelinevibes removed the PLEASE clear CI 🫠 label Jul 2, 2026

ShahanaFarooqui force-pushed the guilt/fix-doc-gen branch 12 times, most recently from 9d0aae6 to 43fdc51 Compare July 8, 2026 01:42

rustyrussell and others added 21 commits July 8, 2026 13:49

autogenerate-rpc-examples.py: canned blocks.

e588bc6

Unless REGENERATE_BLOCKCHAIN is true, in which case we make them. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

autogenerate-rpc-examples.py: ensure blockheights are consistent.

662758c

This makes our transaction generation (nlocktime) consistent, as well as our htlcs for payment. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

autogenerate-rpc-examples.py: use fixed port numbers.

7dfa7fe

Move the elements config writing into an ElementsD.set_port() override. This makes many of our information outputs consistent. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

autogenerate-rpc-examples.py: more block generation and synchronization.

8691453

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

autogenerate-rpc-examples.py: rewrite problematic examples.

a13bef4

And hand in CLN_NEXT_VERSION to replace the version string. Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

autogenerate-rpc-examples.py: parameterized base port and cln next ve…

9391549

…rsion

autogenerate-rpc-examples.py: added 17 new RPC to ignore list

fefc06a

autogenerate-rpc-examples.py: added wait functions like wait_for_htlc…

21fcdf6

…s_settled, wait_for_wallet_txs

autogenerate-rpc-examples.py: added feature to be able to rewrite the…

89db2fc

… request in Rewriter

autogenerate-rpc-examples.py: fixed recover examples via `lightning-h…

5ef0397

…smtool getsecret`

autogenerate-rpc-examples.py: pin the full sorted UTXO set for multiw…

8f6ccf9

…ithdraw examples

autogenerate-rpc-examples.py: added more rewrite for other RPCs

f27acc2

autogenerate-rpc-examples.py: added sorting for some list example to …

1cab669

…stabilise the response And flake fixes

autogenerate-rpc-examples: sanitize plugin paths in plugin examples

15819ed

doc: generate all examples with newchain

1dc4821

make: Pinning PATH in doc scripts so generation always uses the tree'…

b4feb42

…s own binaries

make: Fix repeat-dpc-examples script

7f155d4

CI: re-enable docs examples checks.

bc63b8c

Signed-off-by: Rusty Russell <rusty@rustcorp.com.au>

CI: Add debug and upload artifacts on failure

00dc521

ShahanaFarooqui force-pushed the guilt/fix-doc-gen branch from a8eafc8 to 00dc521 Compare July 8, 2026 20:49

ShahanaFarooqui requested a review from nGoline July 13, 2026 19:57

rustyrussell commented Jul 14, 2026

View reviewed changes

ShahanaFarooqui approved these changes Jul 14, 2026

View reviewed changes

madelinevibes approved these changes Jul 14, 2026

View reviewed changes

madelinevibes removed the Status::Ready for Review The work has been completed and is now awaiting evaluation or approval. label Jul 14, 2026

ShahanaFarooqui merged commit 4aae26d into ElementsProject:master Jul 14, 2026
87 of 89 checks passed

ShahanaFarooqui mentioned this pull request Jul 14, 2026

Add missing RPC examples to autogenerate-rpc-examples script for improved API documentation #9294

Open

nGoline reviewed Jul 14, 2026

View reviewed changes

		if no_entropy:
		self.daemon.env["CLN_DEV_ENTROPY_SEED"] = str(node_id)

Uh oh!

Conversation

rustyrussell commented Sep 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

ShahanaFarooqui left a comment

Choose a reason for hiding this comment

Uh oh!

ShahanaFarooqui commented Oct 7, 2025

Uh oh!

rustyrussell left a comment

Choose a reason for hiding this comment

Uh oh!

ShahanaFarooqui left a comment

Choose a reason for hiding this comment

Uh oh!

madelinevibes left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

nGoline Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

nGoline Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

nGoline Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

nGoline Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

nGoline Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

nGoline Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

nGoline Jul 14, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

rustyrussell commented Sep 19, 2025 •

edited

Loading