@hazbase/simplicity 0.0.3 → 0.0.5

package/README.md

@@ -134,6 +134,212 @@ simplicity-cli definition verify \
 
 For a bond-oriented walkthrough, see [docs/definitions/README.md](./docs/definitions/README.md).
 
+## Trusted Issuance State JSON
+
+The same hash-anchor model now also applies to issuance state documents such as a bond issuance record.
+
+This is useful when you want to say not only:
+
+- "these are the bond terms,"
+
+but also:
+
+- "this bond was issued in this amount, with this outstanding principal, under this controller."
+
+The SDK now supports:
+
+- loading and hashing a state JSON with `sdk.loadStateDocument(...)`,
+- storing its hash in the artifact,
+- committing `STATE_HASH` into custom `.simf` contract logic,
+- verifying later that the issuance state JSON still matches the compiled contract.
+
+For Bond issuance, the recommended shape is:
+
+```json
+{
+  "issuanceId": "BOND-2026-001-ISSUE-1",
+  "bondId": "BOND-2026-001",
+  "issuerEntityId": "hazbase-treasury",
+  "issuedPrincipal": 1000000,
+  "outstandingPrincipal": 1000000,
+  "redeemedPrincipal": 0,
+  "currencyAssetId": "bitcoin",
+  "controllerXonly": "<xonly>",
+  "issuedAt": "2026-03-10T00:00:00Z",
+  "status": "ISSUED"
+}
+```
+
+To move from an issued bond into a redemption state, the SDK now also supports a minimal state transition model:
+
+- `ISSUED -> PARTIALLY_REDEEMED`
+- `ISSUED/PARTIALLY_REDEEMED -> REDEEMED`
+
+The next state records:
+
+- `previousStateHash`
+- `lastTransition.type`
+- `lastTransition.amount`
+- `lastTransition.at`
+
+and the SDK verifies the principal invariant:
+
+- `issuedPrincipal = outstandingPrincipal + redeemedPrincipal`
+
+On top of that, the SDK can now build a `BondSettlementDescriptor`, which bundles the intended settlement envelope into one canonical document:
+
+- `definitionHash`
+- `previousStateHash`
+- `nextStateHash`
+- `nextContractAddress`
+- `nextAmountSat`
+- `maxFeeSat`
+- status progression and principal deltas
+
+The redemption machine commits that settlement descriptor hash as an additional anchor. This does not yet mean full runtime output introspection, but it does mean the machine can now honestly claim a committed settlement envelope instead of just a scattered set of fields.
+
+Minimal TypeScript flow:
+
+```ts
+const compiled = await sdk.bonds.defineBond({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  issuancePath: "./docs/definitions/bond-issuance-state.json",
+  simfPath: "./docs/definitions/bond-issuance-anchor.simf",
+  artifactPath: "./bond-issuance.artifact.json",
+});
+
+const verification = await sdk.bonds.verifyBond({
+  artifactPath: "./bond-issuance.artifact.json",
+  definitionPath: "./docs/definitions/bond-definition.json",
+  issuancePath: "./docs/definitions/bond-issuance-state.json",
+});
+
+console.log(verification.crossChecks.principalInvariantValid);
+console.log(verification.issuance.trust.effectiveMode);
+```
+
+Minimal redemption flow:
+
+```ts
+const preview = await sdk.bonds.buildBondRedemption({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
+  amount: 250000,
+  redeemedAt: "2027-03-10T00:00:00Z",
+});
+
+const compiled = await sdk.bonds.redeemBond({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
+  amount: 250000,
+  redeemedAt: "2027-03-10T00:00:00Z",
+  simfPath: "./docs/definitions/bond-issuance-anchor.simf",
+  artifactPath: "./bond-redemption.artifact.json",
+});
+
+const transition = await sdk.bonds.verifyBondTransition({
+  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
+  nextIssuancePath: "./docs/definitions/bond-issuance-state-partial-redemption.json",
+});
+
+const payload = await sdk.bonds.buildBondPayload({
+  artifactPath: "./bond-redemption.artifact.json",
+  definitionPath: "./docs/definitions/bond-definition.json",
+  issuancePath: "./docs/definitions/bond-issuance-state-partial-redemption.json",
+});
+
+const transitionPayload = await sdk.bonds.buildBondTransitionPayload({
+  definitionPath: "./docs/definitions/bond-definition.json",
+  previousIssuancePath: "./docs/definitions/bond-issuance-state.json",
+  nextIssuancePath: "./docs/definitions/bond-issuance-state-partial-redemption.json",
+});
+
+console.log(preview.nextHash);
+console.log(compiled.state()?.hash);
+console.log(transition.transition.statusProgressionValid);
+console.log(payload.payload);
+console.log(transitionPayload.payload.redeemAmount);
+```
+
+CLI equivalents:
+
+```bash
+simplicity-cli state show \
+  --type bond-issuance \
+  --id BOND-2026-001-ISSUE-1 \
+  --json-path ./docs/definitions/bond-issuance-state.json
+
+simplicity-cli state verify \
+  --artifact ./bond-issuance.artifact.json \
+  --type bond-issuance \
+  --id BOND-2026-001-ISSUE-1 \
+  --json-path ./docs/definitions/bond-issuance-state.json
+
+simplicity-cli bond verify \
+  --artifact ./bond-issuance.artifact.json \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --issuance-json ./docs/definitions/bond-issuance-state.json
+
+simplicity-cli bond redeem \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --amount 250000 \
+  --redeemed-at 2027-03-10T00:00:00Z \
+  --simf ./docs/definitions/bond-issuance-anchor.simf \
+  --next-issuance-out ./next-bond-issuance-state.json \
+  --artifact ./bond-redemption.artifact.json
+
+simplicity-cli bond verify-transition \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
+
+simplicity-cli bond compile-transition \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
+  --simf ./docs/definitions/bond-redemption-transition.simf \
+  --artifact ./bond-transition.artifact.json
+
+simplicity-cli bond compile-redemption-machine \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
+  --simf ./docs/definitions/bond-redemption-state-machine.simf \
+  --artifact ./bond-redemption-machine.artifact.json
+
+simplicity-cli bond verify-machine \
+  --artifact ./bond-redemption-machine.artifact.json \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
+
+simplicity-cli bond plan-rollover \
+  --current-artifact ./bond-issuance.artifact.json \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
+  --next-simf ./docs/definitions/bond-issuance-anchor.simf \
+  --next-artifact ./bond-next.artifact.json
+
+simplicity-cli bond plan-machine-rollover \
+  --current-artifact ./bond-issuance.artifact.json \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json \
+  --machine-simf ./docs/definitions/bond-redemption-state-machine.simf \
+  --machine-artifact ./bond-redemption-machine.artifact.json
+
+simplicity-cli bond transition-payload \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --previous-issuance-json ./docs/definitions/bond-issuance-state.json \
+  --next-issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
+
+simplicity-cli bond payload \
+  --artifact ./bond-redemption.artifact.json \
+  --definition-json ./docs/definitions/bond-definition.json \
+  --issuance-json ./docs/definitions/bond-issuance-state-partial-redemption.json
+```
+
 ## Install
 
 You need three things:
