@hsuite/smart-engines-sdk 3.14.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## 4.1.0 — 2026-06-25
+
+### Added
+
+- **`AgentRegisterRequest.primaryChain?: string`.** Agent registration mints the agent's on-chain wallet ENTITY on the chain named by `primaryChain`; the host requires it and defaults a missing value to `'hedera'` (which has no funded payer in XRPL-only deployments → `PAYER_ACCOUNT_NOT_FOUND`). The field was always accepted at runtime (`AgentsClient.register` forwards the whole body to `POST /api/v3/baas/agents/register`), but the SDK type omitted it, so consumers couldn't set it type-safely. Now declared as a plain optional `string` — valid host values: `'hedera'`, `'xrpl'`, `'polkadot'`, `'solana'`, `'ethereum'`, `'polygon'`, `'bitcoin'`, `'stellar'`. Additive and backward-compatible.
+
+## 4.0.0 — 2026-06-25
+
+**SDK revision — align the surface to the REAL reachable endpoints; remove the un-ingressed-tier footguns.** Two profiles, two tiers: `BaasClient` is the app-as-proxy / external profile (host BaaS tier, `{gateway}/host/api/v3/baas/*`); `SmartEngineClient` is the in-cluster / validator-direct profile (raw `/api/v3/*` tier, un-ingressed at the gateway). The web3 authorization proxy is the HOST, which already exposes the entity value-movement routes — so value-movement now lives on `BaasClient.entities`, and the raw-tier transactions arm is removed from `BaasClient`.
+
+### Breaking changes
+
+- **Removed `BaasClient.transactions` (the `TransactionsClient` sub-client) and `BaasClient`'s internal `txHttp`.** This arm rooted at the RAW `{hostUrl}/api/v3/transactions` origin — a sibling of `/host` that is un-ingressed at the public gateway (RFC #1236), so every call from a gateway-routed `BaasClient` 404'd. That was the footgun. The `TransactionsClient` class itself is unchanged and still ships on `SmartEngineClient` (the validator-direct profile). Migration: external/app-as-proxy callers use `BaasClient.entities.{transfer,withdraw,mint,burn,compliance,trustline}` (host BaaS tier) or, for in-cluster prepare/execute, construct a `SmartEngineClient` with an explicit `validatorBaseUrl`.
+- **`SmartEngineClientConfig.baseUrl` → `validatorBaseUrl` (renamed, type-fence).** `SmartEngineClient` is now constructible ONLY with an explicit VALIDATOR origin. The rename makes it impossible to silently pass a gateway URL into the validator-direct client (whose raw `/api/v3/*` tier 404s at the gateway). Migration: `new SmartEngineClient({ baseUrl })` → `new SmartEngineClient({ validatorBaseUrl })`.
+- **Removed `SmartEngineClient.connectToCluster()` (and its `ClusterConnectionConfig` / `ClusterConnectionSeed` / `ClusterConnectionResult` types).** It resolved a cluster's `gatewayUrl` and fed it into a gateway-pointed `SmartEngineClient` — the same footgun. To reach web3 through a cluster use `BaasClient.connectToCluster({ network })` (host BaaS tier); for an explicit in-cluster validator origin use `new SmartEngineClient({ validatorBaseUrl })` or `SmartEngineClient.connectToNetwork(...)` (which resolves a real validator `apiEndpoint` from the HCS registry — never a gateway URL). `connectToNetwork` is unchanged.
+
+### Added
+
+- **`BaasClient.entities` value-movement (prepare-bytes only).** Six new methods mirroring the host's entity-scoped routes (`POST /api/v3/baas/entities/:entityId/{transfer,withdraw,mint,burn,compliance,trustline}`), each returning the host's `PreparedEntityTransactionResult` and threading `HttpCallOptions` (`onBehalfOf` / `customerToken` / `headers`) — owner-acting via the end user's Mode-1 customer-session JWT, exactly as `agents.execute`. The entity is the source / treasury / authority + fee-payer (resolved server-side; never named in the body), so a caller can never name a foreign payer or drain another account; a rule-deny surfaces as a 403 `rule_rejected` (use `isRuleRejected`), never as signed bytes. New signatures:
+  - `entities.transfer(entityId, body: TransferEntityRequest, opts?) → Promise<PreparedEntityTransactionResult>`
+  - `entities.withdraw(entityId, body: WithdrawEntityRequest, opts?) → Promise<PreparedEntityTransactionResult>`
+  - `entities.mint(entityId, body: MintEntityRequest, opts?) → Promise<PreparedEntityTransactionResult>`
+  - `entities.burn(entityId, body: BurnEntityRequest, opts?) → Promise<PreparedEntityTransactionResult>`
+  - `entities.compliance(entityId, body: ComplianceEntityRequest, opts?) → Promise<PreparedEntityTransactionResult>`
+  - `entities.trustline(entityId, body: TrustlineEntityRequest, opts?) → Promise<PreparedEntityTransactionResult>`
+  - New exported types: `TransferEntityRequest`, `WithdrawEntityRequest`, `MintEntityRequest`, `BurnEntityRequest`, `ComplianceEntityRequest`, `ComplianceAction`, `TrustlineEntityRequest`, `PreparedEntityTransactionResult`.
+
 ## 3.14.0 — 2026-06-25
 
 ### Added

