@conquest-eth/tools 0.0.0

package/src/storage/interface.ts

@@ -0,0 +1,111 @@
+import type {Address} from 'viem';
+import {PendingExit, PendingFleet} from '../types.js';
+
+/**
+ * Storage interface for managing fleets and planet exits
+ * Provides methods to persist and retrieve game state data
+ */
+export interface FleetStorage {
+	// Fleet operations
+
+	/**
+	 * Save a pending fleet to storage
+	 * @param fleet - The fleet to save
+	 */
+	saveFleet(fleet: PendingFleet): Promise<void>;
+
+	/**
+	 * Retrieve a fleet by its ID
+	 * @param fleetId - The fleet ID to retrieve
+	 * @returns The fleet or null if not found
+	 */
+	getFleet(fleetId: string): Promise<PendingFleet | null>;
+
+	/**
+	 * Get all pending fleets for a specific sender
+	 * @param sender - The address of the fleet sender
+	 * @returns Array of pending fleets
+	 */
+	getPendingFleetsBySender(sender: Address): Promise<PendingFleet[]>;
+
+	/**
+	 * Get all fleets that can be resolved (not yet resolved)
+	 * @returns Array of resolvable fleets
+	 */
+	getResolvableFleets(): Promise<PendingFleet[]>;
+
+	/**
+	 * Mark a fleet as resolved
+	 * @param fleetId - The fleet ID to mark as resolved
+	 * @param resolvedAt - The timestamp when the fleet was resolved
+	 */
+	markResolved(fleetId: string, resolvedAt: number): Promise<void>;
+
+	/**
+	 * Clean up old resolved fleets from storage
+	 * @param olderThan - Unix timestamp; fleets resolved before this time will be removed
+	 */
+	cleanupOldResolvedFleets(olderThan: number): Promise<void>;
+
+	/**
+	 * Get all fleets in storage
+	 * @returns Array of all fleets
+	 */
+	getAllFleets(): Promise<PendingFleet[]>;
+
+	// Exit operations
+
+	/**
+	 * Save a pending exit to storage
+	 * @param exit - The exit to save
+	 */
+	savePendingExit(exit: PendingExit): Promise<void>;
+
+	/**
+	 * Retrieve a pending exit by planet ID
+	 * @param planetId - The planet location ID
+	 * @returns The pending exit or null if not found
+	 */
+	getPendingExit(planetId: bigint): Promise<PendingExit | null>;
+
+	/**
+	 * Get all pending exits for a specific player
+	 * @param player - The address of the player
+	 * @returns Array of pending exits
+	 */
+	getPendingExitsByPlayer(player: Address): Promise<PendingExit[]>;
+
+	/**
+	 * Update the status of a pending exit
+	 * @param planetId - The planet location ID
+	 * @param updates - Partial updates to apply to the exit record
+	 */
+	updateExitStatus(planetId: bigint, updates: Partial<PendingExit>): Promise<void>;
+
+	/**
+	 * Mark an exit as completed
+	 * @param planetId - The planet location ID
+	 * @param completedAt - The timestamp when the exit completed
+	 */
+	markExitCompleted(planetId: bigint, completedAt: number): Promise<void>;
+
+	/**
+	 * Mark an exit as interrupted by an attack
+	 * @param planetId - The planet location ID
+	 * @param interruptedAt - The timestamp when the exit was interrupted
+	 * @param newOwner - The address of the new owner who interrupted the exit
+	 */
+	markExitInterrupted(planetId: bigint, interruptedAt: number, newOwner: Address): Promise<void>;
+
+	/**
+	 * Clean up old completed exits from storage
+	 * @param olderThan - Unix timestamp; exits completed before this time will be removed
+	 */
+	cleanupOldCompletedExits(olderThan: number): Promise<void>;
+
+	/**
+	 * Get all pending exits in storage
+	 * @returns Array of all pending exits
+	 */
+	getAllPendingExits(): Promise<PendingExit[]>;
+}

package/src/storage/json-storage.ts

