@misofm/partyos 0.1.0

package/src/queries.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Typed reads: fetch an on-chain object (or dynamic field) via the Core API, BCS-parse
+// it through the generated struct, and map to the public camelCase types.
+
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import { deriveDynamicFieldID, deriveObjectID, normalizeStructTag } from "@mysten/sui/utils";
+import { bcs } from "@mysten/sui/bcs";
+import {
+  MembershipKey as MembershipKeyBcs,
+  Party as PartyBcs,
+  PendingInviteKey as PendingInviteKeyBcs,
+  PendingMembershipKey as PendingMembershipKeyBcs,
+} from "./contracts/partyos/party.ts";
+import { keyBytes, mapParty } from "./internal.ts";
+import type { Party } from "./types.ts";
+
+/** True for the Core API's "object does not exist" error (a missing dynamic field). */
+export function isNotFound(e: unknown): boolean {
+  const msg = e instanceof Error ? e.message : String(e);
+  return /not\s*found|does not exist|no object/i.test(msg);
+}
+
+/**
+ * Reads an object's BCS content, or null when it does not exist. A missing
+ * object (e.g. an unset dynamic field) surfaces as a thrown "not found" from the
+ * Core API, not an empty result, so optional reads can treat it as absence.
+ */
+export async function getObjectContent(client: ClientWithCoreApi, objectId: string): Promise<Uint8Array | null> {
+  try {
+    const { object } = await client.core.getObject({ objectId, include: { content: true } });
+    return object?.content ?? null;
+  } catch (e) {
+    if (isNotFound(e)) return null;
+    throw e;
+  }
+}
+
+/** The `Party` struct tag of one partyos deployment. */
+export function partyType(partyPackageId: string): string {
+  return normalizeStructTag(`${partyPackageId}::party::Party`);
+}
+
+// A Party from another partyos package (a previous generation) parses
+// identically but no deployed package accepts it, so the object's type is
+// checked against the deployment before its content is trusted.
+function assertPartyType(objectId: string, type: string | undefined, partyPackageId: string): void {
+  const expected = partyType(partyPackageId);
+  if (type === undefined || normalizeStructTag(type) !== expected) {
+    throw new Error(
+      `Object ${objectId} is ${type ?? "of unknown type"}, not a ${expected}` +
+        (type?.endsWith("::party::Party") ? " (a Party from a different partyos deployment)" : ""),
+    );
+  }
+}
+
+/** Fetches and parses a shared `Party` object of this deployment's partyos package. */
+export async function getPartyById(
+  client: ClientWithCoreApi,
+  partyId: string,
+  partyPackageId: string,
+): Promise<Party> {
+  let object;
+  try {
+    ({ object } = await client.core.getObject({ objectId: partyId, include: { content: true } }));
+  } catch (e) {
+    if (isNotFound(e)) throw new Error(`Party not found: ${partyId}`);
+    throw e;
+  }
+  if (!object?.content) throw new Error(`Party not found: ${partyId}`);
+  assertPartyType(partyId, object.type, partyPackageId);
+  return mapParty(partyId, PartyBcs.parse(object.content));
+}
+
+/**
+ * Fetches and parses multiple shared `Party` objects in one Core request.
+ * Missing objects are skipped; an object of another type is an error.
+ */
+export async function getPartiesByIds(
+  client: ClientWithCoreApi,
+  partyIds: readonly string[],
+  partyPackageId: string,
+): Promise<Partial<Record<string, Party>>> {
+  if (partyIds.length === 0) return {};
+  const { objects } = await client.core.getObjects({
+    objectIds: [...new Set(partyIds)],
+    include: { content: true },
+  });
+  const parties: Partial<Record<string, Party>> = {};
+  for (const obj of objects) {
+    if (obj instanceof Error) continue;
+    assertPartyType(obj.objectId, obj.type, partyPackageId);
+    parties[obj.objectId] = mapParty(obj.objectId, PartyBcs.parse(obj.content));
+  }
+  return parties;
+}
+
+/** Derives a party's `PartyAdminCap` id (it is a `derived_object` off the party UID). */
+export function derivePartyAdminCapId(partyId: string, partyPackageId: string): string {
+  return deriveObjectID(
+    partyId,
+    `${partyPackageId}::party::PartyAdminCapKey`,
+    bcs.Address.serialize(partyId).toBytes(),
+  );
+}
+
+// === Group membership reads ===
+
+/** Collects the ids stored in every dynamic-field key of `parentId` whose type ends with `keySuffix`. */
+async function collectKeyIds(
+  client: ClientWithCoreApi,
+  parentId: string,
+  keySuffix: string,
+  codec: { parse(bytes: Uint8Array): readonly unknown[] },
+): Promise<string[]> {
+  const ids: string[] = [];
+  let cursor: string | null | undefined;
+  do {
+    const page = await client.core.listDynamicFields({ parentId, cursor: cursor ?? undefined });
+    for (const f of page.dynamicFields) {
+      if (typeof f.name?.type === "string" && f.name.type.endsWith(keySuffix) && f.name.bcs != null) {
+        const [id] = codec.parse(keyBytes(f.name.bcs));
+        ids.push(String(id));
+      }
+    }
+    cursor = page.hasNextPage ? page.cursor : null;
+  } while (cursor);
+  return ids;
+}
+
+/**
+ * The group ids a party currently belongs to, read from its `MembershipKey`
+ * dynamic fields (the member-side record). No indexer required.
+ */
+export async function getMemberships(client: ClientWithCoreApi, partyId: string): Promise<string[]> {
+  return collectKeyIds(client, partyId, "::party::MembershipKey", MembershipKeyBcs);
+}
+
+/** The member ids invited to a group but not yet accepted (its `PendingInviteKey` fields). */
+export async function getPendingInvites(client: ClientWithCoreApi, groupId: string): Promise<string[]> {
+  return collectKeyIds(client, groupId, "::party::PendingInviteKey", PendingInviteKeyBcs);
+}
+
+/**
+ * The group ids that have invited a party but are still awaiting its response.
+ * This reads the member-side `PendingMembershipKey` inbox index, so it only
+ * enumerates the target party's dynamic fields.
+ */
+export async function getPendingMemberships(client: ClientWithCoreApi, partyId: string): Promise<string[]> {
+  return collectKeyIds(client, partyId, "::party::PendingMembershipKey", PendingMembershipKeyBcs);
+}
+
+/** Whether `memberId` currently holds a membership record for `groupId`. */
+export async function isMember(
+  client: ClientWithCoreApi,
+  memberId: string,
+  groupId: string,
+  partyPackageId: string,
+): Promise<boolean> {
+  const fieldId = deriveDynamicFieldID(
+    memberId,
+    `${partyPackageId}::party::MembershipKey`,
+    MembershipKeyBcs.serialize([groupId]).toBytes(),
+  );
+  return (await getObjectContent(client, fieldId)) !== null;
+}