package/README.md

@@ -79,15 +79,15 @@ baas.setAppId(init.appId);
 ```ts
 import { SmartEngineClient } from '@hsuite/smart-engines-sdk';
 
-const { client, cluster, session } = await SmartEngineClient.connectToCluster({
-  network: 'testnet',           // resolves canonical gateway entrypoint
+const { client, validator, session } = await SmartEngineClient.connectToNetwork({
+  network: 'testnet',           // resolves a real validator origin from the HCS registry
   chain: 'xrpl',
   address: wallet.address,
   publicKey: wallet.publicKey,
   signFn: (challenge) => /* sign the challenge */ '',
 });
 
-// All sub-clients are wired against the discovered cluster
+// All sub-clients are wired against the discovered validator
 await client.tss.signMPC({ chain: 'hedera', entityId: '...', transactionBytes: '0x...' });
 await client.ipfs.upload(file, 'document.pdf');
 ```
@@ -115,8 +115,11 @@ const baas = new BaasClient({
   pathPrefix: '/host',          // gateway routes /host/* → smart-host
 });
 
+// `SmartEngineClient` is validator-direct: `validatorBaseUrl` MUST be a
+// validator origin, NEVER the gateway. Its raw `/api/v3/*` tier is un-ingressed
+// at the gateway (RFC #1236), so a gateway URL here 404s every call.
 const client = new SmartEngineClient({
-  baseUrl: 'https://v3-testnet-gateway.hsuite.network',
+  validatorBaseUrl: 'http://smart-validator:3000', // in-cluster validator origin
   authToken: '<jwt-from-validator-auth-verify>',
 });
 ```
@@ -357,12 +360,12 @@ await baas.deployment.rollback(init.appId, { toTag: 'v0' });
 
 For direct chain operations independent of BaaS — e.g., a custodial backend
 that creates accounts and tokens on behalf of users — use the methods on the
-`SmartEngineClient` returned by `connectToCluster`:
+`SmartEngineClient` returned by `connectToNetwork`:
 
 ```ts
 import { SmartEngineClient } from '@hsuite/smart-engines-sdk';
 
