@ottochain/sdk 2.2.5 → 2.4.0

package/dist/esm/apps/contracts/index.js

@@ -6,7 +6,7 @@
  * @example
  * ```typescript
  * import {
- *   ContractState,
+ *   State,
  *   Contract,
  *   getContractDefinition,
  *   CONTRACTS_DEFINITIONS
@@ -18,8 +18,12 @@
  *
  * @packageDocumentation
  */
-// Re-export generated protobuf types (source of truth)
-export { ContractState, Contract, ProposeContractRequest, AcceptContractRequest, CompleteContractRequest, RejectContractRequest, DisputeContractRequest, ContractDefinition, contractStateFromJSON, contractStateToJSON, } from "../../generated/ottochain/apps/contracts/v1/contract.js";
+// Re-export generated protobuf types (source of truth).
+// The nested lifecycle enum dropped its app prefix in the proto; under this
+// app-scoped entrypoint it is unambiguously State.
+export { State, Contract, ProposeContractRequest, AcceptContractRequest, CompleteContractRequest, RejectContractRequest, DisputeContractRequest, ContractDefinition, stateFromJSON, stateToJSON, } from "../../generated/ottochain/apps/contracts/v1/contract.js";
+// Deprecated app-prefixed alias (renamed to State); kept for compat.
+export { State as ContractState, stateFromJSON as contractStateFromJSON, stateToJSON as contractStateToJSON, } from "../../generated/ottochain/apps/contracts/v1/contract.js";
 // ---------------------------------------------------------------------------
 // State Machine Definitions (generated from JSON at build time)
 // ---------------------------------------------------------------------------

package/dist/esm/apps/contracts/state-machines/contract-agreement.js

@@ -1,4 +1,5 @@
 import { defineFiberApp } from "../../../schema/fiber-app.js";
+import { signerIsParty, signerIsAnyParty } from "../../../schema/guards.js";
 /**
  * Two-party agreement with mutual completion attestation and dispute resolution.
  */
@@ -33,7 +34,7 @@ export const contractAgreementDef = defineFiberApp({
         },
     },
     createSchema: {
-        required: ["proposer", "counterparty"],
+        required: ["proposer", "counterparty", "arbitrator"],
         properties: {
             proposer: {
                 type: "address",
@@ -45,6 +46,11 @@ export const contractAgreementDef = defineFiberApp({
                 description: "DAG address of the counterparty",
                 immutable: true,
             },
+            arbitrator: {
+                type: "address",
+                description: "DAG address of the arbitrator authorized to resolve a dispute",
+                immutable: true,
+            },
         },
     },
     stateSchema: {
@@ -52,6 +58,7 @@ export const contractAgreementDef = defineFiberApp({
             status: { type: "string" },
             proposer: { type: "address" },
             counterparty: { type: "address" },
+            arbitrator: { type: "address", immutable: true },
             completions: { type: "array" },
             acceptedAt: { type: "integer", nullable: true },
             rejectedAt: { type: "integer", nullable: true },
@@ -75,21 +82,66 @@ export const contractAgreementDef = defineFiberApp({
         dispute: { properties: { reason: { type: "string" } } },
         resolve: {
             properties: {
-                judicialRuling: { type: "boolean", nullable: true },
-                proposerApproves: { type: "boolean", nullable: true },
-                counterpartyApproves: { type: "boolean", nullable: true },
                 resolution: { type: "string" },
                 rulingId: { type: "string", nullable: true },
             },
         },
     },
     states: {
-        PROPOSED: { id: "PROPOSED", isFinal: false, metadata: null },
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        COMPLETED: { id: "COMPLETED", isFinal: true, metadata: null },
-        DISPUTED: { id: "DISPUTED", isFinal: false, metadata: null },
-        REJECTED: { id: "REJECTED", isFinal: true, metadata: null },
-        CANCELLED: { id: "CANCELLED", isFinal: true, metadata: null },
+        PROPOSED: {
+            id: "PROPOSED",
+            isFinal: false,
+            metadata: {
+                label: "Proposed",
+                description: "Agreement proposed; awaiting the counterparty",
+                category: "initial",
+            },
+        },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Agreement accepted and in effect",
+                category: "active",
+            },
+        },
+        COMPLETED: {
+            id: "COMPLETED",
+            isFinal: true,
+            metadata: {
+                label: "Completed",
+                description: "Agreement completed and attested (terminal)",
+                category: "terminal",
+            },
+        },
+        DISPUTED: {
+            id: "DISPUTED",
+            isFinal: false,
+            metadata: {
+                label: "Disputed",
+                description: "A party has raised a dispute; awaiting resolution",
+                category: "pending",
+            },
+        },
+        REJECTED: {
+            id: "REJECTED",
+            isFinal: true,
+            metadata: {
+                label: "Rejected",
+                description: "Proposal rejected by the counterparty (terminal)",
+                category: "terminal",
+            },
+        },
+        CANCELLED: {
+            id: "CANCELLED",
+            isFinal: true,
+            metadata: {
+                label: "Cancelled",
+                description: "Agreement cancelled before completion (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "PROPOSED",
     transitions: [
@@ -97,11 +149,11 @@ export const contractAgreementDef = defineFiberApp({
             from: "PROPOSED",
             to: "ACTIVE",
             eventName: "accept",
-            guard: { "===": [{ var: "event.agent" }, { var: "state.counterparty" }] },
+            guard: signerIsParty("state.counterparty"),
             effect: {
                 merge: [
                     { var: "state" },
-                    { status: "ACTIVE", acceptedAt: { var: "$timestamp" } },
+                    { status: "ACTIVE", acceptedAt: { var: "$ordinal" } },
                 ],
             },
             dependencies: [],
@@ -110,13 +162,13 @@ export const contractAgreementDef = defineFiberApp({
             from: "PROPOSED",
             to: "REJECTED",
             eventName: "reject",
-            guard: { "===": [{ var: "event.agent" }, { var: "state.counterparty" }] },
+            guard: signerIsParty("state.counterparty"),
             effect: {
                 merge: [
                     { var: "state" },
                     {
                         status: "REJECTED",
-                        rejectedAt: { var: "$timestamp" },
+                        rejectedAt: { var: "$ordinal" },
                         rejectReason: { var: "event.reason" },
                     },
                 ],
@@ -127,11 +179,11 @@ export const contractAgreementDef = defineFiberApp({
             from: "PROPOSED",
             to: "CANCELLED",
             eventName: "cancel",
-            guard: { "===": [{ var: "event.agent" }, { var: "state.proposer" }] },
+            guard: signerIsParty("state.proposer"),
             effect: {
                 merge: [
                     { var: "state" },
-                    { status: "CANCELLED", cancelledAt: { var: "$timestamp" } },
+                    { status: "CANCELLED", cancelledAt: { var: "$ordinal" } },
                 ],
             },
             dependencies: [],
@@ -142,14 +194,7 @@ export const contractAgreementDef = defineFiberApp({
             eventName: "submit_completion",
             guard: {
                 and: [
-                    {
-                        or: [
-                            { "===": [{ var: "event.agent" }, { var: "state.proposer" }] },
-                            {
-                                "===": [{ var: "event.agent" }, { var: "state.counterparty" }],
-                            },
-                        ],
-                    },
+                    signerIsAnyParty(["state.proposer", "state.counterparty"]),
                     {
                         "!": [
                             {
@@ -173,7 +218,7 @@ export const contractAgreementDef = defineFiberApp({
                                     {
                                         agent: { var: "event.agent" },
                                         proof: { var: "event.proof" },
-                                        submittedAt: { var: "$timestamp" },
+                                        submittedAt: { var: "$ordinal" },
                                     },
                                 ],
                             ],
@@ -187,11 +232,11 @@ export const contractAgreementDef = defineFiberApp({
             from: "ACTIVE",
             to: "COMPLETED",
             eventName: "finalize",
-            guard: { ">=": [{ size: { var: "state.completions" } }, 2] },
+            guard: { ">=": [{ length: [{ var: "state.completions" }] }, 2] },
             effect: {
                 merge: [
                     { var: "state" },
-                    { status: "COMPLETED", completedAt: { var: "$timestamp" } },
+                    { status: "COMPLETED", completedAt: { var: "$ordinal" } },
                 ],
             },
             dependencies: [],
@@ -200,18 +245,13 @@ export const contractAgreementDef = defineFiberApp({
             from: "ACTIVE",
             to: "DISPUTED",
             eventName: "dispute",
-            guard: {
-                or: [
-                    { "===": [{ var: "event.agent" }, { var: "state.proposer" }] },
-                    { "===": [{ var: "event.agent" }, { var: "state.counterparty" }] },
-                ],
-            },
+            guard: signerIsAnyParty(["state.proposer", "state.counterparty"]),
             effect: {
                 merge: [
                     { var: "state" },
                     {
                         status: "DISPUTED",
-                        disputedAt: { var: "$timestamp" },
+                        disputedAt: { var: "$ordinal" },
                         disputeReason: { var: "event.reason" },
                         disputedBy: { var: "event.agent" },
                     },
@@ -223,13 +263,14 @@ export const contractAgreementDef = defineFiberApp({
             from: "DISPUTED",
             to: "COMPLETED",
             eventName: "resolve",
+            // authority gate — an ARBITER/SLASHER attestation check layers on additively when the identity registry lands (see docs/design/app-hardening-identity-integration.md §4.2)
             guard: {
                 or: [
-                    { var: "event.judicialRuling" },
+                    signerIsParty("state.arbitrator"),
                     {
                         and: [
-                            { "===": [{ var: "event.proposerApproves" }, true] },
-                            { "===": [{ var: "event.counterpartyApproves" }, true] },
+                            signerIsParty("state.proposer"),
+                            signerIsParty("state.counterparty"),
                         ],
                     },
                 ],
@@ -239,9 +280,16 @@ export const contractAgreementDef = defineFiberApp({
                     { var: "state" },
                     {
                         status: "COMPLETED",
-                        resolvedAt: { var: "$timestamp" },
+                        resolvedAt: { var: "$ordinal" },
                         resolution: { var: "event.resolution" },
-                        rulingId: { var: "event.rulingId" },
+                        // rulingId is recorded only on the arbitrator-resolved path
+                        rulingId: {
+                            if: [
+                                signerIsParty("state.arbitrator"),
+                                { var: "event.rulingId" },
+                                null,
+                            ],
+                        },
                     },
                 ],
             },
@@ -251,16 +299,11 @@ export const contractAgreementDef = defineFiberApp({
             from: "ACTIVE",
             to: "CANCELLED",
             eventName: "cancel",
-            guard: {
-                or: [
-                    { "===": [{ var: "event.agent" }, { var: "state.proposer" }] },
-                    { "===": [{ var: "event.agent" }, { var: "state.counterparty" }] },
-                ],
-            },
+            guard: signerIsAnyParty(["state.proposer", "state.counterparty"]),
             effect: {
                 merge: [
                     { var: "state" },
-                    { status: "CANCELLED", cancelledAt: { var: "$timestamp" } },
+                    { status: "CANCELLED", cancelledAt: { var: "$ordinal" } },
                 ],
             },
             dependencies: [],

package/dist/esm/apps/contracts/state-machines/contract-escrow.js

@@ -1,4 +1,5 @@
 import { defineFiberApp } from "../../../schema/fiber-app.js";
+import { signerIsParty } from "../../../schema/guards.js";
 /**
  * Asset custody with conditional release, dispute resolution, and split payments.
  */
@@ -38,7 +39,7 @@ export const contractEscrowDef = defineFiberApp({
         },
     },
     createSchema: {
-        required: ["depositor", "beneficiary", "requiredAmount"],
+        required: ["depositor", "beneficiary", "requiredAmount", "arbiter"],
         properties: {
             depositor: {
                 type: "address",
@@ -48,6 +49,11 @@ export const contractEscrowDef = defineFiberApp({
                 type: "address",
                 description: "DAG address of the beneficiary",
             },
+            arbiter: {
+                type: "address",
+                description: "DAG address of the arbiter authorized to rule on a dispute",
+                immutable: true,
+            },
             requiredAmount: {
                 type: "number",
                 minimum: 0,
@@ -74,6 +80,7 @@ export const contractEscrowDef = defineFiberApp({
         properties: {
             depositor: { type: "address" },
             beneficiary: { type: "address" },
+            arbiter: { type: "address", immutable: true },
             requiredAmount: { type: "number" },
             balance: { type: "number" },
             fundedAt: { type: "integer", nullable: true },
@@ -108,27 +115,86 @@ export const contractEscrowDef = defineFiberApp({
         dispute: {},
         ruling: {
             properties: {
-                judicialRuling: { type: "boolean" },
                 splits: { type: "array" },
                 rulingId: { type: "string" },
             },
         },
-        refund: {
-            properties: {
-                mutualConsent: { type: "boolean", nullable: true },
-            },
-        },
+        refund: {},
         cancel: {},
     },
     states: {
-        CREATED: { id: "CREATED", isFinal: false, metadata: null },
-        FUNDED: { id: "FUNDED", isFinal: false, metadata: null },
-        ACTIVE: { id: "ACTIVE", isFinal: false, metadata: null },
-        RELEASING: { id: "RELEASING", isFinal: false, metadata: null },
-        DISPUTED: { id: "DISPUTED", isFinal: false, metadata: null },
-        RELEASED: { id: "RELEASED", isFinal: true, metadata: null },
-        REFUNDED: { id: "REFUNDED", isFinal: true, metadata: null },
-        SPLIT: { id: "SPLIT", isFinal: true, metadata: null },
+        CREATED: {
+            id: "CREATED",
+            isFinal: false,
+            metadata: {
+                label: "Created",
+                description: "Escrow created; awaiting funding",
+                category: "initial",
+            },
+        },
+        FUNDED: {
+            id: "FUNDED",
+            isFinal: false,
+            metadata: {
+                label: "Funded",
+                description: "Funds deposited into escrow",
+                category: "active",
+            },
+        },
+        ACTIVE: {
+            id: "ACTIVE",
+            isFinal: false,
+            metadata: {
+                label: "Active",
+                description: "Escrow in effect while work is performed",
+                category: "active",
+            },
+        },
+        RELEASING: {
+            id: "RELEASING",
+            isFinal: false,
+            metadata: {
+                label: "Releasing",
+                description: "Release approved; payout in progress",
+                category: "pending",
+            },
+        },
+        DISPUTED: {
+            id: "DISPUTED",
+            isFinal: false,
+            metadata: {
+                label: "Disputed",
+                description: "A party disputed the escrow; awaiting arbitration",
+                category: "pending",
+            },
+        },
+        RELEASED: {
+            id: "RELEASED",
+            isFinal: true,
+            metadata: {
+                label: "Released",
+                description: "Funds released to the beneficiary (terminal)",
+                category: "terminal",
+            },
+        },
+        REFUNDED: {
+            id: "REFUNDED",
+            isFinal: true,
+            metadata: {
+                label: "Refunded",
+                description: "Funds refunded to the depositor (terminal)",
+                category: "terminal",
+            },
+        },
+        SPLIT: {
+            id: "SPLIT",
+            isFinal: true,
+            metadata: {
+                label: "Split",
+                description: "Funds split between parties per arbitration (terminal)",
+                category: "terminal",
+            },
+        },
     },
     initialState: "CREATED",
     transitions: [
@@ -138,14 +204,14 @@ export const contractEscrowDef = defineFiberApp({
             eventName: "deposit",
             guard: {
                 and: [
-                    { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
+                    signerIsParty("state.depositor"),
                     { ">=": [{ var: "event.amount" }, { var: "state.requiredAmount" }] },
                 ],
             },
             effect: {
                 merge: [
                     { var: "state" },
-                    { balance: { var: "event.amount" }, fundedAt: { var: "$timestamp" } },
+                    { balance: { var: "event.amount" }, fundedAt: { var: "$ordinal" } },
                 ],
             },
             dependencies: [],
@@ -156,12 +222,12 @@ export const contractEscrowDef = defineFiberApp({
             eventName: "activate",
             guard: {
                 or: [
-                    { "===": [{ var: "event.agent" }, { var: "state.beneficiary" }] },
+                    signerIsParty("state.beneficiary"),
                     { var: "state.autoActivate" },
                 ],
             },
             effect: {
-                merge: [{ var: "state" }, { activatedAt: { var: "$timestamp" } }],
+                merge: [{ var: "state" }, { activatedAt: { var: "$ordinal" } }],
             },
             dependencies: [],
         },
@@ -169,7 +235,7 @@ export const contractEscrowDef = defineFiberApp({
             from: "ACTIVE",
             to: "RELEASING",
             eventName: "request_release",
-            guard: { "===": [{ var: "event.agent" }, { var: "state.beneficiary" }] },
+            guard: signerIsParty("state.beneficiary"),
             effect: {
                 merge: [
                     { var: "state" },
@@ -178,10 +244,10 @@ export const contractEscrowDef = defineFiberApp({
                             requestedBy: { var: "event.agent" },
                             amount: { var: "event.amount" },
                             reason: { var: "event.reason" },
-                            requestedAt: { var: "$timestamp" },
+                            requestedAt: { var: "$ordinal" },
                         },
                         releaseDeadline: {
-                            "+": [{ var: "$timestamp" }, { var: "state.releaseWindowMs" }],
+                            "+": [{ var: "$ordinal" }, { var: "state.releaseWindowMs" }],
                         },
                     },
                 ],
@@ -194,15 +260,15 @@ export const contractEscrowDef = defineFiberApp({
             eventName: "approve_release",
             guard: {
                 or: [
-                    { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
-                    { ">=": [{ var: "$timestamp" }, { var: "state.releaseDeadline" }] },
+                    signerIsParty("state.depositor"),
+                    { ">=": [{ var: "$ordinal" }, { var: "state.releaseDeadline" }] },
                 ],
             },
             effect: {
                 merge: [
                     { var: "state" },
                     {
-                        releasedAt: { var: "$timestamp" },
+                        releasedAt: { var: "$ordinal" },
                         releasedTo: { var: "state.beneficiary" },
                     },
                 ],
@@ -215,24 +281,37 @@ export const contractEscrowDef = defineFiberApp({
             eventName: "dispute",
             guard: {
                 and: [
-                    { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
-                    { "<": [{ var: "$timestamp" }, { var: "state.releaseDeadline" }] },
+                    signerIsParty("state.depositor"),
+                    { "<": [{ var: "$ordinal" }, { var: "state.releaseDeadline" }] },
                 ],
             },
             effect: {
-                merge: [{ var: "state" }, { disputedAt: { var: "$timestamp" } }],
-            },
-            spawns: {
-                sm: "Judiciary",
-                initialData: {
-                    caseType: "escrow_dispute",
-                    plaintiff: { var: "state.depositor" },
-                    defendant: { var: "state.beneficiary" },
-                    claim: {
-                        escrowId: { var: "fiberId" },
-                        amount: { var: "state.balance" },
+                merge: [
+                    { var: "state" },
+                    { disputedAt: { var: "$ordinal" } },
+                    {
+                        // A3 fix: transition-level `spawns` is dropped by the chain. No Judiciary state machine is
+                        // defined to inline under `_spawn`, and escrow already resolves disputes via its own pinned
+                        // `arbiter` (the `ruling` transition) — the spawned Judiciary was fire-and-forget (never read
+                        // by escrow). So the dispute case is surfaced to the judiciary subsystem as an `_emit`
+                        // notification instead of a child fiber.
+                        _emit: [
+                            {
+                                name: "dispute_opened",
+                                data: {
+                                    caseType: "escrow_dispute",
+                                    plaintiff: { var: "state.depositor" },
+                                    defendant: { var: "state.beneficiary" },
+                                    claim: {
+                                        escrowId: { var: "machineId" },
+                                        amount: { var: "state.balance" },
+                                    },
+                                },
+                                destination: "Judiciary",
+                            },
+                        ],
                     },
-                },
+                ],
             },
             dependencies: [],
         },
@@ -240,7 +319,29 @@ export const contractEscrowDef = defineFiberApp({
             from: "DISPUTED",
             to: "SPLIT",
             eventName: "ruling",
-            guard: { var: "event.judicialRuling" },
+            // authority gate — an ARBITER/SLASHER attestation check layers on additively when the identity registry lands (see docs/design/app-hardening-identity-integration.md §4.2)
+            guard: {
+                and: [
+                    signerIsParty("state.arbiter"),
+                    {
+                        "===": [
+                            {
+                                reduce: [
+                                    { var: "event.splits" },
+                                    {
+                                        "+": [
+                                            { var: "accumulator" },
+                                            { var: "current.amount" },
+                                        ],
+                                    },
+                                    0,
+                                ],
+                            },
+                            { var: "state.balance" },
+                        ],
+                    },
+                ],
+            },
             effect: {
                 merge: [
                     { var: "state" },
@@ -256,14 +357,20 @@ export const contractEscrowDef = defineFiberApp({
             from: "ACTIVE",
             to: "REFUNDED",
             eventName: "refund",
+            // authority gate — an ARBITER/SLASHER attestation check layers on additively when the identity registry lands (see docs/design/app-hardening-identity-integration.md §4.2)
             guard: {
                 or: [
-                    { var: "event.mutualConsent" },
-                    { ">=": [{ var: "$timestamp" }, { var: "state.expiresAt" }] },
+                    {
+                        and: [
+                            signerIsParty("state.depositor"),
+                            signerIsParty("state.beneficiary"),
+                        ],
+                    },
+                    { ">=": [{ var: "$ordinal" }, { var: "state.expiresAt" }] },
                 ],
             },
             effect: {
-                merge: [{ var: "state" }, { refundedAt: { var: "$timestamp" } }],
+                merge: [{ var: "state" }, { refundedAt: { var: "$ordinal" } }],
             },
             dependencies: [],
         },
@@ -271,9 +378,9 @@ export const contractEscrowDef = defineFiberApp({
             from: "CREATED",
             to: "REFUNDED",
             eventName: "cancel",
-            guard: { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
+            guard: signerIsParty("state.depositor"),
             effect: {
-                merge: [{ var: "state" }, { refundedAt: { var: "$timestamp" } }],
+                merge: [{ var: "state" }, { refundedAt: { var: "$ordinal" } }],
             },
             dependencies: [],
         },