@conquest-eth/tools 0.0.0

package/src/cli.ts

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+import {StdioServerTransport} from '@modelcontextprotocol/sdk/server/stdio.js';
+import {createServer} from './index.js';
+import {Command} from 'commander';
+import pkg from '../package.json' with {type: 'json'};
+import {getChain} from 'tools-ethereum/helpers';
+import {loadEnv} from 'ldenv';
+import * as tools from './tools/index.js';
+import {registerAllToolCommands} from './cli-tool-generator.js';
+
+loadEnv();
+
+const program = new Command();
+
+// Get the binary name from package.json
+const binName = Object.keys(pkg.bin || {})[0];
+
+program
+	.name(binName)
+	.description(pkg.description || 'Conquest.eth CLI - MCP server and direct tool execution')
+	.version(pkg.version)
+	// Global options available to all commands
+	.option('--rpc-url <url>', 'RPC URL for the Ethereum network', process.env.RPC_URL || '')
+	.option(
+		'--game-contract <address>',
+		'Contract address of the game',
+		process.env.GAME_CONTRACT || '',
+	)
+	.option('--storage <type>', 'Storage backend: json or sqlite', process.env.STORAGE_TYPE || 'json')
+	.option(
+		'--storage-path <path>',
+		'Path to storage directory',
+		process.env.STORAGE_PATH || './data',
+	)
+	.option(
+		'--private-key <key>',
+		'Private key for sending transactions',
+		process.env.PRIVATE_KEY || '',
+	)
+	.action(() => {
+		program.help();
+	});
+
+// MCP subcommand - starts the MCP server
+program
+	.command('mcp')
+	.description('Start the MCP server')
+	.option(
+		'--ethereum',
+		'Whether to also provide tools-ethereum tools',
+		process.env.ETHEREUM_TOOLS === 'true',
+	)
+	.action(async () => {
+		const options = program.opts();
+		const mcpOptions = program.commands.find((cmd) => cmd.name() === 'mcp')?.opts() || {};
+
+		const rpcUrl = options.rpcUrl;
+		const gameContract = options.gameContract;
+		const ethereum = mcpOptions.ethereum ?? process.env.ETHEREUM_TOOLS === 'true';
+		const privateKey = options.privateKey;
+		const storage = options.storage;
+		const storagePath = options.storagePath;
+
+		// Validate required options
+		if (!rpcUrl) {
+			console.error('Error: --rpc-url option or RPC_URL environment variable is required');
+			process.exit(1);
+		}
+
+		if (!gameContract) {
+			console.error(
+				'Error: --game-contract option or GAME_CONTRACT environment variable is required',
+			);
+			process.exit(1);
+		}
+
+		// Warn if private key is not provided for write operations
+		if (!privateKey) {
+			console.warn(
+				'Warning: PRIVATE_KEY environment variable is required for sending transactions',
+			);
+		} else if (!privateKey.startsWith('0x')) {
+			console.error('Error: PRIVATE_KEY must start with 0x');
+			process.exit(1);
+		}
+
+		const chain = await getChain(rpcUrl);
+		const transport = new StdioServerTransport();
+		const server = createServer(
+			{
+				chain,
+				privateKey: privateKey as `0x${string}`,
+				gameContract: gameContract as `0x${string}`,
+			},
+			{
+				ethereum,
+				storageConfig: {
+					type: storage as 'json' | 'sqlite',
+					dataDir: storagePath,
+				},
+			},
+		);
+		await server.connect(transport);
+	});
+
+// Register all tool commands dynamically
+registerAllToolCommands(program, tools);
+
+program.parse(process.argv);

package/src/contracts/space-info.ts

