@provablehq/veil-aleo-sdk 0.10.0 → 0.11.0

package/README.md

@@ -28,42 +28,34 @@ import { loadNetwork } from '@provablehq/veil-aleo-sdk'
 
 const aleo = await loadNetwork('testnet')
 
-// A record scanner so the wallet client can find the private records that
-// program calls spend. The first requestRecords registers the view key with the
-// service (one network round-trip); later calls reuse it.
-// `url` defaults to Provable's hosted scanner, so this needs no arguments.
-const scanner = aleo.createRemoteScanner()
-
 // A fully-wired client pair: an account from the private key, a public client
-// for reads, and a wallet client with proving + the scanner attached. The
-// credential store holds one Provable API session shared by proving and
-// scanning — it registers a consumer on the first run and reuses it after.
-import { fileCredentialStore } from '@provablehq/veil-aleo-sdk/node'
-
+// for reads, and a wallet client with delegated proving and a record scanner
+// attached. Every service defaults to the Provable gateway.
 const { publicClient, walletClient, account } = aleo.createAleoClient({
   privateKey: PRIVATE_KEY,
-  networkUrl: 'https://api.provable.com/v2',
-  credentialStore: fileCredentialStore('./.provable-credentials.json'),
-  records: scanner,
 })
 
 account.address // 'aleo1...'
 ```
 
-No API key appears above: the store registers a Provable API consumer the first
-time something needs one and reuses it from then on. Already hold credentials?
-Pass `consumerId` and `apiKey` instead and drop the store — see
-[Provable API credentials](#provable-api-credentials).
-
-`proverUrl` is a base URL — the active network is appended, the same way the
-record scanner's `url` works — so `switchChain` re-targets proving instead of
-leaving it on the network the client started from. Do not include the network
-segment yourself. It defaults to Provable's hosted prover
-(`DEFAULT_PROVER_URL`) under delegated proving, so the option only needs setting
-for a self-hosted one.
+No URL or API key appears above: the node API, the hosted prover, and the
+record scanner all run on the Provable gateway, which needs no credentials.
+`networkUrl` defaults to `DEFAULT_NETWORK_URL`, `proverUrl` to
+`DEFAULT_PROVER_URL`, and `records` to `aleo.createRemoteScanner()` against
+`DEFAULT_SCANNER_URL`; each is an option for a self-hosted or legacy service.
+The prover pays fees from its FeeMaster account by default (`useFeeMaster:
+true`), so a faucet-funded account with no public credits can write; pass
+`useFeeMaster: false` when the account funds its own fees. A provisioned key,
+when an operator issues one, goes through `auth` — see
+[Provable API access](#provable-api-access).
+
+`networkUrl`, `proverUrl`, and the scanner's `url` are base URLs — the active
+network is appended — so `switchChain` re-targets reads, proving, and scanning
+instead of leaving them on the network the client started from. Do not include
+the network segment yourself.
 
 Pass `provingMode: 'local'` to prove in-process instead of delegating to a prover
-service (drop `proverUrl`/`apiKey`/`consumerId`). The `walletClient` composes with
+service. The `walletClient` composes with
 action packages the same way a wallet-backed client does:
 
 ```ts