-const { client } = await SmartEngineClient.connectToCluster({
+const { client } = await SmartEngineClient.connectToNetwork({
   network: 'testnet',
   chain: 'xrpl',
   address: wallet.address,
@@ -420,7 +423,7 @@ import { SmartEngineModule } from '@hsuite/smart-engines-sdk/nestjs';
     SmartEngineModule.forRootAsync({
       imports: [ConfigModule],
       useFactory: (config: ConfigService) => ({
-        baseUrl: config.get('VALIDATOR_URL')!,
+        validatorBaseUrl: config.get('VALIDATOR_URL')!,
         timeout: 30000,
         testConnection: true,
         autoReconnect: true,

package/dist/index.d.ts

@@ -3825,6 +3825,7 @@ export type AgentRegisterRequest = {
 	description?: string;
 	capabilities: string[];
 	rules: AgentRules;
+	primaryChain?: string;
 	fundingConfig?: {
 		chain: string;
 		maxAmount: string;
@@ -4741,7 +4742,7 @@ export declare class OperatorClient {
 	getTopup(chain: OperatorChain, accountId: string): Promise<OperatorTopUpResponse>;
 }
 export interface SmartEngineClientConfig {
-	baseUrl: string;
+	validatorBaseUrl: string;
 	apiKey?: string;
 	authToken?: string;
 	timeout?: number;
@@ -4761,35 +4762,6 @@ export interface NetworkConnectionConfig {
 	mirrorNodeUrl?: string;
 	allowInsecure?: boolean;
 }
-export interface ClusterConnectionAuth {
-	chain: AuthChain;
-	address: string;
-	publicKey: string;
-	signFn: (challenge: string) => string | Promise<string>;
-	metadata?: {
-		appId?: string;
-		appName?: string;
-	};
-	trustAnchor?: {
-		network: "mainnet" | "testnet" | "previewnet";
-		registryTopicId: string;
-		mirrorNodeUrl?: string;
-	};
-	allowInsecure?: boolean;
-}
-export type ClusterConnectionSeed = {
-	bootstrap: string[];
-	network?: never;
-} | {
-	bootstrap?: never;
-	network: NetworkName;
-};
-export type ClusterConnectionConfig = ClusterConnectionSeed & ClusterConnectionAuth;
-export interface ClusterConnectionResult {
-	client: SmartEngineClient;
-	cluster: ClusterInfo;
-	session: AuthenticateResponse;
-}
 export interface NetworkConnectionResult {
 	client: SmartEngineClient;
 	validator: ValidatorInfo;
@@ -4827,7 +4799,6 @@ export declare class SmartEngineClient {
 	constructor(config: SmartEngineClientConfig);
 	static fromEnv(env: Record<string, string | undefined>): SmartEngineClient;
 	static connectToNetwork(config: NetworkConnectionConfig): Promise<NetworkConnectionResult>;
-	static connectToCluster(config: ClusterConnectionConfig): Promise<ClusterConnectionResult>;
 	getBaseUrl(): string;
 	isAuthenticated(): boolean;
 	getHttpHealth(): {
@@ -25409,6 +25380,56 @@ export type LaunchpadEntityResult = {
 	tokenId: string;
 	chainAccounts: Record<string, string>;
 };
+export type TransferEntityRequest = {
+	chain: ChainType;
+	to: string;
+	amount: string;
+	tokenId?: string;
+	memo?: string;
+};
+export type WithdrawEntityRequest = {
+	chain: ChainType;
+	destination: string;
+	amount: string;
+	tokenId?: string;
+	memo?: string;
+};
+export type MintEntityRequest = {
+	chain: ChainType;
+	tokenId: string;
+	amount: string;
+	memo?: string;
+};
+export type BurnEntityRequest = {
+	chain: ChainType;
+	tokenId: string;
+	amount: string;
+	memo?: string;
+};
+export type ComplianceAction = "pause" | "restrict" | "wipe";
+export type ComplianceEntityRequest = {
+	action: ComplianceAction;
+	chain: ChainType;
+	tokenId: string;
+	account?: string;
+	amount?: string;
+	memo?: string;
+};
+export type TrustlineEntityRequest = {
+	chain: ChainType;
+	currency: string;
+	issuerAddress: string;
+	limit?: string;
+};
+export type PreparedEntityTransactionResult = {
+	chain: string;
+	transactionId: string;
+	transactionBytes: string;
+	transactionType?: string;
+	payerAccountId?: string;
+	expiresAt?: string;
+	metadata?: Record<string, unknown>;
+};
 export declare class EntitiesClient {
 	private readonly http;
 	constructor(http: HttpClient);
@@ -25453,6 +25474,12 @@ export declare class EntitiesClient {
 	launchpad(req: LaunchpadEntityRequest): Promise<LaunchpadEntityResult>;
 	get(entityId: string): Promise<EntityInfo>;
 	listByOwner(filter?: ListEntitiesFilter): Promise<ListEntitiesResponse>;
+	transfer(entityId: string, body: TransferEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	withdraw(entityId: string, body: WithdrawEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	mint(entityId: string, body: MintEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	burn(entityId: string, body: BurnEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	compliance(entityId: string, body: ComplianceEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
+	trustline(entityId: string, body: TrustlineEntityRequest, opts?: HttpCallOptions): Promise<PreparedEntityTransactionResult>;
 }
 export type AuthenticateOptions = {
 	chain: BaasSupportedChain;
@@ -25486,7 +25513,6 @@ export declare class BaasClient {
 	private readonly timeout;
 	private readonly allowInsecure;
 	private readonly http;
-	private readonly txHttp;
 	private lastHttpError?;
 	private authContext?;
 	readonly db: DatabaseClient;
@@ -25498,7 +25524,6 @@ export declare class BaasClient {
 	readonly customerSession: CustomerSessionClient;
 	readonly rules: RulesClient;
 	readonly entities: EntitiesClient;
-	readonly transactions: TransactionsClient;
 	constructor(config: BaasClientConfig);
 	static connectToCluster(config: BaasConnectToClusterConfig): Promise<BaasClient>;
 	setAppId(appId: string): void;
@@ -25718,7 +25743,7 @@ declare namespace personhood {
 	export { PERSONHOOD_VERIFIER_NOT_CONFIGURED, PersonhoodAttestationMethod, PersonhoodCert, PersonhoodClient, PersonhoodProof, PersonhoodVerifyParams, isPersonhoodVerifierNotConfigured };
 }
 declare namespace baas {
-	export { AgentBalance, AgentCertification, AgentEvent, AgentFundRequest, AgentInfo, AgentOperation, AgentPendingApprovalResponse, AgentPreparedTransactionResponse, AgentRegisterRequest, AgentRules, AgentRulesValidationResult, AgentStatus, AgentTradeRequest, AgentWithdrawRequest, AgentsClient, AuthenticateOptions, BaasAppListResponse, BaasAuthConfig, BaasAuthResult, BaasChallengeRequest, BaasChallengeResponse, BaasChannelConfig, BaasClient, BaasClientConfig, BaasConnectToClusterConfig, BaasDeleteResult, BaasDeployRequest, BaasDeployResponse, BaasDocument, BaasEndpoints, BaasError, BaasErrorDetails, BaasErrorResponse, BaasFileInfo, BaasFileMetadata, BaasFindResult, BaasFunctionCode, BaasFunctionDeployRequest, BaasFunctionDeployResult, BaasFunctionEvalRequest, BaasFunctionInfo, BaasFunctionLog, BaasFunctionLogOptions, BaasFunctionResources, BaasFunctionResult, BaasFunctionRuntime, BaasHistoryOptions, BaasInitRequest, BaasInitResponse, BaasInsertResult, BaasMerkleProof, BaasMessage, BaasPresenceInfo, BaasPresenceMember, BaasPublishResult, BaasQueryOptions, BaasReissuePushCredentialsResponse, BaasRevokeKekResponse, BaasRollbackRequest, BaasRotateKekResponse, BaasRuntimeStatus, BaasService, BaasSessionInfo, BaasSetWebhookResponse, BaasSignedCode, BaasStateTransition, BaasStorageUsage, BaasSupportedChain, BaasTriggerType, BaasUpdateResult, BaasUploadFrontendResponse, BaasUploadResult, BaasVerifyRequest, ChannelSubscription, CreateAccountRequest$1 as BaasCreateAccountRequest, CreateAgentRequest, CreateTokenRequest$1 as CreateTokenRequest, CreateTopicRequest, DatabaseClient, DatabaseStatsResponse, DbComparisonOperator, DbDocument, DbQuery, DeployedApp, DeployedAppInfo, DeployedAppLimits, DeployedAppStatus, DeployedAppUsage, DeploymentClient, DeprecateRuleResponse, DocumentProofResponse, EntitiesClient, EntityCreationResult, EntityInfo, EntitySecurityMode, EntityType$1 as BaasEntityType, FunctionsClient, FundWith, LaunchpadEntityRequest, LaunchpadEntityResult, ListEntitiesFilter, ListEntitiesResponse, ListRulesFilter, ListRulesResponse, MessageHandler, MessagingClient, PreparedEntityCreation, PublishRuleResponse, RulesClient, SimulateRuleRequest, StateRootResponse, StateTransitionsResponse, StorageClient, ValidationResult, VersionHistoryResponse, isAgentFundPending, validateAgentRules };
+	export { AgentBalance, AgentCertification, AgentEvent, AgentFundRequest, AgentInfo, AgentOperation, AgentPendingApprovalResponse, AgentPreparedTransactionResponse, AgentRegisterRequest, AgentRules, AgentRulesValidationResult, AgentStatus, AgentTradeRequest, AgentWithdrawRequest, AgentsClient, AuthenticateOptions, BaasAppListResponse, BaasAuthConfig, BaasAuthResult, BaasChallengeRequest, BaasChallengeResponse, BaasChannelConfig, BaasClient, BaasClientConfig, BaasConnectToClusterConfig, BaasDeleteResult, BaasDeployRequest, BaasDeployResponse, BaasDocument, BaasEndpoints, BaasError, BaasErrorDetails, BaasErrorResponse, BaasFileInfo, BaasFileMetadata, BaasFindResult, BaasFunctionCode, BaasFunctionDeployRequest, BaasFunctionDeployResult, BaasFunctionEvalRequest, BaasFunctionInfo, BaasFunctionLog, BaasFunctionLogOptions, BaasFunctionResources, BaasFunctionResult, BaasFunctionRuntime, BaasHistoryOptions, BaasInitRequest, BaasInitResponse, BaasInsertResult, BaasMerkleProof, BaasMessage, BaasPresenceInfo, BaasPresenceMember, BaasPublishResult, BaasQueryOptions, BaasReissuePushCredentialsResponse, BaasRevokeKekResponse, BaasRollbackRequest, BaasRotateKekResponse, BaasRuntimeStatus, BaasService, BaasSessionInfo, BaasSetWebhookResponse, BaasSignedCode, BaasStateTransition, BaasStorageUsage, BaasSupportedChain, BaasTriggerType, BaasUpdateResult, BaasUploadFrontendResponse, BaasUploadResult, BaasVerifyRequest, BurnEntityRequest, ChannelSubscription, ComplianceAction, ComplianceEntityRequest, CreateAccountRequest$1 as BaasCreateAccountRequest, CreateAgentRequest, CreateTokenRequest$1 as CreateTokenRequest, CreateTopicRequest, DatabaseClient, DatabaseStatsResponse, DbComparisonOperator, DbDocument, DbQuery, DeployedApp, DeployedAppInfo, DeployedAppLimits, DeployedAppStatus, DeployedAppUsage, DeploymentClient, DeprecateRuleResponse, DocumentProofResponse, EntitiesClient, EntityCreationResult, EntityInfo, EntitySecurityMode, EntityType$1 as BaasEntityType, FunctionsClient, FundWith, LaunchpadEntityRequest, LaunchpadEntityResult, ListEntitiesFilter, ListEntitiesResponse, ListRulesFilter, ListRulesResponse, MessageHandler, MessagingClient, MintEntityRequest, PreparedEntityCreation, PreparedEntityTransactionResult, PublishRuleResponse, RulesClient, SimulateRuleRequest, StateRootResponse, StateTransitionsResponse, StorageClient, TransferEntityRequest, TrustlineEntityRequest, ValidationResult, VersionHistoryResponse, WithdrawEntityRequest, isAgentFundPending, validateAgentRules };
 }
 declare namespace pqcVerify {
 	export { FetchRegistryOptions, PqcCertV1, PqcCertV1Schema, PqcCertV1Signer, ValidatorRegistrySnapshot, VerifyResult, fetchRegistrySnapshot, parsePqcCert, verifyPqcAttestation };

package/dist/index.js

@@ -6478,9 +6478,11 @@ var ClusterDiscoveryClient = class {
   }
   /**
    * Convenience wrapper returning just the gateway URL of a random
-   * active cluster. The single most-used SDK entry point — most
-   * downstream callers want `new SmartEngineClient({ baseUrl: ... })`
-   * and don't care about the rest of the metadata.
+   * active cluster. Feed this to `BaasClient` (the host BaaS tier) — e.g.
+   * `new BaasClient({ hostUrl, pathPrefix: '/host' })` or
+   * `BaasClient.connectToCluster({ network })`. Do NOT feed it to
+   * `SmartEngineClient`: that client's raw `/api/v3/*` tier is un-ingressed at
+   * the gateway and will 404 (it requires an explicit `validatorBaseUrl`).
    */
   async getRandomGatewayUrl(forceRefresh = false) {
     const cluster = await this.getRandomCluster(forceRefresh);
@@ -9245,7 +9247,7 @@ var SmartEngineClient = class _SmartEngineClient {
   discovery;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
-    this.baseUrl = validateClientUrl(config.baseUrl, this.allowInsecure);
+    this.baseUrl = validateClientUrl(config.validatorBaseUrl, this.allowInsecure);
     this.http = createHttpClient({
       baseUrl: `${this.baseUrl}/api/v3`,
       apiKey: config.apiKey,
@@ -9307,7 +9309,7 @@ var SmartEngineClient = class _SmartEngineClient {
     const timeoutRaw = env["REQUEST_TIMEOUT"];
     const timeout = timeoutRaw ? Number.parseInt(timeoutRaw, 10) : void 0;
     return new _SmartEngineClient({
-      baseUrl,
+      validatorBaseUrl: baseUrl,
       apiKey: env["VALIDATOR_API_KEY"],
       authToken: env["APP_TOKEN"],
       allowInsecure: env["ALLOW_INSECURE"] === "true",
@@ -9355,90 +9357,21 @@ var SmartEngineClient = class _SmartEngineClient {
       config.metadata
     );
     const client = new _SmartEngineClient({
-      baseUrl: validatorUrl,
+      validatorBaseUrl: validatorUrl,
       authToken: session.token,
       allowInsecure
     });
     return { client, validator, session };
   }
-  /**
-   * Connect to the smart-engines network via the **service-registry**.
-   * Preferred over {@link connectToNetwork} once the validator pods in the
-   * target network have published their cluster endpoints — the SDK
-   * auto-balances across the active cluster set and rides permissionless
-   * cluster join/leave without code edits.
-   *
-   * Resolution ladder:
-   *   1. HTTP fetch `/api/v3/discovery/clusters` from each bootstrap seed.
-   *   2. (Optional) HCS trust-anchor membership cross-check.
-   *   3. Random-pick over the verified set.
-   *
-   * @param config - Seed + auth config. See {@link ClusterConnectionConfig}.
-   * @returns The configured client, the selected cluster, and the auth session.
-   * @throws SmartEngineError 400 if neither `bootstrap` nor `network` is given.
-   * @throws SmartEngineError 503 if no active cluster can be reached.
-   *
-   * @example Zero-config (recommended for smart-app callers)
-   * ```ts
-   * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
-   *   network: 'testnet',          // resolves canonical gateway entrypoint
-   *   chain: 'xrpl',
-   *   address: '...',
-   *   publicKey: '...',
-   *   signFn: async (challenge) => sign(challenge),
-   * });
-   * ```
-   *
-   * @example Custom seeds (private deployments / local dev)
-   * ```ts
-   * const { client, cluster, session } = await SmartEngineClient.connectToCluster({
-   *   bootstrap: ['https://sn1.testnet.hsuite.network', 'https://sn2.testnet.hsuite.network'],
-   *   chain: 'xrpl',
-   *   address: '...',
-   *   publicKey: '...',
-   *   signFn: async (challenge) => sign(challenge),
-   * });
-   * ```
-   */
-  static async connectToCluster(config) {
-    const allowInsecure = config.allowInsecure ?? false;
-    const resolved = await resolveClusterEndpoint({
-      bootstrap: config.bootstrap,
-      network: config.network,
-      allowInsecure,
-      trustAnchor: config.trustAnchor
-    });
-    if (!resolved.ok) {
-      if (resolved.reason === "no-seeds") {
-        throw new SmartEngineError2(
-          "connectToCluster requires either a non-empty `bootstrap` list or a known `network` name.",
-          400
-        );
-      }
-      throw new SmartEngineError2(
-        "No active clusters available via bootstrap seeds. Check bootstrap URLs and network reachability.",
-        503
-      );
-    }
-    const cluster = resolved.cluster;
-    const gatewayUrl = cluster.endpoints.gatewayUrl;
-    validateClientUrl(gatewayUrl, allowInsecure);
-    const auth = new ValidatorAuthClient({ security: { allowInsecure } });
-    const session = await auth.authenticateWithSigner(
-      gatewayUrl,
-      config.chain,
-      config.address,
-      config.publicKey,
-      config.signFn,
-      config.metadata
-    );
-    const client = new _SmartEngineClient({
-      baseUrl: gatewayUrl,
-      authToken: session.token,
-      allowInsecure
-    });
-    return { client, cluster, session };
-  }
+  // NOTE (SDK 4.0 type-fence): the former `SmartEngineClient.connectToCluster`
+  // was REMOVED. It resolved a cluster's `gatewayUrl` and fed it into
+  // `new SmartEngineClient({ baseUrl: gatewayUrl })` — a gateway-pointed
+  // validator-direct client whose raw `/api/v3/*` calls 404 (the raw tier is
+  // un-ingressed at the gateway). That was the footgun. To reach web3 through a
+  // cluster use `BaasClient.connectToCluster({ network })` (the host BaaS tier);
+  // for an explicit in-cluster validator origin use `new SmartEngineClient({
+  // validatorBaseUrl })` or `connectToNetwork` (which resolves a real validator
+  // `apiEndpoint` from the HCS registry, never a gateway URL).
   /** Get the current validator URL */
   getBaseUrl() {
     return this.baseUrl;
@@ -11760,6 +11693,96 @@ var EntitiesClient = class _EntitiesClient {
     const path = filter?.type ? `/api/v3/baas/entities?type=${encodeURIComponent(filter.type)}` : "/api/v3/baas/entities";
     return this.http.get(path);
   }
+  // ─── Value-movement (prepare-bytes only) ──────────────────────────────────
+  //
+  // Each method POSTs the host's entity-scoped value-movement route. The entity
+  // is the source / treasury / authority + fee-payer (resolved server-side from
+  // the entity record — never the body), so a caller can never name a foreign
+  // payer or drain another account. The host authorises the call (session
+  // caller identity + `loadOwnedEntity` ownership), delegates to the validator
+  // preparer, and returns prepared bytes for the caller to sign + submit; the
+  // host never submits and never pays. A rule-deny surfaces as an HTTP 403
+  // `rule_rejected` (use `isRuleRejected`), never as signed bytes.
+  //
+  // `opts` threads {@link HttpCallOptions} (`onBehalfOf` / `customerToken` /
+  // `headers`) so an app-as-proxy can act on behalf of an owner — the owner's
+  // Mode-1 customer-session JWT rides as both `Authorization: Bearer` and
+  // `X-Customer-Session-Claim`, exactly as `agents.execute` does.
+  /**
+   * Prepare a native or token transfer FROM an account entity.
+   *
+   * `POST /api/v3/baas/entities/:entityId/transfer`.
+   */
+  async transfer(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/transfer`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a withdrawal FROM an account entity to a destination.
+   *
+   * `POST /api/v3/baas/entities/:entityId/withdraw`.
+   */
+  async withdraw(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/withdraw`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a token/NFT mint whose supply authority is the account entity.
+   *
+   * `POST /api/v3/baas/entities/:entityId/mint`.
+   */
+  async mint(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/mint`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a token/NFT burn from the account entity's treasury.
+   *
+   * `POST /api/v3/baas/entities/:entityId/burn`.
+   */
+  async burn(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/burn`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare a compliance action (pause / restrict / wipe) on a token whose
+   * compliance authority is the account entity. The body `account` is the
+   * per-account subject for restrict/wipe — never the payer.
+   *
+   * `POST /api/v3/baas/entities/:entityId/compliance`.
+   */
+  async compliance(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/compliance`,
+      body,
+      opts
+    );
+  }
+  /**
+   * Prepare an XRPL TrustSet authorising the account entity to hold a currency
+   * from an issuer.
+   *
+   * `POST /api/v3/baas/entities/:entityId/trustline`.
+   */
+  async trustline(entityId, body, opts) {
+    return this.http.post(
+      `/api/v3/baas/entities/${encodePathParam(entityId)}/trustline`,
+      body,
+      opts
+    );
+  }
 };
 
 // src/baas/client.ts
@@ -11770,13 +11793,6 @@ var BaasClient = class _BaasClient {
   timeout;
   allowInsecure;
   http;
-  /**
-   * Validator-routed HTTP client for the `/api/v3/transactions/*` prepare/execute
-   * surface — a SIBLING of `/host`, NOT under the `pathPrefix`. Rooted at the
-   * raw gateway/ingress origin (`hostUrl`) so transactions reach the validator
-   * even when BaaS traffic is gateway-routed at `/host/*`.
-   */
-  txHttp;
   /** Last HTTP error (for getHttpHealth) */
   lastHttpError;
   /**
@@ -11805,14 +11821,6 @@ var BaasClient = class _BaasClient {
   rules;
   /** Canonical entity authoring surface (token/account/topic/agent + launchpad). */
   entities;
-  /**
-   * Validator-routed transaction prepare/execute (sovereignty model). The
-   * prepare endpoints accept an explicit `payerAccountId` for the session-less
-   * payer path, OR carry the web3-auth session token for the JWT-wallet payer
-   * path (kept in sync with the main client's token — see {@link authenticate}).
-   * Targets `/api/v3/transactions/*`, a sibling of the `/host` BaaS surface.
-   */
-  transactions;
   constructor(config) {
     this.allowInsecure = config.allowInsecure ?? false;
     this.hostUrl = validateUrl2(config.hostUrl, this.allowInsecure);
@@ -11829,11 +11837,6 @@ var BaasClient = class _BaasClient {
       // been called (authContext set). Excludes /api/v3/{,baas/}auth/* (see http client).
       onUnauthorized: () => this.reauthenticate()
     });
-    this.txHttp = createHttpClient({
-      baseUrl: `${this.hostUrl.replace(/\/$/, "")}/api/v3/transactions`,
-      timeout: this.timeout,
-      onUnauthorized: () => this.reauthenticate()
-    });
     const getAppId = () => this.requireAppId();
     this.db = new DatabaseClient(this.http, getAppId);
     this.storage = new StorageClient(this.http, getAppId);
@@ -11844,7 +11847,6 @@ var BaasClient = class _BaasClient {
     this.customerSession = new CustomerSessionClient(baseUrlWithPrefix, this.timeout);
     this.rules = new RulesClient(this.http);
     this.entities = new EntitiesClient(this.http);
-    this.transactions = new TransactionsClient(this.txHttp);
   }
   /**
    * Connect to the Smart Engines BaaS via cluster auto-discovery.
@@ -11992,7 +11994,6 @@ var BaasClient = class _BaasClient {
       throw asBaasError(err);
     }
     this.http.setAuthToken(result.token);
-    this.txHttp.setAuthToken(result.token);
     return result;
   }
   /**
@@ -12018,7 +12019,6 @@ var BaasClient = class _BaasClient {
       publicKey: ctx.publicKey
     });
     this.http.setAuthToken(result.token);
-    this.txHttp.setAuthToken(result.token);
   }
   /** Validate the current session */
   async validateSession() {
@@ -12038,7 +12038,6 @@ var BaasClient = class _BaasClient {
       }
     }
     this.http.setAuthToken(void 0);
-    this.txHttp.setAuthToken(void 0);
   }
   // ========== HTTP Helpers ==========
   requireAuth() {