@@ -0,0 +1,41 @@
+import {SpaceInfo} from 'conquest-eth-v0-contracts';
+import type {ClientsWithOptionalWallet, ContractConfig, GameContract} from '../types.js';
+
+export async function createSpaceInfo(
+	clients: ClientsWithOptionalWallet,
+	gameContract: GameContract,
+): Promise<{spaceInfo: SpaceInfo; contractConfig: ContractConfig}> {
+	// Fetch config from contract
+	const config = await clients.publicClient.readContract({
+		...gameContract,
+		functionName: 'getConfig',
+	});
+
+	const contractConfig: ContractConfig = {
+		genesis: BigInt(config.genesis),
+		resolveWindow: BigInt(config.resolveWindow),
+		timePerDistance: BigInt(config.timePerDistance),
+		exitDuration: BigInt(config.exitDuration),
+		acquireNumSpaceships: Number(config.acquireNumSpaceships),
+	};
+
+	// Create SpaceInfo instance with config
+	const spaceInfo = new SpaceInfo({
+		genesis: config.genesis as `0x${string}`,
+		resolveWindow: Number(config.resolveWindow),
+		timePerDistance: Number(config.timePerDistance),
+		exitDuration: Number(config.exitDuration),
+		acquireNumSpaceships: Number(config.acquireNumSpaceships),
+		productionSpeedUp: Number(config.productionSpeedUp),
+		productionCapAsDuration: Number(config.productionCapAsDuration),
+		upkeepProductionDecreaseRatePer10000th: Number(config.upkeepProductionDecreaseRatePer10000th),
+		fleetSizeFactor6: Number(config.fleetSizeFactor6),
+		giftTaxPer10000: Number(config.giftTaxPer10000),
+		stakeRange: config.stakeRange,
+		stakeMultiplier10000th: Number(config.stakeMultiplier10000th),
+		bootstrapSessionEndTime: Number(config.bootstrapSessionEndTime),
+		infinityStartTime: Number(config.infinityStartTime),
+	});
+
+	return {spaceInfo, contractConfig};
+}

package/src/fleet/index.ts

@@ -0,0 +1,8 @@
+// Fleet Manager and exports
+export {FleetManager} from './manager.js';
+
+// Send functions
+export {sendFleet} from './send.js';
+
+// Resolve functions
+export {resolveFleet, resolveFleetWithSpaceInfo, getResolvableFleets} from './resolve.js';

package/src/fleet/manager.ts

