Add EIP-7805 (FOCIL) endpoints by ensi321 · Pull Request #490 · ethereum/beacon-APIs

ensi321 · 2025-01-27T23:22:36Z

No description provided.

rolfyone · 2025-01-29T01:07:16Z

+Focil:
+  InclusionList:


we'll want a fork name rather than a EIP name for the api, but it's probably premature to know that I guess...

I think for now we should keep it as EIP name (or number) but it would be good if we can merge new endpoints before those are officially part of a hard fork. I added a new tag "Draft" here to separate those in the api explorer, but maybe even a EIP specific tag would make sense.

In teku i just use Experimental tag but draft also works, that'd be fine...

That's what I was using but it had a different purpose previously when it was used for the rewards apis. I think either one works, if we do this for more EIPs it might even be good to use a separate tag for each. This would allow to disable spec tests based on tag

its been super problematic merging with feature flags sometimes, that's my hesitation.

Yeah we probably won't be merging this any time soon since the CL spec isn't even merged yet but it would be nice if we can come up with an approach to allow merging this before it's confirmed as part of a hard fork.

I pushed a few changes group files / types under EIP specific namespace and used the EIP as tag as well, this would allow us to have more than one EIP in "Draft" stage and be part of the api explorer.

gfukushima · 2025-04-15T03:42:34Z

+            required: [data]
+            properties:
+              data:
+                $ref: "../../beacon-node-oapi.yaml#/components/schemas/Bellatrix.Transactions"


is this meant to return EIP7805.InclusionList? maybe I'm reading things wrong but this seems to expect the transactions of the IL in the data property whereas description says this will request BN to produce an IL.

depends how you define what a inclusion list is, technically it's just a list of transactions which is the return type of this api and also the engine-api

the other return type could be InclusionList (ie. wrap it in container) but this would return useless and even confusing data, eg. validator_index isn't even set by beacon node, so beacon node would just set some value (maybe 0) and then the validator client is responsible for overriding it

we can think about if we wanna wrap this in a container, and maybe even make the api fork-aware by adding version metadata, this might be better for future forward compatibility

is this meant to return EIP7805.InclusionList? maybe I'm reading things wrong but this seems to expect the transactions of the IL in the data property whereas description says this will request BN to produce an IL.

@gfukushima Yes. As @nflaig mentioned, IL can mean

A list of IL transactions. It is used here, execution api spec and anything as far as EL is concerned

IL container as defined in consensus specs. Basically 1 + any other useful consensus info

Here we only return IL transactions because any additional consensus info (slot, validator index, ILC root) are all available in VC. No need to grab them from BN

jihoonsong · 2026-03-20T06:18:52Z

@ensi321 Does this PR require some updates for Heze rebase?

bharath-123 · 2026-06-04T15:18:48Z

              value: |
                event: payload_attributes
