@hsuite/smart-engines-sdk 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -1,5 +1,121 @@
 # Changelog
 
+## 3.3.0 — 2026-05-29
+
+**Smart-App Rules SDK arc.** Adds a complete canonical-rule authoring surface
+so smart-app devs can compose, locally validate, publish, and reference
+canonical `ValidatorRules` from a single SDK — the prerequisite for entity
+creation since the cluster requires a `ruleRef` on every binding.
+
+No breaking changes. Bundle grows ~260 KB (vendored Zod schemas mirroring
+`libs/shared/src/dto/validator.dto.ts` + builder/composer/template factories).
+`sideEffects: false` added — tree-shaking excludes any sub-namespace a
+consumer doesn't import.
+
+### Added — `Rules` namespace (`import { Rules } from '@hsuite/smart-engines-sdk'`)
+
+- **Fluent builders** — `Rules.forToken()` / `.forAccount()` / `.forTopic()` /
+  `.forAgent()` with shared `withSecurity` / `withController` / `withOperations` /
+  `withTokenGates` / `withGovernance` / `withInvariants` / `withMetadata` /
+  `addModule` / `build()` flow. Throws `RuleBuildError` with dot-path messages
+  on schema failure.
+- **Composer factories** — 100% coverage of `libs/rules-engine`:
+  - `Rules.atom.*` — 17 atoms (timeRange, limits, permissionList, rateLimiter,
+    cooldown, approvalThreshold, approvedPairs, tradeLimit, snapshot,
+    cronSchedule, countApproval, externalEvidence, fieldValues,
+    registryReference, schemaValidation, stopLoss, workflowState)
+  - `Rules.molecule.*` — 6 molecules (tokenGate, swap, airdrop, vesting,
+    streaming, governance)
+  - `Rules.module.*` — 5 organism wrappers as canonical `ModuleEntry`
+    (launchpad, stakingPool, dao, dex, agent)
+- **Templates** — 8 one-call factories producing schema-conformant rules:
+  `Rules.template.fairLaunch`, `tieredIDO`, `simpleStaking`, `tokenDAO`,
+  `multisigDAO`, `simpleAMM`, `vestingSchedule`, `tradingAgent`.
+- **Preflight** — `Rules.validate(rule)` routes by `type` discriminator for
+  path-rich error messages (`operations.mint.enabled: Expected boolean`).
+- **Vendored Zod schemas** — `ValidatorRulesSchema`, `TokenValidatorRulesSchema`,
+  `AccountValidatorRulesSchema`, `TopicValidatorRulesSchema`,
+  `AgentValidatorRulesSchema`, plus every sub-schema (governance, invariants,
+  modules, payloadSchema, soulbound, etc.). Mirrors `libs/shared` verbatim;
+  re-vendor on schema upgrades.
+
+### Added — `BaasClient` sub-clients
+
+- **`baas.rules: RulesClient`** — publish a canonical rule and get back a
+  cluster-stamped `ruleRef`:
+  - `publish(rule)` → `{ ruleRef: { chain, topicId, consensusTimestamp } }`
+  - `get(consensusTimestamp)` → `PublishedRule`
+  - `listByOwner({ type? })` → `{ rules, count }`
+  - `simulate({ ruleRef? | rule?, action, context })` → `ValidationResult`
+  - `getVersionHistory(consensusTimestamp)` → `{ versions }`
+  - `deprecate(consensusTimestamp)` → `{ deprecated: true, consensusTimestamp }`
+- **`baas.entities: EntitiesClient`** — ruleRef-gated entity creation. The
+  cluster's mandatory creation gate enforces that every entity references a
+  published rule:
+  - `createToken({ chain, name, symbol, decimals?, initialSupply?, ruleRef, memo? })`
+  - `createAccount({ chain, ruleRef, initialBalance?, publicKey? })`
+  - `createTopic({ chain, ruleRef, memo? })`
+  - `createAgent({ primaryChain, ruleRef, name, agentType? })`
+  - `launchpad({ chain, name, symbol, launchpad })` — mega-helper: publishes
+    a token rule with a `launchpad` ModuleEntry attached + creates the token
+    entity referencing the new ruleRef. Single round-trip.
+  - `get(entityId)` → `EntityInfo`
+  - `listByOwner({ type? })` → `{ entities, count }`
+
+### Added — NestJS providers (subpath: `@hsuite/smart-engines-sdk/nestjs`)
+
+`SmartEngineModule.forRoot` / `.forRootAsync` now expose three injection
+tokens consumers can `@Inject(...)`:
+
+- `SDK_BAAS_CLIENT` — shared `BaasClient` instance
+- `RULES_CLIENT` — `RulesClient` (alias for `baasClient.rules`)
+- `ENTITIES_CLIENT` — `EntitiesClient` (alias for `baasClient.entities`)
+
+```ts
+class MyService {
+  constructor(
+    @Inject(RULES_CLIENT)    private readonly rules:    RulesClient,
+    @Inject(ENTITIES_CLIENT) private readonly entities: EntitiesClient,
+  ) {}
+}
+```
+
+`SmartEngineService` provider unchanged.
+
+### Documentation
+
+- Package README extended with a `## Rules — author + publish canonical
+  ValidatorRules` section, two new rows in the "Available clients" table,
+  and a pointer to the full developer guide.
+- Complete developer guide added at
+  `docs/developers/libs/rules-engine.md#smart-app-sdk-guide` — covers
+  authoring paths, composer reference tables, publish + entity-create
+  end-to-end flow, `baas.rules.*` + `baas.entities.*` reference, and 7
+  common pitfalls.
+
+### Cluster-side (FYI for SDK consumers — not in this package)
+
+This SDK release lights up server-side endpoints already shipped on the
+`smart-engines-multichain` cluster:
+
+- Smart-host: `POST /api/rules/publish`, `GET /api/rules/:ts`,
+  `GET /api/rules` (listByOwner), `POST /api/rules/simulate`,
+  `GET /api/rules/:ts/versions`, `POST /api/rules/:ts/deprecate`,
+  `POST /api/entities/{createToken|createAccount|createTopic|createAgent|launchpad}`,
+  `GET /api/entities/:id`, `GET /api/entities` (PRs #949, #950).
+- Smart-validator: `POST /api/v3/entities/create` wrapping
+  `EntityCreationOrchestrator.createMultisigEntity` for cluster-internal
+  service-mesh calls from smart-host (PR #956).
+
+### Build
+
+- tsup CJS bundle: `dist/index.js` 396 KB, `dist/nestjs/index.js` 326 KB,
+  `dist/pqc-verify/index.js` 8 KB.
+- `dts-bundle-generator` outputs preserved for all three subpaths.
+- `sideEffects: false` declared so consumers can tree-shake unused
+  sub-namespaces (`baas.rules` excludable if you don't use canonical rules,
+  etc.).
+
 ## 3.2.1 — 2026-05-16
 
 **Documentation-only fix.** No runtime behavior change.

package/README.md

@@ -88,6 +88,8 @@ from the dev wallet used to authenticate.
 | Client | Purpose |
 |---|---|
 | `BaasClient` | Authentication + database + storage + functions + messaging + deployment + agents |
+| `baas.rules.*` | Publish / get / list / simulate / deprecate canonical `ValidatorRules` documents on HCS |
+| `baas.entities.*` | Create canonical token / account / topic / agent entities (plus launchpad mega-helper), each bound to a published `ruleRef` |
 | `SmartEngineClient` | Chain operations: account create, token create / mint / burn / freeze / wipe, transfers, HCS topics, TSS, IPFS |
 | `SmartGatewayClient` | Gateway operations: routing, domains, DNS |
 | `ValidatorAuthClient` | Standalone Web3 challenge-response auth (lower-level than `BaasClient.authenticate`) |
@@ -100,6 +102,55 @@ the cluster gateway. Set `pathPrefix: ''` for direct host access.
 
 ---
 
+## Rules — author + publish canonical ValidatorRules
+
+`ValidatorRules` are the canonical, HCS-pinned policy documents the cluster
+quorum evaluates before signing any entity action (mint, burn, transfer,
+trade, …). Smart-apps author rules locally (via templates or a fluent
+builder), publish them to HCS via `baas.rules.publish`, and bind the
+returned `ruleRef` into the entity at creation time via `baas.entities.*`.
+Every action against the entity is then rules-checked + TSS-signed.
+
+```ts
+import { BaasClient, Rules } from '@hsuite/smart-engines-sdk';
+
+// Template — opinionated fair-launch token with all knobs pre-set.
+const rule = Rules.template.fairLaunch({
+  maxSupply: '1000000000',
+  mintWindow: { startsAt: '2026-06-01T00:00:00Z', endsAt: '2026-06-08T00:00:00Z' },
+});
+
+const { ruleRef } = await baas.rules.publish(rule);
+
+const token = await baas.entities.createToken({
+  chain: 'hedera',
+  name: 'Fair Launch Token',
+  symbol: 'FAIR',
+  decimals: 6,
+  ruleRef,
+});
+```
+
+```ts
+// Fluent builder — when you want to compose the rule yourself.
+const rule = Rules.forToken()
+  .withSecurity('full')                            // 'none' | 'partial' | 'full'
+  .withOperations({
+    mint: { enabled: true, limits: { dailyLimit: '1000000' } },
+    burn: { enabled: true },
+  })
+  .withInvariants({ maxSupply: '1000000000' })
+  .build();
+
+const { ruleRef } = await baas.rules.publish(rule);
+const sim = await baas.rules.simulate({ ruleRef, action: 'mint', context: { amount: '500' } });
+// sim.isValid === true | false (+ reason)
+```
+
+Full reference: [Smart-App SDK Guide](../../docs/developers/libs/rules-engine.md#smart-app-sdk-guide)
+
+---
+
 ## BaaS sub-clients
 
 Once authenticated, every BaaS sub-client is reachable from a single