@opendatalabs/vana-sdk 3.21.0 → 3.22.0-pr.207.5c11fe3

package/README.md

@@ -621,6 +621,70 @@ These helpers require `personal-server-ts` main `d91124d` or later, which is
 where the query-in-the-signed-uri rule, the `nonce` claim, the 404 for an
 unknown id and the full-view `recompute` answer landed.
 
+### Watching a derived scope as the reader
+
+The helpers above are the builder's: every one of them needs a write session,
+which an app holding only a bare read entry on the derived scope cannot open.
+That reader sees `GET /v1/data/<derivedScope>` answer 404 whether the compute
+is running, retrying, or finished failing.
+
+`getDerivativeStatus` is the reader's view of the same question. It
+authenticates like a data read — a live grant covering the derived scope, or
+the owner — and nothing is charged, so a priced grant raises no 402 here.
+
+```typescript
+import {
+  getDerivativeStatus,
+  waitForDerivativeStatus,
+} from "@opendatalabs/vana-sdk";
+
+const status = await getDerivativeStatus({
+  personalServerUrl: "https://ps.example.com",
+  derivedScope: "coach.weekly",
+  grantId,
+  signer,
+});
+// { derivedScope, status, lastComputedAt, derivedVersion,
+//   derivedCollectedAt, errorCode, retryAfterSeconds }
+
+const settled = await waitForDerivativeStatus({
+  personalServerUrl: "https://ps.example.com",
+  derivedScope: "coach.weekly",
+  grantId,
+  signer,
+  timeoutMs: 60_000,
+});
+```
+
+The view is lifecycle only: the question text, the source scopes, the question
+id, the registrar and the server's raw `error` string stay owner-only.
+`errorCode` is a closed vocabulary — `inference_unavailable`,
+`source_missing`, `grant_invalid`, `internal` — and is `null` unless `status`
+is `failed`.
+
+`retryAfterSeconds` is what separates a failure that is still being worked on
+from one that is over: `inference_unavailable` is the one transient class, and
+the Personal Server retries it on its own schedule. `waitForDerivativeStatus`
+returns as soon as the scope is `ready` or has failed with no retry pending,
+keeps waiting through a retrying failure, and takes the server's
+`retryAfterSeconds` as the cadence in place of `pollIntervalMs`, longer or
+shorter — it is when the next compute actually happens, so asking sooner sees
+nothing new and asking later sits on an answer that already exists. Once the
+remaining budget cannot cover the next cadence it raises the timeout rather
+than spending one more request that cannot carry new data. `signal` aborts
+the wait and the request in flight with it. A failed status is returned, not thrown; branch
+on `errorCode`. `isDerivativeStatusSettled` is the same predicate, exported
+for callers that poll on their own.
+
+When several questions write the same derived scope, the most optimistic true
+state answers (`ready`, then `stale`, then `pending`, then `failed`), because
+serving data is registration-agnostic: a duplicate that never wrote anything
+must not report away an answer the scope has.
+
+The status route needs a Personal Server that ships it; an older one answers
+404 for the route itself, which arrives as `DerivativeQuestionNotFoundError`
+— the same error as a covered scope with no question behind it.
+
 ## Networks
 
 | Network        | Chain ID | RPC URL                     |

package/dist/index.browser.d.ts

