From c8412221139d117ab9eda38f6538616a1fd2c0c2 Mon Sep 17 00:00:00 2001 From: Michael Kernaghan Date: Thu, 9 Oct 2025 08:46:30 -0700 Subject: [PATCH] docs: Clarify attestation_with_dal applies to all key types Fixes #671 - Clarify that attestation_with_dal policy is required for ALL key types when DAL node is connected - Add detailed explanation of tz1/tz2/tz3 behavior with DAL node - Distinguish between attestation encoding vs shard attestation capability - Add concrete log examples from Seoulnet testing - Update baker command examples for both tz1 and tz4 scenarios - Add new 'DAL Behavior by Key Type' section with practical examples The documentation now accurately reflects that the attestation_with_dal encoding is triggered by DAL node connectivity, not key type. Testing on Seoulnet demonstrated that tz1 keys do sign attestation_with_dal operations when a DAL node is connected, even without shard attestation capability (bitset 0). This prevents operators from mistakenly omitting the attestation_with_dal policy for tz1-only setups. --- docs/bakers.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++---- 1 file changed, 75 insertions(+), 5 deletions(-) diff --git a/docs/bakers.md b/docs/bakers.md index bb7605f4..7592432e 100644 --- a/docs/bakers.md +++ b/docs/bakers.md @@ -246,7 +246,7 @@ tezos: block: # Standard block baking attestation: # Standard attestations preattestation: # Pre-attestations - attestation_with_dal: # Required for DAL attestations + attestation_with_dal: # Required for ALL key types when DAL node is connected generic: - transaction - reveal @@ -255,12 +255,20 @@ tezos: ``` :::warning Important -Without `attestation_with_dal` in your Signatory policy, DAL attestation requests will be rejected, and you'll miss those rewards. +The `attestation_with_dal` policy applies to **all key types** (tz1, tz2, tz3, tz4) when a DAL node is connected to the baker. This is an encoding/policy distinction triggered by DAL node connectivity, not a key type requirement. + +* **tz1/tz2/tz3 keys**: Sign `attestation_with_dal` operations with empty DAL content (bitset 0) +* **tz4 keys**: Can attest actual DAL shards (bitset > 0) when consensus + companion keys are properly configured +* **Both trigger the same signatory policy check** for `attestation_with_dal` + +Even if your baker uses only tz1 keys, you **must** include `attestation_with_dal` in your signatory policy when running with a DAL node, otherwise attestation requests will be rejected and you'll miss those rewards. ::: ### Key Requirements -**BLS Consensus Keys (tz4)**: A **companion key is mandatory** for DAL attestations. Without it, tz4 bakers cannot produce DAL attestations. +**Standard Keys (tz1/tz2/tz3)**: Can participate in DAL attestations without companion keys. When a DAL node is connected, the baker will sign `attestation_with_dal` operations with the consensus key (or manager key if no separate consensus key is configured). However, these attestations will have bitset 0 (no shard attestation capability) since DAL shard attestation requires BLS signature aggregation. + +**BLS Consensus Keys (tz4)**: A **companion key is mandatory** for DAL attestations with tz4 keys. Without it, tz4 bakers cannot produce DAL attestations with shard attestation capability. ```bash # Register companion key for existing delegate @@ -271,15 +279,21 @@ octez-client set companion key for to For DAL participation, your baker command must include: - **Consensus key**: Required for all attestation operations -- **Companion key**: Required for DAL attestations (especially for tz4 consensus keys) +- **Companion key**: Required for tz4 keys to enable DAL shard attestation (optional for tz1/tz2/tz3) - **DAL node endpoint**: `--dal-node` parameter pointing to your DAL node ```bash -# Example baker command for DAL participation +# Example baker command for DAL participation (tz4 with companion) octez-baker run with local node ~/.tezos-node \ --liquidity-baking-toggle-vote pass \ --dal-node http://localhost:10732 \ consensus_key companion_key + +# Example baker command for DAL participation (tz1 without companion) +octez-baker run with local node ~/.tezos-node \ + --liquidity-baking-toggle-vote pass \ + --dal-node http://localhost:10732 \ + manager_or_consensus_key ``` **DAL Operations**: @@ -305,6 +319,62 @@ octez-baker run with local node ~/.tezos-node \ **Further Reading**: [Tezos DAL Architecture](https://docs.tezos.com/architecture/data-availability-layer) | [DAL Node Setup Guide](https://octez.tezos.com/docs/shell/dal_run.html) +### DAL Behavior by Key Type + +Understanding how different key types interact with DAL attestations: + +#### tz1/tz2/tz3 Keys with DAL Node + +**What Happens:** +- Baker sends `attestation_with_dal` requests to Signatory +- Signatory logs show: `"request=attestation_with_dal"` +- Attestations have bitset 0 (no shard attestation) +- Baker logs show: `"injected attestation (without DAL)"` +- DAL rewards can still be earned + +**Signatory Logs Example:** +``` +msg="Requesting signing operation" request=attestation_with_dal pkh=tz1YourKey +msg="Signed attestation_with_dal successfully" pkh=tz1YourKey +``` + +**Baker Logs Example:** +``` +tz1YourKey has no assigned DAL shards at level 1234567 +injected attestation (without DAL) for level 1234567 +``` + +**Configuration Required:** +```yaml +tezos: + tz1YourKey: + allow: + attestation_with_dal: # REQUIRED even for tz1 keys with DAL node +``` + +#### tz4 Keys with DAL Node and Companion Key + +**What Happens:** +- Baker sends `attestation_with_dal` requests for both consensus and companion keys +- Attestations can have bitset > 0 when assigned DAL shards +- Full shard attestation capability with BLS aggregation +- Higher DAL rewards potential + +**Configuration Required:** +```yaml +tezos: + tz4ConsensusKey: + allow: + attestation_with_dal: # REQUIRED + tz4CompanionKey: + allow: + attestation_with_dal: # REQUIRED +``` + +#### Key Takeaway + +**The `attestation_with_dal` encoding is triggered by DAL node connectivity, not key type.** All keys signing through a baker with `--dal-node` configured will use the `attestation_with_dal` request type, regardless of whether they can actually attest DAL shards. + --- ## Protocol-Agnostic Baker Commands