@tangle-network/sandbox 0.60.16 → 0.60.17-develop.20261006080745.649508b

package/dist/gpu-lease/index.d.ts

@@ -0,0 +1,503 @@
+//#region src/gpu-lease/intent.d.ts
+declare const INTENT_VERSION = 1;
+/** keccak256 of the canonical intent string. */
+declare function gpuLeaseIntentHash(input: {
+  intentVersion: number;
+  gpuClass: string;
+  durationSeconds: bigint | number;
+  confidentiality: number;
+  region: string;
+}): `0x${string}`;
+/** ABI shape of GpuLeaseRequest — mirrors the blueprint's sol! type. */
+declare const GPU_LEASE_REQUEST_ABI: never;
+interface GpuLeaseRequestParams {
+  intentVersion: number;
+  intentHash: `0x${string}`;
+  pricePerSecondWei: bigint;
+  durationSeconds: bigint;
+  confidentiality: number;
+  gpuClass: string;
+  region: string;
+  lessee: `0x${string}`;
+  leaseId: `0x${string}`;
+}
+/**
+ * ABI-encoded GpuLeaseRequest — the LEASE job calldata payload.
+ * Positional (ABI order) — order is pinned by the blueprint's generated
+ * encodeType in metadata/blueprint.json.
+ */
+declare function encodeGpuLeaseRequest(params: GpuLeaseRequestParams): `0x${string}`;
+//#endregion
+//#region src/gpu-lease/types.d.ts
+/**
+ * GPU lease client types — mirrors the gpu-lease-blueprint operator API
+ * (gpu-lease-blueprint/gpu-lease-blueprint-lib/src/api.rs) and the on-chain
+ * ABI (contracts/src/GpuLeaseBlueprint.sol sol! mirror).
+ *
+ * Every on-chain and off-chain surface is schemaVersioned; unknown versions
+ * fail closed (SPEC §3 of the blueprint).
+ */
+/** The only schema this client understands. */
+declare const GPU_LEASE_SCHEMA_VERSION: 1;
+interface ClassCapability {
+  id: string;
+  tee: boolean;
+  unit: string;
+  /** Indicative policy price (wei/second) — the binding price is the quote. */
+  pricePerSecond: string;
+  idleCount: number;
+}
+interface Capabilities {
+  schemaVersion: number;
+  compute: {
+    kind: string;
+    classes: ClassCapability[];
+  };
+}
+interface OperatorQuote {
+  schemaVersion: number;
+  gpuClass: string;
+  /** The operator's EVM address — who the escrow names (I5 binding).
+   * When the quote is signed this MUST equal the recovered signer (verified
+   * in quotes.ts); config-supplied values are interim-trust only. */
+  operatorAddress: `0x${string}`;
+  /** EIP-191 personal_sign over the canonical quote payload (0x RSV). */
+  signature?: `0x${string}`;
+  /** wei/second, from the operator's signed policy at request time. */
+  pricePerSecond: string;
+  durationSeconds: number;
+  confidentiality: number;
+  /** wei — pricePerSecond × durationSeconds exactly. */
+  escrowTotal: string;
+  /** Utilization the price was struck at (bps of 10_000) — the surge "why". */
+  utilizationBps: number;
+  /** keccak256(canonical intent) — binds the RFQ and the vault lease (I5). */
+  intentHash: `0x${string}`;
+  /** Unix seconds after which the quote is stale. */
+  validUntil: number;
+}
+interface LeaseStatus {
+  schemaVersion: number;
+  leaseId: `0x${string}`;
+  deviceId: string;
+  lessee: string;
+  /** Unix seconds — the chain-of-truth session end (parking meter). */
+  expiresAt: number;
+  endpoint: string;
+}
+interface SessionChallenge {
+  nonce: `0x${string}`;
+  /** The exact string the lessee must EIP-191 personal_sign. */
+  message: string;
+  expiresAt: number;
+}
+interface SessionCredential {
+  token: string;
+  leaseId: `0x${string}`;
+  scopes: string[];
+  expiresAt: number;
+}
+/** A validated, ready-to-escrow quote. */
+interface ValidatedQuote {
+  quote: OperatorQuote;
+  pricePerSecondWei: bigint;
+  escrowTotalWei: bigint;
+}
+/** A resolved lease handed to the caller by `gpuLease()`. */
+interface GpuLease {
+  leaseId: `0x${string}`;
+  /** Public endpoint descriptor (versioned union; v1 = local-attach). */
+  endpoint: string;
+  schemaVersion: number;
+  quote: ValidatedQuote;
+}
+interface RefundReceipt {
+  leaseId: `0x${string}`;
+  /** Exact wei refunded: pricePerSecond × remainingSeconds at settle time. */
+  refundWei: bigint;
+  operatorTakeWei: bigint;
+}
+//#endregion
+//#region src/gpu-lease/operators.d.ts
+interface QuoteParams {
+  gpuClass: string;
+  durationSeconds: number;
+  confidentiality?: number;
+  region?: string;
+}
+interface OperatorEndpoint {
+  /** Operator base URL, e.g. https://gpu.example.com */
+  baseUrl: string;
+  /** The operator's EVM address (escrow + job binding). */
+  address: `0x${string}`;
+  fetch?: typeof fetch;
+}
+/** JSON request body — named at the I/O boundary (anti-slop: no `unknown`). */
+type JsonRequestBody = Record<string, unknown>;
+declare class GpuLeaseOperatorClient {
+  private readonly endpoint;
+  constructor(endpoint: OperatorEndpoint);
+  capabilities(): Promise<Capabilities>;
+  quote(params: QuoteParams): Promise<OperatorQuote>;
+  leaseStatus(leaseId: `0x${string}`): Promise<LeaseStatus>;
+  sessionChallenge(leaseId: `0x${string}`, lessee: string): Promise<SessionChallenge>;
+  sessionVerify(nonce: `0x${string}`, signature: `0x${string}`): Promise<SessionCredential>;
+}
+//#endregion
+//#region src/gpu-lease/output.d.ts
+interface GpuLeaseOutputDecoded {
+  leaseId: `0x${string}`;
+  endpoint: string;
+  schemaVersion: number;
+}
+/** Decode + fail closed on unknown schemaVersion (blueprint SPEC §3). */
+declare function decodeGpuLeaseOutput(encoded: `0x${string}`): GpuLeaseOutputDecoded;
+//#endregion
+//#region src/gpu-lease/quotes.d.ts
+/** The exact string the operator signs — mirrors the blueprint's
+ * `canonical_quote_payload` byte-for-byte. Every priced field is bound. */
+declare function canonicalQuotePayload(quote: {
+  gpuClass: string;
+  pricePerSecond: string;
+  durationSeconds: number;
+  confidentiality: number;
+  escrowTotal: string;
+  intentHash: string;
+  validUntil: number;
+}): string;
+/** Offline EIP-191 recovery over the canonical payload. */
+declare function verifyOperatorQuote(quote: OperatorQuote): Promise<`0x${string}`>;
+type QuoteRejection = {
+  kind: "stale";
+  validUntil: number;
+  now: number;
+} | {
+  kind: "class-mismatch";
+  requested: string;
+  quoted: string;
+} | {
+  kind: "escrow-inconsistent";
+  expected: bigint;
+  actual: bigint;
+} | {
+  kind: "confidentiality-mismatch";
+  requested: number;
+  quoted: number;
+} | {
+  kind: "signature-mismatch";
+  claimed: string;
+  recovered: string;
+} | {
+  kind: "unsigned";
+  operator: string;
+};
+interface QuoteFilterInput {
+  requestedClass: string;
+  requestedDurationSeconds: number;
+  requestedConfidentiality: number;
+  now?: () => number;
+}
+/**
+ * Validate one quote. Fail-closed on every field the RFQ binds:
+ * class, duration-derived escrow, confidentiality, and expiry.
+ */
+declare function validateQuote(quote: OperatorQuote, input: QuoteFilterInput): ValidatedQuote | QuoteRejection;
+/**
+ * Collect validated quotes from N operators and rank cheapest-first.
+ * Operators that fail validation (or whose fetch rejects) are reported,
+ * never silently dropped — the buyer sees why an operator lost.
+ */
+declare function selectQuotes(quotes: {
+  operator: string;
+  quote: OperatorQuote;
+}[], input: QuoteFilterInput): {
+  ranked: {
+    operator: string;
+    validated: ValidatedQuote;
+  }[];
+  rejected: {
+    operator: string;
+    reason: QuoteRejection;
+  }[];
+};
+/**
+ * Enforce the signed RFQ envelope when present:
+ * - signature present => it MUST recover to the claimed operator address;
+ *   invalid signature => reject (config-trust is dead on this path).
+ * - no signature => the endpoint-config address is used (interim fallback);
+ *   strict mode rejects unsigned quotes outright.
+ */
+declare function validateQuoteIdentity(quote: OperatorQuote, opts?: {
+  strict?: boolean;
+}): Promise<ValidatedQuote | QuoteRejection>;
+//#endregion
+//#region src/gpu-lease/vault.d.ts
+declare const GPU_LEASE_VAULT_ABI: readonly [{
+  readonly name: "create";
+  readonly type: "function";
+  readonly stateMutability: "payable";
+  readonly inputs: readonly [{
+    readonly type: "address";
+    readonly name: "operator";
+  }, {
+    readonly type: "uint128";
+    readonly name: "pricePerSecond";
+  }, {
+    readonly type: "uint64";
+    readonly name: "durationSeconds";
+  }, {
+    readonly type: "bytes32";
+    readonly name: "intentHash";
+  }, {
+    readonly type: "uint8";
+    readonly name: "confidentiality";
+  }, {
+    readonly type: "bytes";
+    readonly name: "endpointInfo";
+  }];
+  readonly outputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "leaseId";
+  }];
+}, {
+  readonly name: "extend";
+  readonly type: "function";
+  readonly stateMutability: "payable";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "leaseId";
+  }, {
+    readonly type: "uint64";
+    readonly name: "addSeconds";
+  }];
+  readonly outputs: readonly [];
+}, {
+  readonly name: "release";
+  readonly type: "function";
+  readonly stateMutability: "nonpayable";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "leaseId";
+  }];
+  readonly outputs: readonly [];
+}, {
+  readonly name: "reap";
+  readonly type: "function";
+  readonly stateMutability: "nonpayable";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "leaseId";
+  }];
+  readonly outputs: readonly [];
+}, {
+  readonly name: "withdrawEarnings";
+  readonly type: "function";
+  readonly stateMutability: "nonpayable";
+  readonly inputs: readonly [];
+  readonly outputs: readonly [];
+}, {
+  readonly name: "totalEscrowed";
+  readonly type: "function";
+  readonly stateMutability: "view";
+  readonly inputs: readonly [];
+  readonly outputs: readonly [{
+    readonly type: "uint256";
+  }];
+}, {
+  readonly name: "operatorEarnings";
+  readonly type: "function";
+  readonly stateMutability: "view";
+  readonly inputs: readonly [];
+  readonly outputs: readonly [{
+    readonly type: "uint256";
+  }];
+}, {
+  readonly name: "leases";
+  readonly type: "function";
+  readonly stateMutability: "view";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+  }];
+  readonly outputs: readonly [{
+    readonly type: "address";
+    readonly name: "operator";
+  }, {
+    readonly type: "address";
+    readonly name: "lessee";
+  }, {
+    readonly type: "uint128";
+    readonly name: "escrow";
+  }, {
+    readonly type: "uint128";
+    readonly name: "pricePerSecond";
+  }, {
+    readonly type: "uint64";
+    readonly name: "expiry";
+  }, {
+    readonly type: "bytes32";
+    readonly name: "intentHash";
+  }, {
+    readonly type: "uint8";
+    readonly name: "confidentiality";
+  }, {
+    readonly type: "uint8";
+    readonly name: "state";
+  }];
+}, {
+  readonly name: "LeaseCreated";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "leaseId";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "operator";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "lessee";
+    readonly indexed: true;
+  }, {
+    readonly type: "uint128";
+    readonly name: "escrow";
+  }, {
+    readonly type: "uint128";
+    readonly name: "pricePerSecond";
+  }, {
+    readonly type: "uint64";
+    readonly name: "expiry";
+  }, {
+    readonly type: "bytes32";
+    readonly name: "intentHash";
+  }, {
+    readonly type: "uint8";
+    readonly name: "confidentiality";
+  }, {
+    readonly type: "bytes";
+    readonly name: "endpointInfo";
+  }, {
+    readonly type: "uint16";
+    readonly name: "schemaVersion";
+  }];
+}, {
+  readonly name: "LeaseReleased";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "leaseId";
+    readonly indexed: true;
+  }, {
+    readonly type: "uint128";
+    readonly name: "refund";
+  }, {
+    readonly type: "uint128";
+    readonly name: "operatorTake";
+  }];
+}, {
+  readonly name: "LeaseReaped";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "leaseId";
+    readonly indexed: true;
+  }, {
+    readonly type: "uint128";
+    readonly name: "operatorTake";
+  }, {
+    readonly type: "address";
+    readonly name: "caller";
+  }];
+}];
+/** Vault lease states (mirrors the contract). */
+declare const LEASE_STATE: {
+  readonly LIVE: 0;
+  readonly RELEASED: 1;
+  readonly REAPED: 2;
+};
+interface VaultLeaseView {
+  operator: `0x${string}`;
+  lessee: `0x${string}`;
+  escrowWei: bigint;
+  pricePerSecondWei: bigint;
+  /** Unix seconds — the chain clock is the parking meter's truth. */
+  expiry: bigint;
+  intentHash: `0x${string}`;
+  confidentiality: number;
+  state: number;
+}
+/**
+ * Exact refund projection (I3): pricePerSecond × max(expiry − now, 0).
+ * Exact by construction because escrow === price × paidSeconds in the vault.
+ */
+declare function projectRefundWei(lease: VaultLeaseView, nowSeconds: bigint): {
+  refundWei: bigint;
+  operatorTakeWei: bigint;
+};
+/** I2 from the client side: unpayable time can never be requested. */
+declare function maxAffordableSeconds(escrowWei: bigint, pricePerSecondWei: bigint): bigint;
+//#endregion
+//#region src/gpu-lease/resolver.d.ts
+/** Job ids — MUST match the blueprint router (sequential, no gaps). */
+declare const GPU_LEASE_JOBS: {
+  readonly LEASE: 0;
+  readonly RELEASE: 1;
+  readonly EXTEND: 2;
+  readonly REAP: 3;
+};
+interface GpuLeaseChain {
+  /** The buyer's address (the RFQ binds the requester — I5). */
+  readonly account: `0x${string}`;
+  /** Create the escrowed lease on the vault; returns the vault leaseId. */
+  createVaultLease(input: {
+    operator: `0x${string}`;
+    pricePerSecondWei: bigint;
+    durationSeconds: bigint;
+    intentHash: `0x${string}`;
+    confidentiality: number;
+    endpointInfo: string;
+    escrowWei: bigint;
+  }): Promise<`0x${string}`>;
+  /** Submit a job through tnt-core; resolves with the result payload. */
+  submitJob(jobId: number, encodedInput: `0x${string}`): Promise<`0x${string}`>;
+  /** Read a vault lease (chain clock truth for projections). */
+  readLease(leaseId: `0x${string}`): Promise<VaultLeaseView>;
+  /** The chain's current timestamp (unix seconds) — meter truth, not Date.now(). */
+  chainNow?(): Promise<bigint>;
+  /** Voluntary release on the vault; returns {refund, take} wei. */
+  releaseLease(leaseId: `0x${string}`): Promise<{
+    refundWei: bigint;
+    operatorTakeWei: bigint;
+  }>;
+}
+interface GpuLeaseOptions {
+  gpuClass: string;
+  durationSeconds: number;
+  confidentiality?: number;
+  region?: string;
+  /** Operators to request quotes from (multi-quote = the decentralized scheduler). */
+  operators: OperatorEndpoint[];
+  chain: GpuLeaseChain;
+  now?: () => number;
+}
+interface GpuLeaseOutcome {
+  lease: GpuLease;
+  /** Operators ranked cheapest-first. */
+  rankedOperators: string[];
+}
+/** Resolve a GPU lease end-to-end. Throws with the full picture on failure. */
+declare function gpuLease(options: GpuLeaseOptions): Promise<GpuLeaseOutcome>;
+/** Teardown: voluntary release with an exact-refund receipt (I3/I4). */
+declare function releaseGpuLease(leaseId: `0x${string}`, chain: GpuLeaseChain): Promise<RefundReceipt>;
+/**
+ * Refund projection for UI meters. Uses the chain clock when the injected
+ * chain provides `chainNow()`; otherwise requires an explicit timestamp.
+ * Never Date.now() — the drift lesson from the blueprint's own E2E.
+ */
+declare function projectGpuLeaseRefund(leaseId: `0x${string}`, chain: GpuLeaseChain, explicitNowSeconds?: bigint): Promise<{
+  refundWei: bigint;
+  operatorTakeWei: bigint;
+  nowSeconds: bigint;
+}>;
+//#endregion
+export { Capabilities, ClassCapability, GPU_LEASE_JOBS, GPU_LEASE_REQUEST_ABI, GPU_LEASE_SCHEMA_VERSION, GPU_LEASE_VAULT_ABI, GpuLease, GpuLeaseChain, GpuLeaseOperatorClient, GpuLeaseOptions, GpuLeaseOutcome, GpuLeaseOutputDecoded, GpuLeaseRequestParams, INTENT_VERSION, JsonRequestBody, LEASE_STATE, LeaseStatus, OperatorEndpoint, OperatorQuote, QuoteFilterInput, QuoteParams, QuoteRejection, RefundReceipt, SessionChallenge, SessionCredential, ValidatedQuote, VaultLeaseView, canonicalQuotePayload, decodeGpuLeaseOutput, encodeGpuLeaseRequest, gpuLease, gpuLeaseIntentHash, maxAffordableSeconds, projectGpuLeaseRefund, projectRefundWei, releaseGpuLease, selectQuotes, validateQuote, validateQuoteIdentity, verifyOperatorQuote };