@asyncswap/engine-rpc 0.0.1

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @asyncswap/engine-rpc
+
+## 0.0.1
+
+### Patch Changes
+
+- 97a6143: engine rpc spec
+
+  - Adds class for engine api spec
+  - Add example and docs
+
+- Updated dependencies [cad9042]
+  - @asyncswap/eth-rpc@0.4.8

package/README.md

@@ -0,0 +1,35 @@
+# @asyncswap/engine-rpc
+
+A library for Ethereum engine api JSON-RPC spec.
+
+## Installation
+
+```
+bun add @asyncswap/engine-rpc 
+```
+
+## Quick Start
+
+### Engine API Client
+
+```typescript
+import { EngineExecutionClient } from '@asyncswap/eth-rpc';
+
+const engineUrl = 'http://localhost:8551';
+const engine = new EngineExecutionClient(engineUrl, process.env.JWT_TOKEN!);
+const payload = await engine.engine_getPayloadV1("0x1");
+
+console.log(payload);
+```
+
+## References
+
+- [ethereum/execution-apis](https://github.com/ethereum/execution-apis/tree/main/src/engine)
+
+## Dependencies
+
+- `@asyncswap/eth-rpc` - lib for ethereum execution client JSON-RPC 2.0 api.
+
+## License
+
+MIT

package/example.ts

@@ -0,0 +1,6 @@
+import { EngineExecutionClient } from "./src";
+
+const engineUrl = "http://localhost:8551";
+const engine = new EngineExecutionClient(engineUrl, process.env.JWT_TOKEN!);
+const payload = await engine.eth_chainId();
+console.log(payload);

package/package.json

@@ -0,0 +1,45 @@
+{
+  "name": "@asyncswap/engine-rpc",
+  "description": "A library for Ethereum engine api JSON-RPC spec.",
+  "author": "Meek Msaki",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "ethereum",
+    "engine-api",
+    "execution-client",
+    "json-rpc"
+  ],
+  "homepage": "https://github.com/asyncswap/eth-libs/tree/main/packages/flashbots-rpc",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/asyncswap/eth-libs.git",
+    "directory": "packages/flashbots-rpc"
+  },
+  "bugs": {
+    "url": "https://github.com/asyncswap/eth-libs/issues"
+  },
+  "publishConfig": {
+    "access": "public",
+    "directory": "dist"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "publish": "bun run build && bun publish --access public",
+    "format": "bun biome format --write"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.3.11",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "@asyncswap/eth-rpc": "^0.4.8"
+  }
+}

package/src/engine-api.ts

@@ -0,0 +1,19 @@
+import { BaseClient } from "@asyncswap/eth-rpc";
+
+export class EngineExecutionClient extends BaseClient<EngineMethodsSpec> {
+  constructor(url: string, jwt_token: string) {
+    super(url);
+    this.headers = {
+      Authorization: `Bearer ${jwt_token}`,
+    };
+  }
+}
+
+export type EngineRpcMethods<
+  T extends Record<string, { params: readonly unknown[]; result: unknown }>,
+> = {
+    [K in keyof T]: (...params: T[K]["params"]) => Promise<T[K]["result"]>;
+  };
+
+export interface EngineExecutionClient
+  extends EngineRpcMethods<EngineMethodsSpec> { }

package/src/index.ts

@@ -0,0 +1 @@
+export * from "./engine-api";

package/src/types/blob.d.ts

@@ -0,0 +1,12 @@
+declare global {
+	export interface BlobAndProofV1 {
+		blob: Bytes;
+		proof: Bytes48;
+	}
+	export interface BlobAndProofV2 {
+		blob: Bytes;
+		proofs: Bytes48[];
+	}
+}
+
+export { };

package/src/types/forkchoice.d.ts

