@ottochain/sdk 2.3.0 → 2.5.0

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

@@ -1,251 +1,244 @@
-import { defineFiberApp } from "../../../schema/fiber-app.js";
+import { defineFiberApp } from '../../../schema/fiber-app.js';
+import { signerIsParty } from '../../../schema/guards.js';
 /**
  * Asset custody with conditional release, dispute resolution, and split payments.
  */
 export const contractEscrowDef = defineFiberApp({
     metadata: {
-        name: "ContractEscrow",
-        app: "contracts",
-        type: "escrow",
-        version: "1.0.0",
-        description: "Asset custody with conditional release, dispute resolution, and split payments",
+        name: 'ContractEscrow',
+        app: 'contracts',
+        type: 'escrow',
+        version: '1.0.0',
+        description: 'Asset custody with conditional release, dispute resolution, and split payments',
         crossReferences: {
             contractId: {
-                machine: "contract-agreement",
-                field: "contractId",
-                description: "Links to Contract SM that created this escrow",
+                machine: 'contract-agreement',
+                field: 'contractId',
+                description: 'Links to Contract SM that created this escrow',
             },
             marketId: {
-                machine: "market-universal",
-                field: "marketId",
-                description: "Links to Market SM for market-based escrow",
+                machine: 'market-universal',
+                field: 'marketId',
+                description: 'Links to Market SM for market-based escrow',
             },
             insuranceId: {
-                machine: "insurance",
-                field: "insuranceId",
-                description: "Links to Insurance SM for protected escrow",
+                machine: 'insurance',
+                field: 'insuranceId',
+                description: 'Links to Insurance SM for protected escrow',
             },
             arbitrationPoolId: {
-                machine: "arbitration-pool",
-                field: "arbitrationPoolId",
-                description: "Links to ArbitrationPool for dispute resolution",
+                machine: 'arbitration-pool',
+                field: 'arbitrationPoolId',
+                description: 'Links to ArbitrationPool for dispute resolution',
             },
             treasuryId: {
-                machine: "treasury",
-                field: "treasuryId",
-                description: "Links to Treasury for fee collection",
+                machine: 'treasury',
+                field: 'treasuryId',
+                description: 'Links to Treasury for fee collection',
             },
         },
     },
     createSchema: {
-        required: ["depositor", "beneficiary", "requiredAmount"],
+        required: ['depositor', 'beneficiary', 'requiredAmount', 'arbiter'],
         properties: {
             depositor: {
-                type: "address",
-                description: "DAG address of the depositor",
+                type: 'address',
+                description: 'DAG address of the depositor',
             },
             beneficiary: {
-                type: "address",
-                description: "DAG address of the beneficiary",
+                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",
+                type: 'number',
                 minimum: 0,
-                description: "Required escrow amount",
+                description: 'Required escrow amount',
             },
             releaseWindowMs: {
-                type: "integer",
-                description: "Time window for dispute before auto-release",
+                type: 'integer',
+                description: 'Time window for dispute before auto-release',
                 nullable: true,
             },
             expiresAt: {
-                type: "integer",
-                description: "Timestamp when escrow expires",
+                type: 'integer',
+                description: 'Timestamp when escrow expires',
                 nullable: true,
             },
             autoActivate: {
-                type: "boolean",
-                description: "Whether to auto-activate on funding",
+                type: 'boolean',
+                description: 'Whether to auto-activate on funding',
                 nullable: true,
             },
         },
     },
     stateSchema: {
         properties: {
-            depositor: { type: "address" },
-            beneficiary: { type: "address" },
-            requiredAmount: { type: "number" },
-            balance: { type: "number" },
-            fundedAt: { type: "integer", nullable: true },
-            activatedAt: { type: "integer", nullable: true },
-            releaseRequest: { type: "object", nullable: true },
-            releaseDeadline: { type: "integer", nullable: true },
-            releasedAt: { type: "integer", nullable: true },
-            releasedTo: { type: "address", nullable: true },
-            disputedAt: { type: "integer", nullable: true },
-            refundedAt: { type: "integer", nullable: true },
-            splits: { type: "array", nullable: true },
-            rulingId: { type: "string", nullable: true },
-            releaseWindowMs: { type: "integer", nullable: true },
-            expiresAt: { type: "integer", nullable: true },
-            autoActivate: { type: "boolean", nullable: true },
+            depositor: { type: 'address' },
+            beneficiary: { type: 'address' },
+            arbiter: { type: 'address', immutable: true },
+            requiredAmount: { type: 'number' },
+            balance: { type: 'number' },
+            fundedAt: { type: 'integer', nullable: true },
+            activatedAt: { type: 'integer', nullable: true },
+            releaseRequest: { type: 'object', nullable: true },
+            releaseDeadline: { type: 'integer', nullable: true },
+            releasedAt: { type: 'integer', nullable: true },
+            releasedTo: { type: 'address', nullable: true },
+            disputedAt: { type: 'integer', nullable: true },
+            refundedAt: { type: 'integer', nullable: true },
+            splits: { type: 'array', nullable: true },
+            rulingId: { type: 'string', nullable: true },
+            releaseWindowMs: { type: 'integer', nullable: true },
+            expiresAt: { type: 'integer', nullable: true },
+            autoActivate: { type: 'boolean', nullable: true },
         },
     },
     eventSchemas: {
         deposit: {
             properties: {
-                amount: { type: "number" },
+                amount: { type: 'number' },
             },
         },
         activate: {},
         request_release: {
             properties: {
-                amount: { type: "number" },
-                reason: { type: "string", nullable: true },
+                amount: { type: 'number' },
+                reason: { type: 'string', nullable: true },
             },
         },
         approve_release: {},
         dispute: {},
         ruling: {
             properties: {
-                judicialRuling: { type: "boolean" },
-                splits: { type: "array" },
-                rulingId: { type: "string" },
-            },
-        },
-        refund: {
-            properties: {
-                mutualConsent: { type: "boolean", nullable: true },
+                splits: { type: 'array' },
+                rulingId: { type: 'string' },
             },
         },
+        refund: {},
         cancel: {},
     },
     states: {
         CREATED: {
-            id: "CREATED",
+            id: 'CREATED',
             isFinal: false,
             metadata: {
-                label: "Created",
-                description: "Escrow created; awaiting funding",
-                category: "initial",
+                label: 'Created',
+                description: 'Escrow created; awaiting funding',
+                category: 'initial',
             },
         },
         FUNDED: {
-            id: "FUNDED",
+            id: 'FUNDED',
             isFinal: false,
             metadata: {
-                label: "Funded",
-                description: "Funds deposited into escrow",
-                category: "active",
+                label: 'Funded',
+                description: 'Funds deposited into escrow',
+                category: 'active',
             },
         },
         ACTIVE: {
-            id: "ACTIVE",
+            id: 'ACTIVE',
             isFinal: false,
             metadata: {
-                label: "Active",
-                description: "Escrow in effect while work is performed",
-                category: "active",
+                label: 'Active',
+                description: 'Escrow in effect while work is performed',
+                category: 'active',
             },
         },
         RELEASING: {
-            id: "RELEASING",
+            id: 'RELEASING',
             isFinal: false,
             metadata: {
-                label: "Releasing",
-                description: "Release approved; payout in progress",
-                category: "pending",
+                label: 'Releasing',
+                description: 'Release approved; payout in progress',
+                category: 'pending',
             },
         },
         DISPUTED: {
-            id: "DISPUTED",
+            id: 'DISPUTED',
             isFinal: false,
             metadata: {
-                label: "Disputed",
-                description: "A party disputed the escrow; awaiting arbitration",
-                category: "pending",
+                label: 'Disputed',
+                description: 'A party disputed the escrow; awaiting arbitration',
+                category: 'pending',
             },
         },
         RELEASED: {
-            id: "RELEASED",
+            id: 'RELEASED',
             isFinal: true,
             metadata: {
-                label: "Released",
-                description: "Funds released to the beneficiary (terminal)",
-                category: "terminal",
+                label: 'Released',
+                description: 'Funds released to the beneficiary (terminal)',
+                category: 'terminal',
             },
         },
         REFUNDED: {
-            id: "REFUNDED",
+            id: 'REFUNDED',
             isFinal: true,
             metadata: {
-                label: "Refunded",
-                description: "Funds refunded to the depositor (terminal)",
-                category: "terminal",
+                label: 'Refunded',
+                description: 'Funds refunded to the depositor (terminal)',
+                category: 'terminal',
             },
         },
         SPLIT: {
-            id: "SPLIT",
+            id: 'SPLIT',
             isFinal: true,
             metadata: {
-                label: "Split",
-                description: "Funds split between parties per arbitration (terminal)",
-                category: "terminal",
+                label: 'Split',
+                description: 'Funds split between parties per arbitration (terminal)',
+                category: 'terminal',
             },
         },
     },
-    initialState: "CREATED",
+    initialState: 'CREATED',
     transitions: [
         {
-            from: "CREATED",
-            to: "FUNDED",
-            eventName: "deposit",
+            from: 'CREATED',
+            to: 'FUNDED',
+            eventName: 'deposit',
             guard: {
-                and: [
-                    { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
-                    { ">=": [{ var: "event.amount" }, { var: "state.requiredAmount" }] },
-                ],
+                and: [signerIsParty('state.depositor'), { '>=': [{ var: 'event.amount' }, { var: 'state.requiredAmount' }] }],
             },
             effect: {
-                merge: [
-                    { var: "state" },
-                    { balance: { var: "event.amount" }, fundedAt: { var: "$timestamp" } },
-                ],
+                merge: [{ var: 'state' }, { balance: { var: 'event.amount' }, fundedAt: { var: '$ordinal' } }],
             },
             dependencies: [],
         },
         {
-            from: "FUNDED",
-            to: "ACTIVE",
-            eventName: "activate",
+            from: 'FUNDED',
+            to: 'ACTIVE',
+            eventName: 'activate',
             guard: {
-                or: [
-                    { "===": [{ var: "event.agent" }, { var: "state.beneficiary" }] },
-                    { var: "state.autoActivate" },
-                ],
+                or: [signerIsParty('state.beneficiary'), { var: 'state.autoActivate' }],
             },
             effect: {
-                merge: [{ var: "state" }, { activatedAt: { var: "$timestamp" } }],
+                merge: [{ var: 'state' }, { activatedAt: { var: '$ordinal' } }],
             },
             dependencies: [],
         },
         {
-            from: "ACTIVE",
-            to: "RELEASING",
-            eventName: "request_release",
-            guard: { "===": [{ var: "event.agent" }, { var: "state.beneficiary" }] },
+            from: 'ACTIVE',
+            to: 'RELEASING',
+            eventName: 'request_release',
+            guard: signerIsParty('state.beneficiary'),
             effect: {
                 merge: [
-                    { var: "state" },
+                    { var: 'state' },
                     {
                         releaseRequest: {
-                            requestedBy: { var: "event.agent" },
-                            amount: { var: "event.amount" },
-                            reason: { var: "event.reason" },
-                            requestedAt: { var: "$timestamp" },
+                            requestedBy: { var: 'event.agent' },
+                            amount: { var: 'event.amount' },
+                            reason: { var: 'event.reason' },
+                            requestedAt: { var: '$ordinal' },
                         },
                         releaseDeadline: {
-                            "+": [{ var: "$timestamp" }, { var: "state.releaseWindowMs" }],
+                            '+': [{ var: '$ordinal' }, { var: 'state.releaseWindowMs' }],
                         },
                     },
                 ],
@@ -253,91 +246,120 @@ export const contractEscrowDef = defineFiberApp({
             dependencies: [],
         },
         {
-            from: "RELEASING",
-            to: "RELEASED",
-            eventName: "approve_release",
+            from: 'RELEASING',
+            to: 'RELEASED',
+            eventName: 'approve_release',
             guard: {
-                or: [
-                    { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
-                    { ">=": [{ var: "$timestamp" }, { var: "state.releaseDeadline" }] },
-                ],
+                or: [signerIsParty('state.depositor'), { '>=': [{ var: '$ordinal' }, { var: 'state.releaseDeadline' }] }],
             },
             effect: {
                 merge: [
-                    { var: "state" },
+                    { var: 'state' },
                     {
-                        releasedAt: { var: "$timestamp" },
-                        releasedTo: { var: "state.beneficiary" },
+                        releasedAt: { var: '$ordinal' },
+                        releasedTo: { var: 'state.beneficiary' },
                     },
                 ],
             },
             dependencies: [],
         },
         {
-            from: "RELEASING",
-            to: "DISPUTED",
-            eventName: "dispute",
+            from: 'RELEASING',
+            to: 'DISPUTED',
+            eventName: 'dispute',
             guard: {
-                and: [
-                    { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
-                    { "<": [{ var: "$timestamp" }, { var: "state.releaseDeadline" }] },
-                ],
+                and: [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: [],
         },
         {
-            from: "DISPUTED",
-            to: "SPLIT",
-            eventName: "ruling",
-            guard: { var: "event.judicialRuling" },
+            from: 'DISPUTED',
+            to: 'SPLIT',
+            eventName: 'ruling',
+            // 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" },
+                    { var: 'state' },
                     {
-                        splits: { var: "event.splits" },
-                        rulingId: { var: "event.rulingId" },
+                        splits: { var: 'event.splits' },
+                        rulingId: { var: 'event.rulingId' },
                     },
                 ],
             },
             dependencies: [],
         },
         {
-            from: "ACTIVE",
-            to: "REFUNDED",
-            eventName: "refund",
+            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: [],
         },
         {
-            from: "CREATED",
-            to: "REFUNDED",
-            eventName: "cancel",
-            guard: { "===": [{ var: "event.agent" }, { var: "state.depositor" }] },
+            from: 'CREATED',
+            to: 'REFUNDED',
+            eventName: 'cancel',
+            guard: signerIsParty('state.depositor'),
             effect: {
-                merge: [{ var: "state" }, { refundedAt: { var: "$timestamp" } }],
+                merge: [{ var: 'state' }, { refundedAt: { var: '$ordinal' } }],
             },
             dependencies: [],
         },