@hyperscale0/hsx 1.0.0-beta.1 → 1.0.0-rc.1

package/examples/swap/swap.udl

@@ -0,0 +1,876 @@
+{
+  "instruments": [
+    {
+      "actionOrder": [
+        "abandon",
+        "cancel",
+        "create",
+        "dispute",
+        "fund",
+        "post",
+        "release"
+      ],
+      "actions": {
+        "abandon": {
+          "agentDescription": "Walk away from a trade that never funded. Only a created trade abandons, and its escrow account must hold nothing, so there is nothing to refund. No money moves.",
+          "moves": [],
+          "publicAction": "abandonExchange",
+          "requiresDrainedAccount": {
+            "path": "refs.escrowAccountId"
+          },
+          "steps": [],
+          "summary": "Abandon the trade before its atomic funding batch"
+        },
+        "cancel": {
+          "agentDescription": "Unwind a funded trade before release. Both principals return from escrow to their own sides in one batch. The trade must be funded and not yet released. The service fees taken at funding stay with the platform.",
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[1]"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.buyerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.buyerAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "cancel"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                }
+              },
+              "capture": {
+                "cancelSideARefundTransferId": "transferId"
+              },
+              "key": "side_a_refund",
+              "operation": "internal_transfer.create"
+            },
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.sellerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.sellerAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "cancel"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                }
+              },
+              "capture": {
+                "cancelSideBRefundTransferId": "transferId"
+              },
+              "key": "side_b_refund",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "publicAction": "cancelExchange",
+          "steps": [],
+          "summary": "Cancel and return both trade principals atomically"
+        },
+        "create": {
+          "agentDescription": "Open a trade and provision its escrow account. No money moves. Both principals and both exact service fees are fixed here and cannot change afterwards.",
+          "moves": [],
+          "publicAction": "createExchange",
+          "steps": [
+            {
+              "bind": {
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "owner.id": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "owner.type": {
+                  "from": "const",
+                  "value": "product"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "role": {
+                  "from": "const",
+                  "value": "product_escrow"
+                }
+              },
+              "capture": {
+                "escrowAccountId": "accountId"
+              },
+              "operation": "account.escrow.provision"
+            }
+          ],
+          "summary": "Create a exchange atomic trade"
+        },
+        "dispute": {
+          "agentDescription": "Claw back a released trade inside its dispute window. Both cross-payment reservations void and both principals return from escrow in one batch. The trade must be released and the clawback moment must not have passed. Either trading party may call it.",
+          "deadline": {
+            "field": "clawbackAt"
+          },
+          "effects": {
+            "decides": [
+              {
+                "signature": "decides.tenant_port",
+                "source": "port"
+              }
+            ],
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[1]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[2]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[3]"
+              }
+            ],
+            "schedules": [
+              {
+                "signature": "schedules.deadline",
+                "source": "deadline"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "reason": {
+                  "from": "const",
+                  "value": "Whole trade disputed inside the clawback window"
+                },
+                "transferId": {
+                  "from": "instance",
+                  "path": "refs.releaseSideATransferId"
+                }
+              },
+              "key": "side_a_void",
+              "operation": "internal_transfer.void"
+            },
+            {
+              "bind": {
+                "reason": {
+                  "from": "const",
+                  "value": "Whole trade disputed inside the clawback window"
+                },
+                "transferId": {
+                  "from": "instance",
+                  "path": "refs.releaseSideBTransferId"
+                }
+              },
+              "key": "side_b_void",
+              "operation": "internal_transfer.void"
+            },
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.buyerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.buyerAccountId"
+                },
+                "metadata.clawbackOfTransferId": {
+                  "from": "instance",
+                  "path": "refs.releaseSideATransferId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "dispute"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                }
+              },
+              "capture": {
+                "disputeSideARefundTransferId": "transferId"
+              },
+              "key": "side_a_refund",
+              "operation": "internal_transfer.create"
+            },
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.sellerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.sellerAccountId"
+                },
+                "metadata.clawbackOfTransferId": {
+                  "from": "instance",
+                  "path": "refs.releaseSideBTransferId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "dispute"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                }
+              },
+              "capture": {
+                "disputeSideBRefundTransferId": "transferId"
+              },
+              "key": "side_b_refund",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "port": {
+            "allowedParties": [
+              "payer",
+              "beneficiary"
+            ]
+          },
+          "publicAction": "disputeExchange",
+          "steps": [],
+          "summary": "Void both reservations, then refund both principals atomically"
+        },
+        "fund": {
+          "agentDescription": "Fund both sides at once. Each side pays its principal into escrow and its service fee to the platform account, four transfers in one batch. The trade must be created and unfunded. This moves real money from both parties.",
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.collection.pay_in",
+                "source": "moves[0]"
+              },
+              {
+                "signature": "moves.collection.pay_in",
+                "source": "moves[1]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[2]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[3]"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.buyerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "fund"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.buyerAccountId"
+                }
+              },
+              "capture": {
+                "fundSideAPrincipalTransferId": "transferId"
+              },
+              "key": "side_a_principal",
+              "operation": "internal_transfer.create"
+            },
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.sellerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "fund"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.sellerAccountId"
+                }
+              },
+              "capture": {
+                "fundSideBPrincipalTransferId": "transferId"
+              },
+              "key": "side_b_principal",
+              "operation": "internal_transfer.create"
+            },
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.buyerFee"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.platformAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "fund"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.buyerAccountId"
+                }
+              },
+              "capture": {
+                "fundSideAServiceFeeTransferId": "transferId"
+              },
+              "key": "side_a_service_fee",
+              "operation": "internal_transfer.create"
+            },
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.sellerFee"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.platformAccountId"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "fund"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "fields.sellerAccountId"
+                }
+              },
+              "capture": {
+                "fundSideBServiceFeeTransferId": "transferId"
+              },
+              "key": "side_b_service_fee",
+              "operation": "internal_transfer.create"
+            }
+          ],
+          "publicAction": "fundExchange",
+          "steps": [],
+          "summary": "Fund both trade sides and collect on-top fees atomically"
+        },
+        "post": {
+          "due": {
+            "field": "clawbackAt"
+          },
+          "effects": {
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[1]"
+              }
+            ],
+            "schedules": [
+              {
+                "signature": "schedules.due",
+                "source": "due"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "transferId": {
+                  "from": "instance",
+                  "path": "refs.releaseSideATransferId"
+                }
+              },
+              "key": "side_a",
+              "operation": "internal_transfer.post"
+            },
+            {
+              "bind": {
+                "transferId": {
+                  "from": "instance",
+                  "path": "refs.releaseSideBTransferId"
+                }
+              },
+              "key": "side_b",
+              "operation": "internal_transfer.post"
+            }
+          ],
+          "steps": [],
+          "summary": "Post both trade reservations when the clawback window matures"
+        },
+        "release": {
+          "agentDescription": "Reserve each side's principal for the other side and start the dispute window. The trade must be funded. Money is reserved, not settled. It posts on its own when the window matures, and dispute unwinds it before then. Either trading party may call it.",
+          "effects": {
+            "decides": [
+              {
+                "signature": "decides.tenant_port",
+                "source": "port"
+              }
+            ],
+            "holds": [
+              {
+                "signature": "holds.reserve",
+                "source": "moves[0]"
+              },
+              {
+                "signature": "holds.reserve",
+                "source": "moves[1]"
+              }
+            ],
+            "moves": [
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[0]"
+              },
+              {
+                "signature": "moves.transfer.internal",
+                "source": "moves[1]"
+              }
+            ]
+          },
+          "moves": [
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.buyerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.sellerAccountId"
+                },
+                "metadata.clawbackAt": {
+                  "from": "instance",
+                  "path": "fields.clawbackAt"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "release"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                }
+              },
+              "capture": {
+                "releaseSideATransferId": "transferId"
+              },
+              "key": "side_a",
+              "operation": "internal_transfer.reserve"
+            },
+            {
+              "bind": {
+                "amount": {
+                  "from": "instance",
+                  "path": "fields.sellerAmount"
+                },
+                "currency": {
+                  "from": "instance",
+                  "path": "fields.currency"
+                },
+                "destinationAccountId": {
+                  "from": "instance",
+                  "path": "fields.buyerAccountId"
+                },
+                "metadata.clawbackAt": {
+                  "from": "instance",
+                  "path": "fields.clawbackAt"
+                },
+                "metadata.instrumentId": {
+                  "from": "const",
+                  "value": "exchange"
+                },
+                "metadata.instrumentInstanceId": {
+                  "from": "instance",
+                  "path": "instrumentInstanceId"
+                },
+                "metadata.phase": {
+                  "from": "const",
+                  "value": "release"
+                },
+                "productId": {
+                  "from": "instance",
+                  "path": "productId"
+                },
+                "sourceAccountId": {
+                  "from": "instance",
+                  "path": "refs.escrowAccountId"
+                }
+              },
+              "capture": {
+                "releaseSideBTransferId": "transferId"
+              },
+              "key": "side_b",
+              "operation": "internal_transfer.reserve"
+            }
+          ],
+          "port": {
+            "allowedParties": [
+              "payer",
+              "beneficiary"
+            ]
+          },
+          "publicAction": "releaseExchange",
+          "setsAt": {
+            "field": "clawbackAt",
+            "offset": "P7D"
+          },
+          "steps": [],
+          "summary": "Reserve both cross-payments for the whole-trade clawback window"
+        }
+      },
+      "agentDescription": "Reach for swap when two named parties pay each other in one atomic trade and neither leg may settle alone. Both principals fund one escrow together, both cross-payments reserve together, and one dispute unwinds both. A single payer paying a single payee is instant transfer instead.",
+      "description": "Atomic swap between buyer and seller; half-funded and half-released states do not exist",
+      "distinctParties": true,
+      "feeRules": [
+        {
+          "amountField": "buyerFee",
+          "baseField": "buyerAmount",
+          "bearerField": "buyerAccountId",
+          "position": "on_top",
+          "rule": {
+            "currencyField": "currency",
+            "field": "buyerFee",
+            "kind": "exact"
+          }
+        },
+        {
+          "amountField": "sellerFee",
+          "baseField": "sellerAmount",
+          "bearerField": "sellerAccountId",
+          "position": "on_top",
+          "rule": {
+            "currencyField": "currency",
+            "field": "sellerFee",
+            "kind": "exact"
+          }
+        }
+      ],
+      "fields": {
+        "buyerAccountId": {
+          "description": "The buyer account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "buyerAmount": {
+          "description": "Side A amount in SAR minor units, held against the whole trade",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "buyerFee": {
+          "description": "Immutable exact buyer service fee in SAR minor units",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "clawbackAt": {
+          "description": "Machine-owned end of the P7D whole-trade dispute window",
+          "format": "hyperscale-date-time",
+          "type": "string"
+        },
+        "currency": {
+          "description": "ISO 4217 currency code",
+          "maxLength": 3,
+          "minLength": 3,
+          "pattern": "^[A-Z]{3}$",
+          "type": "string"
+        },
+        "platformAccountId": {
+          "description": "The product fee collection account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-fee-collection-port": true,
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance",
+              "product_revenue"
+            ]
+          }
+        },
+        "sellerAccountId": {
+          "description": "The seller account",
+          "pattern": "^acct_(sandbox|live)_[a-z0-9]{8,64}$",
+          "type": "string",
+          "x-hyperscale-reference-filter": {
+            "column": "role",
+            "values": [
+              "customer_balance"
+            ]
+          }
+        },
+        "sellerAmount": {
+          "description": "Side B amount in SAR minor units, held against the whole trade",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        },
+        "sellerFee": {
+          "description": "Immutable exact seller service fee in SAR minor units",
+          "pattern": "^[1-9][0-9]{0,17}$",
+          "type": "string"
+        }
+      },
+      "id": "exchange",
+      "idPrefix": "exch",
+      "lifecycle": {
+        "initial": "created",
+        "states": [
+          "created",
+          "abandoned",
+          "funded",
+          "cancelled",
+          "released",
+          "settled",
+          "clawed_back"
+        ],
+        "transitions": {
+          "abandon": {
+            "from": [
+              "created"
+            ],
+            "to": "abandoned"
+          },
+          "cancel": {
+            "from": [
+              "funded"
+            ],
+            "to": "cancelled"
+          },
+          "dispute": {
+            "from": [
+              "released"
+            ],
+            "to": "clawed_back"
+          },
+          "fund": {
+            "from": [
+              "created"
+            ],
+            "to": "funded"
+          },
+          "post": {
+            "from": [
+              "released"
+            ],
+            "to": "settled"
+          },
+          "release": {
+            "from": [
+              "funded"
+            ],
+            "to": "released"
+          }
+        }
+      },
+      "parties": {
+        "beneficiary": "sellerAccountId",
+        "payer": "buyerAccountId"
+      },
+      "required": [
+        "buyerAccountId",
+        "sellerAccountId",
+        "platformAccountId",
+        "buyerAmount",
+        "sellerAmount",
+        "buyerFee",
+        "sellerFee",
+        "currency"
+      ],
+      "summary": "Two-party atomic trade between buyer and seller",
+      "title": "Exchange"
+    }
+  ],
+  "product": "swap_example",
+  "subjects": [],
+  "title": "Swap example",
+  "udl": 1,
+  "version": 1
+}