@@ -0,0 +1,184 @@
+import {promises as fs} from 'fs';
+import path from 'path';
+import type {Address} from 'viem';
+import type {FleetStorage} from './interface.js';
+import {PendingExit, PendingFleet} from '../types.js';
+import {stringifyWithBigInt} from '../helpers/index.js';
+
+interface StorageData {
+	fleets: Record<string, PendingFleet>;
+	exits: Record<string, PendingExit>;
+}
+
+export class JsonFleetStorage implements FleetStorage {
+	private dataPath: string;
+	private data: StorageData;
+	private initialized = false;
+
+	constructor(dataDir: string = './data') {
+		this.dataPath = path.join(dataDir, 'conquest-data.json');
+		this.data = {fleets: {}, exits: {}};
+	}
+
+	async initialize(): Promise<void> {
+		if (this.initialized) {
+			return;
+		}
+		// Load from disk or create new
+		try {
+			await fs.mkdir(path.dirname(this.dataPath), {recursive: true});
+			const content = await fs.readFile(this.dataPath, 'utf-8');
+			const data = JSON.parse(content);
+			// Convert BigInt strings back to BigInt
+			for (const fleetId in data.fleets) {
+				const fleet = data.fleets[fleetId];
+				fleet.fromPlanetId = BigInt(fleet.fromPlanetId);
+				fleet.toPlanetId = BigInt(fleet.toPlanetId);
+				fleet.arrivalTimeWanted = BigInt(fleet.arrivalTimeWanted);
+			}
+			for (const planetId in data.exits) {
+				const exit = data.exits[planetId];
+				exit.planetId = BigInt(exit.planetId);
+			}
+			this.data = data;
+		} catch (error) {
+			// File doesn't exist, create new
+			await this.save();
+		}
+		this.initialized = true;
+	}
+
+	private async ensureInitialized(): Promise<void> {
+		if (!this.initialized) {
+			await this.initialize();
+		}
+	}
+
+	private async save(): Promise<void> {
+		await fs.writeFile(this.dataPath, stringifyWithBigInt(this.data, 2));
+	}
+
+	// Fleet operations
+	async saveFleet(fleet: PendingFleet): Promise<void> {
+		await this.ensureInitialized();
+		this.data.fleets[fleet.fleetId] = fleet;
+		await this.save();
+	}
+
+	async getFleet(fleetId: string): Promise<PendingFleet | null> {
+		await this.ensureInitialized();
+		return this.data.fleets[fleetId] || null;
+	}
+
+	async getPendingFleetsBySender(sender: Address): Promise<PendingFleet[]> {
+		await this.ensureInitialized();
+		return Object.values(this.data.fleets).filter(
+			(fleet) => fleet.fleetSender.toLowerCase() === sender.toLowerCase() && !fleet.resolved,
+		);
+	}
+
+	async getResolvableFleets(): Promise<PendingFleet[]> {
+		await this.ensureInitialized();
+		const now = Math.floor(Date.now() / 1000);
+		return Object.values(this.data.fleets).filter(
+			(fleet) => !fleet.resolved && fleet.estimatedArrivalTime <= now,
+		);
+	}
+
+	async markResolved(fleetId: string, resolvedAt: number): Promise<void> {
+		await this.ensureInitialized();
+		const fleet = this.data.fleets[fleetId];
+		if (fleet) {
+			fleet.resolved = true;
+			fleet.resolvedAt = resolvedAt;
+			await this.save();
+		}
+	}
+
+	async cleanupOldResolvedFleets(olderThan: number): Promise<void> {
+		await this.ensureInitialized();
+		const now = Math.floor(Date.now() / 1000);
+		for (const fleetId in this.data.fleets) {
+			const fleet = this.data.fleets[fleetId];
+			if (fleet.resolved && fleet.resolvedAt && fleet.resolvedAt < now - olderThan) {
+				delete this.data.fleets[fleetId];
+			}
+		}
+		await this.save();
+	}
+
+	async getAllFleets(): Promise<PendingFleet[]> {
+		await this.ensureInitialized();
+		return Object.values(this.data.fleets);
+	}
+
+	// Exit operations
+	async savePendingExit(exit: PendingExit): Promise<void> {
+		await this.ensureInitialized();
+		this.data.exits[exit.planetId.toString()] = exit;
+		await this.save();
+	}
+
+	async getPendingExit(planetId: bigint): Promise<PendingExit | null> {
+		await this.ensureInitialized();
+		return this.data.exits[planetId.toString()] || null;
+	}
+
+	async getPendingExitsByPlayer(player: Address): Promise<PendingExit[]> {
+		await this.ensureInitialized();
+		return Object.values(this.data.exits).filter(
+			(exit) => exit.player.toLowerCase() === player.toLowerCase() && !exit.completed,
+		);
+	}
+
+	async updateExitStatus(planetId: bigint, updates: Partial<PendingExit>): Promise<void> {
+		await this.ensureInitialized();
+		const exit = this.data.exits[planetId.toString()];
+		if (exit) {
+			Object.assign(exit, updates);
+			await this.save();
+		}
+	}
+
+	async markExitCompleted(planetId: bigint, completedAt: number): Promise<void> {
+		await this.ensureInitialized();
+		const exit = this.data.exits[planetId.toString()];
+		if (exit) {
+			exit.completed = true;
+			exit.lastCheckedAt = completedAt;
+			await this.save();
+		}
+	}
+
+	async markExitInterrupted(
+		planetId: bigint,
+		interruptedAt: number,
+		newOwner: Address,
+	): Promise<void> {
+		await this.ensureInitialized();
+		const exit = this.data.exits[planetId.toString()];
+		if (exit) {
+			exit.interrupted = true;
+			exit.lastCheckedAt = interruptedAt;
+			exit.owner = newOwner;
+			await this.save();
+		}
+	}
+
+	async cleanupOldCompletedExits(olderThan: number): Promise<void> {
+		await this.ensureInitialized();
+		const now = Math.floor(Date.now() / 1000);
+		for (const planetId in this.data.exits) {
+			const exit = this.data.exits[planetId];
+			if (exit.completed && exit.lastCheckedAt < now - olderThan) {
+				delete this.data.exits[planetId];
+			}
+		}
+		await this.save();
+	}
+
+	async getAllPendingExits(): Promise<PendingExit[]> {
+		await this.ensureInitialized();
+		return Object.values(this.data.exits);
+	}
+}