@@ -0,0 +1,32 @@
+declare global {
+	// forkchoice
+	export interface ForkchoiceStateV1 {
+		headBlockHash: Hash32;
+		safeBlockHash: Hash32;
+		finalizedBlockHash: Hash32;
+	}
+	export interface ForkchoiceUpdatedResponseV1 {
+		payloadStatus: RestrictedPayloadStatusV1;
+		payloadId?: Bytes8;
+	}
+	export interface PayloadAttributesV1 {
+		timestamp: Uint64;
+		prevRandao: Bytes32;
+		suggestedFeeRecipient: Address;
+	}
+	export interface PayloadAttributesV2 {
+		timestamp: Uint64;
+		prevRandao: Bytes32;
+		suggestedFeeRecipient: Address;
+		withdrawals: WithdrawalV1[];
+	}
+	export interface PayloadAttributesV3 {
+		timestamp: Uint64;
+		prevRandao: Bytes32;
+		suggestedFeeRecipient: Address;
+		withdrawals: WithdrawalV1[];
+		parentBeaconBlockRoot: Hash32;
+	}
+}
+
+export { };

package/src/types/identification.d.ts

@@ -0,0 +1,24 @@
+declare global {
+	export type ClientVersionV1 = {
+		code: ClientCode;
+		name: string;
+		varsion: string;
+		commit: string;
+	};
+	export type ClientCode =
+		| "BU" // besu
+		| "EJ" // ethereumJs
+		| "EG" // erigon
+		| "GE" // go-ethereum
+		| "GR" // gradine
+		| "LH" // lighthouse
+		| "LS" // lodestar
+		| "NM" // nethermind
+		| "NB" // nimbus
+		| "TE" // thin-execution
+		| "TK" // teku
+		| "PM" // prysm
+		| "RH"; // reth
+}
+
+export { };

package/src/types/methods.d.ts

@@ -0,0 +1,130 @@
+declare global {
+	export type EngineMethodsSpec = {
+		// identification
+		engine_getClientVersionV1: {
+			params: [ClientVersionV1];
+			result: ClientVersionV1[];
+		};
+		// share methods
+		eth_blockNumber: { params: []; result: Uint };
+		eth_call: {
+			params: [GenericTransaction, BlockNumberOrTagOrHash];
+			result: Bytes;
+		};
+		eth_chainId: { params: []; result: Uint };
+		eth_getCode: { params: [Address, BlockNumberOrTagOrHash]; result: Bytes };
+		eth_getBlockByHash: { params: [Hash32, boolean]; result: NotFound | Block };
+		eth_getBlockByNumber: {
+			params: [BlockNumberOrTag, boolean];
+			result: NotFound | Block;
+		};
+		eth_getLogs: { params: [Filter]; result: FilterResults };
+		eth_sendRawTransaction: { params: [Bytes]; result: Hash32 };
+		eth_syncing: { params: []; result: SyncingStatus };
+		// engine/blob
+		engine_getBlobsV1: { params: [Hash32[]]; result: BlobAndProofV1[] };
+		engine_getBlobsV2: { params: [Hash32[]]; result: BlobAndProofV2[] };
+		engine_getBlobsV3: {
+			params: [Hash32[]];
+			result: Array<BlobAndProofV2[] | null> | null;
+		};
+		// engine/capabilities
+		engine_exchangeCapabilities: { params: [string[]]; result: string[] };
+		// engine/forkchoice
+		engine_forkchoiceUpdatedV1: {
+			params: [ForkchoiceStateV1, PayloadAttributesV1];
+			result: ForkchoiceUpdatedResponseV1;
+		};
+		engine_forkchoiceUpdatedV2: {
+			params: [ForkchoiceStateV1, PayloadAttributesV2];
+			result: ForkchoiceUpdatedResponseV1;
+		};
+		engine_forkchoiceUpdatedV3: {
+			params: [ForkchoiceStateV1, PayloadAttributesV3];
+			result: ForkchoiceUpdatedResponseV1;
+		};
+		// engine/payload
+		engine_newPayloadV1: {
+			params: [ExecutionPayloadV1];
+			result: PayloadStatusV1;
+		};
+		engine_newPayloadV2: {
+			params: [ExecutionPayloadV1 | ExecutionPayloadV2];
+			result: PayloadStatusNoInvalidBlockHash;
+		};
+		engine_newPayloadV3: {
+			params: [ExecutionPayloadV3, Hash32[], Hash32];
+			result: PayloadStatusNoInvalidBlockHash;
+		};
+		engine_newPayloadV4: {
+			params: [ExecutionPayloadV3, Hash32[], Hash32, Bytes[]];
+			result: PayloadStatusNoInvalidBlockHash;
+		};
+		engine_getPayloadV1: { params: [Bytes8]; result: ExecutionPayloadV1 };
+		engine_getPayloadV2: {
+			params: [Bytes8];
+			result: {
+				executionPayload: ExecutionPayloadV1 | ExecutionPayloadV2;
+				blockValue: Uint256;
+			};
+		};
+		engine_getPayloadV3: {
+			params: [Bytes8];
+			result: {
+				executionPayload: ExecutionPayloadV3;
+				blockValue: Uint256;
+				blobsBundle: BlobsBundleV1;
+				shouldOverrideBuilder: boolean;
+			};
+		};
+		engine_getPayloadV4: {
+			params: [Bytes8];
+			result: {
+				executionPayload: ExecutionPayloadV3;
+				blockValue: Uint256;
+				blobsBundle: BlobsBundleV1;
+				shouldOverrideBuilder: boolean;
+				executionRequests: Bytes[];
+			};
+		};
+		engine_getPayloadV5: {
+			params: [Bytes8];
+			result: {
+				executionPayload: ExecutionPayloadV3;
+				blockValue: Uint256;
+				blobsBundle: BlobsBundleV2;
+				shouldOverrideBuilder: boolean;
+				executionRequests: Bytes[];
+			};
+		};
+		engine_getPayloadBodiesByHashV1: {
+			params: [Hash32[]];
+			result: ExecutionPayloadBodyV1[];
+		};
+		engine_getPayloadBodiesByRangeV1: {
+			params: [Uint64, Uint64];
+			result: ExecutionPayloadBodyV1[];
+		};
+		engine_newPayloadV5: {
+			params: [ExecutionPayloadV4, Hash32[], Hash32, Bytes[]];
+			result: PayloadStatusNoInvalidBlockHash;
+		};
+		engine_getPayloadV6: {
+			params: [Bytes8];
+			result: {
+				executionPayload: ExecutionPayloadV4;
+				blockValue: Uint256;
+				blobsBundle: BlobsBundleV2;
+				shouldOverrideBuilder: boolean;
+				executionRequests: Bytes[];
+			};
+		};
+		// engine/transition-configuration
+		engine_exchangeTransitionConfigurationV1: {
+			params: [TransitionConfigurationV1];
+			result: TransitionConfigurationV1;
+		};
+	};
+}
+
+export { };

