@usearete/sdk 0.3.0 → 0.4.0

package/dist/index.cjs

@@ -512,6 +512,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 };
@@ -550,6 +551,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;
@@ -594,6 +660,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();
@@ -615,6 +682,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);
@@ -625,8 +698,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;
@@ -671,9 +746,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) {
@@ -681,18 +760,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;
         }
@@ -703,27 +784,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) {
@@ -733,9 +814,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) {
@@ -748,14 +829,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
@@ -765,7 +929,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();
@@ -800,11 +964,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();
@@ -952,17 +1119,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);
@@ -2930,7 +3155,6 @@ async function parseReadResponse(response, path) {
 function programAccountRead(input) {
     return {
         account: input.account,
-        path: input.path,
         schema: input.schema,
     };
 }
@@ -5029,7 +5253,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) {
@@ -5594,6 +5818,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);
@@ -5726,6 +6075,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 ?? {})) {
@@ -5795,11 +6246,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);
@@ -5818,6 +6272,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) => {
@@ -5828,12 +6283,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() {
@@ -5852,13 +6307,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 ?? {})) {
@@ -5908,21 +6364,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;
             },
         };
@@ -5977,7 +6477,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). */
@@ -5989,21 +6498,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,
@@ -6020,8 +6543,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();
         }
@@ -6232,12 +6757,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,
@@ -6248,33 +6783,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];
@@ -6293,21 +6882,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;
@@ -6388,6 +6979,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) {
@@ -6580,6 +7307,7 @@ exports.canonicalQueryKey = canonicalQueryKey;
 exports.chainAccountLoader = chainAccountLoader;
 exports.createChainClient = createChainClient;
 exports.createEntityStream = createEntityStream;
+exports.createHostedSolanaGatewayTransports = createHostedSolanaGatewayTransports;
 exports.createInstructionExecutor = createInstructionExecutor;
 exports.createInstructionHandler = createInstructionHandler;
 exports.createPreparedFlow = createPreparedFlow;
@@ -6659,6 +7387,7 @@ exports.toRawAmount = toRawAmount;
 exports.transactionOperation = transactionOperation;
 exports.unwrapOperationExecutionError = unwrapOperationExecutionError;
 exports.validateAccountResolution = validateAccountResolution;
+exports.validateProgramReadDescriptor = validateProgramReadDescriptor;
 exports.validateSubscriptionId = validateSubscriptionId;
 exports.withPrograms = withPrograms;
 //# sourceMappingURL=index.cjs.map