@@ -74,132 +66,53 @@ const client = walletClient.extend(
 )
 ```
 
-## Provable API credentials
-
-Delegated proving and the hosted record scanner both authenticate with a consumer
-id and API key, which the SDK exchanges for short-lived JWTs. A client builds a
-single session covering both services, so one credential mints one token instead
-of each service minting its own.
-
-Where that credential comes from is the only decision. Three options:
-
-| | Use when | Registers? |
-| --- | --- | --- |
-| `fileCredentialStore(path)` from `/node` | Bots, scripts, servers, CI that can write to disk | On first run, then reuses |
-| `consumerId` + `apiKey` | You already hold credentials — from a secret manager or env | Never |
-| `memoryCredentialStore()` (the default) | Tests, ephemeral workers | Every process, key discarded at exit |
-
-`memoryCredentialStore()` is what a client falls back to when given neither, so
-delegated proving works with no configuration at all. It is only appropriate for
-a single short run: the API issues each key exactly once, so a process that
-registers into memory and runs again registers a second consumer nobody can
-reclaim. Anything long-lived wants a persistent store.
-
-The session resolves on the first prove or scan. `authenticateProvableApi()` does
-it eagerly, which is worth doing at startup so a bad key fails before you have
-built a transaction:
-
-```ts
-const { credentials, expiration, registered, applied } =
-  await walletClient.authenticateProvableApi()
-
-applied // { proving: true, recordScanning: true }
-```
-
-`applied` reports which paths the session actually reaches. `recordScanning` is
-`false` when the client was given a record provider it cannot share a session
-with — any implementation other than the ones this package builds — in which case
-that provider keeps using whatever credentials it was constructed with.
+## Provable API access
 
-If you do not have credentials yet, register a consumer once. The API key is
-issued exactly once and cannot be recovered, so persist it immediately:
-
-```ts
-import { registerProvableApi } from '@provablehq/veil-aleo-sdk'
-
-const credentials = await registerProvableApi({ username: 'my-bot-42' })
-await writeFile('creds.json', JSON.stringify(credentials), { mode: 0o600 })
-```
-
-A username is spent once. It is globally unique, the API exposes no endpoint that
-reads a consumer back, and a duplicate registration answers 409 with nothing
-usable in it — so a taken name cannot be traded for the credentials it belongs to.
-The stored key is the only copy, which is the real reason to give a client a
-persistent store rather than the in-memory default.
-
-When a client registers for you, `username` chooses the name:
+The hosted prover and record scanner run on the Provable gateway,
+`https://edge.provable.com/api`, and every default in this package points there.
+The gateway is unauthenticated: a client built from nothing but a private key and
+a network URL proves and scans. An operator may issue a provisioned API key; pass
+it through `auth` and every request carries it in an `X-API-Key` header:
 
 ```ts
 const { walletClient } = aleo.createAleoClient({
-  privateKey: PRIVATE_KEY,
-  networkUrl: 'https://api.provable.com/v2',
-  proverUrl: 'https://api.provable.com/prove',
-  credentialStore: fileCredentialStore('./.provable-credentials.json'),
-  username: 'my-bot-42',        // or () => `bot-${shard}`, resolved at registration
+  privateKey,
+  auth: { mode: 'api-key', value: process.env.PROVABLE_API_KEY! },
 })
 ```
 
-Supplied names are used verbatim, so the consumer is identifiable in your account
-— and a collision fails with an error saying the name is taken rather than quietly
-registering something else. Omit it and the name is derived from the account
-address with a random suffix, which keeps the zero-configuration path working:
-since a username cannot be reused, an account that lost its stored key still needs
-to be able to register.
+A 401 under keyed auth means the key is invalid or revoked, which only the
+operator can fix. `auth` is mutually exclusive with the consumer options below;
+combining them throws at construction.
 
-On Node, `fileCredentialStore` covers this. It writes with mode `0600`, treats a
-missing file as "not registered yet", and reports a corrupt one rather than
-registering over credentials that might still be recoverable by hand. It lives on
-the `/node` subpath so the `node:fs` import never reaches a browser bundle:
+The legacy gateway, `https://api.provable.com`, authenticates with JWTs minted
+from a consumer id and API key. That model is still supported for a caller who
+points the client at it: set `proverUrl` (and the scanner `url`) to the legacy
+gateway and pass `consumerId` and `apiKey` (or a `credentialStore` that holds
+them), and one session mints the JWT at that gateway and hands it to proving and
+scanning. The mint root is the origin of the prover URL, so a self-hosted legacy gateway
+serving `/jwts` at its own origin works the same way. On the default gateway the pair
+is carried and nothing mints, because edge has no JWT route:
 
 ```ts
-import { fileCredentialStore } from '@provablehq/veil-aleo-sdk/node'
-
 const { walletClient } = aleo.createAleoClient({
-  privateKey: PRIVATE_KEY,
+  privateKey,
   networkUrl: 'https://api.provable.com/v2',
   proverUrl: 'https://api.provable.com/prove',
-  credentialStore: fileCredentialStore('./.provable-credentials.json'),
-  records: scanner,
+  records: aleo.createRemoteScanner({ url: 'https://api.provable.com/scanner' }),
+  consumerId,
+  apiKey,
 })
-
-const { registered } = await walletClient.authenticateProvableApi()
-registered // true on the first run, false afterward
-```
-
-Anywhere else, implement the two-method interface yourself — a keychain,
-`localStorage`, IndexedDB, or a secret manager all satisfy it, and the SDK assumes
-nothing about which:
-
-```ts
-import type { ProvableCredentialStore } from '@provablehq/veil-aleo-sdk'
-
-const credentialStore: ProvableCredentialStore = {
-  load: () => {
-    const raw = localStorage.getItem('provable-credentials')
-    return raw ? JSON.parse(raw) : undefined // undefined → register
-  },
-  save: (c) => localStorage.setItem('provable-credentials', JSON.stringify(c)),
-}
+const { expiration } = await walletClient.authenticateProvableApi() // mints eagerly
 ```
 