@@ -811,6 +1017,19 @@ These examples are included to help you jump to the right workflow quickly.
 - [gasless-transfer.ts](./examples/gasless-transfer.ts): standard relayer-backed gasless L-BTC transfer.
 - [define-bond.ts](./examples/define-bond.ts): compile a bond example with a trusted definition hash anchor.
 - [show-bond-definition.ts](./examples/show-bond-definition.ts): verify and retrieve a trusted bond definition from JSON + artifact.
+- [define-bond-issuance.ts](./examples/define-bond-issuance.ts): compile a bond example with both trusted definition and issuance state anchors.
+- [show-bond-issuance.ts](./examples/show-bond-issuance.ts): load a bond artifact together with its verified issuance state.
+- [verify-bond-issuance.ts](./examples/verify-bond-issuance.ts): run combined Bond definition/state verification and invariant checks.
+- [redeem-bond-issuance.ts](./examples/redeem-bond-issuance.ts): build the next redemption state and compile a new anchored artifact.
+- [verify-bond-transition.ts](./examples/verify-bond-transition.ts): verify a previous/next issuance state transition.
+- [compile-bond-transition.ts](./examples/compile-bond-transition.ts): compile a transition contract that commits both previous and next issuance state hashes.
+- [compile-bond-redemption-machine.ts](./examples/compile-bond-redemption-machine.ts): compile a redemption transition contract that also commits redeem amount and transition kind.
+- [verify-bond-redemption-machine.ts](./examples/verify-bond-redemption-machine.ts): verify a compiled redemption machine artifact against definition, previous state, and next state inputs.
+- [plan-bond-rollover.ts](./examples/plan-bond-rollover.ts): build a runtime rollover plan that spends the current state UTXO into the next state's contract address.
+- [show-bond-transition-payload.ts](./examples/show-bond-transition-payload.ts): emit a bridge-ready payload for a previous/next redemption transition.
+- [show-bond-payload.ts](./examples/show-bond-payload.ts): emit a bridge-ready payload from a verified bond artifact.
+- [redeem-bond-issuance.ts](./examples/redeem-bond-issuance.ts): build a partially redeemed bond issuance state and anchor it in a new artifact.
+- [verify-bond-transition.ts](./examples/verify-bond-transition.ts): verify a redemption transition between two issuance state documents.
 
 In addition to the in-repo examples, the package has also been validated from a blank external consumer project with:
 - `npm install @hazbase/simplicity`
@@ -843,6 +1062,16 @@ When you compile with `definition: { ... }`, the artifact also carries:
 
 That is what allows the SDK and CLI to verify that an off-chain JSON definition still matches the contract you compiled.
 
+When you also compile with `state: { ... }`, the artifact can additionally carry:
+- `stateType`
+- `stateId`
+- `schemaVersion`
+- `hash`
+- `trustMode`
+- `anchorMode`
+
+That is what allows the SDK and CLI to verify that an off-chain issuance state document still matches the contract you compiled.
+
 ### When should I use a preset instead of a custom `.simf` file?
 
 Use a preset first when you are learning the lifecycle or your use case already matches a built-in contract. Move to custom `.simf` when your business rules are app-specific.