package/src/tools/acquire_planets.ts

@@ -0,0 +1,81 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+import {stringifyWithBigInt} from '../helpers/index.js';
+
+export const acquire_planets = createTool({
+	description:
+		'Acquire (stake) multiple planets in the Conquest game. This allows you to take ownership of unclaimed planets.',
+	schema: z.object({
+		planetIds: z
+			.array(z.union([z.string(), z.number()]))
+			.describe('Array of planet location IDs to acquire (as hex strings or numbers)'),
+		amountToMint: z
+			.number()
+			.optional()
+			.describe(
+				'Amount of native token to spend to acquire the planets. If not provided, will be calculated automatically based on planet stats.',
+			),
+		tokenAmount: z
+			.number()
+			.optional()
+			.describe(
+				'Amount of staking token to spend to acquire the planets. If not provided, will be calculated automatically based on planet stats.',
+			),
+	}),
+	execute: async (env, {planetIds, amountToMint, tokenAmount}) => {
+		try {
+			// Convert planet IDs to BigInt
+			const planetIdsBigInt = planetIds.map((id) =>
+				typeof id === 'string' ? BigInt(id) : BigInt(id),
+			);
+
+			let result: {
+				hash: `0x${string}`;
+				planetsAcquired: bigint[];
+				amountToMint: bigint;
+				tokenAmount: bigint;
+			};
+
+			// If BOTH amounts are provided, use them; otherwise use auto-calculation
+			if (amountToMint !== undefined && tokenAmount !== undefined) {
+				// Use provided amounts
+				// TODO decimal handling, for now BigInt()
+				const acquireResult = await env.planetManager.acquire(
+					planetIdsBigInt,
+					BigInt(amountToMint),
+					BigInt(tokenAmount),
+				);
+				result = {
+					hash: acquireResult.hash,
+					planetsAcquired: acquireResult.planetsAcquired,
+					amountToMint: BigInt(amountToMint),
+					tokenAmount: BigInt(tokenAmount),
+				};
+			} else {
+				// Use auto-calculation
+				const autoResult = await env.planetManager.acquireWithAutoCalc(planetIdsBigInt);
+				result = {
+					hash: autoResult.hash,
+					planetsAcquired: autoResult.planetsAcquired,
+					amountToMint: autoResult.costs.amountToMint,
+					tokenAmount: autoResult.costs.tokenAmount,
+				};
+			}
+
+			return {
+				success: true,
+				result: {
+					transactionHash: result.hash,
+					planetsAcquired: result.planetsAcquired,
+					amountToMint: result.amountToMint,
+					tokenAmount: result.tokenAmount,
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/exit_planets.ts

@@ -0,0 +1,35 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+
+export const exit_planets = createTool({
+	description:
+		'Exit (unstake) multiple planets to retrieve staked tokens. The exit process takes time and must be completed later.',
+	schema: z.object({
+		planetIds: z
+			.array(z.union([z.string(), z.number()]))
+			.describe('Array of planet location IDs to exit (as hex strings or numbers)'),
+	}),
+	execute: async (env, {planetIds}) => {
+		try {
+			// Convert planet IDs to BigInt
+			const planetIdsBigInt = planetIds.map((id) =>
+				typeof id === 'string' ? BigInt(id) : BigInt(id),
+			);
+
+			const result = await env.planetManager.exit(planetIdsBigInt);
+
+			return {
+				success: true,
+				result: {
+					transactionHash: result.hash,
+					exitsInitiated: result.exitsInitiated,
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/get_my_planets.ts

@@ -0,0 +1,30 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+
+export const get_my_planets = createTool({
+	description: 'Get all planets owned by the current user address.',
+	schema: z.object({
+		radius: z.number().max(50).describe('Search radius around origin (0,0) to find planets'),
+	}),
+	execute: async (env, {radius}) => {
+		try {
+			const planets = await env.planetManager.getMyPlanets(radius);
+
+			return {
+				success: true,
+				result: {
+					planets: planets.map(({info, state}) => ({
+						planetId: info.location.id.toString(),
+						location: info.location,
+						...state,
+					})),
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/get_pending_exits.ts

@@ -0,0 +1,37 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+
+export const get_pending_exits = createTool({
+	description: 'Get all pending exit (unstake) operations for your planets.',
+	schema: z.object({
+		// No properties needed for this tool
+	}),
+	execute: async (env) => {
+		try {
+			const exits = await env.planetManager.getMyPendingExits();
+
+			return {
+				success: true,
+				result: {
+					exits: exits.map((exit) => ({
+						planetId: exit.planetId,
+						player: exit.player,
+						exitStartTime: exit.exitStartTime,
+						exitDuration: exit.exitDuration,
+						exitCompleteTime: exit.exitCompleteTime,
+						numSpaceships: exit.numSpaceships,
+						owner: exit.owner,
+						completed: exit.completed,
+						interrupted: exit.interrupted,
+						lastCheckedAt: exit.lastCheckedAt,
+					})),
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/get_pending_fleets.ts

@@ -0,0 +1,41 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+
+export const get_pending_fleets = createTool({
+	description: 'Get all pending fleets sent from your planets.',
+	schema: z.object({
+		// No properties needed for this tool
+	}),
+	execute: async (env) => {
+		try {
+			const fleets = await env.fleetManager.getMyPendingFleets();
+
+			return {
+				success: true,
+				result: {
+					fleets: fleets.map((fleet) => ({
+						fleetId: fleet.fleetId,
+						fromPlanetId: fleet.fromPlanetId,
+						toPlanetId: fleet.toPlanetId,
+						quantity: fleet.quantity,
+						secret: fleet.secret,
+						gift: fleet.gift,
+						specific: fleet.specific,
+						arrivalTimeWanted: fleet.arrivalTimeWanted,
+						fleetSender: fleet.fleetSender,
+						operator: fleet.operator,
+						committedAt: fleet.committedAt,
+						estimatedArrivalTime: fleet.estimatedArrivalTime,
+						resolved: fleet.resolved,
+						resolvedAt: fleet.resolvedAt,
+					})),
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/get_planets_around.ts

@@ -0,0 +1,44 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+
+export const get_planets_around = createTool({
+	description:
+		'Get planets around a specific location within a certain radius. Useful for finding targets for fleet movement.',
+	schema: z.object({
+		centerX: z.number().describe('X coordinate of the center point'),
+		centerY: z.number().describe('Y coordinate of the center point'),
+		radius: z
+			.number()
+			.max(50)
+			.describe('Radius in distance units to search around the center point'),
+	}),
+	execute: async (env, {centerX, centerY, radius}) => {
+		try {
+			const planets = await env.planetManager.getPlanetsAround(centerX, centerY, radius);
+
+			return {
+				success: true,
+				result: {
+					center: {
+						x: centerX,
+						y: centerY,
+					},
+					radius,
+					planets: planets.map(({info, state}) => ({
+						planetId: info.location.id,
+						distance: Math.sqrt(
+							Math.pow(info.location.x - centerX, 2) + Math.pow(info.location.y - centerY, 2),
+						),
+						location: info.location,
+						...state,
+					})),
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/index.ts

@@ -0,0 +1,10 @@
+// Export all tools for auto-registration
+export {acquire_planets} from './acquire_planets.js';
+export {send_fleet} from './send_fleet.js';
+export {resolve_fleet} from './resolve_fleet.js';
+export {exit_planets} from './exit_planets.js';
+export {get_pending_exits} from './get_pending_exits.js';
+export {verify_exit_status} from './verify_exit_status.js';
+export {get_my_planets} from './get_my_planets.js';
+export {get_planets_around} from './get_planets_around.js';
+export {get_pending_fleets} from './get_pending_fleets.js';

package/src/tools/resolve_fleet.ts

@@ -0,0 +1,37 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+
+export const resolve_fleet = createTool({
+	description:
+		'Resolve a previously sent fleet. This must be called after the fleet arrival time + resolve window to reveal the destination and secret.',
+	schema: z.object({
+		fleetId: z.string().describe('Fleet ID to resolve'),
+	}),
+	execute: async (env, {fleetId}) => {
+		try {
+			const result = await env.fleetManager.resolve(fleetId);
+
+			if (result.resolved) {
+				return {
+					success: true,
+					result: {
+						fleetId: result.fleet.fleetId,
+						fromPlanetId: result.fleet.fromPlanetId,
+						toPlanetId: result.fleet.toPlanetId,
+						quantity: result.fleet.quantity,
+					},
+				};
+			} else {
+				return {
+					success: false,
+					error: result.reason,
+				};
+			}
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/send_fleet.ts

@@ -0,0 +1,68 @@
+import {z} from 'zod';
+import {createTool} from '../types.js';
+import {zeroAddress} from 'viem';
+
+export const send_fleet = createTool({
+	description:
+		'Send a fleet from one planet to another in the Conquest game. The fleet will travel through space and can be resolved after arrival.',
+	schema: z.object({
+		from: z.object({x: z.number(), y: z.number()}).describe('Source planet coordinates {x, y}'),
+		to: z.object({x: z.number(), y: z.number()}).describe('Destination planet coordinates {x, y}'),
+		quantity: z.number().describe('Number of spaceships to send'),
+		arrivalTimeWanted: z
+			.number()
+			.optional()
+			.describe(
+				'Desired arrival time (timestamp in seconds). If not specified, will be calculated based on distance.',
+			),
+		gift: z
+			.boolean()
+			.optional()
+			.describe('Whether the fleet is a gift (sent without requiring arrival)'),
+		specific: z.string().optional().describe('Additional specific data for the fleet'),
+	}),
+	execute: async (env, {from, to, quantity, arrivalTimeWanted, gift, specific}) => {
+		try {
+			// Convert coordinates to planet IDs
+			const fromPlanetId = env.planetManager.getPlanetIdByCoordinates(from.x, from.y);
+			if (!fromPlanetId) {
+				return {
+					success: false,
+					error: `No planet found at source coordinates (${from.x}, ${from.y})`,
+				};
+			}
+
+			const toPlanetId = env.planetManager.getPlanetIdByCoordinates(to.x, to.y);
+			if (!toPlanetId) {
+				return {
+					success: false,
+					error: `No planet found at destination coordinates (${to.x}, ${to.y})`,
+				};
+			}
+
+			const result = await env.fleetManager.send(fromPlanetId, toPlanetId, quantity, {
+				arrivalTimeWanted:
+					typeof arrivalTimeWanted === 'undefined' ? undefined : BigInt(arrivalTimeWanted),
+				gift: gift ?? false,
+				specific: (specific as `0x${string}`) ?? zeroAddress,
+			});
+
+			return {
+				success: true,
+				result: {
+					fleetId: result.fleetId,
+					from: result.fromPlanetId,
+					to: result.toPlanetId,
+					quantity: result.quantity,
+					arrivalTimeWanted: result.arrivalTimeWanted,
+					secret: result.secret,
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});