From 38707e4bfe0a6053373f6128745a58725389c6c9 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?R=C3=A9my=20Roy?= <303593+remyroy@users.noreply.github.com>
Date: Thu, 19 Sep 2024 17:26:10 -0400
Subject: [PATCH] Add documentation page for BLS to execution change file

---
 docs/src/SUMMARY.md                          |  1 +
 docs/src/bls_to_execution_change_file.md     | 28 ++++++++++++++++++++
 docs/src/generate_bls_to_execution_change.md |  3 +++
 3 files changed, 32 insertions(+)
 create mode 100644 docs/src/bls_to_execution_change_file.md

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
index e95737bc..466ae1db 100644
--- a/docs/src/SUMMARY.md
+++ b/docs/src/SUMMARY.md
@@ -17,6 +17,7 @@
 
 - [Keystore](keystore_file.md)
 - [Deposit Data](deposit_data_file.md)
+- [BLS to execution change](bls_to_execution_change_file.md)
 
 # Development
 
diff --git a/docs/src/bls_to_execution_change_file.md b/docs/src/bls_to_execution_change_file.md
new file mode 100644
index 00000000..626f8a81
--- /dev/null
+++ b/docs/src/bls_to_execution_change_file.md
@@ -0,0 +1,28 @@
+# BLS to execution change file
+
+A BLS to execution change file is created when calling the **[generate-bls-to-execution-change](generate_bls_to_execution_change.md)** command.
+
+The BLS to execution change file is a JSON file. It contains a list of messages to change the withdrawal credentials for one or many validators. The format of the BLS to execution change file is loosly based on the input for the POST `/eth/v1/beacon/pool/bls_to_execution_changes` [API endpoint](https://ethereum.github.io/beacon-APIs/#/Beacon/submitPoolBLSToExecutionChange) as defined by [the Ethereum Beacon APIs](https://github.com/ethereum/beacon-APIs). Part of this content is based on the [SignedBLSToExecutionChange](https://github.com/ethereum/consensus-specs/blob/v1.3.0/specs/capella/beacon-chain.md#signedblstoexecutionchange) container as defined in the [Ethereum Consensus Specifications](https://github.com/ethereum/consensus-specs/).
+
+## Broadcasting
+
+If you have access to a beacon node client running on your target network, you can publish these messages simply by calling the POST `/eth/v1/beacon/pool/bls_to_execution_changes` [API endpoint](https://ethereum.github.io/beacon-APIs/#/Beacon/submitPoolBLSToExecutionChange) and passing the content of the BLS to execution change file as the payload. You can also use [the Beaconcha.in Broadcast Signed Messages tool](https://beaconcha.in/tools/broadcast) which might be easier for most users.
+
+## Example
+```JSON
+[
+  {
+    "message":{
+      "validator_index":"1804776",
+      "from_bls_pubkey":"0x970245df5f9cf7a082db195136a3066412b62e8bf04e21d7c3408d7fb36f34f20c4cb0883e798b82523b466f7a61c838",
+      "to_execution_address":"0x4d496ccc28058b1d74b7a19541663e21154f9c84"
+    },
+    "signature":"0xa1e47e6b1fdf4dd5f1dd3ddb3d47d2dcf446d096d49d90afef06a38dc02fba6b4d16d1dc1184c791e54666dabb8bdedd0660bc9bb3bc5d0e592eaf5f0c978cca4fcafe4037672940d6f1a44d2a33503c30cb98ca695979b1de9e321a8a694bc2",
+    "metadata":{
+      "network_name":"holesky",
+      "genesis_validators_root":"0x9143aa7c615a7f7115e2b6aac319c03529df8242ae705fba9df39b79c59fa8b1",
+      "deposit_cli_version":"0.1.4-dev"
+    }
+  }
+]
+```
\ No newline at end of file
diff --git a/docs/src/generate_bls_to_execution_change.md b/docs/src/generate_bls_to_execution_change.md
index 1dd79e3b..931b4476 100644
--- a/docs/src/generate_bls_to_execution_change.md
+++ b/docs/src/generate_bls_to_execution_change.md
@@ -25,6 +25,9 @@ Generates a BLS to execution address change message. This is used to add a withd
 
 - **`--devnet_chain_setting`**: The custom chain setting of a devnet or testnet. Note that it will override your `--chain` choice. This should be a JSON string containing an object with the following keys: network_name, genesis_fork_version, exit_fork_version and genesis_validator_root.
 
+## Output files
+A successful call to this command will result in one [BLS to execution change file](bls_to_execution_change_file.md) created.
+
 ## Example Usage
 
 ```sh