@@ -37,6 +37,7 @@ export { parseWeb3SignedHeader, verifyWeb3Signed, type Web3SignedPayload, type V
 export { buildWeb3SignedHeader, computeBodyHash, type Web3SignedSignFn, } from "./auth/web3-signed-builder.js";
 export { MissingAuthError, InvalidSignatureError, ExpiredTokenError, } from "./auth/errors.js";
 export { NATIVE_VANA_ASSET, dataRegistryDomain, grantRegistrationDomain, grantRevocationDomain, serverRegistrationDomain, builderRegistrationDomain, escrowPaymentDomain, GRANT_REGISTRATION_TYPES, GRANT_REVOCATION_TYPES, SERVER_REGISTRATION_TYPES, BUILDER_REGISTRATION_TYPES, ADD_DATA_TYPES, RECORD_DATA_ACCESS_TYPES, type DataPortabilityContracts, type DataPortabilityGatewayConfig, type GrantRegistrationMessage, type GrantRevocationMessage, type ServerRegistrationMessage, type BuilderRegistrationMessage, type AddDataMessage, type RecordDataAccessMessage, } from "./protocol/eip712.js";
+export { ENCLAVE_IDENTITY_EVIDENCE_VERSION, USER_PS_ID_DOMAIN, ENCLAVE_WALLET_PURPOSE, MASTER_SIGNATURE_DELIVERY_VERSION, SEALED_ENVELOPE_VERSION, ENCLAVE_TRUST_ANCHORS, userPsId, appRootPreimage, kmsIssuedPreimage, verifyEnclaveIdentityEvidence, buildMasterSignatureDelivery, encryptMasterSignatureDelivery, type UserPsId, type EnclaveIdentityEvidence, type ExpectedIdentity, type IdentityRequest, type IdentityState, type IdentityResponse, type IdentityRegistrationRequest, type IdentityRegistrationResponse, type MasterSignatureDelivery, type SealedSecretSubmission, type SealedSecretResponse, type AesGcmBox, type SealedEnvelope, type EnclaveTrustAnchors, } from "./protocol/identity.js";
 export { PERSONAL_SERVER_REGISTRATION_DEFAULT_CHAIN_ID, PERSONAL_SERVER_REGISTRATION_DEFAULT_VERIFYING_CONTRACT, personalServerRegistrationDomain, createViemPersonalServerRegistrationSigner, buildPersonalServerRegistrationTypedData, buildPersonalServerRegistrationSignature, registerPersonalServerSignature, type PersonalServerRegistrationTypedData, type PersonalServerRegistrationSigner, type PersonalServerRegistrationDomainInput, type ViemPersonalServerRegistrationWalletClient, type ViemPersonalServerRegistrationSignerSource, type BuildPersonalServerRegistrationTypedDataInput, type BuildPersonalServerRegistrationSignatureInput, type PersonalServerRegistrationSignature, } from "./protocol/personal-server-registration.js";
 export { PERSONAL_SERVER_LITE_OWNER_BINDING_VERSION, PERSONAL_SERVER_LITE_OWNER_BINDING_PURPOSE, PERSONAL_SERVER_LITE_OWNER_BINDING_PREFIX, buildPersonalServerLiteOwnerBindingMessage, createViemPersonalServerLiteOwnerBindingSigner, buildPersonalServerLiteOwnerBindingSignature, signPersonalServerLiteOwnerBinding, type PersonalServerLiteOwnerBindingPurpose, type PersonalServerLiteOwnerBindingMessage, type PersonalServerLiteOwnerBindingSigner, type ViemPersonalServerLiteOwnerBindingWalletClient, type ViemPersonalServerLiteOwnerBindingSignerSource, type BuildPersonalServerLiteOwnerBindingSignatureInput, type PersonalServerLiteOwnerBindingSignature, } from "./personal-server-lite/owner-binding.js";
 export { ACCOUNT_PERSONAL_SERVER_REGISTRATION_INTENT, AccountPersonalServerRegistrationError, signPersonalServerRegistrationWithAccount, type AccountPersonalServerRegistrationIntent, type AccountPersonalServerRegistrationSignature, type AccountPersonalServerRegistrationStatus, type AccountPersonalServerRegistrationRequest, type AccountPersonalServerRegistrationConfig, type AccountSignedPersonalServerRegistration, type AccountConfirmationRequiredPersonalServerRegistration, type AccountFallbackSignedPersonalServerRegistration, type AccountPersonalServerRegistrationResult, } from "./account/personal-server-registration.js";
@@ -51,7 +52,8 @@ export { ScopeSchema, parseScope, scopeToPathSegments, scopeMatchesPattern, scop
 export { SCOPE_ACTIONS, InvalidScopeEntryError, parseScopeEntry, formatScopeEntry, grantPermissions, permissionsToScopes, tryGrantPermissions, hasAction, type ScopeAction, type ParsedScopeEntry, type GrantPermission, } from "./protocol/scope-actions.js";
 export { WRITE_SESSION_PATH, WRITE_SIGNATURE_HEADER, WRITE_METADATA_HEADER, WRITE_FILENAME_HEADER, WRITE_CONTENT_DISPOSITION_HEADER, WRITER_ATTRIBUTION_KEY, LINEAGE_KEY, LINEAGE_FIELD, MAX_LINEAGE_SOURCES, RESERVED_WRITE_KEYS, openWriteSession, writeData, writePersonalServerData, sessionCoversScope, binaryWriteSignedBytes, normalizeBinaryMimeType, parseWriteMetadataHeader, encodeWriteMetadataHeader, type WriteTransportRetryOptions, type WriteSession, type OpenWriteSessionParams, type WriteBinaryPayload, type LineageSource, type WriteJsonDataParams, type WriteBinaryDataParams, type WriteDataParams, type WriteDataResult, type WritePersonalServerDataParams, type WritePersonalServerDataResult, type BinaryWriteSignedBytesInput, } from "./protocol/personal-server-write.js";
 export { resolveWriteSigner, type WriteSigner, type WriteSignerSource, type ViemWriteAccount, type ViemWriteWalletClient, type ResolveWriteSignerOptions, } from "./protocol/write-signer.js";
-export { DERIVATIVE_QUESTIONS_PATH, MAX_QUESTION_SOURCE_SCOPES, MAX_QUESTION_CHARS, MAX_QUESTION_MODEL_CHARS, DEFAULT_QUESTION_TIMEOUT_MS, DEFAULT_QUESTION_POLL_INTERVAL_MS, QUESTION_STATUSES, registerQuestion, getQuestion, listQuestions, recomputeQuestion, deleteQuestion, waitForQuestion, askPersonalServer, QuestionStatusSchema, QuestionRegisteredBySchema, DerivativeQuestionSchema, QuestionRecomputeResultSchema, QuestionDeleteResultSchema, type QuestionStatus, type QuestionRegisteredBy, type DerivativeQuestion, type QuestionRecomputeResult, type QuestionDeleteResult, type DerivativeQuestionAuthParams, type RegisterQuestionParams, type GetQuestionParams, type ListQuestionsParams, type RecomputeQuestionParams, type DeleteQuestionParams, type WaitForQuestionParams, type AskPersonalServerParams, type AskPersonalServerResult, } from "./protocol/derivative-questions.js";
+export { DERIVATIVE_QUESTIONS_PATH, MAX_QUESTION_SOURCE_SCOPES, MAX_QUESTION_CHARS, MAX_QUESTION_MODEL_CHARS, DEFAULT_QUESTION_TIMEOUT_MS, DEFAULT_QUESTION_POLL_INTERVAL_MS, QUESTION_STATUSES, DERIVATIVE_ERROR_CODES, DerivativeErrorCodeSchema, type DerivativeErrorCode, registerQuestion, getQuestion, listQuestions, recomputeQuestion, deleteQuestion, waitForQuestion, askPersonalServer, QuestionStatusSchema, QuestionRegisteredBySchema, DerivativeQuestionSchema, QuestionRecomputeResultSchema, QuestionDeleteResultSchema, type QuestionStatus, type QuestionRegisteredBy, type DerivativeQuestion, type QuestionRecomputeResult, type QuestionDeleteResult, type DerivativeQuestionAuthParams, type RegisterQuestionParams, type GetQuestionParams, type ListQuestionsParams, type RecomputeQuestionParams, type DeleteQuestionParams, type WaitForQuestionParams, type AskPersonalServerParams, type AskPersonalServerResult, } from "./protocol/derivative-questions.js";
+export { DERIVATIVE_STATUS_PATH, DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS, DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS, derivativeStatusTarget, getDerivativeStatus, waitForDerivativeStatus, isDerivativeStatusSettled, DerivativeStatusSchema, type DerivativeStatus, type GetDerivativeStatusParams, type WaitForDerivativeStatusParams, } from "./protocol/derivative-status.js";
 export { deriveDataPointId, isDataPointId, scopeNamespace, derivedScopeViolatesNaming, assertDerivedScopeNaming, isRedactedLineageNode, personalServerLineagePath, gatewayLineagePath, getLineage, getPersonalServerLineage, getGatewayLineage, LineageNodeSchema, RedactedLineageNodeSchema, LineageEntrySchema, LineageGraphSchema, type LineageNode, type RedactedLineageNode, type LineageEntry, type LineageGraph, type LineageReadResult, type PersonalServerLineageParams, type GatewayLineageParams, type GetLineageParams, } from "./protocol/lineage.js";
 export { DataFileEnvelopeSchema, createDataFileEnvelope, IngestResponseSchema, type DataFileEnvelope, type IngestResponse, } from "./protocol/data-file.js";
 export { createGatewayClient, type GatewayEnvelope, type GatewayProof, type Builder, type Schema, type ServerInfo, type OwnerServerRecord, type OwnerServersResult, type GatewayGrantFee, type GatewayGrantStatus, type GatewayGrantResponse, type GrantListItem, type DataPointRecord, type DataPointListResult, type ListDataPointsOptions, type RegisterServerParams, type RegisterServerResult, type RegisterBuilderParams, type RegisterBuilderResult, type RegisterDataPointParams, type RegisterDataPointResult, type GetDataPointOptions, type DeleteDataPointParams, type DeleteDataPointResult, type CreateGrantParams, type RevokeGrantParams, type AccessRecord, type PayForOperationParams, type PayForOperationResult, type SettleOpType, type SettleItem, type SettlePromoteResult, type SettleReconcileItem, type SettleParams, type SettleResult, type GatewayClient, } from "./protocol/gateway.js";

package/dist/index.browser.js

@@ -31736,6 +31736,147 @@ var RECORD_DATA_ACCESS_TYPES = {
   ]
 };
 
+// src/protocol/identity.ts
+init_interface();
+import * as secp256k13 from "@noble/secp256k1";
+import {
+  concat as concat4,
+  encodePacked,
+  fromHex as fromHex5,
+  getAddress,
+  isAddressEqual,
+  keccak256,
+  recoverPublicKey,
+  toBytes
+} from "viem";
+import { publicKeyToAddress } from "viem/accounts";
+var ENCLAVE_IDENTITY_EVIDENCE_VERSION = 1;
+var USER_PS_ID_DOMAIN = "vana.ps-enclave.v1";
+var ENCLAVE_WALLET_PURPOSE = "vana.ps-enclave.wallet.v1";
+var MASTER_SIGNATURE_DELIVERY_VERSION = "vana.ps-enclave.delivery.v1";
+var SEALED_ENVELOPE_VERSION = 1;
+var VANA_MAINNET_CHAIN_ID = 1480;
+var MOKSHA_CHAIN_ID = 14800;
+var KMS_ISSUED_PREFIX = "dstack-kms-issued";
+var PREIMAGE_SEPARATOR = ":";
+var UNCOMPRESSED_PUBLIC_KEY_BYTES = 65;
+var UNCOMPRESSED_PUBLIC_KEY_PREFIX = "04";
+var ENCLAVE_TRUST_ANCHORS = {
+  // filled at fleet provisioning; verify fails closed while empty
+  [VANA_MAINNET_CHAIN_ID]: { kmsRootPubkey: "0x", appIds: [] },
+  // filled at fleet provisioning; verify fails closed while empty
+  [MOKSHA_CHAIN_ID]: { kmsRootPubkey: "0x", appIds: [] }
+};
+function userPsId(chainId, ownerAddress) {
+  const packed = encodePacked(
+    ["string", "uint256", "address"],
+    [USER_PS_ID_DOMAIN, BigInt(chainId), getAddress(ownerAddress)]
+  );
+  return keccak256(packed);
+}
+function appRootPreimage(purpose, publicKey) {
+  const keyHex = publicKey.slice(2).toLowerCase();
+  return keccak256(toBytes(`${purpose}${PREIMAGE_SEPARATOR}${keyHex}`));
+}
+function kmsIssuedPreimage(appId, appRootPublicKey) {
+  const appIdHex = appId.slice(2).toLowerCase();
+  const prefix = toBytes(
+    `${KMS_ISSUED_PREFIX}${PREIMAGE_SEPARATOR}${appIdHex}`
+  );
+  const compressed = secp256k13.ProjectivePoint.fromHex(
+    fromHex5(appRootPublicKey, "bytes")
+  ).toRawBytes(true);
+  return keccak256(concat4([prefix, compressed]));
+}
+async function recoverChainKey(hash, signature, link) {
+  try {
+    return (await recoverPublicKey({ hash, signature })).toLowerCase();
+  } catch {
+    throw new Error(`Invalid enclave signature chain link ${link}`);
+  }
+}
+async function verifyEnclaveIdentityEvidence(evidence, anchors, expected) {
+  if (evidence.v !== ENCLAVE_IDENTITY_EVIDENCE_VERSION) {
+    throw new Error("Unsupported enclave identity evidence version");
+  }
+  if (!Number.isInteger(evidence.epoch) || evidence.epoch < 1) {
+    throw new Error("Invalid enclave identity epoch");
+  }
+  if (evidence.chainId !== expected.chainId) {
+    throw new Error(
+      "Enclave identity chain ID does not match expected chain ID"
+    );
+  }
+  if (!isAddressEqual(evidence.ownerAddress, expected.ownerAddress)) {
+    throw new Error("Enclave identity owner does not match expected owner");
+  }
+  if (evidence.epoch !== expected.epoch) {
+    throw new Error("Enclave identity epoch does not match expected epoch");
+  }
+  const expectedUserPsId = userPsId(expected.chainId, expected.ownerAddress);
+  if (evidence.userPsId.toLowerCase() !== expectedUserPsId.toLowerCase()) {
+    throw new Error("Enclave userPsId does not match expected identity");
+  }
+  if (evidence.purpose !== ENCLAVE_WALLET_PURPOSE) {
+    throw new Error("Unexpected enclave wallet purpose");
+  }
+  const derivedAddress = publicKeyToAddress(evidence.publicKey);
+  if (getAddress(derivedAddress) !== getAddress(evidence.address)) {
+    throw new Error("Enclave public key does not match its address");
+  }
+  const appRootPublicKey = await recoverChainKey(
+    appRootPreimage(evidence.purpose, evidence.publicKey),
+    evidence.signatureChain[0],
+    0
+  );
+  const kmsRootPublicKey = await recoverChainKey(
+    kmsIssuedPreimage(evidence.appId, appRootPublicKey),
+    evidence.signatureChain[1],
+    1
+  );
+  if (anchors.kmsRootPubkey === "0x") {
+    throw new Error("KMS root trust anchor is not provisioned");
+  }
+  if (kmsRootPublicKey !== anchors.kmsRootPubkey.toLowerCase()) {
+    throw new Error("KMS root public key does not match the trust anchor");
+  }
+  if (keccak256(kmsRootPublicKey) !== evidence.kmsRootFingerprint.toLowerCase()) {
+    throw new Error("KMS root fingerprint does not match the evidence");
+  }
+  const appId = evidence.appId.toLowerCase();
+  if (!anchors.appIds.some((allowedAppId) => allowedAppId.toLowerCase() === appId)) {
+    throw new Error("Enclave app ID is not trusted");
+  }
+}
+async function buildMasterSignatureDelivery(evidence, masterSignature, now = Math.floor(Date.now() / 1e3)) {
+  deriveMasterKey(masterSignature);
+  const signerAddress = await recoverServerOwner(masterSignature);
+  if (!isAddressEqual(signerAddress, evidence.ownerAddress)) {
+    throw new Error("Master signature signer does not match evidence owner");
+  }
+  return {
+    v: MASTER_SIGNATURE_DELIVERY_VERSION,
+    userPsId: evidence.userPsId,
+    epoch: evidence.epoch,
+    enclaveAddress: evidence.address,
+    ownerAddress: evidence.ownerAddress,
+    masterSignature,
+    issuedAt: now
+  };
+}
+function assertUncompressedKey(publicKey) {
+  const hex = publicKey.slice(2);
+  if (hex.length !== UNCOMPRESSED_PUBLIC_KEY_BYTES * 2 || !hex.startsWith(UNCOMPRESSED_PUBLIC_KEY_PREFIX) || !/^[0-9a-fA-F]+$/.test(hex)) {
+    throw new Error("Public key must be a 65-byte uncompressed secp256k1 key");
+  }
+}
+async function encryptMasterSignatureDelivery(delivery, publicKey, ecies) {
+  assertUncompressedKey(publicKey);
+  const plaintext = toBytes(JSON.stringify(delivery));
+  const encrypted = await ecies.encrypt(fromHex5(publicKey, "bytes"), plaintext);
+  return `0x${serializeECIES(encrypted)}`;
+}
+
 // src/protocol/personal-server-registration.ts
 import {
   isAddress
@@ -32435,7 +32576,7 @@ function buildMarkDataPointUnavailableRequest(config, input) {
 // src/protocol/data-point-deletion.ts
 import {
   isAddress as isAddress5,
-  keccak256 as keccak2562,
+  keccak256 as keccak2563,
   maxUint256,
   stringToBytes as stringToBytes3
 } from "viem";
@@ -32444,7 +32585,7 @@ import {
 import {
   encodeAbiParameters,
   isAddress as isAddress4,
-  keccak256
+  keccak256 as keccak2562
 } from "viem";
 import { z } from "zod";
 
@@ -32528,7 +32669,7 @@ function deriveDataPointId(ownerAddress, scope) {
       `ownerAddress is not an EVM address: ${String(ownerAddress)}`
     );
   }
-  return keccak256(
+  return keccak2562(
     encodeAbiParameters(
       [
         { name: "ownerAddress", type: "address" },
@@ -32755,7 +32896,7 @@ var TOMBSTONE_METADATA_HASH_PREIMAGE = "vana.data-point.tombstone.metadata.v1";
 var TOMBSTONE_DATA_HASH = "0x30c45ee72fe56d1927701316925ab7ceacd3b6f9267061735d59396f075c6222";
 var TOMBSTONE_METADATA_HASH = "0xc5255a141acd6a2ae55971b62c0a85977c2511989dc114ad2abc2b7644f57d90";
 function computeTombstoneHash(preimage) {
-  return keccak2562(stringToBytes3(preimage));
+  return keccak2563(stringToBytes3(preimage));
 }
 function isTombstoneHashes(dataHash, metadataHash) {
   return typeof dataHash === "string" && typeof metadataHash === "string" && dataHash.toLowerCase() === TOMBSTONE_DATA_HASH && metadataHash.toLowerCase() === TOMBSTONE_METADATA_HASH;
@@ -33777,6 +33918,13 @@ var QUESTION_STATUSES = [
   "failed",
   "stale"
 ];
+var DERIVATIVE_ERROR_CODES = [
+  "inference_unavailable",
+  "source_missing",
+  "grant_invalid",
+  "internal"
+];
+var DerivativeErrorCodeSchema = z5.enum(DERIVATIVE_ERROR_CODES);
 var QuestionStatusSchema = z5.enum(QUESTION_STATUSES);
 var QuestionRegisteredBySchema = z5.union([
   z5.object({ kind: z5.literal("owner") }),
@@ -33798,6 +33946,14 @@ var DerivativeQuestionSchema = z5.object({
   status: QuestionStatusSchema,
   /** A short reason, set only while `status` is `failed`. */
   error: nullableString,
+  /**
+   * The coarse failure class behind `error`, set only while `status` is
+   * `failed`. `null` from a Personal Server that predates the class
+   * (`personal-server-ts` before the status route).
+   */
+  errorCode: DerivativeErrorCodeSchema.nullish().transform(
+    (value) => value ?? null
+  ),
   createdAt: z5.string(),
   updatedAt: nullableString,
   /** When the last compute finished, or `null` while `pending`. */
@@ -33930,6 +34086,7 @@ async function questionErrorFromResponse(response, body) {
       );
   }
 }
+var personalServerErrorFromQuestionResponse = questionErrorFromResponse;
 async function sendOnce(params, resolved, session, spec, bodyBytes) {
   return sendWithFreshProof(
     spec.label,
@@ -34209,6 +34366,166 @@ async function askPersonalServer(params) {
   return { registration, record };
 }
 
+// src/protocol/derivative-status.ts
+import { z as z6 } from "zod";
+var DERIVATIVE_STATUS_PATH = "/v1/derivatives/status";
+var DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS = 12e4;
+var DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS = 2e3;
+var nullable = (schema) => schema.nullish().transform((value) => value ?? null);
+var DerivativeStatusSchema = z6.object({
+  derivedScope: z6.string().min(1),
+  status: QuestionStatusSchema,
+  /** When the last compute finished, or `null` if none ever has. */
+  lastComputedAt: nullable(z6.string()),
+  /** Local version of the derived record the last compute wrote. */
+  derivedVersion: nullable(z6.number()),
+  derivedCollectedAt: nullable(z6.string()),
+  /** The failure class; `null` unless `status` is `failed`. */
+  errorCode: nullable(DerivativeErrorCodeSchema),
+  /**
+   * Seconds until the Personal Server's next automatic retry, or `null` when
+   * none is pending or running — the terminal signature. Poll on this cadence
+   * rather than guessing one.
+   */
+  retryAfterSeconds: nullable(z6.number())
+});
+function derivativeStatusTarget(derivedScope) {
+  return `${DERIVATIVE_STATUS_PATH}?derivedScope=${encodeURIComponent(derivedScope)}`;
+}
+function normalizeBaseUrl3(url) {
+  return url.replace(/\/+$/, "");
+}
+function resolveFetch3(fetchFn) {
+  const resolved = fetchFn ?? globalThis.fetch;
+  if (resolved === void 0) {
+    throw new WriteRequestError("No fetch implementation available");
+  }
+  return resolved;
+}
+function requireDerivedScope(derivedScope) {
+  if (typeof derivedScope !== "string" || derivedScope.length === 0) {
+    throw new WriteRequestError("derivedScope is required");
+  }
+  return derivedScope;
+}
+function sleep3(ms, signal) {
+  if (ms <= 0) return Promise.resolve();
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      signal?.removeEventListener("abort", onAbort);
+      resolve();
+    }, ms);
+    const onAbort = () => {
+      clearTimeout(timer);
+      reject(abortError2(signal));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+function timeoutError(latest, timeoutMs) {
+  return new DerivativeQuestionTimeoutError(
+    `Derived scope ${latest.derivedScope} was still ${latest.status} after ${timeoutMs}ms`,
+    {
+      derivedScope: latest.derivedScope,
+      status: latest.status,
+      errorCode: latest.errorCode,
+      retryAfterSeconds: latest.retryAfterSeconds,
+      timeoutMs
+    }
+  );
+}
+function abortError2(signal) {
+  const reason = signal?.reason;
+  return reason instanceof Error ? reason : new WriteRequestError("Derivative status wait was aborted");
+}
+function isDerivativeStatusSettled(status) {
+  if (status.status === "ready") return true;
+  return status.status === "failed" && status.retryAfterSeconds === null;
+}
+async function getDerivativeStatus(params) {
+  const derivedScope = requireDerivedScope(params.derivedScope);
+  const fetchFn = resolveFetch3(params.fetch);
+  const baseUrl = normalizeBaseUrl3(params.personalServerUrl);
+  const signer = resolveWriteSigner(params.signer, { account: params.account });
+  const headers = new Headers(params.headers);
+  headers.set(
+    "Authorization",
+    await buildWeb3SignedHeader({
+      signMessage: signer.signMessage,
+      aud: params.audience ?? baseUrl,
+      method: "GET",
+      uri: DERIVATIVE_STATUS_PATH,
+      grantId: params.grantId
+    })
+  );
+  let response;
+  try {
+    response = await fetchFn(
+      `${baseUrl}${derivativeStatusTarget(derivedScope)}`,
+      {
+        method: "GET",
+        headers,
+        ...params.signal ? { signal: params.signal } : {}
+      }
+    );
+  } catch (err) {
+    throw new WriteTransportError(
+      `Derivative status read failed: ${err instanceof Error ? err.message : String(err)}`,
+      1,
+      err
+    );
+  }
+  if (!response.ok) {
+    throw await personalServerErrorFromQuestionResponse(
+      response
+    );
+  }
+  let body;
+  try {
+    body = await response.json();
+  } catch (err) {
+    throw new DerivativeQuestionRejectedError(
+      "Derivative status response is not JSON",
+      response.status,
+      null,
+      { cause: err instanceof Error ? err.message : String(err) }
+    );
+  }
+  const parsed = DerivativeStatusSchema.safeParse(body);
+  if (!parsed.success) {
+    throw new DerivativeQuestionRejectedError(
+      "Derivative status response is not a status view",
+      response.status,
+      null,
+      { issues: parsed.error.issues }
+    );
+  }
+  return parsed.data;
+}
+async function waitForDerivativeStatus(params) {
+  const timeoutMs = Math.max(
+    0,
+    params.timeoutMs ?? DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS
+  );
+  const pollIntervalMs = Math.max(
+    0,
+    params.pollIntervalMs ?? DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS
+  );
+  const deadline = Date.now() + timeoutMs;
+  for (; ; ) {
+    if (params.signal?.aborted) throw abortError2(params.signal);
+    const latest = await getDerivativeStatus(params);
+    if (isDerivativeStatusSettled(latest)) return latest;
+    const remaining = deadline - Date.now();
+    if (remaining <= 0) throw timeoutError(latest, timeoutMs);
+    const waitMs = latest.retryAfterSeconds === null ? pollIntervalMs : latest.retryAfterSeconds * 1e3;
+    if (waitMs > remaining) {
+      throw timeoutError(latest, timeoutMs);
+    }
+    await sleep3(waitMs, params.signal);
+  }
+}
+
 // src/protocol/gateway.ts
 function withGrantPermissions(grant) {
   const stripped = { ...grant };
@@ -34821,9 +35138,13 @@ export {
   ContractFactory,
   ContractNotFoundError,
   DATA_REGISTRY_STATUS_ABI,
+  DEFAULT_DERIVATIVE_STATUS_POLL_INTERVAL_MS,
+  DEFAULT_DERIVATIVE_STATUS_TIMEOUT_MS,
   DEFAULT_QUESTION_POLL_INTERVAL_MS,
   DEFAULT_QUESTION_TIMEOUT_MS,
+  DERIVATIVE_ERROR_CODES,
   DERIVATIVE_QUESTIONS_PATH,
+  DERIVATIVE_STATUS_PATH,
   DataFileEnvelopeSchema,
   DataPointDeletedError,
   DataPointNotFoundError,
@@ -34832,6 +35153,7 @@ export {
   DerivativeComputeUnavailableError,
   DerivativeCycleError,
   DerivativeDerivedScopeRequiredError,
+  DerivativeErrorCodeSchema,
   DerivativeQuestionFailedError,
   DerivativeQuestionInvalidError,
   DerivativeQuestionNotFoundError,
@@ -34839,8 +35161,12 @@ export {
   DerivativeQuestionSchema,
   DerivativeQuestionTimeoutError,
   DerivativeSourceNotGrantedError,
+  DerivativeStatusSchema,
   DropboxStorage,
   ECIESError,
+  ENCLAVE_IDENTITY_EVIDENCE_VERSION,
+  ENCLAVE_TRUST_ANCHORS,
+  ENCLAVE_WALLET_PURPOSE,
   ESCROW_DEPOSIT_ABI2 as ESCROW_DEPOSIT_ABI,
   ExpiredTokenError,
   FEE_REGISTRY_ABI,
@@ -34861,6 +35187,7 @@ export {
   LineageNodeSchema,
   LineageReadError,
   MASTER_KEY_MESSAGE,
+  MASTER_SIGNATURE_DELIVERY_VERSION,
   MAX_LINEAGE_SOURCES,
   MAX_QUESTION_CHARS,
   MAX_QUESTION_MODEL_CHARS,
@@ -34896,6 +35223,7 @@ export {
   RedactedLineageNodeSchema,
   RelayerError,
   SCOPE_ACTIONS,
+  SEALED_ENVELOPE_VERSION,
   SERVER_REGISTRATION_TYPES,
   ScopeSchema,
   SerializationError,
@@ -34908,6 +35236,7 @@ export {
   TOMBSTONE_METADATA_HASH,
   TOMBSTONE_METADATA_HASH_PREIMAGE,
   TransactionPendingError,
+  USER_PS_ID_DOMAIN,
   UserRejectedRequestError,
   VanaError,
   VanaStorage,
@@ -34926,6 +35255,7 @@ export {
   WriteSessionExpiredError,
   WriteTransportError,
   WriteUnauthorizedError,
+  appRootPreimage,
   askPersonalServer,
   assertDerivedScopeNaming,
   assertValidPkceVerifier,
@@ -34935,6 +35265,7 @@ export {
   buildDepositNativeRequest,
   buildDepositTokenRequest,
   buildMarkDataPointUnavailableRequest,
+  buildMasterSignatureDelivery,
   buildPersonalServerDataReadRequest,
   buildPersonalServerLiteOwnerBindingMessage,
   buildPersonalServerLiteOwnerBindingSignature,
@@ -34963,6 +35294,7 @@ export {
   decryptWithPassword,
   deleteDataPoint,
   deleteQuestion,
+  derivativeStatusTarget,
   deriveDataPointId,
   deriveMasterKey,
   deriveScopeKey,
@@ -34973,6 +35305,7 @@ export {
   encodeDepositTokenData,
   encodeSetDataPointStatusData,
   encodeWriteMetadataHeader,
+  encryptMasterSignatureDelivery,
   encryptWithPassword,
   escrowContractAddress,
   escrowPaymentDomain,
@@ -34986,6 +35319,7 @@ export {
   getContractAddress,
   getContractController,
   getContractInfo,
+  getDerivativeStatus,
   getFee,
   getGatewayLineage,
   getLineage,
@@ -35001,10 +35335,12 @@ export {
   isDataPointId,
   isDataPointTombstone,
   isDataPortabilityGatewayConfig,
+  isDerivativeStatusSettled,
   isECIESEncrypted,
   isPlatformSupported,
   isRedactedLineageNode,
   isTombstoneHashes,
+  kmsIssuedPreimage,
   listQuestions,
   mainnetServices,
   moksha,
@@ -35039,10 +35375,13 @@ export {
   signPersonalServerRegistrationWithAccount,
   tombstoneDeletedAt,
   tryGrantPermissions,
+  userPsId,
   vanaMainnet2 as vanaMainnet,
+  verifyEnclaveIdentityEvidence,
   verifyGrantRegistration,
   verifyPkceChallenge,
   verifyWeb3Signed,
+  waitForDerivativeStatus,
   waitForQuestion,
   writeData,
   writePersonalServerData