@@ -0,0 +1,140 @@
+import type {Address} from 'viem';
+import type {SpaceInfo} from 'conquest-eth-v0-contracts';
+import type {FleetStorage} from '../storage/interface.js';
+import type {
+	Clients,
+	ClientsWithOptionalWallet,
+	ContractConfig,
+	GameContract,
+	PendingFleet,
+} from '../types.js';
+import {getResolvableFleets, resolveFleetWithSpaceInfo} from './resolve.js';
+import {sendFleet} from './send.js';
+/**
+ * FleetManager manages the lifecycle of fleets in the Conquest game
+ * including sending new fleets and resolving existing ones
+ */
+export class FleetManager {
+	constructor(
+		private readonly clients: ClientsWithOptionalWallet,
+		private readonly gameContract: GameContract,
+		private readonly spaceInfo: SpaceInfo,
+		private readonly contractConfig: ContractConfig,
+		private readonly storage: FleetStorage,
+		// private readonly contractAddress: Address,
+	) {}
+
+	/**
+	 * Ensure walletClient is available for operations that require it
+	 */
+	private requireWalletClient(): Clients {
+		if (!this.clients.walletClient) {
+			throw new Error(
+				'Wallet client is required for this operation. Please provide a PRIVATE_KEY environment variable.',
+			);
+		}
+		return this.clients as Clients;
+	}
+
+	/**
+	 * Send a fleet to a destination planet
+	 */
+	async send(
+		fromPlanetId: bigint,
+		toPlanetId: bigint,
+		quantity: number,
+		options?: {
+			gift?: boolean;
+			specific?: Address;
+			arrivalTimeWanted?: bigint;
+			secret?: `0x${string}`;
+		},
+	): Promise<PendingFleet> {
+		return sendFleet(
+			this.requireWalletClient(),
+			this.gameContract,
+			fromPlanetId,
+			toPlanetId,
+			quantity,
+			this.spaceInfo,
+			this.contractConfig,
+			this.storage,
+			options,
+		);
+	}
+
+	/**
+	 * Resolve (reveal) a fleet to complete its journey
+	 */
+	async resolve(
+		fleetId: string,
+	): Promise<{resolved: true; fleet: PendingFleet} | {resolved: false; reason: string}> {
+		return resolveFleetWithSpaceInfo(
+			this.requireWalletClient(),
+			this.gameContract,
+			this.spaceInfo,
+			fleetId,
+			this.storage,
+		);
+	}
+
+	/**
+	 * Get fleets that can be resolved (not yet resolved and past resolve window)
+	 */
+	async getResolvableFleets(): Promise<PendingFleet[]> {
+		return getResolvableFleets(this.storage, this.contractConfig.resolveWindow);
+	}
+
+	/**
+	 * Get all pending fleets for the current sender
+	 */
+	async getMyPendingFleets(): Promise<PendingFleet[]> {
+		const sender = this.requireWalletClient().walletClient.account!.address;
+		return this.storage.getPendingFleetsBySender(sender);
+	}
+
+	/**
+	 * Get a specific fleet by ID
+	 */
+	async getFleet(fleetId: string): Promise<PendingFleet | null> {
+		return this.storage.getFleet(fleetId);
+	}
+
+	/**
+	 * Get all fleets in storage
+	 */
+	async getAllFleets(): Promise<PendingFleet[]> {
+		return this.storage.getAllFleets();
+	}
+
+	/**
+	 * Resolve all fleets that are ready (batch operation)
+	 */
+	async resolveAllReady(): Promise<{
+		successful: PendingFleet[];
+		failed: Array<{fleetId: string; reason: string}>;
+	}> {
+		const readyFleets = await this.getResolvableFleets();
+		const successful: PendingFleet[] = [];
+		const failed: Array<{fleetId: string; reason: string}> = [];
+
+		for (const fleet of readyFleets) {
+			const result = await this.resolve(fleet.fleetId);
+			if (result.resolved) {
+				successful.push(result.fleet);
+			} else {
+				failed.push({fleetId: fleet.fleetId, reason: result.reason});
+			}
+		}
+
+		return {successful, failed};
+	}
+
+	/**
+	 * Clean up old resolved fleets from storage
+	 */
+	async cleanupOldResolvedFleets(olderThanDays: number = 7): Promise<void> {
+		const olderThan = Math.floor(Date.now() / 1000) - olderThanDays * 24 * 60 * 60;
+		await this.storage.cleanupOldResolvedFleets(olderThan);
+	}
+}

package/src/fleet/resolve.ts

