@hyperscale0/hsx 1.0.0-rc.1 → 1.0.123

package/std/savings.hsx

@@ -0,0 +1,68 @@
+header savings
+
+// Economics: Contributions and returned pots are principal, not company earnings.
+
+// Expose circle.create and membership.create; create one pending contribution
+// record per member per circle date before membership.activate. Circle activation
+// is clock-owned and needs exactly members joined memberships at or after startsAt.
+// Membership.activate needs the active circle and its full pending schedule.
+// Membership.received means the member received the pot. Contribution.paid means
+// one contribution was collected. Neither record's state proves the other's state.
+// A member can have received the pot with future unpaid contributions, or paid
+// a contribution while their membership still waits for its payout seat.
+// Receive counts preceding received memberships, never paid contributions.
+// Eight members at 300 SAR require 2400 SAR per payout; seven payments supply 2100,
+// so a full payout lacks 300 unless other cash exists. There is no reduced payout.
+// Contribution.pay has a due time and no deadline or prior-payment requirement.
+// Late and out-of-order collection is admitted while membership is active or
+// received and circle is active. Clock admission does not promise scheduler retry.
+// Circle.close needs every membership received and an empty held account.
+// Circle creation collects circleDates, one date per member for contributions and payouts.
+
+// Cost: circle.create declares one owned account. Each contribution payment
+// and each pot payout declares one transfer. Multiply by the actual member and
+// period counts for a completed circle; hsx cost reports per-action bounds.
+
+instrument circle(contribution: money, members: integer(1, 60), starts: date, memberships: ref<savings.membership> = object(savings.membership)) {
+  summary: "A fixed group contributes on its explicit calendar and takes the pot in order."
+  fields { contribution: money = contribution, members: integer = members, startsAt: date = starts, circleDates: list(date, members), pot: money = multiply(self.contribution, self.members), held: account of self }
+  lifecycle { states: [forming, active, closed, disbanded], initial: forming }
+  action create { }
+  action activate {
+    from: forming, to: active, actor: clock, due: { at: self.startsAt }
+    requires count of { instrument: memberships, reference: "circle", anchor: self.id, states: [joined], limit: 60 } == self.members
+  }
+  action close {
+    from: active, to: closed
+    requires count of { instrument: memberships, reference: "circle", anchor: self.id, states: [received], limit: 60 } == self.members
+    requires self.held.balance == "0"
+  }
+  action disband { from: forming, to: disbanded }
+}
+
+instrument membership(circle: ref<savings.circle>, member: party) {
+  summary: "A member contributes on the circle calendar and receives the pot in the assigned seat."
+  fields { circle: ref<circle>, member: account of member, seat: integer(1, 60), preceding: integer = subtract(self.seat, 1), receivesAt: date = at(self.circle.circleDates, self.seat), contribution: money = self.circle.contribution, total: money = self.circle.pot }
+  lifecycle { states: [joined, active, received, withdrawn], initial: joined }
+  action create { requires self.seat <= self.circle.members; requires self.circle in [forming]; requires unique "circle_seat" on [self.circle, self.seat]; requires unique "circle_member" on [self.circle, self.member] }
+  action activate {
+    from: joined, to: active
+    requires self.circle in [active]
+    requires count of { instrument: contribution, reference: "membership", anchor: self.id, states: [pending], limit: 60 } == self.circle.members
+  }
+  action receive {
+    from: active, to: received, actor: clock, due: { at: self.receivesAt }
+    requires self.circle in [active]
+    requires count of { instrument: all(savings.membership), reference: "circle", anchor: self.circle, states: [received], limit: 60 } == self.preceding
+    moves self.total from self.circle.held to self.member economics { purpose: principal, sourceParty: programOperator }
+  }
+  action withdraw { from: joined, to: withdrawn, requires self.circle in [disbanded] }
+  records {
+    contribution: {
+      fields { membership: ref<parent>, period: integer(1, 60), dueAt: date = at(self.membership.circle.circleDates, self.period), amount: money = self.membership.contribution }
+      lifecycle { states: [pending, paid], initial: pending }
+      action create { requires self.period <= self.membership.circle.members; requires self.membership in [joined]; requires unique "seat_period" on [self.membership, self.period] }
+      action pay { from: pending, to: paid, actor: clock, due: { at: self.dueAt }, requires self.membership in [active, received]; requires self.membership.circle in [active], moves self.amount from self.membership.member to self.membership.circle.held economics { purpose: principal, sourceParty: member } }
+    }
+  }
+}

package/std/wallet.hsx

@@ -0,0 +1,57 @@
+header wallet
+
+// Economics: Topups and withdrawals are excluded prepaid credit. Spending remains
+// unclassified because the bound payee alone does not state the purchase purpose.
+
+// Expose balance.create, activate, topup and withdraw as needed. Holder moves
+// cash only while active. Freeze blocks new topups, withdrawals and spend reserves;
+// close requires no held cash. Freeze/unfreeze use caller operation authority.
+// A separate spend record checks its amount against spendLimit at creation.
+// Expose reserve, pay and cancel for the bound payee. Reserve requires an active
+// wallet before expiresAt; pay posts the whole reservation, cancel/expiry void it.
+// Existing reservations may still post after the wallet freezes. There is no
+// daily aggregate limit, partial spend or card-network settlement in this header.
+
+// Cost: balance.create declares one owned account; topup and withdraw each
+// declare one transfer. Spend reserve, pay and cancel each declare one transfer
+// instruction. These are counts, not the executor tariff.
+
+instrument balance(holder: party, spend_limit: money = 100000 SAR) {
+  summary: "A holder's reusable balance with an immutable per-spend ceiling."
+  fields { holder: account of holder, held: account of self, spendLimit: money = spend_limit }
+  lifecycle { states: [pending, active, frozen, closed], initial: pending }
+  action create { }
+  action activate { from: pending, to: active, actor: { party: holder } }
+  action topup {
+    from: active, to: active, actor: { party: holder }
+    input { amount: money }
+    moves input.amount from holder to self.held economics { purpose: prepaid_credit, sourceParty: holder }
+  }
+  action withdraw {
+    from: active, to: active, actor: { party: holder }
+    input { amount: money }
+    moves input.amount from self.held to holder economics { purpose: prepaid_credit, sourceParty: programOperator }
+  }
+  action freeze { from: active, to: frozen, }
+  action unfreeze { from: frozen, to: active, }
+  action close { from: [pending, active], to: closed, requires self.held.balance == "0" }
+}
+
+instrument spend(wallet: ref<wallet.balance>, payee: party) {
+  summary: "Reserve one wallet spend, then post or void the same reservation."
+  fields { wallet: ref<wallet>, amount: money, expiresAt: date, reservation: text? }
+  lifecycle { states: [pending, reserved, paid, cancelled, expired], initial: pending }
+  action create {
+    requires self.wallet in [active]
+    requires self.amount <= self.wallet.spendLimit
+  }
+  action reserve {
+    from: pending, to: reserved, actor: { party: payee }
+    requires self.wallet in [active]
+    deadline: { at: self.expiresAt }
+    moves reserve self.amount from self.wallet.held to payee capture "reservation"
+  }
+  action pay { from: reserved, to: paid, actor: { party: payee }, moves post self.reservation }
+  action cancel { from: reserved, to: cancelled, actor: { party: payee }, moves void self.reservation }
+  action expire { from: reserved, to: expired, actor: clock, due: { at: self.expiresAt }, moves void self.reservation }
+}