@jsm-mit/map-routes-package 0.1.0 → 0.2.0

package/declarations/map-routes-coordinator/map-routes-coordinator.did.d.ts

@@ -0,0 +1,764 @@
+import type { Principal } from '@icp-sdk/core/principal';
+import type { ActorMethod } from '@icp-sdk/core/agent';
+import type { IDL } from '@icp-sdk/core/candid';
+
+/**
+ * One area as a client sees it: where to ask.
+ */
+export interface AreaInfo {
+  'sha256' : [] | [string],
+  'area' : string,
+  'bbox' : Bbox,
+  /**
+   * The live copies: a client draws one for every call.
+   */
+  'copies' : Array<Principal>,
+  'osmDate' : [] | [string],
+}
+/**
+ * Stored: the hysteresis of one area (key = its name).
+ */
+export interface AreaLoad {
+  /**
+   * Readings in a row with the average per live copy above H.
+   */
+  'above' : number,
+  /**
+   * The last copy the load made (created or unmarked).
+   */
+  'lastGrowthNs' : [] | [bigint],
+  /**
+   * Since when the load would fit into one live copy less (sum / (n − 1) < H/2).
+   */
+  'belowSinceNs' : [] | [bigint],
+  'area' : string,
+}
+export interface Areas {
+  /**
+   * How long a client keeps this list.
+   */
+  'ttlSeconds' : number,
+  'areas' : Array<AreaInfo>,
+}
+/**
+ * A rectangle in degrees, edges included.
+ */
+export interface Bbox {
+  'minLat' : number,
+  'minLon' : number,
+  'maxLat' : number,
+  'maxLon' : number,
+}
+export interface BeginWasmArgs {
+  'sha256' : string,
+  /**
+   * `null` = the worker.
+   */
+  'kind' : [] | [WasmKind],
+  'size' : bigint,
+}
+/**
+ * Stored: a bisection of one area (key = its name). The users stay in the cores.
+ */
+export interface BisectionRun {
+  /**
+   * Set when it ended; a new one starts at least an hour later.
+   */
+  'endedAtNs' : [] | [bigint],
+  'area' : string,
+  'copyA' : Principal,
+  'copyB' : Principal,
+  /**
+   * Suspects left, summed over the cores.
+   */
+  'suspects' : bigint,
+  'steps' : number,
+  /**
+   * The split of this step began then.
+   */
+  'stepStartedNs' : bigint,
+}
+/**
+ * Stored: a blocked user (key = system/user). Only a superadmin unblocks.
+ */
+export interface Block {
+  'who' : UserKey,
+  'atNs' : bigint,
+  /**
+   * The measured surplus in instructions/s (bisection).
+   */
+  'load' : [] | [number],
+  'reason' : string,
+}
+/**
+ * Stored: one worker copy (key = its canister). A new field is `Option<…>` + `#[serde(default)]`.
+ */
+export interface Copy {
+  'area' : string,
+  'createdAtNs' : bigint,
+  'state' : CopyState,
+  'subnet' : [] | [Principal],
+  'canister' : Principal,
+  /**
+   * The last step that failed; `advanceCopy` tries it again.
+   */
+  'lastError' : [] | [string],
+  /**
+   * When the copy was marked for removal (off the list since then).
+   */
+  'markedAtNs' : [] | [bigint],
+}
+export type CopyState = {
+    /**
+     * A later copy: it pulls the graph from a live copy of the area.
+     */
+    'Copying' : null
+  } |
+  {
+    /**
+     * Answers queries and is on the list of the area.
+     */
+    'Live' : null
+  } |
+  {
+    /**
+     * Created; its wasm is not installed yet.
+     */
+    'Installing' : null
+  } |
+  {
+    /**
+     * The first copy of an area: an uploader sends the graph (`upload-graph.sh --no-activate`).
+     */
+    'AwaitingData' : null
+  } |
+  {
+    /**
+     * The load fits without it; only a superadmin deletes it.
+     */
+    'MarkedForRemoval' : null
+  };
+/**
+ * Stored: a pass core of the group (key = its canister).
+ */
+export interface CoreCanister {
+  /**
+   * The snapshot version the core holds.
+   */
+  'syncedVersion' : [] | [bigint],
+  'createdAtNs' : bigint,
+  /**
+   * Its balance at the last round (the round tops it up like a copy).
+   */
+  'cycles' : [] | [bigint],
+  'state' : CoreState,
+  'subnet' : [] | [Principal],
+  'canister' : Principal,
+  'lastError' : [] | [string],
+}
+/**
+ * A core's report (`coreReport`).
+ */
+export interface CoreReport {
+  /**
+   * Blocks made in the core (renewals).
+   */
+  'blocks' : Array<Block>,
+  /**
+   * Users with a valid pass, per area.
+   */
+  'users' : Array<[string, bigint]>,
+  /**
+   * Systems refused for passes a minute.
+   */
+  'rateLimited' : Array<Principal>,
+}
+export type CoreState = {
+    /**
+     * Issues passes; gets the snapshot.
+     */
+    'Live' : null
+  } |
+  {
+    /**
+     * Created; its wasm is not installed yet (`advanceCore`).
+     */
+    'Installing' : null
+  };
+export type Error = {
+    /**
+     * A call to another canister failed (named); the step can be tried again.
+     */
+    'CallFailed' : string
+  } |
+  {
+    /**
+     * The user gets no pass: the reason and whom to contact.
+     */
+    'Blocked' : string
+  } |
+  { 'NotFound' : string } |
+  { 'NotAuthorized' : string } |
+  {
+    /**
+     * The limit of copies of the area is reached (`maxCopies`).
+     */
+    'LimitReached' : string
+  } |
+  { 'InvalidData' : string } |
+  {
+    /**
+     * The system asks too often (or the demo used its hour): try later.
+     */
+    'RateLimited' : string
+  } |
+  {
+    /**
+     * The step waits for something outside (named), e.g. the graph upload.
+     */
+    'Waiting' : string
+  };
+/**
+ * Test feed (local replica only: it does not count `query_stats`).
+ */
+export interface FeedArgs { 'totals' : QueryTotals, 'canister' : Principal }
+/**
+ * A Candid-encodable representation of an HTTP request. This struct is used by
+ * the `http_request` method of the HTTP Gateway Protocol's Candid interface.
+ * 
+ * # Examples
+ * 
+ * ```
+ * use ic_http_certification::{HttpRequest, Method};
+ * 
+ * let request = HttpRequest::builder()
+ * .with_method(Method::GET)
+ * .with_url("/")
+ * .with_headers(vec![("X-Custom-Foo".into(), "Bar".into())])
+ * .with_body(&[1, 2, 3])
+ * .with_certificate_version(2)
+ * .build();
+ * 
+ * assert_eq!(request.method(), Method::GET);
+ * assert_eq!(request.url(), "/");
+ * assert_eq!(request.headers(), &[("X-Custom-Foo".into(), "Bar".into())]);
+ * assert_eq!(request.body(), &[1, 2, 3]);
+ * assert_eq!(request.certificate_version(), Some(2));
+ * ```
+ * 
+ * # Helpers
+ * 
+ * There are also a number of convenience methods for quickly creating an [HttpRequest] with
+ * commonly used HTTP methods:
+ * 
+ * - [GET](HttpRequest::get)
+ * - [POST](HttpRequest::post)
+ * - [PUT](HttpRequest::put)
+ * - [PATCH](HttpRequest::patch)
+ * - [DELETE](HttpRequest::delete)
+ * 
+ * ```
+ * use ic_http_certification::HttpRequest;
+ * 
+ * let request = HttpRequest::get("/").build();
+ * 
+ * assert_eq!(request.method(), "GET");
+ * assert_eq!(request.url(), "/");
+ * ```
+ */
+export interface HttpRequest {
+  /**
+   * HTTP request URL.
+   */
+  'url' : string,
+  /**
+   * HTTP request method.
+   */
+  'method' : string,
+  /**
+   * HTTP request body as an array of bytes.
+   */
+  'body' : Uint8Array | number[],
+  /**
+   * HTTP request headers.
+   */
+  'headers' : Array<[string, string]>,
+  /**
+   * The max response verification version to use in the response's
+   * certificate.
+   */
+  'certificate_version' : [] | [number],
+}
+/**
+ * A Candid-encodable representation of an HTTP response. This struct is used
+ * by the `http_request` method of the HTTP Gateway Protocol's Candid interface.
+ * 
+ * # Examples
+ * 
+ * ```
+ * use ic_http_certification::{HttpResponse, StatusCode};
+ * 
+ * let response = HttpResponse::builder()
+ * .with_status_code(StatusCode::OK)
+ * .with_headers(vec![("Content-Type".into(), "text/plain".into())])
+ * .with_body(b"Hello, World!")
+ * .with_upgrade(false)
+ * .build();
+ * 
+ * assert_eq!(response.status_code(), StatusCode::OK);
+ * assert_eq!(response.headers(), &[("Content-Type".into(), "text/plain".into())]);
+ * assert_eq!(response.body(), b"Hello, World!");
+ * assert_eq!(response.upgrade(), Some(false));
+ * ```
+ * 
+ * # Helpers
+ * 
+ * There are also a number of convenience methods for quickly creating an [HttpResponse] with
+ * commonly used HTTP status codes:
+ * 
+ * - [OK](HttpResponse::ok)
+ * - [CREATED](HttpResponse::created)
+ * - [NO_CONTENT](HttpResponse::no_content)
+ * - [MOVED_PERMANENTLY](HttpResponse::moved_permanently)
+ * - [TEMPORARY_REDIRECT](HttpResponse::temporary_redirect)
+ * - [BAD_REQUEST](HttpResponse::bad_request)
+ * - [UNAUTHORIZED](HttpResponse::unauthorized)
+ * - [FORBIDDEN](HttpResponse::forbidden)
+ * - [NOT_FOUND](HttpResponse::not_found)
+ * - [METHOD_NOT_ALLOWED](HttpResponse::method_not_allowed)
+ * - [TOO_MANY_REQUESTS](HttpResponse::too_many_requests)
+ * - [INTERNAL_SERVER_ERROR](HttpResponse::internal_server_error)
+ * 
+ * ```
+ * use ic_http_certification::{HttpResponse, StatusCode};
+ * 
+ * let response = HttpResponse::ok(b"Hello, World!", vec![("Content-Type".into(), "text/plain".into())]).build();
+ * 
+ * assert_eq!(response.status_code(), StatusCode::OK);
+ * assert_eq!(response.headers(), &[("Content-Type".into(), "text/plain".into())]);
+ * assert_eq!(response.body(), b"Hello, World!");
+ * ```
+ */
+export interface HttpResponse {
+  /**
+   * HTTP response body as an array of bytes.
+   */
+  'body' : Uint8Array | number[],
+  /**
+   * HTTP response headers.
+   */
+  'headers' : Array<[string, string]>,
+  /**
+   * Whether the corresponding HTTP request should be upgraded to an update
+   * call.
+   */
+  'upgrade' : [] | [boolean],
+  /**
+   * HTTP response status code.
+   */
+  'status_code' : number,
+}
+export interface InitArgs { 'mode' : Mode, 'superadmins' : Array<Principal> }
+export type Mode = {
+    /**
+     * The local replica: copies by the management canister (no CMC there), any subnet.
+     */
+    'Local' : null
+  } |
+  { 'Stage' : null } |
+  { 'Prod' : null };
+/**
+ * Stored: one notification for the superadmin (key = its id).
+ */
+export interface Notice {
+  'id' : bigint,
+  'area' : [] | [string],
+  'atNs' : bigint,
+  'kind' : NoticeKind,
+  'text' : string,
+  'canister' : [] | [Principal],
+}
+export type NoticeKind = {
+    /**
+     * The status of a copy could not be read.
+     */
+    'StatusFailed' : null
+  } |
+  { 'BisectionStarted' : null } |
+  { 'CopyCreated' : null } |
+  { 'CopyDeleted' : null } |
+  {
+    /**
+     * The load needs another copy, but `maxCopies` is reached.
+     */
+    'MaxCopiesReached' : null
+  } |
+  {
+    /**
+     * The pass keys of a copy could not be set.
+     */
+    'KeysFailed' : null
+  } |
+  { 'CopyMarked' : null } |
+  { 'CopyUnmarked' : null } |
+  { 'CopyFailed' : null } |
+  {
+    /**
+     * The bisection found no single user (the load is honest) or lost its copies.
+     */
+    'BisectionEnded' : null
+  } |
+  {
+    /**
+     * A core did not take the snapshot or an order.
+     */
+    'CoreFailed' : null
+  } |
+  {
+    /**
+     * A system asked for too many passes in a minute.
+     */
+    'SystemRateLimited' : null
+  } |
+  {
+    /**
+     * A user is blocked (bisection or too many renewals).
+     */
+    'UserBlocked' : null
+  } |
+  {
+    /**
+     * A copy runs low and the coordinator cannot top it up.
+     */
+    'CyclesLow' : null
+  };
+export interface PassState {
+  /**
+   * Copy → the id of its newest key and whether it holds `passRequired`.
+   */
+  'keys' : Array<[Principal, number, boolean]>,
+  'cores' : Array<CoreCanister>,
+  /**
+   * Users with a valid pass, as the cores reported last.
+   */
+  'activePasses' : bigint,
+  'systems' : Array<System>,
+  'blocks' : Array<Block>,
+  'bisections' : Array<BisectionRun>,
+}
+/**
+ * The cumulative `query_stats` of one copy (`canister_status`), as numbers.
+ */
+export interface QueryTotals {
+  'calls' : bigint,
+  'instructions' : bigint,
+  'responseBytes' : bigint,
+}
+/**
+ * The load of one copy between two readings, per second.
+ */
+export interface Rates {
+  'responseBytesPerS' : number,
+  'callsPerS' : number,
+  'instructionsPerS' : number,
+}
+/**
+ * Stored: the last reading of one copy (key = its canister).
+ */
+export interface Reading {
+  'atNs' : bigint,
+  /**
+   * The reading before (the rates cover `sinceNs..atNs`).
+   */
+  'sinceNs' : [] | [bigint],
+  'cycles' : bigint,
+  'totals' : QueryTotals,
+  'canister' : Principal,
+  /**
+   * Since the reading before; none after the first one (or after the totals went down).
+   */
+  'rates' : [] | [Rates],
+}
+export type Result = { 'Ok' : Shard } |
+  { 'Err' : Error };
+export type Result_1 = { 'Ok' : Array<Principal> } |
+  { 'Err' : Error };
+export type Result_10 = { 'Ok' : System } |
+  { 'Err' : Error };
+export type Result_11 = { 'Ok' : RoundReport } |
+  { 'Err' : Error };
+export type Result_12 = { 'Ok' : Settings } |
+  { 'Err' : Error };
+export type Result_13 = { 'Ok' : boolean } |
+  { 'Err' : Error };
+export type Result_2 = { 'Ok' : Copy } |
+  { 'Err' : Error };
+export type Result_3 = { 'Ok' : CoreCanister } |
+  { 'Err' : Error };
+export type Result_4 = { 'Ok' : WasmMeta } |
+  { 'Err' : Error };
+export type Result_5 = { 'Ok' : number } |
+  { 'Err' : Error };
+export type Result_6 = { 'Ok' : null } |
+  { 'Err' : Error };
+export type Result_7 = { 'Ok' : PassState } |
+  { 'Err' : Error };
+export type Result_8 = { 'Ok' : State } |
+  { 'Err' : Error };
+export type Result_9 = { 'Ok' : Array<Notice> } |
+  { 'Err' : Error };
+/**
+ * What one round saw and did.
+ */
+export interface RoundReport {
+  'atNs' : bigint,
+  /**
+   * What the round did, one line each.
+   */
+  'actions' : Array<string>,
+  'loads' : Array<AreaLoad>,
+  'readings' : Array<Reading>,
+}
+/**
+ * Stored: the settings (key 0).
+ */
+export interface Settings {
+  'hInstructionsPerS' : bigint,
+  'subnets' : Array<Subnet>,
+  'copyCycles' : bigint,
+  /**
+   * `null` = false (stored before phase 4).
+   */
+  'passRequired' : [] | [boolean],
+  'mode' : Mode,
+  /**
+   * `null` = `DEFAULT_CORE_CYCLES` (stored before 2026-11-06).
+   */
+  'coreCycles' : [] | [bigint],
+  'superadmins' : Array<Principal>,
+  'maxCopies' : number,
+}
+export interface SettingsArgs {
+  'hInstructionsPerS' : bigint,
+  /**
+   * Where copies may go (stage / prod); ignored on the local replica.
+   */
+  'subnets' : Array<Subnet>,
+  'copyCycles' : bigint,
+  /**
+   * Workers refuse a query without a pass (`PassMissing`); `null` keeps the value held.
+   */
+  'passRequired' : [] | [boolean],
+  /**
+   * Cycles of a new pass core (≥ 0.6 TC); `null` keeps the value held.
+   */
+  'coreCycles' : [] | [bigint],
+  'maxCopies' : number,
+}
+/**
+ * Stored: one area (key = its name).
+ */
+export interface Shard {
+  /**
+   * The graph every live copy holds; set when the first copy goes live.
+   */
+  'sha256' : [] | [string],
+  'area' : string,
+  'bbox' : Bbox,
+  'osmDate' : [] | [string],
+}
+export interface State {
+  'coreWasm' : [] | [WasmMeta],
+  'shards' : Array<Shard>,
+  'lastRoundNs' : [] | [bigint],
+  'cores' : Array<CoreCanister>,
+  'wasm' : [] | [WasmMeta],
+  'loads' : Array<AreaLoad>,
+  /**
+   * The coordinator's own balance now.
+   */
+  'cycles' : bigint,
+  'readings' : Array<Reading>,
+  'settings' : Settings,
+  'copies' : Array<Copy>,
+}
+export interface Subnet {
+  'id' : Principal,
+  /**
+   * A SEV subnet: the first copy of an area must stand on one.
+   */
+  'sev' : boolean,
+}
+/**
+ * Stored: one system (key = its principal).
+ */
+export interface System {
+  'id' : Principal,
+  'demo' : boolean,
+  'blocked' : boolean,
+  'name' : string,
+  'hourlyLimit' : [] | [number],
+  /**
+   * The demo hour: its start and the passes in it.
+   */
+  'hourStartNs' : bigint,
+  'passesThisHour' : number,
+  'perMinute' : number,
+}
+/**
+ * A trusted system: a canister of another project or an outside system with a principal.
+ */
+export interface SystemArgs {
+  /**
+   * Its principal (`principal` is a Candid keyword).
+   */
+  'id' : Principal,
+  /**
+   * Demo: short passes, a small bbox, `hourlyLimit` passes an hour for the whole system.
+   */
+  'demo' : boolean,
+  /**
+   * A blocked system gets nothing (the superadmin's decision).
+   */
+  'blocked' : boolean,
+  'name' : string,
+  'hourlyLimit' : [] | [number],
+  /**
+   * Passes a minute before `RateLimited`.
+   */
+  'perMinute' : number,
+}
+export interface UserKey { 'user' : Principal, 'system' : Principal }
+export interface WasmChunkArgs {
+  /**
+   * `null` = the worker.
+   */
+  'kind' : [] | [WasmKind],
+  'offset' : bigint,
+  'bytes' : Uint8Array | number[],
+}
+/**
+ * Which wasm: the worker of the copies, or the pass core.
+ */
+export type WasmKind = { 'Core' : null } |
+  { 'Worker' : null };
+/**
+ * Stored: the worker wasm that is uploaded or held (key 0); its bytes lie in their own memory.
+ */
+export interface WasmMeta {
+  'sha256' : string,
+  'size' : bigint,
+  'ready' : boolean,
+}
+export interface _SERVICE {
+  /**
+   * A new area; its first copy comes with `createCopy`.
+   */
+  'addShard' : ActorMethod<[string, Bbox], Result>,
+  /**
+   * A superadmin adds another (e.g. the Internet Identity principal of the front: it differs
+   * from a dfx identity). At most 8; never anonymous.
+   */
+  'addSuperadmin' : ActorMethod<[Principal], Result_1>,
+  /**
+   * The next steps of a copy, from where it stands; a failed step is tried again.
+   */
+  'advanceCopy' : ActorMethod<[Principal], Result_2>,
+  /**
+   * Installs a core that was created but not installed (a failed `createCore`).
+   */
+  'advanceCore' : ActorMethod<[Principal], Result_3>,
+  /**
+   * Where to ask: the areas and their live copies. Public; a client keeps it `ttlSeconds`.
+   */
+  'areas' : ActorMethod<[], Areas>,
+  'beginWasm' : ActorMethod<[BeginWasmArgs], Result_4>,
+  /**
+   * The superadmin has read the notifications up to `id`.
+   */
+  'clearNotifications' : ActorMethod<[bigint], Result_5>,
+  /**
+   * `null` = the worker.
+   */
+  'commitWasm' : ActorMethod<[[] | [WasmKind]], Result_4>,
+  /**
+   * A core reports: its users per area (the bisection starts on them), its blocks, the systems
+   * it refused. It arms a round (at most every 10 min).
+   */
+  'coreReport' : ActorMethod<[CoreReport], Result_6>,
+  /**
+   * A new copy of `area`: created, installed, then its steps as far as they go (`advanceCopy`
+   * goes on).
+   */
+  'createCopy' : ActorMethod<[string], Result_2>,
+  /**
+   * A new pass core: created (on a SEV subnet outside the local replica), installed with the
+   * core wasm, then given the snapshot.
+   */
+  'createCore' : ActorMethod<[], Result_3>,
+  /**
+   * Only a superadmin deletes, only a marked copy off the list for one list TTL.
+   */
+  'deleteCopy' : ActorMethod<[Principal], Result_6>,
+  /**
+   * Local replica only: totals of `query_stats` for the next rounds (it counts none itself).
+   */
+  'feedQueryStats' : ActorMethod<[Array<FeedArgs>], Result_6>,
+  'getPassState' : ActorMethod<[], Result_7>,
+  'getState' : ActorMethod<[], Result_8>,
+  /**
+   * Every coordinator (`sharding.md`): the crafting table asks before a reinstall.
+   */
+  'hasDependents' : ActorMethod<[], boolean>,
+  /**
+   * The superadmin front, for everybody: the page and its files. It shows nothing by itself;
+   * it asks the methods of the superadmins, as the person who signed in.
+   */
+  'http_request' : ActorMethod<[HttpRequest], HttpResponse>,
+  /**
+   * Which core issues the passes of `user` (public; a system keeps it with the list TTL).
+   */
+  'issuerFor' : ActorMethod<[Principal], [] | [Principal]>,
+  'listDependents' : ActorMethod<[], Array<Principal>>,
+  /**
+   * A superadmin takes a live copy off the list (the coordinator marks after 24 h of low load).
+   */
+  'markCopy' : ActorMethod<[Principal], Result_2>,
+  'notifications' : ActorMethod<[], Result_9>,
+  /**
+   * A superadmin removes one; the last one stays.
+   */
+  'removeSuperadmin' : ActorMethod<[Principal], Result_1>,
+  /**
+   * A system is gone: the cores forget it (its users' passes are refused from the next sync;
+   * passes already given stay valid until they end). E.g. a core of a group replaced by the
+   * group's coordinator as the system.
+   */
+  'removeSystem' : ActorMethod<[Principal], Result_10>,
+  /**
+   * A round now, whatever the time of the last one; refused while one runs.
+   */
+  'runRound' : ActorMethod<[], Result_11>,
+  'setSettings' : ActorMethod<[SettingsArgs], Result_12>,
+  /**
+   * A system added or changed; the cores get it at once.
+   */
+  'setSystem' : ActorMethod<[SystemArgs], Result_10>,
+  /**
+   * Only a superadmin unblocks: every core lifts the block (the renewal count starts again).
+   */
+  'unblockUser' : ActorMethod<[UserKey], Result_13>,
+  /**
+   * A live (or marked) replicated instance gets the worker wasm held (stop → upgrade → start);
+   * its graphs and pass keys stay (stable memory). A failed step is kept in `lastError`.
+   */
+  'upgradeCopy' : ActorMethod<[Principal], Result_2>,
+  /**
+   * A live core gets the core wasm held (stop → upgrade → start); its state stays. Then every
+   * core gets the snapshot again. A failed step is kept in `lastError`.
+   */
+  'upgradeCore' : ActorMethod<[Principal], Result_3>,
+  'wasmChunk' : ActorMethod<[WasmChunkArgs], Result_6>,
+}
+export declare const idlFactory: IDL.InterfaceFactory;
+export declare const init: (args: { IDL: typeof IDL }) => IDL.Type[];