@@ -0,0 +1,187 @@
+import type {Address, WalletClient} from 'viem';
+import type {SpaceInfo} from 'conquest-eth-v0-contracts';
+import type {FleetStorage} from '../storage/interface.js';
+import {Clients, FleetResolution, GameContract, PendingFleet} from '../types.js';
+import {getCurrentTimestamp} from '../util/time.js';
+
+/**
+ * Resolve (reveal) a fleet to complete its journey and trigger combat
+ *
+ * @param walletClient - Viem wallet client for signing transactions
+ * @param fleetsRevealContract - The fleets reveal contract instance with address, abi, and clients
+ * @param fleetId - The fleet ID to resolve
+ * @param storage - Storage instance for tracking pending fleets
+ * @returns The resolution result with either resolved fleet or reason for failure
+ */
+export async function resolveFleet(
+	walletClient: WalletClient,
+	fleetsRevealContract: {
+		address: Address;
+		abi: readonly unknown[];
+		publicClient: unknown;
+		walletClient: WalletClient | undefined;
+	},
+	fleetId: string,
+	storage: FleetStorage,
+): Promise<{resolved: true; fleet: PendingFleet} | {resolved: false; reason: string}> {
+	// Get the pending fleet from storage
+	const pendingFleet = await storage.getFleet(fleetId);
+
+	if (!pendingFleet) {
+		return {resolved: false, reason: `Fleet ${fleetId} not found in storage`};
+	}
+
+	if (pendingFleet.resolved) {
+		return {resolved: false, reason: `Fleet ${fleetId} has already been resolved`};
+	}
+
+	// The operator must be the same as the wallet client account
+	const operator = walletClient.account!.address;
+	if (pendingFleet.operator !== operator) {
+		return {resolved: false, reason: `Only the operator can resolve this fleet`};
+	}
+
+	// Build the FleetResolution struct
+	const resolution: FleetResolution = {
+		from: pendingFleet.fromPlanetId,
+		to: pendingFleet.toPlanetId,
+		distance: 0n, // Will be calculated by SpaceInfo
+		arrivalTimeWanted: pendingFleet.arrivalTimeWanted,
+		gift: pendingFleet.gift,
+		specific: pendingFleet.specific,
+		secret: pendingFleet.secret,
+		fleetSender: pendingFleet.fleetSender,
+		operator: pendingFleet.operator,
+	};
+
+	// Get the contract resolveFleet function signature
+	const publicClient = fleetsRevealContract.publicClient as any;
+	const request = await publicClient.simulateContract({
+		address: fleetsRevealContract.address,
+		abi: fleetsRevealContract.abi,
+		functionName: 'resolveFleet',
+		args: [BigInt('0x' + fleetId), resolution],
+		account: operator,
+	});
+
+	// Send the transaction
+	const hash = await walletClient.writeContract(request);
+
+	// Mark fleet as resolved in storage
+	const resolvedAt = getCurrentTimestamp();
+	await storage.markResolved(fleetId, resolvedAt);
+
+	// Update the fleet record
+	const resolvedFleet: PendingFleet = {
+		...pendingFleet,
+		resolved: true,
+		resolvedAt,
+	};
+
+	return {resolved: true, fleet: resolvedFleet};
+}
+
+/**
+ * Resolve a fleet with custom SpaceInfo for distance calculation
+ *
+ * @param clients - Viem clients (publicClient and walletClient)
+ * @param gameContract - The game contract instance with address and ABI
+ * @param spaceInfo - SpaceInfo instance for distance calculation
+ * @param fleetId - The fleet ID to resolve
+ * @param storage - Storage instance for tracking pending fleets
+ * @returns The resolution result with either resolved fleet or reason for failure
+ */
+export async function resolveFleetWithSpaceInfo(
+	clients: Clients,
+	gameContract: GameContract,
+	spaceInfo: SpaceInfo,
+	fleetId: string,
+	storage: FleetStorage,
+): Promise<{resolved: true; fleet: PendingFleet} | {resolved: false; reason: string}> {
+	// Get the pending fleet from storage
+	const pendingFleet = await storage.getFleet(fleetId);
+
+	if (!pendingFleet) {
+		return {resolved: false, reason: `Fleet ${fleetId} not found in storage`};
+	}
+
+	if (pendingFleet.resolved) {
+		return {resolved: false, reason: `Fleet ${fleetId} has already been resolved`};
+	}
+
+	// The operator must be the same as the wallet client account
+	const operator = clients.walletClient.account!.address;
+	if (pendingFleet.operator !== operator) {
+		return {resolved: false, reason: `Only the operator can resolve this fleet`};
+	}
+
+	// Get planet info for distance calculation
+	const fromPlanet = spaceInfo.getPlanetInfoViaId(pendingFleet.fromPlanetId);
+	const toPlanet = spaceInfo.getPlanetInfoViaId(pendingFleet.toPlanetId);
+
+	if (!fromPlanet || !toPlanet) {
+		return {resolved: false, reason: 'Could not get planet info for one or both planets'};
+	}
+
+	// Calculate distance using SpaceInfo
+	const distance = spaceInfo.distance(fromPlanet, toPlanet);
+
+	// Build the FleetResolution struct
+	const resolution: FleetResolution = {
+		from: pendingFleet.fromPlanetId,
+		to: pendingFleet.toPlanetId,
+		distance: BigInt(distance),
+		arrivalTimeWanted: pendingFleet.arrivalTimeWanted,
+		gift: pendingFleet.gift,
+		specific: pendingFleet.specific,
+		secret: pendingFleet.secret,
+		fleetSender: pendingFleet.fleetSender,
+		operator: pendingFleet.operator,
+	};
+
+	// Get the contract resolveFleet function signature
+	const simulation = await clients.publicClient.simulateContract({
+		address: gameContract.address,
+		abi: gameContract.abi,
+		functionName: 'resolveFleet',
+		args: [BigInt(fleetId), resolution],
+		account: operator,
+	});
+
+	// Send the transaction
+	const hash = await clients.walletClient.writeContract(simulation.request);
+
+	// Mark fleet as resolved in storage
+	const resolvedAt = getCurrentTimestamp();
+	await storage.markResolved(fleetId, resolvedAt);
+
+	// Update the fleet record
+	const resolvedFleet: PendingFleet = {
+		...pendingFleet,
+		resolved: true,
+		resolvedAt,
+	};
+
+	return {resolved: true, fleet: resolvedFleet};
+}
+
+/**
+ * Get fleets that can be resolved (not yet resolved and past resolve window)
+ *
+ * @param storage - Storage instance for tracking pending fleets
+ * @param resolveWindow - The resolve window duration in seconds from contract config
+ * @returns List of fleets that can be resolved
+ */
+export async function getResolvableFleets(
+	storage: FleetStorage,
+	resolveWindow: bigint,
+): Promise<PendingFleet[]> {
+	const currentTime = getCurrentTimestamp();
+	const fleets = await storage.getResolvableFleets();
+
+	return fleets.filter((fleet) => {
+		// Check if fleet is past the resolve window
+		const resolveWindowOpen = fleet.estimatedArrivalTime + Number(resolveWindow);
+		return !fleet.resolved && currentTime >= resolveWindowOpen;
+	});
+}

