chore: remove outdated reasoning of the API definitions comment (#7475)

**Motivation**

Forgot to update this as part of
#6749, but adding new
endpoints is much simpler / cleaner now and everything is inferred from
`Endpoint` type definition when adding a new route, it's not possible to
forget updating something as typescript will complain (and also spec
tests). So instead of updating this I figured it's best to just remove
it, looking at the code is much easier to figure out what do to than
having to read some text I would put there, eg. see example
#7472.

**Description**

Remove outdated reasoning of the API definitions comment

Author: nflaig

packages/api/src/beacon/routes/beacon/block.ts

@@ -27,8 +27,6 @@ import {
 } from "../../../utils/metadata.js";
 import {WireFormat} from "../../../utils/wireFormat.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export const BlockHeaderResponseType = new ContainerType({
   root: ssz.Root,
   canonical: ssz.Boolean,

packages/api/src/beacon/routes/beacon/index.ts

@@ -7,8 +7,6 @@ import * as pool from "./pool.js";
 import * as rewards from "./rewards.js";
 import * as state from "./state.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 // NOTE: We choose to split the block, pool, state and rewards namespaces so the files are not too big.
 // However, for a consumer all these methods are within the same service "beacon"
 export {block, pool, state, rewards};

packages/api/src/beacon/routes/beacon/pool.ts

@@ -27,8 +27,6 @@ import {fromHeaders} from "../../../utils/headers.js";
 import {Endpoint, RouteDefinitions, Schema} from "../../../utils/index.js";
 import {MetaHeader, VersionCodec, VersionMeta} from "../../../utils/metadata.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 const SingleAttestationListTypePhase0 = ArrayOf(ssz.phase0.Attestation);
 const SingleAttestationListTypeElectra = ArrayOf(ssz.electra.SingleAttestation);
 const AttestationListTypePhase0 = ArrayOf(ssz.phase0.Attestation);

packages/api/src/beacon/routes/beacon/rewards.ts

@@ -9,8 +9,6 @@ import {fromValidatorIdsStr, toValidatorIdsStr} from "../../../utils/serdes.js";
 import {BlockArgs} from "./block.js";
 import {ValidatorId} from "./state.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 const BlockRewardsType = new ContainerType(
   {
     /** Proposer of the block, the proposer index who receives these rewards */

packages/api/src/beacon/routes/beacon/state.ts

@@ -14,8 +14,6 @@ import {fromValidatorIdsStr, toValidatorIdsStr} from "../../../utils/serdes.js";
 import {WireFormat} from "../../../utils/wireFormat.js";
 import {RootResponse, RootResponseType} from "./block.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export type StateId = RootHex | Slot | "head" | "genesis" | "finalized" | "justified";
 
 export type StateArgs = {

packages/api/src/beacon/routes/config.ts

@@ -12,8 +12,6 @@ import {
 } from "../../utils/codecs.js";
 import {Endpoint, RouteDefinitions} from "../../utils/index.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export const DepositContractType = new ContainerType(
   {
     chainId: ssz.UintNum64,

packages/api/src/beacon/routes/debug.ts

@@ -19,8 +19,6 @@ import {Endpoint, RouteDefinitions} from "../../utils/types.js";
 import {WireFormat} from "../../utils/wireFormat.js";
 import {StateArgs} from "./beacon/state.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 const stringType = new StringType();
 const ProtoNodeType = new ContainerType(
   {

packages/api/src/beacon/routes/events.ts

@@ -25,8 +25,6 @@ import {getPostAltairForkTypes, getPostBellatrixForkTypes} from "../../utils/for
 import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
 import {VersionType} from "../../utils/metadata.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 const stringType = new StringType();
 export const blobSidecarSSE = new ContainerType(
   {

packages/api/src/beacon/routes/index.ts

@@ -30,43 +30,3 @@ export type Endpoints = {
   proof: ProofEndpoints;
   validator: ValidatorEndpoints;
 };
-
-// TODO: update to reflect new design
-// Reasoning of the API definitions
-// ================================
-//
-// An HTTP request to the Lodestar BeaconNode API involves these steps regarding serialization:
-// 1. Serialize request: api args => req params
-//    --- wire
-// 2. Deserialize request: req params => api args
-//    --- exec api
-// 3. Serialize api return => res body
-//    --- wire
-// 4. Deserialize res body => api return
-//
-// In our case we define the client in the exact same interface as the API executor layer.
-// Therefore we only need to define how to translate args <-> request, and return <-> response.
-//
-// All files in the /routes directory provide succinct definitions to do those transformations plus:
-// - URL + method, for each route ID
-// - Runtime schema, for each route ID
-//
-// Almost all routes receive JSON and return JSON. So both the client and the server can be
-// auto-generated from the definitions. Also, the design allows for customizability for the few
-// routes that need non-JSON serialization (like debug.getState and lightclient.getProof)
-//
-// With this approach Typescript help us ensure that the client and server are compatible at build
-// time, ensure there are tests for all routes and makes it very cheap to maintain and add new routes.
-//
-//
-// How to add new routes
-// =====================
-//
-// 1. Add the route function signature to the `Api` type. The function name MUST match the routeId from the spec.
-//    The arguments should use spec types if appropriate. Non-spec types MUST be defined in before the Api type
-//    so they are scoped by routes namespace. The all arguments MUST use camelCase casing.
-// 2. Add URL + METHOD in `routesData` matching the spec.
-// 3. Declare request serializers in `getReqSerializers()`. You MAY use `RouteReqTypeGenerator` to declare the
-//    ReqTypes and request serializers in the same place.
-// 4. Add the return type of the route to `getReturnTypes()` if it has any. The return type doesn't have to be
-//    a full SSZ type, but just a TypeJson with allows to convert from struct -> json -> struct.

packages/api/src/beacon/routes/lightclient.ts

@@ -23,8 +23,6 @@ import {getPostAltairForkTypes, toForkName} from "../../utils/fork.js";
 import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
 import {MetaHeader, VersionCodec, VersionMeta} from "../../utils/metadata.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export const HashListType = new ListCompositeType(ssz.Root, 10000);
 export type HashList = ValueOf<typeof HashListType>;
 

packages/api/src/beacon/routes/lodestar.ts

@@ -16,8 +16,6 @@ import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
 import {StateArgs} from "./beacon/state.js";
 import {FilterGetPeers, NodePeer, PeerDirection, PeerState} from "./node.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export type SyncChainDebugState = {
   targetRoot: string | null;
   targetSlot: number | null;

packages/api/src/beacon/routes/node.ts

@@ -16,8 +16,6 @@ import {HttpStatusCode} from "../../utils/httpStatusCode.js";
 import {Endpoint, RouteDefinitions, Schema} from "../../utils/index.js";
 import {WireFormat} from "../../utils/wireFormat.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export const NetworkIdentityType = new ContainerType(
   {
     /** Cryptographic hash of a peer’s public key. [Read more](https://docs.libp2p.io/concepts/peer-id/) */

packages/api/src/beacon/routes/proof.ts

@@ -12,8 +12,6 @@ export const CompactMultiProofType = new ContainerType({
   descriptor: new ByteListType(2048),
 });
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export type Endpoints = {
   /**
    * Returns a multiproof of `descriptor` at the requested `stateId`.

packages/api/src/beacon/routes/validator.ts

@@ -45,8 +45,6 @@ import {
 } from "../../utils/metadata.js";
 import {fromGraffitiHex, toBoolean, toGraffitiHex} from "../../utils/serdes.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 export enum BuilderSelection {
   Default = "default",
   BuilderAlways = "builderalways",

packages/api/src/builder/routes.ts

@@ -30,8 +30,6 @@ import {fromHeaders} from "../utils/headers.js";
 import {Endpoint, RouteDefinitions, Schema} from "../utils/index.js";
 import {MetaHeader, VersionCodec, VersionMeta} from "../utils/metadata.js";
 
-// See /packages/api/src/routes/index.ts for reasoning and instructions to add new routes
-
 // Mev-boost might not return any data if there are no bids from builders or min-bid threshold was not reached.
 // In this case, we receive a success response (204) which is not handled as an error. The generic response
 // handler already checks the status code and will not attempt to parse the body, but it will return no value.