-Two rules for a hand-written store. `load` MUST return `undefined` rather than
-throw when nothing is stored, or resolution fails instead of registering. And
-`save` must actually persist: it runs before the credentials are handed back
-precisely so a failed write fails the call, since a swallowed one orphans a
-consumer whose key cannot be reissued. That also means a genuinely read-only
-environment should supply `consumerId`/`apiKey` directly rather than rely on
-registration.
-
-An explicit `consumerId`/`apiKey` pair takes precedence over the store, so an
-operator can inject a rotated key or CI credentials without clearing persisted
-state first.
-
-One caveat on the mint itself: the API does not validate the consumer id against
-the API key. A mismatched id still yields a working token, because the token's
-issuer comes from the key. The mismatch surfaces later as a rejection from the
-service you call — the record scanner reports it as `No credentials found for
-given 'iss'`. Nothing in the mint path can catch that for you, so keep the pair
-together.
+Consumer registration is retired: `registerProvableApi` is a no-op that resolves
+`undefined`, `username` is ignored, and a client without a pair never registers
+one. `authenticateProvableApi()` never throws for lack of credentials; on a
+credential-less or keyed client it resolves with `credentials: undefined`,
+`expiration: undefined`, and `registered: false`. `fileCredentialStore` and
+`memoryCredentialStore` remain for a pair held on disk; a store is read once and
+never written.
 
 The handle also exposes the pieces individually when the caller does not want the
 full pair:
@@ -217,29 +130,6 @@ For local iteration without a live chain, `createDevnodeClient()` returns the
 same client pair pointed at an Aleo Devnode instance with a pre-funded seeded
 account.
 
-## Provisioned API keys (edge gateway)
-
-The edge gateway (`edge.provable.com`) runs a different auth model: no consumer
-registration and no JWTs. An operator hands out an API key, and every request
-carries it verbatim in an `X-API-Key` header. Configure it with `auth` instead
-of the consumer options:
-
-```ts
-const { walletClient } = aleo.createAleoClient({
-  privateKey,
-  networkUrl: 'https://edge.provable.com/api/v2',
-  proverUrl: 'https://edge.provable.com/api/prove',
-  records: aleo.createRemoteScanner({ url: 'https://edge.provable.com/api/scanner' }),
-  auth: { mode: 'api-key', value: process.env.PROVABLE_API_KEY! },
-})
-```
-
-The two models are mutually exclusive: combining `auth` with `apiKey`,
-`consumerId`, `username`, `credentialStore`, or `session` throws at
-construction. There is no session under keyed auth — nothing registers,
-persists, or refreshes — so `authenticateProvableApi()` throws, and a 401
-means the key is invalid or revoked, which only the operator can fix.
-
 ## WASM dependency
 
 `@provablehq/sdk` ships the Aleo cryptography as WebAssembly, and this package

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 import { loadNetwork as loadNetwork$1 } from '@provablehq/sdk/dynamic.js';
 export { DEVNODE_ADDR, DEVNODE_PRIVATE_KEY } from '@provablehq/veil-aleo-devnode';
 import { LocalAccount, RecordProvider, StandaloneRecordScanner, PublicClient, WalletClient } from '@provablehq/veil-core';