package/src/fleet/send.ts

@@ -0,0 +1,112 @@
+import {zeroAddress, type Address} from 'viem';
+import type {SpaceInfo} from 'conquest-eth-v0-contracts';
+import type {FleetStorage} from '../storage/interface.js';
+import type {Clients, ContractConfig, GameContract, PendingFleet} from '../types.js';
+import {computeFleetId, computeToHash, generateSecret} from '../util/hashing.js';
+import {calculateEstimatedArrivalTime, getCurrentTimestamp} from '../util/time.js';
+
+/**
+ * Send a fleet to a destination planet
+ *
+ * @param clients - Viem clients (publicClient and walletClient)
+ * @param gameContract - The game contract instance with address and ABI
+ * @param fromPlanetId - Source planet location ID
+ * @param toPlanetId - Destination planet location ID
+ * @param quantity - Number of spaceships to send
+ * @param spaceInfo - SpaceInfo instance for distance calculation
+ * @param contractConfig - Contract config for time calculations
+ * @param storage - Storage instance for tracking pending fleets
+ * @param options - Optional parameters
+ * @param options.gift - Whether the fleet is a gift (no combat)
+ * @param options.specific - Specific target address (advanced feature)
+ * @param options.arrivalTimeWanted - Preferred arrival time (advanced feature)
+ * @param options.secret - Random secret for hash commitment (auto-generated if not provided)
+ * @returns The pending fleet information
+ */
+export async function sendFleet(
+	clients: Clients,
+	gameContract: GameContract,
+	fromPlanetId: bigint,
+	toPlanetId: bigint,
+	quantity: number,
+	spaceInfo: SpaceInfo,
+	contractConfig: ContractConfig,
+	storage: FleetStorage,
+	options?: {
+		gift?: boolean;
+		specific?: Address;
+		arrivalTimeWanted?: bigint;
+		secret?: `0x${string}`;
+	},
+): Promise<PendingFleet> {
+	const fleetSender = clients.walletClient.account!.address;
+	const operator = fleetSender; // Default to same address
+
+	// Get planet info for distance calculation
+	const fromPlanet = spaceInfo.getPlanetInfoViaId(fromPlanetId);
+	const toPlanet = spaceInfo.getPlanetInfoViaId(toPlanetId);
+
+	if (!fromPlanet || !toPlanet) {
+		throw new Error('Could not get planet info for one or both planets');
+	}
+
+	// Calculate distance
+	const distance = spaceInfo.distance(fromPlanet, toPlanet);
+
+	// Generate secret if not provided
+	const secret = options?.secret || generateSecret();
+
+	// Calculate estimated arrival time using contract config
+	const estimatedArrivalTime = calculateEstimatedArrivalTime({
+		startTime: BigInt(getCurrentTimestamp()),
+		distance: BigInt(distance),
+		timePerDistance: contractConfig.timePerDistance,
+	});
+
+	const parameters = {
+		gift: options?.gift ?? false,
+		specific: options?.specific ?? zeroAddress,
+		arrivalTimeWanted: options?.arrivalTimeWanted || 0n,
+	};
+	const toHash = computeToHash(toPlanetId, secret, parameters);
+
+	// Get the contract send function signature
+	const simulation = await clients.publicClient.simulateContract({
+		address: gameContract.address,
+		abi: gameContract.abi,
+		functionName: 'send',
+		args: [fromPlanetId, quantity, toHash],
+		account: fleetSender,
+	});
+
+	// Compute fleet ID
+	const fleetId = computeFleetId(toHash, fromPlanetId, fleetSender, operator);
+
+	// Create pending fleet record
+	const pendingFleet: PendingFleet = {
+		fleetId,
+		fromPlanetId,
+		toPlanetId,
+		quantity,
+		secret,
+		gift: parameters.gift,
+		specific: parameters.specific,
+		arrivalTimeWanted: parameters.arrivalTimeWanted,
+		fleetSender,
+		operator,
+		committedAt: getCurrentTimestamp(),
+		estimatedArrivalTime,
+		resolved: false,
+	};
+
+	// we always save to storage first in case an error happen while the tx is still broadcasted
+	await storage.saveFleet(pendingFleet);
+
+	// Send the transaction
+	const hash = await clients.walletClient.writeContract(simulation.request);
+
+	pendingFleet.hash = hash;
+	await storage.saveFleet(pendingFleet);
+
+	return pendingFleet;
+}