-                data: {"version": "capella", "data": {"proposer_index": "123", "proposal_slot": "10", "parent_block_number": "9", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "payload_attributes": {"timestamp": "123456", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "suggested_fee_recipient": "0x0000000000000000000000000000000000000000", "withdrawals": [{"index": "5", "validator_index": "10", "address": "0x0000000000000000000000000000000000000000", "amount": "15640"}]}}}
+                data: {"version": "eip7805", "data": {"proposer_index": "123", "proposal_slot": "10", "parent_block_number": "9", "parent_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "parent_block_hash": "0x9a2fefd2fdb57f74993c7780ea5b9030d2897b615b89f808011ca5aebed54eaf", "payload_attributes": {"timestamp": "123456", "prev_randao": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "suggested_fee_recipient": "0x0000000000000000000000000000000000000000", "withdrawals": [{"index": "5", "validator_index": "10", "address": "0x0000000000000000000000000000000000000000", "amount": "15640"}], "parent_beacon_block_root": "0xcf8e0d4e9587369b2301d0790347320302cc0943d5a1884560367e8208d920f2", "inclusion_list_transactions": ["0x03f88f0780843b9aca008506fc23ac00830186a09400000000000000000000000000000000000001008080c001e1a0010657f37554c781402a22917dee2f75def7ab966d7b770905398eba3c44401401a0840650aa8f74d2b07f40067dc33b715078d73422f01da17abdbd11e02bbdfda9a04b2260f6022bf53eadb337b3e59514936f7317d872defb891a708ee279bdca90"]}}}


Can we also return the inclusion_list_bits? would it make sense to return that for the builder to add the correct list of bits in the bid

why do you need that, you have literally the inclusion_list_transactions, aren't the inclusion_list_bits in the bid supposed to signal which ILs your payload has/will satisfy? cc @jihoonsong

A builder listens to this event for their payload building and constructs a bid. So the builder expects to have all the information they need for a bid from this event.

However, inclusion_list_bits indicates which ILs a builder considered. This is what the builder cannot derive from inclusion_list_transactions.

Correct me if I'm wrong @bharath-123

why do you need that, you have literally the inclusion_list_transactions

I got confused, this is not a list of inclusion lists, it's a deduplicated list of transactions the payload needs to include to satisfy the ILs, so you cannot derive inclusion_list_bits from that

the inclusion_list_bits are the indices of the commitee members whose ILs were considered. its hard for a builder to derive that from just the txs.

Following the discussion in FOCIL breakout #36, I've opened a PR that removes the IL bitlist from bid. cc @bharath-123

FOCIL (EIP-7805) is officially scheduled as part of Heze. Use Heze as the fork name to match the consensus-specs naming. - types/eip7805/ → types/heze/, namespace EIP7805 → Heze - Tag EIP-7805 → Heze (description still references EIP-7805 + FOCIL for discoverability) - Event version strings "eip7805" → "heze" - Bump spec links to v1.7.0-alpha.10 Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

publishInclusionList accepts Eth-Consensus-Version header and event stream examples use "heze" as version string. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Other events don't tag fork in description; the version field in the payload already conveys this. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

nflaig mentioned this pull request Jan 28, 2025

FOCIL tracker ChainSafe/lodestar#7340

Open

38 tasks

poojaranjan mentioned this pull request Jan 28, 2025

FOCIL Breakout #3 ethereum/pm#1266

Closed

rolfyone reviewed Jan 29, 2025

View reviewed changes

nflaig changed the title ~~Add Inclusion List endpoints~~ Add EIP-7805 (FOCIL) endpoints Feb 4, 2025

mehdi-aouadi mentioned this pull request Feb 13, 2025

Beacon APIs Consensys/teku#8995

Closed

3 tasks

This was referenced Apr 13, 2025

Produce IL (GET) Consensys/teku#9345

Closed

Produce IL (POST) Consensys/teku#9346

Closed

gfukushima reviewed Apr 15, 2025

View reviewed changes

eth2353 mentioned this pull request Jul 16, 2025

FOCIL (EIP-7805) support serenita-org/vero#174

Open

ensi321 force-pushed the focil branch from 99a184b to 5960c4f Compare August 26, 2025 05:04

bharath-123 reviewed Jun 4, 2026

View reviewed changes

ensi321 force-pushed the focil branch from a7ba2f0 to 4f8b818 Compare June 22, 2026 22:11

ensi321 and others added 17 commits June 22, 2026 15:16

Add IL related endpoints

74cd5d3

Remove multiple ILs support on endpoints

f4c722f

Add note about chain reorgs to duties endpoint

a76f540

Fix lint errors

bc0fd7e

Update endpoint descriptions

9a2a545

Make inclusion endpoints fork-aware to be forward compatible

6a5b07e

Add inclusion_list event

580958d

Add focil to word list

7bec89a

Tag new inclusion list endpoint / event as Experimental

6d3ba47

Add EIPs to word list

d0c0e88

Rename tag from Experimental to Draft

237d709

Simplifies produceInclusionList. Move ILC root to ILC duty

385c145

Remove version meta, shouldn't be required if it's jsut a list of txs

4f8236b

Use eip7805 instead of focil as fork name

032eb22

Use EIP-7805 as tag to separate new apis

8df7b4a

Update word list

8c419c1

Update tag description

7517789

ensi321 and others added 5 commits June 22, 2026 15:17

Rebase on fulu

c760301

Update payload_attributes example

49ad0b2

Add heze to ConsensusVersion enum

24a7a65

publishInclusionList accepts Eth-Consensus-Version header and event stream examples use "heze" as version string. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Drop (Heze) prefix from inclusion_list event description

274b87a

Other events don't tag fork in description; the version field in the payload already conveys this. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

ensi321 force-pushed the focil branch from 4f8b818 to 274b87a Compare June 22, 2026 22:19

		Focil:
		InclusionList:

Uh oh!

Conversation

ensi321 commented Jan 27, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nflaig Apr 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ensi321 Apr 17, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jihoonsong commented Mar 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nflaig Jun 4, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

7 participants

nflaig Apr 15, 2025 •

edited

Loading

ensi321 Apr 17, 2025 •

edited

Loading

nflaig Jun 4, 2026 •

edited

Loading