-import { P as ProvableSession, a as ProvableKeyedAuth, b as ProvingConfigWithSession, c as ProvableCredentialStore, d as ProvableWalletClient } from './provableApi-C4bT37jI.js';
-export { A as AuthenticateProvableApiParameters, e as AuthenticateProvableApiReturnType, C as CreateProvableSessionOptions, f as ProvableApiActions, g as ProvableApiCredentials, h as ProvableJwt, i as ProvableSessionConsumers, R as RegisterProvableApiParameters, j as authenticateProvableApi, k as createProvableSession, m as memoryCredentialStore, p as provableApiActions, r as registerProvableApi } from './provableApi-C4bT37jI.js';
+import { P as ProvableSession, a as ProvableKeyedAuth, b as ProvingConfigWithSession, c as ProvableCredentialStore, d as ProvableWalletClient } from './provableApi-BTVe8yl5.js';
+export { A as AuthenticateProvableApiParameters, e as AuthenticateProvableApiReturnType, C as CreateProvableSessionOptions, f as ProvableApiActions, g as ProvableApiCredentials, h as ProvableJwt, i as ProvableSessionConsumers, R as RegisterProvableApiParameters, j as authenticateProvableApi, k as createProvableSession, m as memoryCredentialStore, p as provableApiActions, r as registerProvableApi } from './provableApi-BTVe8yl5.js';
 import '@provablehq/sdk';
 
 /**
@@ -156,7 +156,7 @@ declare function mnemonicToHDKey(mnemonic: string, options?: {
  *   const account = aleo.privateKeyToAccount('APrivateKey1...')
  *   const { publicClient, walletClient } = aleo.createAleoClient({
  *     privateKey: 'APrivateKey1...',
- *     networkUrl: 'https://api.provable.com/v2',
+ *     networkUrl: 'https://edge.provable.com/api/v2',
  *   })
  *
  * Switching networks: load a new handle. Existing accounts remain valid —
@@ -169,16 +169,26 @@ type SupportedNetwork = 'mainnet' | 'testnet';
  * Base URL of Provable's hosted delegated proving service.
  *
  * The default `proverUrl` for `mode: 'delegated'`. A base, so the active network
- * is appended — which is what lets `switchChain` re-target proving.
+ * is appended — which is what lets `switchChain` re-target proving. Served by
+ * the edge gateway, which needs no credentials; a provisioned key is optional.
  */
-declare const DEFAULT_PROVER_URL = "https://api.provable.com/prove";
+declare const DEFAULT_PROVER_URL = "https://edge.provable.com/api/prove";
 /**
  * Base URL of Provable's hosted Record Scanner Service.
  *
  * The default `url` for both scanner factories. A base — the SDK appends the
- * network segment, which is what lets a scanner follow `switchChain`.
+ * network segment, which is what lets a scanner follow `switchChain`. Served by
+ * the edge gateway, which needs no credentials; a provisioned key is optional.
  */
