Skip to content

Track legacy compatibility layers and backfills for removal #72

Open

Description

@j0sh

Track the compatibility layers and data backfills that we want to retire, with their introduction release and a concrete removal gate. Group related call sites together; check an item off only when its compatibility behavior has actually been removed or explicitly retained as a supported contract.

Release accounting / scope

  • Audited the current checkout on 2026-11-10, including local ja-codex/standalone-redeemer at 6f9cd607ddaf871d6305d825f78fd7e68b481a3d. Also checked remote main at 4100e8dbc0aa7b1e23cfe9d1b38578176557edd2; its two commits beyond local main add drain/registration-limit behavior, with no additional compatibility adapter found.
  • “Added in” means the first tagged Node release containing the implementation, established with Git introduction/history searches and tag ancestry. Imported go-livepeer source history is not treated as a Node release. The first available Node release tag is 1.0.1.
  • Public source links are pinned to 17713df (a published ancestor of current main), or the stated release tag. Local-only occurrences use exact paths/symbols and local commit IDs instead of broken GitHub links.

Open inventory: 22 groups (10 first present in 1.0.1, 2 in 1.0.6, 9 assigned to 1.07, 1 unreleased; metric/protocol antecedents are noted separately).

Track Added in Occurrences / retained behavior Introducing commit Removal gate
C01 1.07 Scalar runner heartbeats alongside apps[]: top-level app fields, scalarApp(), mixed-format rejection, runner ID reused as app ID, and scalar session_ids responses. orchestrator/registry.go:83; orchestrator/registry.go:113; orchestrator/registry.go:403. 833dc2e (#44); scalar protocol itself already existed in 1.0.1. Require apps[] from supported runner SDKs; remove scalar request/response branches and legacy route-identity handling together.
C02 1.07 Heartbeat sequence fencing is opt-in: owners can keep omitting seq until their first authenticated sequenced heartbeat. orchestrator/registry.go:455; orchestrator/seq_test.go:27. 17713df (#68). Require sequence numbers after bootstrap once supported runners send them; retire the unsequenced owner mode.
C03 1.0.1 GPU JSON accepts a nonnegative integer index as well as the structured GPU object. orchestrator/registry.go:41. ceb0973. Confirm supported runners emit GPU objects before removing the integer decoder.
C04 1.0.1 Prior /proxy/{proxy_id} and /proxy/{proxy_id}/{app_path...} routes remain aliases alongside /run/... and configured generated URLs. orchestrator/http.go:76; generated-proxy dispatch also recognizes both prefixes. bcccb63. Migrate consumers and proxy URL templates; then remove both aliases and their dispatch/metrics handling.
C05 1.0.1 Payment authentication accepts expiration metadata in either Payment.Expiration or nested TicketParams.Expiration; if both exist they must match. orchestrator/payment_engine.go:438. e9ee69a. Choose a canonical location and upgrade both SDKs/signers before removing the alternate-copy fallback.
C06 1.0.1 Older external field names survive internal payer/ticket terminology: refresh-payment JSON sender (orchestrator/payment.go:215), signed-state SenderNonce and InitialPixelsPerUnit (signer/payment.go:53). ceb0973 / 1acef23; f3e97d5 explicitly retains the SenderNonce JSON key while renaming the Go field. Version the HTTP/signed-state format and let old client-held state expire before renaming or deleting these keys.
C07 1.0.1 Legacy unversioned remote-signer Protobuf envelopes and original field numbers; UnitsPerPrice retains the wire field historically called pixelsPerUnit. Consumed messages: PriceInfo, expiration, tickets, auth, orchestrator info, payment, payer params, and SegData. pm/wire/wire.go:1. ceb0973 (then signercompat/wire.go); relocated by 252a926. Requires a coordinated replacement/versioned payment protocol; unknown-field handling is normal Protobuf behavior, not a shim to delete on its own.
C08 1.0.1 Legacy ticket-signature recovery uses V=27/28; Key.SignMessage produces that form. Segment credentials retain the historical manifest + 32 zero bytes + hash signing layout in signer and recipient. pm/sigverifier.go:34; eth/key.go:271; signer/payment.go:175; orchestrator/payment_engine.go:251. ceb0973; signing moved to keystore/key code before 1.0.1. Protocol-dependent: coordinate SDKs and on-chain ticket verification. These are active signing rules, not safe to remove merely because clients are newer.
C09 1.0.1 RemoteBatchSize preserves the legacy minimum credit floor of one ticket EV, even when the billable fee is smaller. pm/remotepayment.go:15. 4205405. Agree and test replacement payment/credit semantics with SDK consumers before changing the floor.
C10 1.0.1 Retained signer HTTP response semantics, including nonstandard 480 (refresh), 481 (price), 482 (no tickets), and precheck errors reported as 400. signer/service.go:346. signer/metrics.go:12 explicitly separates these compatibility responses from internal failure classifications. ceb0973; response policy refined before 1.0.1. Introduce a client migration/versioning plan before replacing status codes; keep error classifications separate from the public contract.
C11 1.0.1 Kafka create_signed_ticket accounting retains empty gateway and zero pixels fields. signer/events.go:18; signer/events.go:60. 2de42ef. Version/update accounting consumers and event schema before dropping the placeholders.
C12 1.07 adapter Metrics.Legacy registers collectors without the new component label: internal/observability/metrics.go:165. All callers: orchestrator/registry.go:246, signer/service.go:160, discovery/server.go:91, signer/app.go:225. Families include runners, sessions, signer_up, discovery_up, and existing signer_kafka_* collectors. a4b68ed (#20). Underlying metrics predate the adapter: runner/session/signer/Kafka families in 1.0.1; standalone discovery in 1.0.3. Migrate dashboards/alerts to the chosen metric names/labels, then remove the adapter and update all four callers together.
C13 1.0.1 Ten generated deprecated ABI aliases; each redirects the old *ABI variable to *MetaData.ABI. Exact files/symbols are listed below. c36992c imported the generated bindings with these aliases. Retire old Go API consumers and update bindings through the documented upstream import/regeneration workflow; avoid hand-editing generated files.
C14 1.0.6 Ported transaction manager supports pre-London LegacyTx replacement and an explicit chain-ID signer bridge, with a SignTx interface fallback. eth/transactionmanager.go:218; eth/transactionmanager.go:366; eth/key.go:32. c74c593 (#15). Confirm supported callers and retained signed transactions no longer require legacy transaction replacement; then simplify the transaction type/signer interfaces together.
C15 Unreleased livepeer chain ticketbroker fund --amount remains a silent alias for --deposit, preserving existing scripts while help and documentation use the canonical name. Local chain/cli.go:fundCommand normalizes the flag name; alias behavior is covered in chain/cli_test.go:TestActionValidationBeforeRPC and chain/management_test.go:TestResolvedAmountsAndCalldata. Local working-tree change; introducing commit and first release pending. Migrate supported scripts to --deposit, then remove the funding-only alias and its compatibility tests. Preserve --deposit/--reserve zero defaults, positive-total validation, and --recipient support.
D01 1.0.6 Migration 002 backfills redemption_transactions from the former one-row-per-ticket redemption_attempts + winning_tickets.tx_hash representation, synthesizing root identity, broadcast time and acknowledgment. DOWN guards prevent lossy conversion. Released at orchestrator/migrations/002_redemption_transactions.sql:15; current local path is redemption/migrations/002_redemption_transactions.sql. c74c593 (#15); moved to the shared package by local 381a6f9. Retire upgrades from the old schema via an explicit supported baseline/upgrade policy; preserve signed identities and rollback guarantees.
D02 1.07 Migration 003 backfills every preexisting ticket's enqueued_at with migration time. orchestrator/migrations/003_ticket_enqueue_time.sql:1; current local path is redemption/migrations/003_ticket_enqueue_time.sql. Metrics documentation notes the resulting age underestimate. a4b68ed (#20). Retire pre-003 upgrade paths through a migration baseline; existing timestamps cannot be reconstructed by deleting this code.
D03 1.07 redemption/migrations/005_delivery_state.sql adds nullable ticket_hash plus logical ticket/delivery state. redemption/redeemer_db.go:117 runs backfill() at every store open; redemption/state.go:158–214 fills missing hashes in pages of 128, creates logical identity, and reconstructs exposure/settlement from prior attempts and redeemed_at, preserving signature aliases. Local 381a6f9 (unpublished at audit time). Ensure every supported store has canonical identities and migrated state, including old backups; then retire only the old-row reconstruction, preserving identity creation for new tickets.
D04 1.07 redemption/state.go:35–114 lets an unbound Node DB adopt supplied chain/controller/role/destination, checking retained transaction chain IDs and nonce drainage. An existing populated DB cannot be adopted by the standalone redeemer. Local 381a6f9. Require an existing deployment binding once all supported stores are bound; keep normal binding validation and destination-change checks.
D05 1.07 redemption/worker.go:183–203 reopens legacy nonfinal awaiting_finality / expired observations after fresh pinned eligibility reads, checking unresolved signature aliases before marking retryable. Local 24d3571 (follow-up to 381a6f9). Prove old nonfinal observations cannot remain or be produced by retained compatibility entry points; preserve current finality/reorg handling and unresolved transaction history.
D06 1.07 redemption/redemption_store.go:103–116 reports a backfilled settled ticket with an empty settlement label as used via COALESCE(NULLIF(settlement,''),'used'). Local 43fd62e. Explicitly normalize legacy settled labels, and stop creating empty labels for migrated settlements, before removing the reporting fallback.
D07 1.07 dual mode Candidate compatibility debt (inferred from the parallel paths): shared redemption preserves the old unbound/no-worker path alongside the bound worker: redemption/redeemer.go:27,130,183; redeemer_db.go:250,326,399,410; state.go:223,388; redemption_store.go:103; redemption_recovery.go:267,287,296,333,348,390; redemption_nonce.go:113; redemption_metrics.go:90,125. This includes old liability/count/pending queries, unrestricted/unbounded recovery branches, and capacity defaults when no binding exists. Local 381a6f9 introduces the dual path around APIs that previously shipped in 1.0.1/1.0.6. Require binding and a configured worker in supported entry points; migrate older direct callers/tests, then consolidate queries and recovery branches.

Removal checklist

  • C01: Retire scalar heartbeat compatibility.
  • C02: Require heartbeat sequences after bootstrap.
  • C03: Retire integer GPU JSON.
  • C04: Retire prior proxy route aliases.
  • C05: Choose one payment expiration metadata location.
  • C06: Migrate old external JSON/signed-state names.
  • C07: Replace or explicitly retain the unversioned payment wire protocol.
  • C08: Resolve legacy ticket/segment signing conventions.
  • C09: Resolve the one-ticket-EV credit floor.
  • C10: Migrate retained signer response codes.
  • C11: Drop Kafka compatibility placeholders.
  • C12: Retire the legacy metrics adapter.
  • C13: Retire generated deprecated ABI aliases.
  • C14: Resolve legacy transaction replacement/signing support.
  • C15: Remove the TicketBroker funding --amount alias after supported scripts use --deposit.
  • D01: Retire the migration 002 backfill upgrade path.
  • D02: Retire the migration 003 timestamp backfill upgrade path.
  • D03: Retire startup ticket identity/exposure/settlement reconstruction.
  • D04: Retire unbound database adoption.
  • D05: Retire reopening of legacy nonfinal observations.
  • D06: Retire the empty-settlement status fallback.
  • D07: Consolidate the unbound/no-worker redemption mode.

C13 — every deprecated generated alias

Follow eth/contracts/README.md:24 for binding updates.

Already removed locally before release

  • Orchestrator re-export compatibility wrappers introduced in local 381a6f9, assigned to 1.07, then removed in local 6f9cd60 during this audit: RedemptionOptions, RedemptionStatus, ReceiptReader, SubmittedRedemption, forwarding StartRedemptionRecovery, ProcessRedemptions, RetryRedemption, ReconcileSubmitted, RedeemPending, and redundant migration/command/metrics/storage-check wrappers. These were not in 1.0.6 and have not shipped in a published release. Remaining orchestrator RedeemerDB integration adds receipt admission/readiness behavior and is not this removed re-export layer.

Other backfill / compatibility matches reviewed

  • Runtime canonical-chain backfill/reorg reconstruction: eth/payment_observer.go:203 (introduced by c6d7411, assigned 1.07) and eth/senderwatcher.go:172 (introduced by 3562562, assigned 1.07). These rebuild current chain observations after polling gaps/reorgs; they are ongoing recovery behavior, not old-database upgrade shims. Keep them unless their runtime responsibility is replaced.
  • SDK compatibility fixtures (cmd/livepeer/testdata/*compat*, runner session/media fixture scripts, pm/wire/*_test.go) exercise the contracts above. Retire or update their affected cases with the matching item; do not delete all SDK integration coverage as “legacy.”
  • lpdb.sqlite3 fixtures in chain/cli_test.go and orchestrator/app_test.go verify old files are left untouched, not an old-database reader/backfill. Legacy signed client state is explicitly not migrated (docs/payment-recovery.md).
  • No missing-observed_at compatibility backfill exists: v1.0.3+ deliberately rejects unstamped v1.0.2 inventories; see #51. .github/scripts/test-release.sh likewise tests rejection of the old release invocation. These are not retained compatibility implementations.
  • +incompatible in the indirect module version, Chainlink/ABI “compatible” descriptions, normal zero/default fallbacks, and ordinary historical transaction reconciliation are not independently removable upgrade shims.

Completion criteria

  • Record the actual removal release, replacement/minimum supported client or DB version, and implementing PR against each checked item.
  • For C07–C10/C14, distinguish a deliberate protocol/API change from ordinary cleanup; these still implement active consumer/on-chain contracts.
  • For D01–D04/D06, use an explicit minimum-schema/baseline or offline upgrade plan. Embedded migrations are checksummed and history-validated; do not edit/delete an applied migration while its upgrade path remains supported. Preserve winning tickets, signature aliases, signed transactions, settlement/exposure evidence, and recovery from supported backups.
  • Update the relevant documentation and focused SDK/HTTP/upgrade/recovery checks when each behavior is retired. No removal deadline is assumed by this inventory.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions