feat: add Fynd subsolver provider (COW-1274)

.env.fynd-subsolver.example

@@ -0,0 +1,14 @@
+ORDERBOOK_URL=http://host.docker.internal:8080
+BYOS_URL=http://host.docker.internal:9585
+RPC_URL=
+SUBSOLVER_PRIVATE_KEY=
+CONFIG_PATH=config.toml
+SUBSOLVER_PROVIDER=fynd
+FYND_URL=http://fynd:3000
+FYND_SLIPPAGE_BPS=50
+FYND_QUOTE_CONCURRENCY=32
+FYND_MAX_QUOTE_AGE_SECONDS=10
+GPV2_SETTLEMENT=
+BYOS_REQUESTS_PER_MINUTE=100
+BYOS_READ_RESERVE=10
+PROPOSAL_REFRESH_INTERVAL_SECONDS=15

.env.subsolver.example

@@ -0,0 +1,8 @@
+ORDERBOOK_URL=http://host.docker.internal:8080
+BYOS_URL=http://host.docker.internal:9585
+RPC_URL=
+SUBSOLVER_PRIVATE_KEY=
+CONFIG_PATH=config.toml
+BYOS_REQUESTS_PER_MINUTE=100
+BYOS_READ_RESERVE=10
+PROPOSAL_REFRESH_INTERVAL_SECONDS=15

.gitignore

@@ -9,6 +9,7 @@ node_modules/
 .env
 .env.*
 !.env.example
+!.env.*.example
 
 # Local agent state
 .claude/

Dockerfile

@@ -8,6 +8,7 @@ COPY pnpm-lock.yaml pnpm-workspace.yaml package.json ./
 COPY apps/byos/package.json apps/byos/
 COPY apps/subsolver/package.json apps/subsolver/
 COPY packages/common/package.json packages/common/
+COPY packages/subsolver-core/package.json packages/subsolver-core/
 
 RUN pnpm install --frozen-lockfile
 
@@ -32,6 +33,13 @@ COPY --from=build /app/apps/byos/node_modules apps/byos/node_modules/
 COPY --from=build /app/packages/common/dist packages/common/dist/
 COPY --from=build /app/packages/common/package.json packages/common/
 COPY --from=build /app/packages/common/node_modules packages/common/node_modules/
+# Configurable subsolver executable and reusable provider package.
+COPY --from=build /app/apps/subsolver/dist apps/subsolver/dist/
+COPY --from=build /app/apps/subsolver/package.json apps/subsolver/
+COPY --from=build /app/apps/subsolver/node_modules apps/subsolver/node_modules/
+COPY --from=build /app/packages/subsolver-core/dist packages/subsolver-core/dist/
+COPY --from=build /app/packages/subsolver-core/package.json packages/subsolver-core/
+COPY --from=build /app/packages/subsolver-core/node_modules packages/subsolver-core/node_modules/
 
 EXPOSE 9585 9586
 CMD ["node", "apps/byos/dist/index.js"]

apps/byos/drizzle/0004_nonce_uniqueness_and_supersession.sql

@@ -0,0 +1,16 @@
+ALTER TABLE "proposals" ADD COLUMN "superseded_by_proposal_id" bigint;--> statement-breakpoint
+ALTER TABLE "proposals" ADD CONSTRAINT "proposals_superseded_by_proposal_id_proposals_id_fk" FOREIGN KEY ("superseded_by_proposal_id") REFERENCES "public"."proposals"("id") ON DELETE no action ON UPDATE no action;--> statement-breakpoint
+WITH newest_active AS (
+  SELECT DISTINCT ON (sub_solver, order_uid) id, sub_solver, order_uid
+  FROM "proposals"
+  WHERE status = 'active'
+  ORDER BY sub_solver, order_uid, id DESC
+)
+UPDATE "proposals" AS old
+SET status = 'superseded', superseded_by_proposal_id = newest_active.id
+FROM newest_active
+WHERE old.sub_solver = newest_active.sub_solver
+  AND old.order_uid = newest_active.order_uid
+  AND old.id < newest_active.id
+  AND old.status IN ('submitted', 'active');--> statement-breakpoint
+CREATE UNIQUE INDEX "proposals_sub_solver_nonce_key" ON "proposals" USING btree ("sub_solver","nonce");