-declare const DEFAULT_SCANNER_URL = "https://api.provable.com/scanner";
+declare const DEFAULT_SCANNER_URL = "https://edge.provable.com/api/scanner";
+/**
+ * Base URL of Provable's hosted Aleo node API.
+ *
+ * The default `networkUrl` for `createAleoClient`. A base — the transport
+ * appends the network segment, so `switchChain` re-targets reads and
+ * broadcasts. Served by the edge gateway, which needs no credentials.
+ */
+declare const DEFAULT_NETWORK_URL = "https://edge.provable.com/api/v2";
 type SdkModule = Awaited<ReturnType<typeof loadNetwork$1<'testnet'>>>;
 /**
  * A network-bound SDK handle. All functions on this handle use the binary
@@ -249,6 +259,13 @@ interface AleoSdk {
      *   is re-targeted rather than doubled. Defaults to
      *   {@link DEFAULT_PROVER_URL} under `mode: 'delegated'`; unused under
      *   `mode: 'local'`, which reaches no prover.
+     * @param options.consumerId Optional consumer id for the legacy JWT model.
+     *   With `apiKey` it forms the pair a session mints JWTs from when
+     *   `proverUrl` names a legacy gateway such as
+     *   `https://api.provable.com/prove`. On the default gateway the pair is
+     *   carried and nothing mints. Omit both for the default gateway.
+     * @param options.apiKey Optional API key paired with `consumerId`. For a
+     *   provisioned gateway key use `auth` instead.
      * @param options.session Optional Provable API session. When present the
      *   configuration authenticates from it and withholds `apiKey`/`consumerId`
      *   from the prover client, so one party mints JWTs. The session is attached
@@ -284,12 +301,14 @@ interface AleoSdk {
      *
      * @param options.url Base URL of the service (the SDK appends the network
      *   segment — do not include it). Defaults to {@link DEFAULT_SCANNER_URL}.
-     * @param options.consumerId Optional consumer id used for JWT refresh.
-     *   Unnecessary when a `session` supplies the token. Required alongside
-     *   `apiKey` otherwise — a JWT is minted from the pair, so half of it
-     *   authenticates nothing and construction throws rather than 401ing later.
-     * @param options.apiKey Optional API key for the authenticated service
-     *   (e.g. the hosted Provable RSS). Omit for an open/unauthenticated service.
+     * @param options.consumerId Optional consumer id for the legacy JWT model.
+     *   With `apiKey` it forms the pair a session mints JWTs from when `url`
+     *   names a legacy gateway such as `https://api.provable.com/scanner`. On
+     *   the default gateway the pair is carried and nothing mints. Required
+     *   alongside `apiKey`, since a lone key is ambiguous with a provisioned
+     *   key. Omit both for the default gateway.
+     * @param options.apiKey Optional API key paired with `consumerId`. For a
+     *   provisioned gateway key use `auth` instead.
      * @param options.session Optional Provable API session to authenticate from,
      *   shared with delegated proving. `createAleoClient` supplies its own
      *   session through `setSession` on the returned provider, so a caller who
@@ -302,7 +321,8 @@ interface AleoSdk {
      *   `consumerId` — combining them throws.
      * @returns The provider, plus `setSession` and `setAuth` for a factory to
      *   share one credential source across proving and scanning after
-     *   construction.
+     *   construction, and `url`, the base the scanner targets, so the factory
+     *   can tell whether a legacy gateway is in play.
      */
     createRemoteScanner(options?: {
         url?: string;
@@ -312,6 +332,7 @@ interface AleoSdk {
         startBlock?: number;
         auth?: ProvableKeyedAuth;
     }): RecordProvider & {
+        url: string;
         setSession: (session: ProvableSession) => void;
         setAuth: (auth: ProvableKeyedAuth) => void;
     };
@@ -323,13 +344,13 @@ interface AleoSdk {
      *
      * @param options.url Base URL of the service (the SDK appends the network
      *   segment). Defaults to {@link DEFAULT_SCANNER_URL}.
-     * @param options.consumerId Optional consumer id used for JWT refresh.
-     *   Unnecessary when a `session` supplies the token. Required alongside
-     *   `apiKey` otherwise — a JWT is minted from the pair, so half of it
-     *   authenticates nothing and construction throws rather than 401ing later.
+     * @param options.consumerId Optional consumer id from the retired consumer
+     *   model. Accepted so existing configuration keeps loading; the gateway
+     *   needs no consumer, so nothing is sent or minted from it. Required
+     *   alongside `apiKey`, since a lone key is ambiguous with a provisioned key.
      * @param options.viewKey The view key (`AViewKey1…`) to scan and decrypt with.
-     * @param options.apiKey Optional API key for the authenticated service. Omit
-     *   for an open/unauthenticated service.
+     * @param options.apiKey Optional API key paired with `consumerId`. For a
+     *   provisioned gateway key use `auth` instead.
      * @param options.session Optional Provable API session to authenticate from.
      *   Supplied at construction only — a standalone scanner is not pluggable
      *   into a wallet client, so nothing shares a session with it later.
@@ -350,16 +371,36 @@ interface AleoSdk {
         auth?: ProvableKeyedAuth;
     }): StandaloneRecordScanner;
     /**
-     * Creates a fully-wired Aleo client from a private key and network URL.
+     * Creates a fully-wired Aleo client from a private key.
      *
-     * Builds one Provable API session from the credential options and shares it
-     * across delegated proving and record scanning, so a single
-     * `walletClient.authenticateProvableApi()` covers both. Omit the credential
-     * options for a client that authenticates neither.
+     * Targets the Provable gateway, which needs no credentials: with nothing but
+     * the private key the client reads and broadcasts through the hosted node,
+     * proves through the hosted delegated prover with the FeeMaster paying fees,
+     * and scans records through the hosted scanner. Every one of those is an
+     * option for a self-hosted or legacy service. A consumer pair together with
+     * legacy URLs (`https://api.provable.com/...`) selects the legacy JWT model,
+     * with one session minting for proving and scanning; a provisioned gateway
+     * key goes through `auth`.
      *
-     * @param options.apiKey Optional Provable API key. Paired with `consumerId`,
-     *   it seeds the session directly.
-     * @param options.consumerId Optional Provable API consumer id.
+     * @param options.networkUrl Base URL of the Aleo node both clients read from
+     *   and broadcast to, without the network segment. Defaults to
+     *   {@link DEFAULT_NETWORK_URL}; pass an override for a self-hosted node or
+     *   a devnode.
+     * @param options.provingMode Where proofs are produced. Defaults to
+     *   `'delegated'`; `'local'` proves in-process and reaches no prover.
+     * @param options.useFeeMaster Whether the delegated prover pays the fee from
+     *   its FeeMaster account instead of the caller's public credits. Defaults
+     *   to true, so a faucet-funded account with no public credits can write.
+     *   Pass false when the account funds its own fees. Only meaningful under
+     *   delegated proving.
+     * @param options.records Record provider behind `requestRecords`. Defaults
+     *   to `createRemoteScanner()` against the hosted scanner; pass a scanner
+     *   built with a custom `url` or any `RecordProvider` to override.
+     * @param options.apiKey Optional API key for the legacy JWT model. Paired
+     *   with `consumerId`, it seeds the session that mints JWTs at the legacy
+     *   gateway `proverUrl` or the scanner's `url` names. On the default gateway
+     *   the pair is carried and nothing mints.
+     * @param options.consumerId Optional consumer id for the legacy JWT model.
      * @param options.proverUrl Base URL of the delegated proving service — the
      *   network segment is appended, so do not include it. That is what lets
      *   `switchChain` re-target proving. Defaults to {@link DEFAULT_PROVER_URL},
@@ -371,46 +412,30 @@ interface AleoSdk {
      *   that is more often one the node never included than one about to land.
      *   Raise it for a congested network or a multi-transition call that takes
      *   longer to include, rather than treating a slow confirmation as a failure.
-     * @param options.username Optional handle to register a Provable API consumer
-     *   under, used only when no credentials and no stored pair are available.
-     *   A function is called lazily, at the moment registration happens. Defaults
-     *   to a name derived from the account address plus a random suffix — the
-     *   suffix matters because a username is spent once, so an account that lost
-     *   its stored key must still be able to register. Supplying a fixed name
-     *   makes the consumer identifiable but fails if that name is taken, since
-     *   credentials cannot be recovered from a username.
-     * @param options.credentialStore Optional persistence for Provable API
-     *   credentials. When neither `consumerId`/`apiKey` nor a stored pair is
-     *   available, a consumer is registered under a name derived from the account
-     *   address and saved here. Defaults to `memoryCredentialStore()`, which holds
-     *   a registered consumer only for the life of the process — pass
-     *   `fileCredentialStore` from `@provablehq/veil-aleo-sdk/node`, or any
-     *   {@link ProvableCredentialStore}, for anything longer-lived. A client left
-     *   fully unconfigured does not share its session with `records`, so a scanner
-     *   aimed at an open service keeps needing no credential.
+     * @param options.username Ignored. Nothing registers anymore; accepted so
+     *   existing calls compile.
+     * @param options.credentialStore Optional store holding a consumer pair for
+     *   the legacy JWT model. Read once and never written. Defaults to
+     *   `memoryCredentialStore()`. A client left fully unconfigured does not
+     *   share its session with `records`, so a scanner aimed at the gateway stays
+     *   exactly as it was built.
      * @param options.session Optional pre-built session, for a caller that owns
      *   one already. Takes precedence over the credential options.
-     * @param options.auth Optional provisioned-key auth for the edge gateway.
-     *   Selects the keyed model for the whole client: proving and scanning carry
-     *   the key on every request, no session exists, and
-     *   `authenticateProvableApi` throws since there is nothing to resolve.
-     *   Mutually exclusive with every consumer option (`apiKey`, `consumerId`,
-     *   `username`, `credentialStore`, `session`) — edge keys are handed out by
-     *   an operator, not registered.
+     * @param options.auth Optional provisioned key for the gateway. Selects the
+     *   keyed model for the whole client: proving and scanning carry the key on
+     *   every request and no session exists. Mutually exclusive with every
+     *   consumer option (`apiKey`, `consumerId`, `username`, `credentialStore`,
+     *   `session`) — gateway keys are handed out by an operator, not registered.
      * @returns A public client, a wallet client carrying
      *   `authenticateProvableApi`, and the account.
      *
      * @example
-     * const scanner = aleo.createRemoteScanner({ url: SCANNER_URL })
-     * const { walletClient } = aleo.createAleoClient({
-     *   privateKey, networkUrl, proverUrl, records: scanner, credentialStore: store,
-     * })
-     * const { credentials, registered } = await walletClient.authenticateProvableApi()
-     * if (registered) console.log('registered consumer', credentials.consumerId)
+     * const { walletClient } = aleo.createAleoClient({ privateKey })
+     * const txId = await walletClient.writeContract({ program, function: 'transfer_public', inputs })
      */
     createAleoClient(options: {
         privateKey: string;
-        networkUrl: string;
+        networkUrl?: string;
         provingMode?: 'delegated' | 'local';
         proverUrl?: string;
         apiKey?: string;
@@ -422,12 +447,12 @@ interface AleoSdk {
         session?: ProvableSession;
         auth?: ProvableKeyedAuth;
         /**
-         * Record provider for `requestRecords`. Not wired by default — pass
-         * `aleo.createRemoteScanner(...)` or any
-         * custom `RecordProvider`. `requestRecords` throws with a setup hint
-         * when no provider is configured.
+         * Record provider for `requestRecords`. Defaults to
+         * `aleo.createRemoteScanner()` against the hosted scanner; pass a scanner
+         * with a custom `url` or any custom `RecordProvider` to override.
          */
         records?: RecordProvider & {
+            url?: string;
             setSession?: (session: ProvableSession) => void;
             setAuth?: (auth: ProvableKeyedAuth) => void;
         };
@@ -481,4 +506,4 @@ declare function createDevnodeClient(options?: {
     account: LocalAccount<'privateKey'>;
 };
 
-export { type AleoDerivationId, type AleoSdk, BLS12377HDKey, DEFAULT_PROVER_URL, DEFAULT_SCANNER_URL, LEGACY_PATH, ProvableCredentialStore, ProvableKeyedAuth, ProvableSession, ProvableWalletClient, ProvingConfigWithSession, STANDARD_PATH, type SupportedNetwork, createDevnodeClient, generateAccount, generateMnemonic, loadNetwork, mnemonicToHDKey, mnemonicToSeed, validateMnemonic, validateWord };
+export { type AleoDerivationId, type AleoSdk, BLS12377HDKey, DEFAULT_NETWORK_URL, DEFAULT_PROVER_URL, DEFAULT_SCANNER_URL, LEGACY_PATH, ProvableCredentialStore, ProvableKeyedAuth, ProvableSession, ProvableWalletClient, ProvingConfigWithSession, STANDARD_PATH, type SupportedNetwork, createDevnodeClient, generateAccount, generateMnemonic, loadNetwork, mnemonicToHDKey, mnemonicToSeed, validateMnemonic, validateWord };