@polygonlabs/staker-pool-allocations-schemas 0.1.0

package/dist/management.js

@@ -0,0 +1,126 @@
+import { AddressSchema, DistributionIdSchema, NetworkSchema, PolUsdPriceSchema, WeiSchema } from "./common.js";
+import { z } from "./zod.js";
+// Body shape for `POST /v1/:network/management/distributions`.
+// `distributionId` is optional — when omitted, the handler derives the
+// monthly id (`YYYY-MM`) from the current date in UTC. Providing it
+// makes the call idempotent: re-POSTing with an existing id returns
+// 202 with the existing status rather than enqueueing a duplicate.
+//
+// `force` is the escape hatch for re-running a completed distribution
+// — operator confirms the inputs really changed, the prior completed
+// row + its allocations get hard-deleted, and the worker reruns. The
+// audit trail relies on the surrounding ops log + the persisted
+// `inputsHash`; no soft-delete or version history here in Phase 1.
+export const DistributionTriggerRequestSchema = z
+    .object({
+    startPoSBlock: WeiSchema.openapi({
+        description: 'Inclusive lower bound of the PoS block range to allocate over.'
+    }),
+    endPoSBlock: WeiSchema.openapi({
+        description: 'Exclusive upper bound of the PoS block range to allocate over.'
+    }),
+    distributionId: DistributionIdSchema.optional().openapi({
+        description: 'Optional. When omitted, derived as the current `YYYY-MM` (UTC). ' +
+            'Providing it makes the call idempotent — repeat POSTs with the ' +
+            'same id return the existing status.'
+    }),
+    force: z
+        .boolean()
+        .optional()
+        .openapi({
+        description: 'Re-run a previously completed distribution covering the same range. ' +
+            'Hard-deletes the prior completed row + allocations before the worker ' +
+            'starts. Use only after operator-confirmed input drift.'
+    }),
+    polUsdPrice: PolUsdPriceSchema.optional().openapi({
+        description: 'Optional POL/USD price override (decimal string, up to 6 dp). When ' +
+            'omitted, the worker fetches the spot price from CoinGecko at run ' +
+            "start. Pass a prior run's stored `polUsdPrice` to reproduce its " +
+            'merkle root and leaves on a `force` re-run — the price feeds the ' +
+            'USD-threshold exclusion that decides which allocations stay on-chain.'
+    })
+})
+    .openapi('DistributionTriggerRequest');
+// 202 response — the worker runs out-of-band on the same pod after
+// the handler returns. Operators poll the public distributions
+// endpoint (or the management `:id` view, Phase 1 follow-up) to
+// observe the terminal status.
+export const DistributionTriggerResponseSchema = z
+    .object({
+    network: NetworkSchema,
+    distributionId: DistributionIdSchema,
+    status: z.enum(['pending', 'running', 'completed', 'failed']).openapi({
+        description: 'Status snapshot at the moment the trigger returned. A freshly ' +
+            'enqueued run starts at `pending`; an idempotent hit on an ' +
+            'existing id returns whatever the current row says.'
+    })
+})
+    .openapi('DistributionTriggerResponse');
+// 200 response for `DELETE /v1/:network/management/distributions/:id`.
+// `priorStatus` is the state the row was in before removal — never
+// `completed`, which the handler refuses (those are published roots).
+export const DistributionDeleteResponseSchema = z
+    .object({
+    network: NetworkSchema,
+    distributionId: DistributionIdSchema,
+    removed: z.boolean(),
+    priorStatus: z.enum(['pending', 'running', 'failed']),
+    deletedAllocations: z
+        .number()
+        .int()
+        .nonnegative()
+        .openapi({
+        description: 'Number of allocation rows removed alongside the distribution. Normally 0 — ' +
+            'allocations are only persisted at completion, and completed rows cannot be deleted.'
+    })
+})
+    .openapi('DistributionDeleteResponse');
+// Body for `POST /v1/:network/management/excluded-addresses`. Adds (or
+// re-labels, on conflict) an address that receives an allocation but is
+// excluded from the merkle tree and settled off-chain (LST contracts and
+// other manually-handled addresses).
+export const AddExcludedAddressRequestSchema = z
+    .object({
+    address: AddressSchema.openapi({
+        description: 'Address to exclude from the merkle tree (settled off-chain).'
+    }),
+    label: z.string().min(1).max(256).openapi({
+        description: 'Human-readable note for the entry, e.g. the LST protocol name.'
+    }),
+    createdBy: z
+        .string()
+        .min(1)
+        .max(128)
+        .optional()
+        .openapi({
+        description: 'Actor id recorded on the row (who added it). Defaults to "management-api" ' +
+            'when omitted — the x-api-key gate carries no operator identity.'
+    })
+})
+    .openapi('AddExcludedAddressRequest');
+// A single excluded-address row as returned by the management API.
+export const ManagedExcludedAddressSchema = z
+    .object({
+    network: NetworkSchema,
+    address: AddressSchema,
+    label: z.string(),
+    createdBy: z.string(),
+    createdAt: z.iso.datetime(),
+    updatedAt: z.iso.datetime()
+})
+    .openapi('ManagedExcludedAddress');
+export const ExcludedAddressListResponseSchema = z
+    .object({
+    items: z.array(ManagedExcludedAddressSchema)
+})
+    .openapi('ExcludedAddressListResponse');
+// `DELETE` is idempotent: `removed` is false when the address wasn't in
+// the list (no 404), so re-running a delete is safe.
+export const RemoveExcludedAddressResponseSchema = z
+    .object({
+    network: NetworkSchema,
+    address: AddressSchema,
+    removed: z.boolean()
+})
+    .openapi('RemoveExcludedAddressResponse');
+//# sourceMappingURL=management.js.map