apps/byos/drizzle/0005_supersession_reference_retention.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "proposals" DROP CONSTRAINT "proposals_superseded_by_proposal_id_proposals_id_fk";--> statement-breakpoint
+ALTER TABLE "proposals" ADD CONSTRAINT "proposals_superseded_by_proposal_id_proposals_id_fk" FOREIGN KEY ("superseded_by_proposal_id") REFERENCES "public"."proposals"("id") ON DELETE set null ON UPDATE no action;

apps/byos/drizzle/meta/_journal.json

@@ -29,6 +29,20 @@
 			"when": 1786896000000,
 			"tag": "0003_buffer_entries",
 			"breakpoints": true
+		},
+		{
+			"idx": 4,
+			"version": "7",
+			"when": 1787780800000,
+			"tag": "0004_nonce_uniqueness_and_supersession",
+			"breakpoints": true
+		},
+		{
+			"idx": 5,
+			"version": "7",
+			"when": 1787940000000,
+			"tag": "0005_supersession_reference_retention",
+			"breakpoints": true
 		}
 	]
 }

apps/byos/openapi.yml

@@ -1,6 +1,6 @@
 openapi: 3.0.3
 
 info:
   title: BYOS Proposal API
   description: |
     The public HTTP API by which sub-solvers submit signed settlement
@@ -77,7 +77,7 @@
 
 paths:
   /healthz:
     get:
       operationId: healthz
       summary: Health check.
       description: >-
@@ -90,7 +90,7 @@
           description: Service is up.
 
   /proposals:
     post:
       operationId: createProposal
       summary: Submit a signed settlement proposal.
       description: |
@@ -143,7 +143,7 @@
   /proposal/{id}:
     parameters:
       - $ref: "#/components/parameters/ProposalIdPath"
     get:
       operationId: getProposal
       summary: Get one of the caller's proposals.
       description: |
@@ -183,7 +183,7 @@
         "503":
           $ref: "#/components/responses/ServiceUnavailable"
 
     delete:
       operationId: cancelProposal
       summary: Cancel a live proposal.
       description: |
@@ -225,7 +225,7 @@
           $ref: "#/components/responses/ServiceUnavailable"
 
   /proposals/by-sub-solver:
     get:
       operationId: listProposalsBySubSolver
       summary: List the caller's own proposals.
       description: |
@@ -253,7 +253,7 @@
           $ref: "#/components/responses/ServiceUnavailable"
 
   /proposals/{orderUid}:
     get:
       operationId: listProposalsByOrder
       summary: List the caller's proposals on one order.
       description: |
@@ -418,6 +418,9 @@
         - `penalized` — that debit landed; see `penaltyTxHash`.
         - `simFailed` — the settlement simulation reverted.
         - `cancelled` — cancelled by a signed `DELETE`.
+        - `superseded` — a newer validated proposal from the same sub-solver
+          replaced this route for the order. It may still receive a delayed
+          settlement outcome and expires at `validUntil`.
 
         All states except `submitted`, `active`, `executing`, and
         `settleFailed` are terminal.
@@ -433,6 +436,7 @@
         - penalized
         - simFailed
         - cancelled
+        - superseded
     RejectionReason:
       description: |
         Why the background validator rejected a proposal:
@@ -593,17 +597,24 @@
       required:
         - id
         - subSolver
+        - orderUid
         - validUntil
         - status
       properties:
         id:
           $ref: "#/components/schemas/ProposalId"
         subSolver:
           $ref: "#/components/schemas/Address"
+        orderUid:
+          $ref: "#/components/schemas/OrderUid"
         validUntil:
           $ref: "#/components/schemas/UnixTimestamp"
         status:
           $ref: "#/components/schemas/ProposalStatus"
+        supersededByProposalId:
+          description: Present when this proposal was replaced by a newer active proposal.
+          allOf:
+            - $ref: "#/components/schemas/ProposalId"
     ListProposalsResponse:
       type: object
       required:

apps/byos/src/db/schema.ts

@@ -9,6 +9,7 @@ import {
 	primaryKey,
 	text,
 	timestamp,
+	uniqueIndex,
 } from "drizzle-orm/pg-core";
 
 // --- proposals ---
@@ -37,13 +38,15 @@ export const proposals = pgTable(
 		settlementTxHash: text("settlement_tx_hash"),
 		penaltyTxHash: text("penalty_tx_hash"),
 		pendingCancellation: boolean("pending_cancellation").notNull().default(false),
+		supersededByProposalId: bigint("superseded_by_proposal_id", { mode: "number" }),
 		createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
 		statusChangedAt: timestamp("status_changed_at", { withTimezone: true }).notNull().defaultNow(),
 	},
 	(table) => [
 		index("proposals_order_uid_status_idx").on(table.orderUid, table.status),
 		index("proposals_sub_solver_status_idx").on(table.subSolver, table.status),
 		index("proposals_status_status_changed_at_idx").on(table.status, table.statusChangedAt),
+		uniqueIndex("proposals_sub_solver_nonce_key").on(table.subSolver, table.nonce),
 	],
 );
 

apps/byos/src/domain/audit.ts

@@ -4,6 +4,13 @@ import type { Proposal } from "./proposal.js";
 
 export type AuditKind =
 	| { type: "received"; proposal: Proposal }
+	| {
+			type: "nonceConflict";
+			proposalId: number;
+			subSolver: Address;
+			orderUid: string;
+			incomingFingerprint: string;
+	  }
 	| { type: "cancelled"; proposalId: number; subSolver: Address; orderUid: string }
 	// Emitted when a sub-solver requests cancellation while the proposal is in
 	// an active auction settlement ("executing"). The proposal stays executing
@@ -63,6 +70,8 @@ export function eventType(kind: AuditKind): string {
 	switch (kind.type) {
 		case "received":
 			return "received";
+		case "nonceConflict":
+			return "nonce_conflict";
 		case "cancelled":
 			return "cancelled";
 		case "cancellationDeferred":
@@ -115,6 +124,8 @@ export function auditPayload(kind: AuditKind): Record<string, unknown> {
 				nonce: kind.proposal.nonce.toString(),
 				signature: kind.proposal.signature,
 			};
+		case "nonceConflict":
+			return { incomingFingerprint: kind.incomingFingerprint };
 		case "cancelled":
 			return {};
 		case "cancellationDeferred":

apps/byos/src/domain/proposal.ts

@@ -28,6 +28,8 @@ export interface Proposal {
 	settlementTxHash: Hex | null;
 	penaltyTxHash: Hex | null;
 	pendingCancellation: boolean;
+	/** Set when a newer proposal for this sub-solver/order supersedes this one. */
+	supersededByProposalId?: number | null;
 }
 
 /** What the driver reported about a settlement. */

apps/byos/src/infra/__tests__/audit.db.test.ts

@@ -113,4 +113,29 @@ describe("audit persistence", () => {
 
 		expect(rows.length).toBeGreaterThanOrEqual(1);
 	});
+
+	it("persists a nonce conflict against the original proposal", async () => {
+		const event: AuditEvent = {
+			occurredAt: new Date(),
+			kind: {
+				type: "nonceConflict",
+				proposalId: 4,
+				subSolver: "0xe05fcc23807536bee418f142d19fa0d21bb0cff7" as Address,
+				orderUid: `0x${"ab".repeat(56)}`,
+				incomingFingerprint: "signed-payload-fingerprint",
+			},
+		};
+
+		await insertAuditEvent(ctx.db, event);
+
+		const [row] = await ctx.db
+			.select()
+			.from(auditEvents)
+			.where(eq(auditEvents.eventType, "nonce_conflict"));
+		expect(row).toMatchObject({ proposalId: 4, eventType: "nonce_conflict" });
+		if (!row) throw new Error("nonce conflict audit event missing");
+		expect((row.payload as Record<string, unknown>).incomingFingerprint).toBe(
+			"signed-payload-fingerprint",
+		);
+	});
 });