package/src/transactions.ts

@@ -0,0 +1,167 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Core PartyOS transaction builders. Every builder returns a thunk that *appends*
+// commands to a caller-owned Transaction, so flows compose. Package ids are taken
+// in params (the client binds them; see ./client.ts). Calls into the party package
+// go through the generated typed call fns (party.*).
+
+import type { Transaction } from "@mysten/sui/transactions";
+import * as party from "./contracts/partyos/party.ts";
+
+export type TxThunk = (tx: Transaction) => void | Promise<void>;
+
+export interface CreatePartyParams {
+  /** Human-readable party name (not verified; app-layer verifies). */
+  name: string;
+  /** Address that receives the PartyAdminCap. */
+  recipient: string;
+  partyPackageId: string;
+}
+
+/** Creates an individual party, shares it, and transfers its admin cap to `recipient`. */
+export function createIndividualParty(params: CreatePartyParams): TxThunk {
+  return (tx) => {
+    const kind = tx.add(party.newIndividualKind({ package: params.partyPackageId }));
+    const res = tx.add(party._new({ package: params.partyPackageId, arguments: [kind, params.name] }));
+    tx.add(party.share({ package: params.partyPackageId, arguments: [res[0]!, res[1]!] }));
+    tx.transferObjects([res[1]!], params.recipient);
+  };
+}
+
+/** Creates a group party (empty member set), shares it, transfers its admin cap. */
+export function createGroupParty(params: CreatePartyParams): TxThunk {
+  return (tx) => {
+    const kind = tx.add(party.newGroupKind({ package: params.partyPackageId }));
+    const res = tx.add(party._new({ package: params.partyPackageId, arguments: [kind, params.name] }));
+    tx.add(party.share({ package: params.partyPackageId, arguments: [res[0]!, res[1]!] }));
+    tx.transferObjects([res[1]!], params.recipient);
+  };
+}
+
+// === Group membership: invite / accept / decline / revoke / leave / evict ===
+// Membership is consent-based: the group admin invites, the member accepts with
+// its OWN admin cap. `member`/`group`/`*Cap` params are all object ids.
+
+export interface InvitePartyParams {
+  groupId: string;
+  groupCapId: string;
+  /** The individual party (shared object id) to invite. */
+  memberId: string;
+  partyPackageId: string;
+}
+
+/** Invites an individual party to a group (gated by the group's admin cap). */
+export function inviteParty(params: InvitePartyParams): TxThunk {
+  return (tx) => {
+    tx.add(party.inviteParty({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.groupCapId],
+    }));
+  };
+}
+
+export interface AcceptInviteParams {
+  groupId: string;
+  memberId: string;
+  /** The member party's admin cap id (proves consent). */
+  memberCapId: string;
+  partyPackageId: string;
+}
+
+/** Accepts a pending invite, joining the member to the group (member's cap). */
+export function acceptInvite(params: AcceptInviteParams): TxThunk {
+  return (tx) => {
+    tx.add(party.acceptInvite({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.memberCapId],
+    }));
+  };
+}
+
+export interface DeclineInviteParams {
+  groupId: string;
+  /** The invited individual party (shared object id). */
+  memberId: string;
+  memberCapId: string;
+  partyPackageId: string;
+}
+
+/** Declines a pending invite (member's cap). */
+export function declineInvite(params: DeclineInviteParams): TxThunk {
+  return (tx) => {
+    tx.add(party.declineInvite({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.memberCapId],
+    }));
+  };
+}
+
+export interface RevokeInviteParams {
+  groupId: string;
+  /** The invited individual party (shared object id). */
+  memberId: string;
+  groupCapId: string;
+  partyPackageId: string;
+}
+
+/** Revokes a pending invite (group's admin cap). */
+export function revokeInvite(params: RevokeInviteParams): TxThunk {
+  return (tx) => {
+    tx.add(party.revokeInvite({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.groupCapId],
+    }));
+  };
+}
+
+export interface LeaveGroupParams {
+  groupId: string;
+  memberId: string;
+  memberCapId: string;
+  partyPackageId: string;
+}
+
+/** Leaves a group, authorized by the member's own admin cap. */
+export function leaveGroup(params: LeaveGroupParams): TxThunk {
+  return (tx) => {
+    tx.add(party.leave({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.memberId, params.memberCapId],
+    }));
+  };
+}
+
+export interface RemoveMemberParams {
+  groupId: string;
+  groupCapId: string;
+  memberId: string;
+  partyPackageId: string;
+}
+
+/** Evicts a member from a group (group's admin cap); scrubs the member's record too. */
+export function removeMember(params: RemoveMemberParams): TxThunk {
+  return (tx) => {
+    tx.add(party.removeMember({
+      package: params.partyPackageId,
+      arguments: [params.groupId, params.groupCapId, params.memberId],
+    }));
+  };
+}
+
+export interface SetNameParams {
+  partyId: string;
+  capId: string;
+  name: string;
+  partyPackageId: string;
+}
+
+/** Sets the party's human-readable name. */
+export function setName(params: SetNameParams): TxThunk {
+  return (tx) => {
+    tx.add(party.setName({
+      package: params.partyPackageId,
+      arguments: [params.partyId, params.capId, params.name],
+    }));
+  };
+}

package/src/types.ts

@@ -0,0 +1,18 @@
+// Copyright (c) Miso Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+// Public, camelCase result types. The mappers in ./internal.ts turn the generated
+// (snake_case, Move-shaped) parse output into these.
+
+export type PartyKind = "individual" | "group";
+
+export interface Party {
+  id: string;
+  kind: PartyKind;
+  /** Human-readable name (not verified). */
+  name: string;
+  /** Member party ids — present only when `kind === "group"`. */
+  members?: string[];
+  /** Unix ms when the party was created. */
+  createdAtMs: number;
+}