package/dist/management.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"management.js","sourceRoot":"","sources":["../src/management.ts"],"names":[],"mappings":"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"}

package/dist/proof.d.ts

@@ -0,0 +1,10 @@
+import { z } from './zod.ts';
+export declare const ProofResponseSchema: z.ZodObject<{
+    merkleRoot: z.ZodString;
+    address: z.ZodPipe<z.ZodString, z.ZodTransform<string, string>>;
+    amount: z.ZodString;
+    leafIndex: z.ZodNumber;
+    proof: z.ZodArray<z.ZodString>;
+}, z.core.$strip>;
+export type ProofResponse = z.infer<typeof ProofResponseSchema>;
+//# sourceMappingURL=proof.d.ts.map

package/dist/proof.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.d.ts","sourceRoot":"","sources":["../src/proof.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAC;AAS7B,eAAO,MAAM,mBAAmB;;;;;;iBAcL,CAAC;AAE5B,MAAM,MAAM,aAAa,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,mBAAmB,CAAC,CAAC"}

package/dist/proof.js

@@ -0,0 +1,25 @@
+import { AddressSchema, Hex32Schema, WeiSchema } from "./common.js";
+import { z } from "./zod.js";
+// Response for `GET /v1/:network/distributions/:id/allocations/:addr/proof`.
+// `proof` is the array of 32-byte hex sibling hashes the on-chain
+// `MultiRootDistributor` needs to reconstruct the merkle root from the leaf
+// `keccak256(abi.encodePacked(leafIndex, address, amount))`. Generated on
+// demand from the persisted allocations table — no proof is stored at
+// distribution time (spec D9). Pass `leafIndex`, `address`, `amount`, and
+// `proof` straight to `claim(root, index, account, amount, proof)`.
+export const ProofResponseSchema = z
+    .object({
+    merkleRoot: Hex32Schema.openapi({
+        description: 'Distribution merkle root — same value as `DistributionDetail.merkleRoot`.'
+    }),
+    address: AddressSchema,
+    amount: WeiSchema,
+    leafIndex: z.number().int().nonnegative().openapi({
+        description: 'Index of this leaf in the canonical (lowercased-address-sorted) tree.'
+    }),
+    proof: z.array(Hex32Schema).openapi({
+        description: 'Sibling-hash array. Pass straight to the claimer contract.'
+    })
+})
+    .openapi('ProofResponse');
+//# sourceMappingURL=proof.js.map

package/dist/proof.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"proof.js","sourceRoot":"","sources":["../src/proof.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACpE,OAAO,EAAE,CAAC,EAAE,MAAM,UAAU,CAAC;AAE7B,6EAA6E;AAC7E,kEAAkE;AAClE,4EAA4E;AAC5E,0EAA0E;AAC1E,sEAAsE;AACtE,0EAA0E;AAC1E,oEAAoE;AACpE,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC;KACjC,MAAM,CAAC;IACN,UAAU,EAAE,WAAW,CAAC,OAAO,CAAC;QAC9B,WAAW,EAAE,2EAA2E;KACzF,CAAC;IACF,OAAO,EAAE,aAAa;IACtB,MAAM,EAAE,SAAS;IACjB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC;QAChD,WAAW,EAAE,uEAAuE;KACrF,CAAC;IACF,KAAK,EAAE,CAAC,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC,OAAO,CAAC;QAClC,WAAW,EAAE,4DAA4D;KAC1E,CAAC;CACH,CAAC;KACD,OAAO,CAAC,eAAe,CAAC,CAAC"}