package/src/types/payload.d.ts

@@ -0,0 +1,121 @@
+declare global {
+	export enum PAYLOAD_STATUS {
+		VALID = "VALID",
+		INVALID = "INVALID",
+		SYNCING = "SYNCING",
+		ACCEPTED = "ACCEPTED",
+		INVALID_BLOCK_HASH = "INVALID_BLOCK_HASH",
+	}
+	export interface PayloadStatusV1 {
+		status: PAYLOAD_STATUS;
+		latestValidHash?: Hash32;
+		validationError?: string;
+	}
+	export interface RestrictedPayloadStatusV1 {
+		status:
+		| PAYLOAD_STATUS.VALID
+		| PAYLOAD_STATUS.INVALID
+		| PAYLOAD_STATUS.SYNCING;
+		latestValidHash: Hash32;
+		validationError: string;
+	}
+	export interface PayloadStatusNoInvalidBlockHash {
+		status: Exclude<PAYLOAD_STATUS, PAYLOAD_STATUS.INVALID_BLOCK_HASH>;
+		latestValidHash: Hash32;
+		validationError: string;
+	}
+	export interface ExecutionPayloadV1 {
+		parentHash: Hash32;
+		feeRecipient: Address;
+		stateRoot: Bytes32;
+		receiptsRoot: Bytes32;
+		logsBloom: Bytes256;
+		prevRandao: Bytes32;
+		blockNumber: Uint64;
+		gasLimit: Uint64;
+		gasUsed: Uint64;
+		timestamp: Uint64;
+		extraData: Bytes32;
+		baseFeePerGas: Uint64;
+		blockHash: Hash32;
+		transactions: Bytes[];
+	}
+	export interface WithdrawalV1 {
+		index: Uint64;
+		validatorIndex: Uint64;
+		address: Address;
+		amount: Uint64;
+	}
+	export interface ExecutionPayloadV2 {
+		parentHash: Hash32;
+		feeRecipient: Address;
+		stateRoot: Bytes32;
+		receiptsRoot: Bytes32;
+		logsBloom: Bytes256;
+		prevRandao: Bytes32;
+		blockNumber: Uint64;
+		gasLimit: Uint64;
+		gasUsed: Uint64;
+		timestamp: Uint64;
+		extraData: Bytes32;
+		baseFeePerGas: Uint64;
+		blockHash: Hash32;
+		transactions: Bytes[];
+		withdrawals: WithdrawalV1[];
+	}
+	export interface ExecutionPayloadV3 {
+		parentHash: Hash32;
+		feeRecipient: Address;
+		stateRoot: Bytes32;
+		receiptsRoot: Bytes32;
+		logsBloom: Bytes256;
+		prevRandao: Bytes32;
+		blockNumber: Uint64;
+		gasLimit: Uint64;
+		gasUsed: Uint64;
+		timestamp: Uint64;
+		extraData: Bytes32;
+		baseFeePerGas: Uint64;
+		blockHash: Hash32;
+		transactions: Bytes[];
+		withdrawals: WithdrawalV1[];
+		blobGasUsed: Uint64;
+		excessBlobGas: Uint64;
+	}
+	export interface ExecutionPayloadV4 {
+		parentHash: Hash32;
+		feeRecipient: Address;
+		stateRoot: Bytes32;
+		receiptsRoot: Bytes32;
+		logsBloom: Bytes256;
+		prevRandao: Bytes32;
+		blockNumber: Uint64;
+		gasLimit: Uint64;
+		gasUsed: Uint64;
+		timestamp: Uint64;
+		extraData: Bytes32;
+		baseFeePerGas: Uint64;
+		blockHash: Hash32;
+		transactions: Bytes[];
+		withdrawals: WithdrawalV1[];
+		blobGasUsed: Uint64;
+		excessBlobGas: Uint64;
+		blockAccessList: Bytes;
+	}
+	export interface ExecutionPayloadBodyV1 {
+		transactions: Bytes[];
+		withdrawals?: WithdrawalV1[];
+	}
+	export interface BlobsBundleV1 {
+		commitments: Bytes48[];
+		proofs: Bytes48[];
+		blobs: Bytes[];
+	}
+	export interface BlobsBundleV2 {
+		commitments: Bytes48[];
+		proofs: Bytes48[];
+		blobs: Bytes[];
+	}
+}
+
+export { };

