@hsuite/smart-engines-sdk 3.6.0 → 3.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 3.6.1 — 2026-06-15
+
+### Fixed
+
+- **`SmartGatewayClient.getReadiness()` no longer throws when the gateway is not ready.** The gateway's `/api/v3/ready` now returns **HTTP 503** (was 200) when not ready — honest readiness so load balancers / k8s probes can drain a degraded origin. `getReadiness()` now unwraps that 503: the gateway's global exception filter wraps the body as `{statusCode,error,message,context:{status:'not_ready',...}}` (payload under `context`; a non-filtered server's flat top-level body is also accepted), and the method still **resolves** to a `GatewayReadinessResponse` (`{status:'ready'|'not_ready'}`) in both the ready (200) and not-ready (503) cases. Return shape unchanged; genuine errors (non-readiness 503s, 5xx, network) still throw. (#1114)
+
 ## 3.5.0 — 2026-06-01
 
 **100% prod-ready arc.** Final cleanup pass after the 3.4.x publication. Closes every finding from two rounds of adversarial verification: legacy/dead-API code removed, BaaS dual-transport collapsed onto the shared HttpClient, path-traversal exposure closed via `encodePathParam` repo-wide, typed signer surfaces narrowed off `any`, test coverage taken from 62% → 90% statements / 49% → 81% branches / 64% → 85% functions / 63% → 91% lines, README + compodoc shipped, and one phantom test spec (615 lines that never imported the class it claimed to test) replaced with 43 real tests.

package/dist/index.d.ts

@@ -487,6 +487,30 @@ declare const TokenInfoSchema: z.ZodObject<{
 	circulatingSupply?: string | undefined;
 }>;
 export type TokenInfo = z.infer<typeof TokenInfoSchema>;
+declare const RuleRefSchema: z.ZodObject<{
+	chain: z.ZodEnum<[
+		"hedera",
+		"xrpl",
+		"polkadot",
+		"solana",
+		"stellar",
+		"ethereum",
+		"polygon",
+		"bitcoin",
+		"cardano"
+	]>;
+	topicId: z.ZodString;
+	consensusTimestamp: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+	chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+	topicId: string;
+	consensusTimestamp: string;
+}, {
+	chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+	topicId: string;
+	consensusTimestamp: string;
+}>;
+export type RuleRefInput = z.infer<typeof RuleRefSchema>;
 declare const CreateAccountRequestSchema: z.ZodObject<{
 	chain: z.ZodEnum<[
 		"hedera",
@@ -511,6 +535,30 @@ declare const CreateAccountRequestSchema: z.ZodObject<{
 		"full"
 	]>>;
 	appOwnerPublicKey: z.ZodOptional<z.ZodString>;
+	ruleRef: z.ZodOptional<z.ZodObject<{
+		chain: z.ZodEnum<[
+			"hedera",
+			"xrpl",
+			"polkadot",
+			"solana",
+			"stellar",
+			"ethereum",
+			"polygon",
+			"bitcoin",
+			"cardano"
+		]>;
+		topicId: z.ZodString;
+		consensusTimestamp: z.ZodString;
+	}, "strip", z.ZodTypeAny, {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	}, {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	}>>;
+	entityType: z.ZodOptional<z.ZodString>;
 	metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
 	chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
@@ -524,6 +572,12 @@ declare const CreateAccountRequestSchema: z.ZodObject<{
 	appOwnerPublicKey?: string | undefined;
 	memo?: string | undefined;
 	payerAccountId?: string | undefined;
+	ruleRef?: {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	} | undefined;
+	entityType?: string | undefined;
 }, {
 	chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
 	initialBalance: string;
@@ -536,6 +590,12 @@ declare const CreateAccountRequestSchema: z.ZodObject<{
 	memo?: string | undefined;
 	payerAccountId?: string | undefined;
 	immutable?: boolean | undefined;
+	ruleRef?: {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	} | undefined;
+	entityType?: string | undefined;
 }>;
 export type CreateAccountRequest = z.infer<typeof CreateAccountRequestSchema>;
 declare const CreateAccountResponseSchema: z.ZodObject<{
@@ -694,6 +754,30 @@ declare const CreateTokenRequestSchema: z.ZodObject<{
 	validatorTopicId: z.ZodString;
 	immutable: z.ZodDefault<z.ZodBoolean>;
 	payerAccountId: z.ZodOptional<z.ZodString>;
+	ruleRef: z.ZodOptional<z.ZodObject<{
+		chain: z.ZodEnum<[
+			"hedera",
+			"xrpl",
+			"polkadot",
+			"solana",
+			"stellar",
+			"ethereum",
+			"polygon",
+			"bitcoin",
+			"cardano"
+		]>;
+		topicId: z.ZodString;
+		consensusTimestamp: z.ZodString;
+	}, "strip", z.ZodTypeAny, {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	}, {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	}>>;
+	entityType: z.ZodOptional<z.ZodString>;
 	metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodAny>>;
 }, "strip", z.ZodTypeAny, {
 	symbol: string;
@@ -716,6 +800,12 @@ declare const CreateTokenRequestSchema: z.ZodObject<{
 	initialSupply: string;
 	metadata?: Record<string, any> | undefined;
 	payerAccountId?: string | undefined;
+	ruleRef?: {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	} | undefined;
+	entityType?: string | undefined;
 	treasury?: string | undefined;
 }, {
 	symbol: string;
@@ -738,6 +828,12 @@ declare const CreateTokenRequestSchema: z.ZodObject<{
 	metadata?: Record<string, any> | undefined;
 	payerAccountId?: string | undefined;
 	immutable?: boolean | undefined;
+	ruleRef?: {
+		chain: "hedera" | "xrpl" | "polkadot" | "solana" | "stellar" | "ethereum" | "polygon" | "bitcoin" | "cardano";
+		topicId: string;
+		consensusTimestamp: string;
+	} | undefined;
+	entityType?: string | undefined;
 	treasury?: string | undefined;
 }>;
 export type CreateTokenRequest = z.infer<typeof CreateTokenRequestSchema>;
@@ -2591,6 +2687,8 @@ export type PrepareTransferRequest = {
 	securityMode?: SecurityMode;
 	appOwnerPublicKey?: string;
 	ss58Format?: number;
+	ruleRef?: RuleRefInput;
+	entityType?: string;
 };
 export type PrepareNftMintRequest = {
 	chain: ChainType;
@@ -3818,6 +3916,22 @@ export declare class AgentsClient {
 		success: boolean;
 	}>;
 }
+export type BuildAttestation = {
+	readonly version: "1";
+	readonly appId: string;
+	readonly developerWallet: string;
+	readonly developerChain: ChainType;
+	readonly framework: "ionic" | "nestjs";
+	readonly sdkVersion: string;
+	readonly imageDigest: string;
+	readonly bundleSha256: string;
+	readonly cliVersion: string;
+	readonly builtAt: number;
+};
+export declare function canonicalizeAttestation(att: BuildAttestation): string;
+export declare function computeAttestationHash(att: BuildAttestation): string;
+export declare function signAttestation(att: BuildAttestation, xrplSeed: string): string;
+export declare function verifyAttestation(att: BuildAttestation, signature: string, walletAddress: string): boolean;
 export type BaasService = "auth" | "database" | "storage" | "functions" | "messaging";
 export type BaasSupportedChain = "hedera" | "xrpl" | "polkadot" | "solana";
 export type BaasEndpoints = {
@@ -4146,6 +4260,10 @@ export type BaasDeployRequest = {
 		memory?: string;
 	};
 	strategy?: "rolling" | "recreate";
+	attestation?: {
+		payload: BuildAttestation;
+		signature: string;
+	};
 };
 export type BaasDeployResponse = {
 	appId: string;

package/dist/index.js

@@ -78,11 +78,11 @@ var require_utils = __commonJS({
       u8Array[OriginalBuffer] = buffer;
       return u8Array;
     }
-    var bytesToHex2 = (bytes) => {
+    var bytesToHex3 = (bytes) => {
       const buf = Buffer.from(bytes);
       return buf.toString("hex").toUpperCase();
     };
-    exports.bytesToHex = bytesToHex2;
+    exports.bytesToHex = bytesToHex3;
     var hexToBytes2 = (hex) => {
       if (!shared_1.HEX_REGEX.test(hex)) {
         throw new Error("Invalid hex string");
@@ -479,7 +479,7 @@ var require_lib = __commonJS({
         return Uint8Array.from(res);
       }
     };
-    var createBase58check = (sha2562) => /* @__PURE__ */ chain(checksum(4, (data) => sha2562(sha2562(data))), exports.base58);
+    var createBase58check = (sha2563) => /* @__PURE__ */ chain(checksum(4, (data) => sha2563(sha2563(data))), exports.base58);
     exports.createBase58check = createBase58check;
     exports.base58check = exports.createBase58check;
     var BECH_ALPHABET = /* @__PURE__ */ chain(/* @__PURE__ */ alphabet("qpzry9x8gf2tvdw0s3jn54khce6mua7l"), /* @__PURE__ */ join(""));
@@ -3062,7 +3062,7 @@ var require_weierstrass = __commonJS({
         }
         return { seed, k2sig };
       }
-      function sign(message, secretKey, opts = {}) {
+      function sign2(message, secretKey, opts = {}) {
         message = (0, utils_ts_1.ensureBytes)("message", message);
         const { seed, k2sig } = prepSig(message, secretKey, opts);
         const drbg = (0, utils_ts_1.createHmacDrbg)(hash.outputLen, Fn.BYTES, hmac);
@@ -3096,7 +3096,7 @@ var require_weierstrass = __commonJS({
           return false;
         return sig;
       }
-      function verify(signature, message, publicKey, opts = {}) {
+      function verify2(signature, message, publicKey, opts = {}) {
         const { lowS, prehash, format } = validateSigOpts(opts, defaultSigOpts);
         publicKey = (0, utils_ts_1.ensureBytes)("publicKey", publicKey);
         message = validateMsgAndHash((0, utils_ts_1.ensureBytes)("message", message), prehash);
@@ -3135,8 +3135,8 @@ var require_weierstrass = __commonJS({
         utils,
         lengths,
         Point,
-        sign,
-        verify,
+        sign: sign2,
+        verify: verify2,
         recoverPublicKey,
         Signature,
         hash
@@ -4326,7 +4326,7 @@ var require_edwards = __commonJS({
         const msg = (0, utils_ts_1.concatBytes)(...msgs);
         return modN_LE(cHash(domain(msg, (0, utils_ts_1.ensureBytes)("context", context), !!prehash)));
       }
-      function sign(msg, secretKey, options = {}) {
+      function sign2(msg, secretKey, options = {}) {
         msg = (0, utils_ts_1.ensureBytes)("message", msg);
         if (prehash)
           msg = prehash(msg);
@@ -4341,7 +4341,7 @@ var require_edwards = __commonJS({
         return (0, utils_ts_1._abytes2)(rs, lengths.signature, "result");
       }
       const verifyOpts = { zip215: true };
-      function verify(sig, msg, publicKey, options = verifyOpts) {
+      function verify2(sig, msg, publicKey, options = verifyOpts) {
         const { context, zip215 } = options;
         const len = lengths.signature;
         sig = (0, utils_ts_1.ensureBytes)("signature", sig, len);
@@ -4431,8 +4431,8 @@ var require_edwards = __commonJS({
       return Object.freeze({
         keygen,
         getPublicKey,
-        sign,
-        verify,
+        sign: sign2,
+        verify: verify2,
         utils,
         Point,
         lengths
@@ -5053,7 +5053,7 @@ var require_dist2 = __commonJS({
       return (0, ripple_address_codec_1.encodeSeed)(entropy, type);
     }
     exports.generateSeed = generateSeed;
-    function deriveKeypair(seed, options) {
+    function deriveKeypair2(seed, options) {
       var _a;
       const decoded = (0, ripple_address_codec_1.decodeSeed)(seed);
       const proposedAlgorithm = (_a = options === null || options === void 0 ? void 0 : options.algorithm) !== null && _a !== void 0 ? _a : decoded.type;
@@ -5067,27 +5067,27 @@ var require_dist2 = __commonJS({
       }
       return keypair;
     }
-    exports.deriveKeypair = deriveKeypair;
-    function sign(messageHex, privateKey) {
+    exports.deriveKeypair = deriveKeypair2;
+    function sign2(messageHex, privateKey) {
       const algorithm = (0, getAlgorithmFromKey_1.getAlgorithmFromPrivateKey)(privateKey);
       return getSigningScheme(algorithm).sign((0, utils_1.hexToBytes)(messageHex), privateKey);
     }
-    exports.sign = sign;
-    function verify(messageHex, signature, publicKey) {
+    exports.sign = sign2;
+    function verify2(messageHex, signature, publicKey) {
       const algorithm = (0, getAlgorithmFromKey_1.getAlgorithmFromPublicKey)(publicKey);
       return getSigningScheme(algorithm).verify((0, utils_1.hexToBytes)(messageHex), signature, publicKey);
     }
-    exports.verify = verify;
+    exports.verify = verify2;
     function computePublicKeyHash(publicKeyBytes) {
       return (0, ripemd160_1.ripemd160)((0, sha256_1.sha256)(publicKeyBytes));
     }
     function deriveAddressFromBytes(publicKeyBytes) {
       return (0, ripple_address_codec_1.encodeAccountID)(computePublicKeyHash(publicKeyBytes));
     }
-    function deriveAddress(publicKey) {
+    function deriveAddress2(publicKey) {
       return deriveAddressFromBytes((0, utils_1.hexToBytes)(publicKey));
     }
-    exports.deriveAddress = deriveAddress;
+    exports.deriveAddress = deriveAddress2;
     function deriveNodeAddress(publicKey) {
       const generatorBytes = (0, ripple_address_codec_1.decodeNodePublic)(publicKey);
       const accountPublicBytes = (0, utils_2.accountPublicFromPublicGenerator)(generatorBytes);
@@ -5643,6 +5643,14 @@ var PreparedTransactionSovereigntySchema = zod.z.discriminatedUnion("mode", [
     authorizationSet: PreparedTransactionAuthorizationSetSchema.optional()
   })
 ]);
+var RuleRefSchema = zod.z.object({
+  /** Chain whose HCS the rule was published on (canonically 'hedera'). */
+  chain: ChainTypeSchema,
+  /** HCS topic ID the rule message was published to. */
+  topicId: zod.z.string().min(1),
+  /** HCS consensus timestamp of the rule message. */
+  consensusTimestamp: zod.z.string().min(1)
+});
 var CreateAccountRequestSchema = zod.z.object({
   chain: ChainTypeSchema,
   initialBalance: zod.z.string(),
@@ -5682,6 +5690,22 @@ var CreateAccountRequestSchema = zod.z.object({
    * The owner key + TSS network key form a threshold-2 multi-sig.
    */
   appOwnerPublicKey: zod.z.string().optional(),
+  /**
+   * The entity's canonical `ruleRef` (HCS pointer to its `ValidatorRules`). When
+   * present, the chain adapter stamps the IMMUTABLE creation-tx rule anchor
+   * (`rule:<topicId>@<consensusTimestamp>:<entityType>`) — distinct from the
+   * mutable validator-binding memo — so the sign-gate resolves the rule on-chain
+   * (kind:'ref') rather than trusting the replicated binding
+   * (RFC 2026-06-15-onchain-rule-anchor §6.1). Absent ⇒ the degraded
+   * `rule:bootstrap:<entityType>` marker when `entityType` is supplied.
+   */
+  ruleRef: RuleRefSchema.optional(),
+  /**
+   * Entity-type tag stamped into the rule anchor (e.g. 'wallet', 'account').
+   * Supply it to enable the on-chain anchor; omit for the prior memo-less
+   * (legacy) behaviour.
+   */
+  entityType: zod.z.string().min(1).optional(),
   metadata: zod.z.record(zod.z.any()).optional()
 });
 zod.z.object({
@@ -5769,6 +5793,21 @@ var CreateTokenRequestSchema = zod.z.object({
   immutable: zod.z.boolean().default(true),
   /** See CreateAccountRequestSchema.payerAccountId — same resolution rules. */
   payerAccountId: zod.z.string().optional(),
+  /**
+   * The entity's canonical `ruleRef` (HCS pointer to its `ValidatorRules`). When
+   * present, the chain adapter stamps the IMMUTABLE creation-tx rule anchor
+   * (`rule:<topicId>@<consensusTimestamp>:<entityType>`) — distinct from the
+   * mutable validator-binding token memo — so the sign-gate resolves the rule
+   * on-chain (kind:'ref') rather than trusting the replicated binding
+   * (RFC 2026-06-15-onchain-rule-anchor §6.1). Absent ⇒ the degraded
+   * `rule:bootstrap:<entityType>` marker when `entityType` is supplied.
+   */
+  ruleRef: RuleRefSchema.optional(),
+  /**
+   * Entity-type tag stamped into the rule anchor (e.g. 'token'). Supply it to
+   * enable the on-chain anchor; omit for the prior memo-less behaviour.
+   */
+  entityType: zod.z.string().min(1).optional(),
   metadata: zod.z.record(zod.z.any()).optional()
 });
 zod.z.object({
@@ -9688,11 +9727,28 @@ var SmartGatewayClient = class {
     return this.http.get("/status");
   }
   /**
-   * Check gateway readiness. Returns either `{ status: 'ready', ... }` with
-   * a verified host count or `{ status: 'not_ready', reason, ... }`.
+   * Check gateway readiness. Resolves to either `{ status: 'ready', ... }`
+   * with a verified host count or `{ status: 'not_ready', reason, ... }`.
+   *
+   * NOTE: `/api/v3/ready` returns **HTTP 503** when not ready (so load
+   * balancers / k8s probes drain the origin). This method unwraps that 503's
+   * body and still RESOLVES to a `GatewayReadinessResponse` — it does not
+   * throw for a not-ready gateway. Genuine errors (non-readiness 503s, 5xx,
+   * network) still throw.
    */
   async getReadiness() {
-    return this.http.get("/ready");
+    try {
+      return await this.http.get("/ready");
+    } catch (err) {
+      if (err instanceof SdkHttpError && err.statusCode === 503) {
+        const d = err.details;
+        const body = d?.context ?? d;
+        if (body?.status === "not_ready") {
+          return body;
+        }
+      }
+      throw err;
+    }
   }
   /** Check gateway liveness. */
   async getLiveness() {
@@ -11436,6 +11492,49 @@ async function verifyPqcEnvelope(envelope, options = {}) {
   }
   return { valid: true, version, details };
 }
+var { deriveKeypair, deriveAddress, sign, verify } = require_dist2();
+function canonicalizeAttestation(att) {
+  return JSON.stringify(att, Object.keys(att).sort());
+}
+function computeAttestationHash(att) {
+  const canonical = canonicalizeAttestation(att);
+  const digest = sha256.sha256(new TextEncoder().encode(canonical));
+  return bytesToHex2(digest);
+}
+function signAttestation(att, xrplSeed) {
+  const { publicKey, privateKey } = deriveKeypair(xrplSeed);
+  const messageHex = attestationMessageHex(att);
+  const signature = sign(messageHex, privateKey);
+  return `${publicKey}.${signature}`;
+}
+function verifyAttestation(att, signature, walletAddress) {
+  try {
+    const sep = signature.indexOf(".");
+    if (sep <= 0 || sep === signature.length - 1) {
+      return false;
+    }
+    const publicKey = signature.slice(0, sep);
+    const sigHex = signature.slice(sep + 1);
+    if (deriveAddress(publicKey) !== walletAddress) {
+      return false;
+    }
+    const messageHex = attestationMessageHex(att);
+    return verify(messageHex, sigHex, publicKey);
+  } catch {
+    return false;
+  }
+}
+function attestationMessageHex(att) {
+  const hash = computeAttestationHash(att);
+  return Buffer.from(hash, "utf-8").toString("hex").toUpperCase();
+}
+function bytesToHex2(bytes) {
+  let s = "";
+  for (let i = 0; i < bytes.length; i++) {
+    s += bytes[i].toString(16).padStart(2, "0");
+  }
+  return s;
+}
 
 // src/rules/atoms/index.ts
 var atom = {
@@ -12940,7 +13039,9 @@ exports.atom = atom;
 exports.auth = auth_exports;
 exports.baas = baas_exports;
 exports.bridge = bridge_exports;
+exports.canonicalizeAttestation = canonicalizeAttestation;
 exports.chains = chains_exports;
+exports.computeAttestationHash = computeAttestationHash;
 exports.createHttpClient = createHttpClient;
 exports.createResilientFetchWithBreaker = createResilientFetchWithBreaker;
 exports.createXrplWeb3Signer = createXrplWeb3Signer;
@@ -12974,6 +13075,7 @@ exports.resilientFetch = resilientFetch;
 exports.resolveNetwork = resolveNetwork;
 exports.resources = resources_exports;
 exports.settlement = settlement_exports;
+exports.signAttestation = signAttestation;
 exports.simpleAMM = simpleAMM;
 exports.simpleStaking = simpleStaking;
 exports.soulboundNft = soulboundNft;
@@ -12989,6 +13091,7 @@ exports.utilityToken = utilityToken;
 exports.validate = validate;
 exports.validateAgentRules = validateAgentRules;
 exports.validateEnvelopeSchema = validateEnvelopeSchema;
+exports.verifyAttestation = verifyAttestation;
 exports.verifyPqcAttestation = verifyPqcAttestation;
 exports.verifyPqcEnvelope = verifyPqcEnvelope;
 exports.vestingSchedule = vestingSchedule;