@usearete/sdk 0.3.0 → 0.4.0

package/dist/index.esm.js

@@ -510,6 +510,7 @@ const MIN_REFRESH_DELAY_MS = 1000;
 const DEFAULT_QUERY_PARAMETER = 'hs_token';
 const DEFAULT_HOSTED_TOKEN_ENDPOINT = 'https://api.arete.run/ws/sessions';
 const HOSTED_WEBSOCKET_SUFFIX = '.stack.arete.run';
+const MAX_HTTP_AUTH_TOKEN_STATES = 32;
 function normalizeTokenResult(result) {
     if (typeof result === 'string') {
         return { token: result };
@@ -548,6 +549,71 @@ function parseJwtExpiry(token) {
 function normalizeExpiryTimestamp(expiresAt, expires_at) {
     return expiresAt ?? expires_at;
 }
+function normalizeScopes(scopes) {
+    return [...new Set(scopes)].sort();
+}
+function isProgramReadBindingAuthTarget(value) {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return candidate['targetKind'] === 'program-read-binding'
+        && typeof candidate['targetId'] === 'string'
+        && typeof candidate['programReleaseHash'] === 'string';
+}
+function isAuthTokenTarget(value) {
+    if (isProgramReadBindingAuthTarget(value)) {
+        return true;
+    }
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+    const candidate = value;
+    return candidate['targetKind'] === 'solana-gateway-binding'
+        && typeof candidate['targetId'] === 'string'
+        && candidate['programReleaseHash'] === undefined;
+}
+function isAuthTokenRequest(value) {
+    return typeof value === 'object'
+        && value !== null
+        && Array.isArray(value.scopes);
+}
+function hasAuthTokenTarget(request) {
+    return isAuthTokenTarget(request);
+}
+function normalizeAuthTokenRequest(request) {
+    const scopes = normalizeScopes(request.scopes);
+    const hasTargetField = request.targetKind !== undefined
+        || request.targetId !== undefined
+        || request.programReleaseHash !== undefined;
+    if (!hasTargetField) {
+        return { scopes };
+    }
+    if (!hasAuthTokenTarget(request)) {
+        throw new AreteError('Targeted authentication requires a complete supported target identity', 'INVALID_CONFIG');
+    }
+    if (isProgramReadBindingAuthTarget(request)) {
+        return {
+            scopes,
+            targetKind: request.targetKind,
+            targetId: request.targetId,
+            programReleaseHash: request.programReleaseHash,
+        };
+    }
+    return {
+        scopes,
+        targetKind: request.targetKind,
+        targetId: request.targetId,
+    };
+}
+function createTargetedHttpTokenIdentity(request) {
+    return JSON.stringify([
+        request.targetKind,
+        request.targetId,
+        request.programReleaseHash ?? null,
+        normalizeScopes(request.scopes),
+    ]);
+}
 function isRefreshAuthResponseMessage(value) {
     if (typeof value !== 'object' || value === null) {
         return false;
@@ -592,6 +658,7 @@ class ConnectionManager {
         this.tokenRefreshTimeout = null;
         this.tokenRefreshInFlight = null;
         this.tokenRequestInFlight = null;
+        this.httpAuthTokenStates = new Map();
         this.currentState = 'disconnected';
         this.subscriptionQueue = new Map();
         this.activeSubscriptions = new Map();
@@ -613,6 +680,12 @@ class ConnectionManager {
         this.maxReconnectAttempts =
             config.maxReconnectAttempts ?? DEFAULT_CONFIG.maxReconnectAttempts;
         this.authConfig = config.auth;
+        this.authFetch = config.fetch ?? ((input, init) => {
+            if (typeof globalThis.fetch !== 'function') {
+                throw new AreteError('A fetch implementation is required for authentication token requests', 'INVALID_CONFIG');
+            }
+            return globalThis.fetch(input, init);
+        });
         if (config.initialSubscriptions) {
             for (const subscription of config.initialSubscriptions) {
                 this.addQueuedSubscription(subscription);
@@ -623,8 +696,10 @@ class ConnectionManager {
         if (this.authConfig?.tokenEndpoint) {
             return this.authConfig.tokenEndpoint;
         }
-        // Require publishableKey for hosted token endpoint
-        if (this.hostedAreteUrl && this.authConfig?.publishableKey) {
+        // Hosted stacks always mint through the Arete Cloud token endpoint.
+        // Without a publishable key the session is minted anonymously — the API
+        // rate limits by IP/origin and issues low-trust public limits instead.
+        if (this.hostedAreteUrl) {
             return DEFAULT_HOSTED_TOKEN_ENDPOINT;
         }
         return undefined;
@@ -669,9 +744,13 @@ class ConnectionManager {
         return scopes.every((scope) => this.tokenScopes.has(scope));
     }
     async getOrRefreshToken(forceRefresh = false, requiredScopes = ['read']) {
-        for (const scope of requiredScopes)
+        const normalizedRequiredScopes = normalizeScopes(requiredScopes);
+        for (const scope of normalizedRequiredScopes)
             this.requestedScopes.add(scope);
-        if (!forceRefresh && this.currentToken && !this.isTokenExpired() && this.tokenCovers(requiredScopes)) {
+        if (!forceRefresh
+            && this.currentToken
+            && !this.isTokenExpired()
+            && this.tokenCovers(normalizedRequiredScopes)) {
             return this.currentToken;
         }
         if (this.tokenRequestInFlight) {
@@ -679,18 +758,20 @@ class ConnectionManager {
             if (!this.currentToken) {
                 return undefined;
             }
-            if (this.currentToken && !this.isTokenExpired() && this.tokenCovers(requiredScopes)) {
+            if (this.currentToken
+                && !this.isTokenExpired()
+                && this.tokenCovers(normalizedRequiredScopes)) {
                 return this.currentToken;
             }
-            throw new AreteError(`Authentication token was not granted required scopes: ${requiredScopes.join(', ')}`, 'AUTH_REQUIRED');
+            throw new AreteError(`Authentication token was not granted required scopes: ${normalizedRequiredScopes.join(', ')}`, 'AUTH_REQUIRED');
         }
         let request;
-        request = Promise.resolve().then(() => this.fetchAuthToken([...new Set([...this.tokenScopes, ...this.requestedScopes])], () => this.tokenRequestInFlight === request));
+        request = Promise.resolve().then(() => this.fetchAuthToken(normalizeScopes([...this.tokenScopes, ...this.requestedScopes]), () => this.tokenRequestInFlight === request));
         this.tokenRequestInFlight = request;
         try {
             const token = await request;
-            if (token && !this.tokenCovers(requiredScopes)) {
-                throw new AreteError(`Authentication token was not granted required scopes: ${requiredScopes.join(', ')}`, 'AUTH_REQUIRED');
+            if (token && !this.tokenCovers(normalizedRequiredScopes)) {
+                throw new AreteError(`Authentication token was not granted required scopes: ${normalizedRequiredScopes.join(', ')}`, 'AUTH_REQUIRED');
             }
             return token;
         }
@@ -701,27 +782,27 @@ class ConnectionManager {
         }
     }
     async fetchAuthToken(scopes, isCurrent) {
+        const request = { scopes: normalizeScopes(scopes) };
+        const result = await this.requestAuthToken(request, isCurrent);
+        return result === undefined ? undefined : this.updateTokenState(result, request.scopes);
+    }
+    async requestAuthToken(request, isCurrent) {
         const strategy = this.getAuthStrategy();
         const requireCurrent = () => {
             if (!isCurrent()) {
                 throw new AreteError('Authentication request was superseded', 'CONNECTION_CANCELLED');
             }
         };
-        // For hosted Arete URLs, auth is required - fail early with clear message
-        if (strategy.kind === 'none' && this.hostedAreteUrl) {
-            throw new AreteError('Arete authentication required. Please provide auth.publishableKey to AreteProvider. ' +
-                'Get your key from https://arete.run/dashboard', 'AUTH_REQUIRED');
-        }
         switch (strategy.kind) {
             case 'static-token': {
                 requireCurrent();
-                return this.updateTokenState(strategy.token, scopes);
+                return strategy.token;
             }
             case 'token-provider':
                 try {
-                    const result = await strategy.getToken({ scopes });
+                    const result = await strategy.getToken(request);
                     requireCurrent();
-                    return this.updateTokenState(result, scopes);
+                    return result;
                 }
                 catch (error) {
                     if (error instanceof AreteError) {
@@ -731,9 +812,9 @@ class ConnectionManager {
                 }
             case 'token-endpoint':
                 try {
-                    const result = await this.fetchTokenFromEndpoint(strategy.endpoint, scopes);
+                    const result = await this.fetchTokenFromEndpoint(strategy.endpoint, request);
                     requireCurrent();
-                    return this.updateTokenState(result, scopes);
+                    return result;
                 }
                 catch (error) {
                     if (error instanceof AreteError) {
@@ -746,14 +827,97 @@ class ConnectionManager {
                 return undefined;
         }
     }
-    createTokenEndpointRequestBody(scopes) {
+    updateHttpTokenState(state, result, request) {
+        const normalized = normalizeTokenResult(result);
+        if (!normalized.token) {
+            throw new AreteError('Authentication provider returned an empty token', 'TOKEN_INVALID');
+        }
+        const grantedScopes = new Set(normalized.scopes ?? request.scopes);
+        if (!request.scopes.every((scope) => grantedScopes.has(scope))) {
+            throw new AreteError(`Authentication token was not granted required scopes: ${request.scopes.join(', ')}`, 'AUTH_REQUIRED');
+        }
+        const expiresAt = normalizeExpiryTimestamp(normalized.expiresAt, normalized.expires_at)
+            ?? parseJwtExpiry(normalized.token);
+        if (this.isExpiryExpired(expiresAt)) {
+            throw new AreteError('Authentication token is expired', 'TOKEN_EXPIRED');
+        }
+        state.token = normalized.token;
+        state.expiresAt = expiresAt;
+        return normalized.token;
+    }
+    async getTargetedHttpAuthToken(request, forceRefresh) {
+        const identity = createTargetedHttpTokenIdentity(request);
+        let state = this.httpAuthTokenStates.get(identity);
+        if (!forceRefresh && state?.token && !this.isExpiryExpired(state.expiresAt)) {
+            this.touchHttpAuthTokenState(identity, state);
+            return state.token;
+        }
+        if (state?.inFlight) {
+            this.touchHttpAuthTokenState(identity, state);
+            return state.inFlight;
+        }
+        if (!state) {
+            state = {};
+            this.httpAuthTokenStates.set(identity, state);
+        }
+        const tokenState = state;
+        let inFlight;
+        inFlight = Promise.resolve().then(async () => {
+            const result = await this.requestAuthToken(request, () => this.httpAuthTokenStates.get(identity) === tokenState
+                && tokenState.inFlight === inFlight);
+            return result === undefined
+                ? undefined
+                : this.updateHttpTokenState(tokenState, result, request);
+        });
+        tokenState.inFlight = inFlight;
+        this.touchHttpAuthTokenState(identity, tokenState);
+        this.trimHttpAuthTokenStates();
+        try {
+            return await inFlight;
+        }
+        finally {
+            if (this.httpAuthTokenStates.get(identity) === tokenState
+                && tokenState.inFlight === inFlight) {
+                tokenState.inFlight = undefined;
+            }
+            this.trimHttpAuthTokenStates();
+        }
+    }
+    touchHttpAuthTokenState(identity, state) {
+        this.httpAuthTokenStates.delete(identity);
+        this.httpAuthTokenStates.set(identity, state);
+    }
+    trimHttpAuthTokenStates() {
+        if (this.httpAuthTokenStates.size <= MAX_HTTP_AUTH_TOKEN_STATES) {
+            return;
+        }
+        for (const [identity, state] of this.httpAuthTokenStates) {
+            if (!state.inFlight) {
+                this.httpAuthTokenStates.delete(identity);
+            }
+            if (this.httpAuthTokenStates.size <= MAX_HTTP_AUTH_TOKEN_STATES) {
+                break;
+            }
+        }
+    }
+    createTokenEndpointRequestBody(request) {
+        if (hasAuthTokenTarget(request)) {
+            const target = {
+                targetKind: request.targetKind,
+                targetId: request.targetId,
+                scopes: request.scopes,
+            };
+            return isProgramReadBindingAuthTarget(request)
+                ? { ...target, programReleaseHash: request.programReleaseHash }
+                : target;
+        }
         return {
             websocket_url: this.websocketUrl ?? '',
-            scopes,
+            scopes: request.scopes,
         };
     }
-    async fetchTokenFromEndpoint(tokenEndpoint, scopes = [...this.requestedScopes]) {
-        const response = await fetch(tokenEndpoint, {
+    async fetchTokenFromEndpoint(tokenEndpoint, request) {
+        const response = await this.authFetch(tokenEndpoint, {
             method: 'POST',
             headers: {
                 ...(this.authConfig?.publishableKey
@@ -763,7 +927,7 @@ class ConnectionManager {
                 'Content-Type': 'application/json',
             },
             credentials: this.authConfig?.tokenEndpointCredentials,
-            body: JSON.stringify(this.createTokenEndpointRequestBody(scopes)),
+            body: JSON.stringify(this.createTokenEndpointRequestBody(request)),
         });
         if (!response.ok) {
             const rawError = await response.text();
@@ -798,11 +962,14 @@ class ConnectionManager {
         }
         return data;
     }
-    isTokenExpired() {
-        if (!this.tokenExpiry) {
+    isExpiryExpired(expiresAt) {
+        if (!expiresAt) {
             return false;
         }
-        return Date.now() >= (this.tokenExpiry - TOKEN_REFRESH_BUFFER_SECONDS) * 1000;
+        return Date.now() >= (expiresAt - TOKEN_REFRESH_BUFFER_SECONDS) * 1000;
+    }
+    isTokenExpired() {
+        return this.isExpiryExpired(this.tokenExpiry);
     }
     scheduleTokenRefresh() {
         this.clearTokenRefreshTimeout();
@@ -950,17 +1117,75 @@ class ConnectionManager {
     getState() {
         return this.currentState;
     }
-    async getHttpAuthToken(requiredScopesOrForce = ['read'], forceRefresh = false) {
-        const requiredScopes = typeof requiredScopesOrForce === 'boolean'
-            ? ['read']
-            : requiredScopesOrForce;
-        const force = typeof requiredScopesOrForce === 'boolean'
-            ? requiredScopesOrForce
-            : forceRefresh;
-        return this.getOrRefreshToken(force, requiredScopes);
+    async getHttpAuthToken(requestOrScopesOrTargetOrForce = ['read'], scopesTargetOrForce = false, targetOrForce = false) {
+        let request;
+        let force = false;
+        if (typeof requestOrScopesOrTargetOrForce === 'boolean') {
+            request = { scopes: ['read'] };
+            force = requestOrScopesOrTargetOrForce;
+        }
+        else if (Array.isArray(requestOrScopesOrTargetOrForce)) {
+            if (isAuthTokenTarget(scopesTargetOrForce)) {
+                request = {
+                    scopes: requestOrScopesOrTargetOrForce,
+                    ...scopesTargetOrForce,
+                };
+                force = typeof targetOrForce === 'boolean' ? targetOrForce : false;
+            }
+            else if (isAuthTokenTarget(targetOrForce)) {
+                request = {
+                    scopes: requestOrScopesOrTargetOrForce,
+                    ...targetOrForce,
+                };
+                force = typeof scopesTargetOrForce === 'boolean' ? scopesTargetOrForce : false;
+            }
+            else {
+                request = { scopes: requestOrScopesOrTargetOrForce };
+                force = typeof scopesTargetOrForce === 'boolean' ? scopesTargetOrForce : false;
+            }
+        }
+        else if (isAuthTokenRequest(requestOrScopesOrTargetOrForce)) {
+            request = requestOrScopesOrTargetOrForce;
+            force = typeof scopesTargetOrForce === 'boolean' ? scopesTargetOrForce : false;
+        }
+        else if (isAuthTokenTarget(requestOrScopesOrTargetOrForce)) {
+            const requiredScopes = Array.isArray(scopesTargetOrForce)
+                ? scopesTargetOrForce
+                : ['read'];
+            request = {
+                scopes: requiredScopes,
+                ...requestOrScopesOrTargetOrForce,
+            };
+            force = typeof scopesTargetOrForce === 'boolean'
+                ? scopesTargetOrForce
+                : typeof targetOrForce === 'boolean' ? targetOrForce : false;
+        }
+        else {
+            throw new AreteError('Invalid HTTP authentication token request', 'INVALID_CONFIG');
+        }
+        const normalizedRequest = normalizeAuthTokenRequest(request);
+        return hasAuthTokenTarget(normalizedRequest)
+            ? this.getTargetedHttpAuthToken(normalizedRequest, force)
+            : this.getOrRefreshToken(force, normalizedRequest.scopes);
     }
-    clearHttpAuthToken() {
-        this.clearTokenState();
+    clearHttpAuthToken(identity, requiredScopes = ['read']) {
+        if (identity === undefined) {
+            this.clearTokenState();
+            this.httpAuthTokenStates.clear();
+            return;
+        }
+        const request = normalizeAuthTokenRequest(isAuthTokenRequest(identity)
+            ? identity
+            : {
+                scopes: requiredScopes,
+                ...identity,
+            });
+        if (hasAuthTokenTarget(request)) {
+            this.httpAuthTokenStates.delete(createTargetedHttpTokenIdentity(request));
+        }
+        else {
+            this.clearTokenState();
+        }
     }
     onFrame(handler) {
         this.frameHandlers.add(handler);
@@ -2928,7 +3153,6 @@ async function parseReadResponse(response, path) {
 function programAccountRead(input) {
     return {
         account: input.account,
-        path: input.path,
         schema: input.schema,
     };
 }
@@ -5027,7 +5251,7 @@ function mergeOperations(base, extension) {
 function extendProgram(program, extensions) {
     const base = program;
     const extended = { ...program };
-    delete extended.definitionHash;
+    delete extended.sdkDefinitionHash;
     for (const key of ['pdas', 'accounts', 'queries', 'addresses', 'constants', 'defaults', 'math']) {
         const extensionValue = extensions[key];
         if (extensionValue !== undefined) {
@@ -5592,6 +5816,131 @@ function formatPreparedOperation(operation) {
     return lines.join('\n');
 }
 
+function appendUrl(baseUrl, path) {
+    return `${baseUrl.replace(/\/+$/, '')}/${path.replace(/^\/+/, '')}`;
+}
+function responseErrorCode(response, body) {
+    const headerCode = response.headers.get('X-Error-Code');
+    if (headerCode)
+        return headerCode;
+    try {
+        const parsed = JSON.parse(body);
+        if (typeof parsed.error?.code === 'string')
+            return parsed.error.code;
+        return typeof parsed.code === 'string' ? parsed.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function isRefreshableErrorCode(code) {
+    return shouldRefreshToken(parseErrorCode(code.trim().replace(/_/g, '-')));
+}
+function parseProgramReadResponse(response, path, body) {
+    if (!response.ok) {
+        throw new ReadRequestError({
+            status: response.status,
+            path,
+            body,
+            serverErrorCode: responseErrorCode(response, body),
+        });
+    }
+    try {
+        return JSON.parse(body);
+    }
+    catch (error) {
+        throw new AreteError(`Program read '${path}' returned invalid JSON`, 'INVALID_RESPONSE', error);
+    }
+}
+function hostedAuthConfig(binding, runtimeAuth) {
+    const metadata = binding.auth;
+    const runtimeStrategyConfigured = runtimeAuth?.token !== undefined
+        || runtimeAuth?.getToken !== undefined
+        || runtimeAuth?.tokenEndpoint !== undefined;
+    if (runtimeStrategyConfigured)
+        return runtimeAuth;
+    if (metadata.required === false)
+        return runtimeAuth;
+    return { ...runtimeAuth, tokenEndpoint: metadata.sessionEndpoint };
+}
+function hostedAuth(config) {
+    const auth = hostedAuthConfig(config.binding, config.auth);
+    if (auth?.token !== undefined && !auth.token) {
+        throw new AreteError('Authentication token is empty', 'TOKEN_INVALID');
+    }
+    const bindingId = config.binding.programReadBindingId;
+    if (!auth || auth.token !== undefined) {
+        return { staticToken: auth?.token };
+    }
+    return {
+        manager: new ConnectionManager({ websocketUrl: null, auth, fetch: config.fetch }),
+        target: {
+            targetKind: 'program-read-binding',
+            targetId: bindingId,
+            programReleaseHash: config.release.programReleaseHash,
+        },
+    };
+}
+function requestPath(release, request) {
+    const releaseHash = encodeURIComponent(release.programReleaseHash).replace(/%3A/g, ':');
+    const root = `/v1/releases/${releaseHash}`
+        + `/accounts/${encodeURIComponent(request.account)}`;
+    if (request.operation === 'fetchMany')
+        return root;
+    const addressPath = `${root.replace(/\/+$/, '')}/${encodeURIComponent(request.address)}`;
+    return request.operation === 'exists' ? `${addressPath}/exists` : addressPath;
+}
+function createProgramReadTransport(config) {
+    if (config.kind === 'unavailable') {
+        return {
+            async read() {
+                throw new AreteError(config.message, 'INVALID_CONFIG');
+            },
+        };
+    }
+    const auth = config.kind === 'hosted-binding' ? hostedAuth(config) : undefined;
+    const endpoint = config.kind === 'hosted-binding'
+        ? config.binding.endpoint
+        : config.endpoint;
+    return {
+        async read(request) {
+            const path = requestPath(config.release, request);
+            const input = appendUrl(endpoint, path);
+            const attempt = async (forceRefresh) => {
+                const token = auth?.staticToken
+                    ?? (auth?.manager && auth.target
+                        ? await auth.manager.getHttpAuthToken(auth.target, ['read'], forceRefresh)
+                        : undefined);
+                const headers = new Headers(request.operation === 'fetchMany'
+                    ? { 'content-type': 'application/json' }
+                    : undefined);
+                if (token)
+                    headers.set('authorization', `Bearer ${token}`);
+                return config.fetch(input, {
+                    method: request.operation === 'fetchMany' ? 'POST' : 'GET',
+                    headers,
+                    body: request.operation === 'fetchMany'
+                        ? JSON.stringify({ addresses: request.addresses })
+                        : undefined,
+                });
+            };
+            let response = await attempt(false);
+            let body = await response.text();
+            const wireCode = responseErrorCode(response, body);
+            if (response.status === 401
+                && wireCode
+                && isRefreshableErrorCode(wireCode)
+                && auth?.manager
+                && auth.target) {
+                auth.manager.clearHttpAuthToken(auth.target);
+                response = await attempt(true);
+                body = await response.text();
+            }
+            return parseProgramReadResponse(response, path, body);
+        },
+    };
+}
+
 class TransactionTransportError extends Error {
     constructor(status, body) {
         super(body.message);
@@ -5724,6 +6073,108 @@ function createTransactionTransport(baseUrl, authenticatedFetch) {
     };
 }
 
+function effectiveProgramRead(stack, name, override) {
+    return override ?? stack.programReads?.[name];
+}
+function validateReleaseIdentity(programName, definition, release) {
+    if (release
+        && definition.programSpecHash
+        && release.programSpecHash !== definition.programSpecHash) {
+        throw new AreteError(`Program '${programName}' release programSpecHash '${release.programSpecHash}' does not match definition programSpecHash '${definition.programSpecHash}'`, 'PROGRAM_RELEASE_MISMATCH');
+    }
+}
+function isNonEmptyString(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+function isSecureOrLoopbackHttpUrl$1(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:'
+            || (url.protocol === 'http:'
+                && ['localhost', '127.0.0.1', '::1'].includes(url.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+function validateProgramReadDescriptor(programName, descriptor) {
+    if (!descriptor.release
+        || !isNonEmptyString(descriptor.release.programReleaseHash)
+        || !isNonEmptyString(descriptor.release.programSpecHash)) {
+        throw new AreteError(`Program '${programName}' read descriptor requires a complete release`, 'INVALID_CONFIG');
+    }
+    if (!descriptor.transport || typeof descriptor.transport !== 'object') {
+        throw new AreteError(`Program '${programName}' read descriptor requires a transport`, 'INVALID_CONFIG');
+    }
+    if (descriptor.transport.kind === 'local-http') {
+        if (descriptor.transport.endpointSource !== 'connect-http-url') {
+            throw new AreteError(`Program '${programName}' local HTTP transport must use endpointSource 'connect-http-url'`, 'INVALID_CONFIG');
+        }
+        return;
+    }
+    if (descriptor.transport.kind !== 'hosted-binding') {
+        throw new AreteError(`Program '${programName}' read descriptor has an unsupported transport`, 'INVALID_CONFIG');
+    }
+    const { binding } = descriptor.transport;
+    if (!binding
+        || !isSecureOrLoopbackHttpUrl$1(binding.endpoint)
+        || !/^prb_[A-Za-z0-9_-]{32}$/.test(binding.programReadBindingId)
+        || !binding.auth
+        || binding.auth.targetKind !== 'program-read-binding'
+        || binding.auth.targetId !== binding.programReadBindingId
+        || !isSecureOrLoopbackHttpUrl$1(binding.auth.sessionEndpoint)) {
+        throw new AreteError(`Program '${programName}' hosted binding requires secure endpoints, a canonical binding ID, and matching program-read-binding auth metadata`, 'INVALID_CONFIG');
+    }
+}
+function validateProgramReads(stack, overrides, validateDescriptorKeys = true) {
+    const programKeys = Object.keys(stack.programs ?? {});
+    if (validateDescriptorKeys && stack.programReads) {
+        const readKeys = Object.keys(stack.programReads);
+        const missing = programKeys.filter((key) => !readKeys.includes(key));
+        const extra = readKeys.filter((key) => !programKeys.includes(key));
+        if (missing.length > 0 || extra.length > 0) {
+            throw new AreteError(`Stack '${stack.name}' programReads keys must exactly match programs`
+                + `${missing.length > 0 ? `; missing: ${missing.join(', ')}` : ''}`
+                + `${extra.length > 0 ? `; unknown: ${extra.join(', ')}` : ''}`, 'INVALID_CONFIG');
+        }
+    }
+    for (const [name, descriptor] of Object.entries(stack.programReads ?? {})) {
+        validateProgramReadDescriptor(name, descriptor);
+    }
+    for (const key of Object.keys(overrides ?? {})) {
+        if (!programKeys.includes(key)) {
+            throw new AreteError(`Program read override '${key}' does not match a program in stack '${stack.name}'`, 'INVALID_CONFIG');
+        }
+        validateProgramReadDescriptor(key, overrides[key]);
+    }
+    for (const [name, definition] of Object.entries(stack.programs ?? {})) {
+        validateReleaseIdentity(name, definition, stack.programReads?.[name]?.release);
+        validateReleaseIdentity(name, definition, overrides?.[name]?.release);
+    }
+}
+function hasCompleteIndependentProgramReads(stack, overrides, connectHttpUrl) {
+    const programs = Object.entries(stack.programs ?? {});
+    const readablePrograms = programs
+        .filter(([, definition]) => hasProgramAccountReads(definition));
+    return programs.length > 0 && readablePrograms.every(([name]) => {
+        const read = effectiveProgramRead(stack, name, overrides?.[name]);
+        return read?.transport.kind === 'hosted-binding'
+            || (read?.transport.kind === 'local-http' && isNonEmptyString(connectHttpUrl));
+    });
+}
+function validateLocalProgramReadEndpoints(stack, overrides, connectHttpUrl) {
+    for (const [name, definition] of Object.entries(stack.programs ?? {})) {
+        if (!hasProgramAccountReads(definition))
+            continue;
+        const descriptor = effectiveProgramRead(stack, name, overrides?.[name]);
+        if (descriptor?.transport.kind === 'local-http' && !isNonEmptyString(connectHttpUrl)) {
+            throw new AreteError(`Program '${name}' local HTTP transport requires ConnectOptions.httpUrl`, 'INVALID_CONFIG');
+        }
+    }
+}
+function hasProgramAccountReads(definition) {
+    return Object.keys(definition.accounts ?? {}).length > 0;
+}
 function mergeAttachedPrograms(stack, attachedPrograms) {
     const merged = { ...(attachedPrograms ?? {}) };
     for (const [name, definition] of Object.entries(stack.programs ?? {})) {
@@ -5793,11 +6244,14 @@ function composeExecutionCallbacks(defaultCallback, callCallback) {
     };
 }
 let Arete$1 = class Arete {
-    constructor(url, httpBaseUrl, options) {
+    constructor(url, httpBaseUrl, connectHttpUrl, programReadOverrides, options) {
         this.stack = options.stack;
         this._wallet = options.wallet;
         this.executionDefaults = options.execution;
         this.httpBaseUrl = httpBaseUrl;
+        this.connectHttpUrl = connectHttpUrl;
+        this.programReadOverrides = programReadOverrides;
+        this.auth = options.auth;
         this.fetchImpl = options.fetch ?? this.resolveFetchImpl();
         this.storage = new SortedStorageDecorator(options.storage ?? new MemoryAdapter());
         this.queryStore = new QueryStore(this.storage);
@@ -5816,6 +6270,7 @@ let Arete$1 = class Arete {
             reconnectIntervals: options.reconnectIntervals,
             maxReconnectAttempts: options.maxReconnectAttempts,
             auth: options.auth,
+            fetch: this.fetchImpl,
         });
         this.subscriptionRegistry = new SubscriptionRegistry(this.connection, this.queryStore);
         this.connection.onFrame((frame) => {
@@ -5826,12 +6281,12 @@ let Arete$1 = class Arete {
         });
         this._views = createTypedViews(this.stack, this.storage, this.subscriptionRegistry);
         this._queries = this.buildQueries();
-        this._chain = createChainClient(this.httpBaseUrl, ((input, init) => this.authenticatedFetch(typeof input === 'string'
+        this._chain = options.chain ?? createChainClient(this.httpBaseUrl ?? '', ((input, init) => this.authenticatedStackFetch(typeof input === 'string'
             ? input
             : input instanceof URL
                 ? input.toString()
                 : input.url, init, ['read'])));
-        this._transactions = createTransactionTransport(this.httpBaseUrl, (input, init, scope, requirePreDispatchMarker) => this.authenticatedFetch(input, init, [scope], requirePreDispatchMarker));
+        this._transactions = options.transactions ?? createTransactionTransport(this.httpBaseUrl ?? '', (input, init, scope, requirePreDispatchMarker) => this.authenticatedStackFetch(input, init, [scope], requirePreDispatchMarker));
         this._programs = this.buildPrograms();
     }
     resolveFetchImpl() {
@@ -5850,13 +6305,14 @@ let Arete$1 = class Arete {
     buildPrograms() {
         const bases = {};
         for (const [name, definition] of Object.entries(this.stack.programs ?? {})) {
+            const transport = this.createProgramTransport(name, definition);
             const instructions = {};
             for (const [instructionName, handler] of Object.entries(definition.rawInstructions ?? {})) {
                 instructions[instructionName] = this.createTypedInstruction(handler);
             }
             const accounts = {};
             for (const [accountName, accountDefinition] of Object.entries(definition.accounts ?? {})) {
-                accounts[accountName] = this.createAccountReader(accountDefinition);
+                accounts[accountName] = this.createAccountReader(accountDefinition, transport);
             }
             const queries = {};
             for (const [queryName, queryDefinition] of Object.entries(definition.queries ?? {})) {
@@ -5906,21 +6362,65 @@ let Arete$1 = class Arete {
             build: (params, options) => buildInstruction(handler, params, this.withWallet(options)),
         };
     }
-    createAccountReader(definition) {
+    createProgramTransport(name, definition) {
+        if (!hasProgramAccountReads(definition)) {
+            return createProgramReadTransport({
+                kind: 'unavailable',
+                message: `Program '${name}' has no generated account readers`,
+            });
+        }
+        const descriptor = effectiveProgramRead(this.stack, name, this.programReadOverrides[name]);
+        validateReleaseIdentity(name, definition, descriptor?.release);
+        if (descriptor?.transport.kind === 'local-http') {
+            return createProgramReadTransport({
+                kind: 'local-http',
+                endpoint: this.connectHttpUrl,
+                release: descriptor.release,
+                fetch: this.fetchImpl,
+            });
+        }
+        if (descriptor?.transport.kind === 'hosted-binding') {
+            return createProgramReadTransport({
+                kind: 'hosted-binding',
+                release: descriptor.release,
+                binding: descriptor.transport.binding,
+                auth: this.auth,
+                fetch: this.fetchImpl,
+            });
+        }
+        return createProgramReadTransport({
+            kind: 'unavailable',
+            message: `Program '${name}' has no release-aware read descriptor`,
+        });
+    }
+    createAccountReader(definition, transport) {
         return {
             fetch: async (address) => {
-                const result = await this.readJson(`${definition.path}/${encodeURIComponent(address)}`);
+                const result = await transport.read({
+                    operation: 'fetch',
+                    account: definition.account,
+                    address,
+                });
                 return result === null ? null : parseProgramAccountValue(definition, result);
             },
             fetchMany: async (addresses) => {
-                const result = await this.readJson(definition.path, {
-                    method: 'POST',
-                    body: { addresses },
+                const result = await transport.read({
+                    operation: 'fetchMany',
+                    account: definition.account,
+                    addresses,
                 });
-                return result.map((value) => value === null ? null : parseProgramAccountValue(definition, value));
+                return {
+                    items: result.items.map((item) => item.status === 'ok'
+                        ? { ...item, value: parseProgramAccountValue(definition, item.value) }
+                        : item),
+                };
             },
             exists: async (address) => {
-                const result = await this.readJson(`${definition.path}/${encodeURIComponent(address)}/exists`);
+                const result = await transport.read({
+                    operation: 'exists',
+                    account: definition.account,
+                    address,
+                });
                 return result.exists;
             },
         };
@@ -5975,7 +6475,16 @@ let Arete$1 = class Arete {
         }
         return response;
     }
+    authenticatedStackFetch(input, init, requiredScopes = ['read'], requirePreDispatchMarker = false) {
+        if (!this.httpBaseUrl) {
+            throw new AreteError(`Stack '${this.stack.name}' has no HTTP endpoint; this operation is not a program account read`, 'INVALID_CONFIG');
+        }
+        return this.authenticatedFetch(input, init, requiredScopes, requirePreDispatchMarker);
+    }
     resolveReadUrl(path) {
+        if (!this.httpBaseUrl) {
+            throw new AreteError(`Stack '${this.stack.name}' has no HTTP endpoint; stack queries require httpUrl or endpoints.http`, 'INVALID_CONFIG');
+        }
         return `${this.httpBaseUrl.replace(/\/$/, '')}${path.startsWith('/') ? path : `/${path}`}`;
     }
     /** Merge the client's default wallet into call options (call options win). */
@@ -5987,21 +6496,35 @@ let Arete$1 = class Arete {
         return merged;
     }
     static async connect(stack, options) {
+        validateProgramReads(stack, undefined);
+        const attachedPrograms = options?.programs;
+        const effectiveStack = withPrograms(stack, attachedPrograms);
+        const programReadOverrides = options?.programReads ?? {};
+        validateProgramReads(effectiveStack, programReadOverrides, false);
         const requestedUrl = options?.url ?? stack.endpoints.ws;
+        const connectHttpUrl = options?.httpUrl;
+        validateLocalProgramReadEndpoints(effectiveStack, programReadOverrides, connectHttpUrl);
         const autoConnect = options?.autoConnect !== false;
-        const httpOnly = options?.transport === 'http';
+        const independentlyReadable = hasCompleteIndependentProgramReads(effectiveStack, programReadOverrides, connectHttpUrl);
+        const implicitProgramOnlyHttp = options?.transport === undefined
+            && !requestedUrl
+            && independentlyReadable
+            && Object.keys(stack.views).length === 0;
+        const httpOnly = options?.transport === 'http' || implicitProgramOnlyHttp;
         const url = httpOnly ? null : requestedUrl;
-        const httpUrl = options?.httpUrl
-            ?? stack.endpoints.http
-            ?? (requestedUrl ? deriveHttpEndpoint(requestedUrl) : undefined);
+        const hasGeneratedHttp = Object.prototype.hasOwnProperty.call(stack.endpoints, 'http');
+        let httpUrl = options?.httpUrl;
+        if (httpUrl === undefined) {
+            if (hasGeneratedHttp) {
+                httpUrl = stack.endpoints.http;
+            }
+        }
         if (!httpOnly && !url) {
             throw new AreteError('WebSocket URL is required (provide url option or define endpoints.ws in stack)', 'INVALID_CONFIG');
         }
-        if (!httpUrl) {
+        if (!httpUrl && !independentlyReadable) {
             throw new AreteError('HTTP endpoint is required for transport: "http" (provide httpUrl option or define endpoints.http in stack)', 'INVALID_CONFIG');
         }
-        const attachedPrograms = options?.programs;
-        const effectiveStack = withPrograms(stack, attachedPrograms);
         const internalOptions = {
             stack: effectiveStack,
             httpUrl,
@@ -6018,8 +6541,10 @@ let Arete$1 = class Arete {
             wallet: options?.wallet,
             fetch: options?.fetch,
             execution: options?.execution,
+            chain: options?.chain,
+            transactions: options?.transactions,
         };
-        const client = new Arete(url, httpUrl, internalOptions);
+        const client = new Arete(url, httpUrl || undefined, connectHttpUrl, programReadOverrides, internalOptions);
         if (!httpOnly && autoConnect) {
             await client.connection.connect();
         }
@@ -6230,12 +6755,22 @@ function createSignerRegistry(entries = []) {
     };
 }
 
+function mergeProgramReadOverrides(...layers) {
+    return layers.reduce((selected, layer) => layer ?? selected, undefined);
+}
+function resolveSessionProgramReads(stack, member, options) {
+    const reads = Object.fromEntries(Object.keys(stack.programs ?? {}).flatMap((name) => {
+        const override = mergeProgramReadOverrides(options?.programRead, options?.programReads?.[name], member?.programRead, member?.programReads?.[name]);
+        return override ? [[name, override]] : [];
+    }));
+    return Object.keys(reads).length > 0 ? reads : undefined;
+}
 function resolveMemberConnectOptions(stack, member, options, forceHttpOnly) {
     const transport = member?.transport ?? options?.transport ?? (forceHttpOnly ? 'http' : 'ws');
-    // Resolution order: per-member override → the stack's own endpoints →
-    // session-wide fallback endpoints.
+    // Stack endpoints remain on the stack definition. Only explicit session/member
+    // HTTP options are forwarded as ConnectOptions.httpUrl for local Program Reads.
     const url = member?.url ?? (stack.endpoints.ws || options?.endpoints?.ws);
-    const httpUrl = member?.httpUrl ?? stack.endpoints.http ?? options?.endpoints?.http;
+    const httpUrl = member?.httpUrl ?? options?.endpoints?.http;
     return {
         url,
         httpUrl,
@@ -6246,33 +6781,87 @@ function resolveMemberConnectOptions(stack, member, options, forceHttpOnly) {
         autoReconnect: member?.autoReconnect,
         wallet: options?.wallet,
         fetch: options?.fetch,
+        programReads: resolveSessionProgramReads(stack, member, options),
+        chain: options?.chain,
+        transactions: options?.transactions,
     };
 }
-function programAsStack(name, program) {
+function validateCompositionProgramReads(stack, member, options) {
+    const overrides = resolveSessionProgramReads(stack, member, options);
+    for (const [name, program] of Object.entries(stack.programs ?? {})) {
+        const descriptor = overrides?.[name] ?? stack.programReads?.[name];
+        if (descriptor)
+            validateProgramReadDescriptor(name, descriptor);
+        if (Object.keys(program.accounts ?? {}).length === 0)
+            continue;
+        const binding = descriptor?.transport.kind === 'hosted-binding'
+            ? descriptor.transport.binding
+            : undefined;
+        if (!descriptor?.release
+            || !binding
+            || !binding.endpoint?.trim()
+            || !binding.programReadBindingId?.trim()
+            || binding.auth?.targetKind !== 'program-read-binding'
+            || binding.auth.targetId !== binding.programReadBindingId
+            || !binding.auth.sessionEndpoint?.trim()) {
+            throw new AreteError(`Composition session program '${name}' requires a complete hosted-binding descriptor or override`, 'INVALID_CONFIG');
+        }
+    }
+}
+function programAsStack(name, program, descriptor) {
     return {
         name,
         endpoints: { ws: '' },
         views: {},
         programs: { [name]: program },
+        ...(descriptor ? { programReads: { [name]: descriptor } } : {}),
     };
 }
-async function createSession(definition, options) {
+async function createSession(definition, ...args) {
+    const options = args[0];
     const stackEntries = Object.entries(definition.stacks ?? {});
     const programEntries = Object.entries(definition.programs ?? {});
     if (stackEntries.length === 0 && programEntries.length === 0) {
         throw new AreteError('createSession requires at least one stack or program member', 'INVALID_CONFIG');
     }
+    if (definition.mode === 'composition' && (!options?.chain || !options?.transactions)) {
+        throw new AreteError('composition sessions require explicit chain and transaction transports', 'INVALID_CONFIG');
+    }
+    if (definition.mode === 'composition' && options?.endpoints !== undefined) {
+        throw new AreteError('composition sessions require per-member live endpoints, not shared fallback endpoints', 'INVALID_CONFIG');
+    }
+    if (definition.programReads) {
+        const programKeys = programEntries.map(([key]) => key);
+        const descriptorKeys = Object.keys(definition.programReads);
+        if (programKeys.some((key) => !descriptorKeys.includes(key))
+            || descriptorKeys.some((key) => !programKeys.includes(key))) {
+            throw new AreteError('Session definition programReads keys must exactly match standalone programs', 'INVALID_CONFIG');
+        }
+    }
+    if (definition.mode === 'composition') {
+        for (const [key, stack] of stackEntries) {
+            const member = options?.stacks?.[key];
+            validateCompositionProgramReads(withPrograms(stack, member?.programs), member, options);
+        }
+        for (const [key, program] of programEntries) {
+            validateCompositionProgramReads(programAsStack(key, program, definition.programReads?.[key]), options?.programs?.[key], options);
+        }
+    }
     let wallet = options?.wallet;
     const signerRegistry = options?.signerRegistry ?? createSignerRegistry();
     const connectedStacks = await Promise.all(stackEntries.map(async ([key, stack]) => {
         const memberOptions = options?.stacks?.[key];
         const effectiveStack = withPrograms(stack, memberOptions?.programs);
         const connectOptions = resolveMemberConnectOptions(effectiveStack, memberOptions, options, false);
-        const client = await Arete$1.connect(effectiveStack, connectOptions);
+        const client = await Arete$1.connect(stack, {
+            ...connectOptions,
+            programs: memberOptions?.programs,
+            programReads: connectOptions.programReads,
+        });
         return [key, client];
     }));
     const connectedPrograms = await Promise.all(programEntries.map(async ([key, program]) => {
-        const syntheticStack = programAsStack(key, program);
+        const syntheticStack = programAsStack(key, program, definition.programReads?.[key]);
         const connectOptions = resolveMemberConnectOptions(syntheticStack, options?.programs?.[key], options, true);
         const client = await Arete$1.connect(syntheticStack, connectOptions);
         return [key, client];
@@ -6291,21 +6880,23 @@ async function createSession(definition, options) {
         client.programs[key],
     ]);
     const promotedPrograms = Object.fromEntries(connectedProgramEntries);
-    for (const [stackKey, client] of connectedStacks) {
-        for (const [programKey, program] of Object.entries(client.programs)) {
-            if (explicitProgramKeys.has(programKey)) {
-                continue;
-            }
-            const existingOwner = programOwners.get(programKey);
-            if (existingOwner) {
-                console.warn(`Program '${programKey}' is bundled by stacks '${existingOwner.stack}'` +
-                    ` (${existingOwner.programId ?? 'unknown program ID'}) and '${stackKey}'` +
-                    ` (${program.programId ?? 'unknown program ID'}); session.programs.${programKey}` +
-                    ` uses '${existingOwner.stack}' because it was connected first`);
-                continue;
+    if (definition.mode !== 'composition') {
+        for (const [stackKey, client] of connectedStacks) {
+            for (const [programKey, program] of Object.entries(client.programs)) {
+                if (explicitProgramKeys.has(programKey)) {
+                    continue;
+                }
+                const existingOwner = programOwners.get(programKey);
+                if (existingOwner) {
+                    console.warn(`Program '${programKey}' is bundled by stacks '${existingOwner.stack}'` +
+                        ` (${existingOwner.programId ?? 'unknown program ID'}) and '${stackKey}'` +
+                        ` (${program.programId ?? 'unknown program ID'}); session.programs.${programKey}` +
+                        ` uses '${existingOwner.stack}' because it was connected first`);
+                    continue;
+                }
+                promotedPrograms[programKey] = program;
+                programOwners.set(programKey, { stack: stackKey, programId: program.programId });
             }
-            promotedPrograms[programKey] = program;
-            programOwners.set(programKey, { stack: stackKey, programId: program.programId });
         }
     }
     const programs = promotedPrograms;
@@ -6386,6 +6977,142 @@ function flowOperation(prepare) {
     };
 }
 
+function isSecureOrLoopbackHttpUrl(value) {
+    try {
+        const url = new URL(value);
+        return url.protocol === 'https:'
+            || (url.protocol === 'http:'
+                && ['localhost', '127.0.0.1', '::1'].includes(url.hostname));
+    }
+    catch {
+        return false;
+    }
+}
+function validateBinding(capability, binding, requiredScopes) {
+    const auth = binding?.auth;
+    const complete = binding
+        && isSecureOrLoopbackHttpUrl(binding.endpoint)
+        && /^sgb_[A-Za-z0-9_-]{32}$/.test(binding.solanaGatewayBindingId)
+        && binding.cluster.trim().length > 0
+        && binding.region.trim().length > 0
+        && auth
+        && typeof auth.required === 'boolean'
+        && auth.mode === binding.authPolicy
+        && isSecureOrLoopbackHttpUrl(auth.sessionEndpoint)
+        && isSecureOrLoopbackHttpUrl(auth.jwksUrl)
+        && auth.tokenTransport === 'bearer'
+        && auth.audience === 'arete:solana-gateway'
+        && auth.targetKind === 'solana-gateway-binding'
+        && auth.targetId === binding.solanaGatewayBindingId
+        && Array.isArray(auth.scopes)
+        && requiredScopes.every((scope) => auth.scopes.includes(scope))
+        && Array.isArray(auth.acceptedKeyClasses)
+        && typeof auth.transactionEntitlementRequired === 'boolean';
+    if (!complete) {
+        throw new AreteError(`Hosted Solana gateway ${capability} binding is incomplete or inconsistent`, 'INVALID_CONFIG');
+    }
+}
+function resolveFetch(fetchImpl) {
+    if (fetchImpl)
+        return fetchImpl;
+    if (typeof globalThis.fetch === 'function')
+        return globalThis.fetch.bind(globalThis);
+    throw new AreteError('A fetch implementation is required for hosted Solana gateway transports', 'INVALID_CONFIG');
+}
+function hasRuntimeAuthStrategy(auth) {
+    return auth?.token !== undefined
+        || auth?.getToken !== undefined
+        || auth?.tokenEndpoint !== undefined;
+}
+function bindingAuthConfig(binding, runtimeAuth) {
+    if (hasRuntimeAuthStrategy(runtimeAuth))
+        return runtimeAuth;
+    if (!binding.auth.required)
+        return runtimeAuth;
+    return { ...runtimeAuth, tokenEndpoint: binding.auth.sessionEndpoint };
+}
+function refreshableErrorCode(response) {
+    const wireCode = response.headers.get('X-Error-Code');
+    return wireCode !== null
+        && shouldRefreshToken(parseErrorCode(wireCode.trim().replace(/_/g, '-')));
+}
+/**
+ * Construct explicit hosted chain and transaction transports from generated
+ * gateway descriptors. Tokens are isolated by exact binding target and scope.
+ */
+function createHostedSolanaGatewayTransports(bindings, options = {}) {
+    validateBinding('chain', bindings.chain, ['read']);
+    validateBinding('transactions', bindings.transactions, ['transaction:inspect', 'transaction:send']);
+    const fetchImpl = resolveFetch(options.fetch);
+    const managers = new Map();
+    const bindingAuthentication = (binding) => {
+        const auth = bindingAuthConfig(binding, options.auth);
+        if (auth?.token !== undefined) {
+            if (!auth.token) {
+                throw new AreteError('Authentication token is empty', 'TOKEN_INVALID');
+            }
+            return {
+                staticToken: auth.token,
+                target: {
+                    targetKind: 'solana-gateway-binding',
+                    targetId: binding.solanaGatewayBindingId,
+                },
+            };
+        }
+        let manager;
+        if (auth && (auth.getToken || auth.tokenEndpoint)) {
+            const identity = hasRuntimeAuthStrategy(options.auth)
+                ? 'runtime-auth-strategy'
+                : `session-endpoint:${binding.auth.sessionEndpoint}`;
+            manager = managers.get(identity);
+            if (!manager) {
+                manager = new ConnectionManager({ websocketUrl: null, auth, fetch: fetchImpl });
+                managers.set(identity, manager);
+            }
+        }
+        return {
+            manager,
+            target: {
+                targetKind: 'solana-gateway-binding',
+                targetId: binding.solanaGatewayBindingId,
+            },
+        };
+    };
+    const authenticatedFetch = (authentication) => async (input, init, scope, requirePreDispatchMarker) => {
+        const request = { ...authentication.target, scopes: [scope] };
+        const attempt = async (forceRefresh) => {
+            const token = authentication.staticToken
+                ?? (authentication.manager
+                    ? await authentication.manager.getHttpAuthToken(request, forceRefresh)
+                    : undefined);
+            const headers = new Headers(init?.headers);
+            if (token)
+                headers.set('authorization', `Bearer ${token}`);
+            return fetchImpl(input, { ...init, headers });
+        };
+        let response = await attempt(false);
+        const explicitlyNotDispatched = response.headers.get('X-Arete-Upstream-Attempted') === 'false';
+        if (!response.ok
+            && authentication.manager
+            && refreshableErrorCode(response)
+            && (!requirePreDispatchMarker || explicitlyNotDispatched)) {
+            authentication.manager.clearHttpAuthToken(request);
+            response = await attempt(true);
+        }
+        return response;
+    };
+    const chainAuthentication = bindingAuthentication(bindings.chain);
+    const transactionAuthentication = bindingAuthentication(bindings.transactions);
+    const chainFetch = authenticatedFetch(chainAuthentication);
+    const transactionFetch = authenticatedFetch(transactionAuthentication);
+    return {
+        chain: createChainClient(bindings.chain.endpoint, ((input, init) => chainFetch(typeof input === 'string'
+            ? input
+            : input instanceof URL ? input.toString() : input.url, init, 'read', false))),
+        transactions: createTransactionTransport(bindings.transactions.endpoint, (input, init, scope, requirePreDispatchMarker) => transactionFetch(input, init, scope, requirePreDispatchMarker)),
+    };
+}
+
 function chainAccountLoader(chain) {
     return {
         async getAccount(address) {
@@ -6545,5 +7272,5 @@ function stringifyBigints(value) {
 
 const Arete = Object.assign(Arete$1, { session: createSession });
 
-export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationCallbackError, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TransactionExecutionError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, createChainClient, createEntityStream, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isSnapshotFrame, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, safeToRawAmount, serializeInstructionData, serializeViewKey, stackQuery, stringifyBigints, toJsonValue, toRawAmount, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateSubscriptionId, withPrograms };
+export { ASSOCIATED_TOKEN_PROGRAM_ADDRESS, Arete, AreteError, ConnectionManager, DEFAULT_CONFIG, DEFAULT_MAX_ENTRIES_PER_VIEW, FrameProcessor, InstructionError, MemoryAdapter, OperationCallbackError, OperationExecutionError, PROGRAM_OPERATION_EXTENSIONS, ProcessedSlotTimeoutError, QueryStore, ReadRequestError, SPL_TOKEN_PROGRAM_ADDRESS, STACK_RUNTIME_EXTENSIONS, SYSTEM_PROGRAM_ADDRESS, SubscriptionRegistry, TOKEN_2022_PROGRAM_ADDRESS, TransactionExecutionError, TransactionTransportError, account, appendFlowTransactions, appendTransactionInstructions, applyConnectedStackExtensions, arg, buildInstruction, bytes, canonicalQueryKey, chainAccountLoader, createChainClient, createEntityStream, createHostedSolanaGatewayTransports, createInstructionExecutor, createInstructionHandler, createPreparedFlow, createPreparedInstruction, createPreparedTransaction, createPreparedTransactionBody, createProgramPdas, createPublicKeySeed, createRichUpdateStream, createSeed, createSession, createSignerRegistry, createSubscriptionId, createTransactionTransport, createTypedListView, createTypedStateView, createTypedViews, createUpdateStream, decodeBase58, defineProgramExtensions, defineStackExtensions, deriveAssociatedTokenAccount, deriveHttpEndpoint, findProgramAddress as derivePda, describePreparedOperation, encodeBase58, executeInstruction, executePreparedOperation, extendProgram, extendPrograms, extendStack, findProgramAddress, findProgramAddressSync, flowOperation, formatPreparedOperation, formatProgramError, formatRawToUi, getMintDecimals, getProgramRuntimeExtensions, getStackRuntimeExtensions, getTransactionFailureOutcome, inspectPreparedOperation, instructionOperation, isEntityFrame, isErrorFrame, isHostedAreteEndpoint, isSnapshotFrame, isSubscribedFrame, isUnsubscribedFrame, isValidFrame, literal, normalizeSubscription, normalizeSubscriptionQuery, normalizeSubscriptionRequest, normalizeTransactionError, parseFrame, parseFrameFromBlob, parseInstructionError, parseUiAmountToRaw, pda, prependFlowTransactionInstructions, prependTransactionInstructions, programAccountRead, programQuery, resolveAccounts, resolveAmount, resolveAmountToRaw, resolveAmountsToRaw, resolveTokenProgramAddress, safeToRawAmount, serializeInstructionData, serializeViewKey, stackQuery, stringifyBigints, toJsonValue, toRawAmount, transactionOperation, unwrapOperationExecutionError, validateAccountResolution, validateProgramReadDescriptor, validateSubscriptionId, withPrograms };
 //# sourceMappingURL=index.esm.js.map