package/src/types/transition-configuration.d.ts

@@ -0,0 +1,10 @@
+declare global {
+	// engine types
+	export interface TransitionConfigurationV1 {
+		terminalTotalDifficulty: Uint256;
+		terminalBlockHash: Hash32;
+		terminalBlockNumber: Uint64;
+	}
+}
+
+export { };

package/tsconfig.json

@@ -0,0 +1,40 @@
+{
+	"compilerOptions": {
+		// Environment setup & latest features
+		"lib": [
+			"ESNext"
+		],
+		"target": "ESNext",
+		"module": "Preserve",
+		"moduleDetection": "force",
+		"jsx": "react-jsx",
+		"allowJs": true,
+		// Bundler mode
+		"sourceMap": true,
+		"declaration": true,
+		"declarationMap": true,
+		"moduleResolution": "bundler",
+		"outDir": "dist",
+		"rootDir": "src",
+		"allowImportingTsExtensions": false,
+		"verbatimModuleSyntax": true,
+		"noEmit": false,
+		// Best practices
+		"strict": true,
+		"skipLibCheck": true,
+		"noFallthroughCasesInSwitch": true,
+		"noUncheckedIndexedAccess": true,
+		"noImplicitOverride": true,
+		// Some stricter flags (disabled by default)
+		"noUnusedLocals": false,
+		"noUnusedParameters": false,
+		"noPropertyAccessFromIndexSignature": false
+	},
+	"include": [
+		"src/**/*",
+		"global.d.ts"
+	],
+	"exclude": [
+		"example.ts"
+	]
+}