package/src/helpers/index.ts

@@ -0,0 +1,59 @@
+import type {Tool, ToolEnvironment} from '../types.js';
+import type {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import type {FleetManager} from '../fleet/manager.js';
+import type {PlanetManager} from '../planet/manager.js';
+import {convertToCallToolResult} from '../types.js';
+
+// Helper function to handle BigInt serialization in JSON.stringify
+export function stringifyWithBigInt(obj: any, space?: number): string {
+	return JSON.stringify(
+		obj,
+		(_key, value) => (typeof value === 'bigint' ? value.toString() : value),
+		space,
+	);
+}
+
+// Create tool environment with sendStatus
+export function createToolEnvironment(
+	server: McpServer,
+	fleetManager: FleetManager,
+	planetManager: PlanetManager,
+): ToolEnvironment {
+	return {
+		sendStatus: async (_message: string) => {
+			// TODO: Implement progress notifications when sessionId is available
+			// For now, this is a no-op since we don't have sessionId in the current architecture
+		},
+		fleetManager,
+		planetManager,
+	};
+}
+
+// Register tool with MCP server
+export function registerTool({
+	server,
+	name,
+	tool,
+	fleetManager,
+	planetManager,
+}: {
+	server: McpServer;
+	name: string;
+	tool: Tool<any>;
+	fleetManager: FleetManager;
+	planetManager: PlanetManager;
+}): void {
+	server.registerTool(
+		name,
+		{
+			description: tool.description,
+			inputSchema: tool.schema as any,
+		},
+		async (params: unknown) => {
+			const env = createToolEnvironment(server, fleetManager, planetManager);
+
+			const result = await tool.execute(env, params as any);
+			return convertToCallToolResult(result);
+		},
+	);
+}