@interest-protocol/blast-partners-sdk 0.0.0-stage → 0.2.0

package/src/reducer.ts

@@ -0,0 +1,162 @@
+import { U64_MAX } from "@interest-protocol/blast-core/integers";
+import type {
+  DecodedPartnerDelayedEvent,
+  DecodedPartnerEvent,
+  PartnerEventKind,
+} from "./events.ts";
+import { partnerEventBcs, partnerEventId } from "./events.ts";
+
+/** A proposed share or cap: it applies only when someone applies it, at or after `readyAtMs`. */
+export type PartnerProposal<T> = { value: T; readyAtMs: bigint };
+
+export type PartnerProjection = {
+  partnerId: string;
+  /** Null until the partner's `PartnerUpdated`. */
+  recipient: string | null;
+  /** The applied share in basis points; null until its `DelayedCreated`. */
+  shareBps: bigint | null;
+  /** The applied managing cap; null until its `DelayedCreated`. */
+  capId: string | null;
+  pendingShare: PartnerProposal<bigint> | null;
+  pendingCap: PartnerProposal<string> | null;
+  /** Everything sent to the partner, by coin type. */
+  paid: Readonly<Record<string, bigint>>;
+};
+
+/**
+ * Partners rebuilt from their events and their `blast_admin::delayed` events
+ * (`decodePartnerDelayedEvent`); terms match `PartnerState` once replayed.
+ */
+export type PartnersEventProjection = {
+  appliedEventIds: Readonly<Record<string, true>>;
+  /** Counts `blast_partners` events only. */
+  eventCounts: Readonly<Record<PartnerEventKind, number>>;
+  partners: Readonly<Record<string, PartnerProjection>>;
+  /**
+   * Each `PartnerList` by parent (the product configuration's ID): every
+   * partner it named and the millisecond its acceptance ends (`U64_MAX`
+   * while accepted without end). A destroyed list is removed.
+   */
+  lists: Readonly<Record<string, Readonly<Record<string, bigint>>>>;
+};
+
+export function createPartnersEventProjection(): PartnersEventProjection {
+  return {
+    appliedEventIds: {},
+    eventCounts: Object.fromEntries(
+      Object.keys(partnerEventBcs).map((kind) => [kind, 0]),
+    ) as Record<PartnerEventKind, number>,
+    partners: {},
+    lists: {},
+  };
+}
+
+/** Applies one event once; replaying an applied event returns `state` unchanged. */
+export function reducePartnerEvent(
+  state: PartnersEventProjection,
+  event: DecodedPartnerEvent | DecodedPartnerDelayedEvent,
+): PartnersEventProjection {
+  const eventId = partnerEventId(event);
+  if (state.appliedEventIds[eventId]) return state;
+  const applied = { ...state.appliedEventIds, [eventId]: true as const };
+  if (event.source === "delayed") {
+    const partnerId = event.payload.parent;
+    return withPartner(
+      { ...state, appliedEventIds: applied },
+      reduceTerms(state.partners[partnerId] ?? empty(partnerId), event),
+    );
+  }
+  const next: PartnersEventProjection = {
+    ...state,
+    appliedEventIds: applied,
+    eventCounts: {
+      ...state.eventCounts,
+      [event.kind]: state.eventCounts[event.kind] + 1,
+    },
+  };
+  if (event.kind === "PartnerListDestroyed") {
+    const { [event.payload.parent]: _, ...lists } = state.lists;
+    return { ...next, lists };
+  }
+  if (event.kind === "PartnerAdded" || event.kind === "PartnerRemoved") {
+    const { parent, partner_id } = event.payload;
+    const acceptanceEndsAtMs =
+      event.kind === "PartnerAdded"
+        ? U64_MAX
+        : event.payload.acceptance_ends_at_ms;
+    return {
+      ...next,
+      lists: {
+        ...state.lists,
+        [parent]: { ...state.lists[parent], [partner_id]: acceptanceEndsAtMs },
+      },
+    };
+  }
+  const partnerId = event.payload.partner_id;
+  const current = state.partners[partnerId];
+  if (event.kind === "PartnerUpdated")
+    return withPartner(next, {
+      ...(current ?? empty(partnerId)),
+      recipient: event.payload.recipient,
+    });
+  // A partner is registered before it can be paid.
+  if (!current) return next;
+  const coinType = event.coinType;
+  return withPartner(next, {
+    ...current,
+    paid: {
+      ...current.paid,
+      [coinType]: (current.paid[coinType] ?? 0n) + event.payload.amount,
+    },
+  });
+}
+
+/** Applied and proposed terms; readiness alone changes nothing. */
+function reduceTerms(
+  partner: PartnerProjection,
+  event: DecodedPartnerDelayedEvent,
+): PartnerProjection {
+  const [applied, pending] =
+    event.name === "Share"
+      ? (["shareBps", "pendingShare"] as const)
+      : (["capId", "pendingCap"] as const);
+  switch (event.kind) {
+    case "DelayedCreated":
+    case "DelayedApplied":
+      return { ...partner, [applied]: event.payload.value, [pending]: null };
+    case "DelayedScheduled":
+      return {
+        ...partner,
+        [pending]: {
+          value: event.payload.value,
+          readyAtMs: event.payload.ready_at_ms,
+        },
+      };
+    case "DelayedCancelled":
+      return { ...partner, [pending]: null };
+    default:
+      return partner;
+  }
+}
+
+function empty(partnerId: string): PartnerProjection {
+  return {
+    partnerId,
+    recipient: null,
+    shareBps: null,
+    capId: null,
+    pendingShare: null,
+    pendingCap: null,
+    paid: {},
+  };
+}
+
+function withPartner(
+  state: PartnersEventProjection,
+  partner: PartnerProjection,
+): PartnersEventProjection {
+  return {
+    ...state,
+    partners: { ...state.partners, [partner.partnerId]: partner },
+  };
+}

package/src/state.ts

@@ -0,0 +1,166 @@
+import type { Delayed } from "@interest-protocol/blast-core/bcs";
+import {
+  addressBcs,
+  delayedBcs,
+  suiObjectIdBcs,
+  suiUidBcs,
+  tableBcs,
+  u64Bcs,
+  unitKeyBcs,
+} from "@interest-protocol/blast-core/bcs";
+import {
+  BASIS_POINTS_DENOMINATOR,
+  mulDivDown,
+  normalizePositiveU64,
+} from "@interest-protocol/blast-core/integers";
+import type { SharedObjectIdentity } from "@interest-protocol/blast-core/sui";
+import { bcs } from "@mysten/sui/bcs";
+import type { ClientWithCoreApi } from "@mysten/sui/client";
+import { ObjectError } from "@mysten/sui/client";
+import { normalizeSuiObjectId, parseStructTag } from "@mysten/sui/utils";
+
+/**
+ * `blast_partners::delay_ms`: the fixed notice before a share or cap Blast
+ * proposes can be applied.
+ */
+export const PARTNER_DELAY_MS = 604_800_000n;
+
+/**
+ * The partner's recipient, share and managing cap, as Move stores them. A
+ * share or cap proposal changes nothing until someone applies it.
+ */
+export type PartnerTerms = {
+  recipient: string;
+  /** Basis points of Blast's fee on each trade naming the partner. */
+  shareBps: Delayed<null, bigint>;
+  /** The only `PartnerCap` that may set `recipient`. */
+  capId: Delayed<null, string>;
+};
+
+export const partnerTermsBcs = {
+  recipient: addressBcs,
+  share_bps: delayedBcs(unitKeyBcs, u64Bcs),
+  cap_id: delayedBcs(unitKeyBcs, suiObjectIdBcs),
+};
+
+/** BCS layout of `blast_partners::blast_partners::Partner`. */
+export const partnerBcs = bcs.struct("Partner", {
+  id: suiUidBcs,
+  ...partnerTermsBcs,
+});
+
+export type PartnerState = SharedObjectIdentity & PartnerTerms;
+
+export type PartnerObject = SharedObjectIdentity & {
+  type: string;
+  content: Uint8Array;
+};
+
+export function decodePartnerObject(
+  object: PartnerObject,
+  partnersPackageId: string,
+): PartnerState {
+  const tag = parseStructTag(object.type);
+  if (
+    tag.address !== normalizeSuiObjectId(partnersPackageId) ||
+    tag.module !== "blast_partners" ||
+    tag.name !== "Partner"
+  ) {
+    throw new TypeError(`object ${object.objectId} is not a Blast partner`);
+  }
+  const parsed = partnerBcs.parse(object.content);
+  const objectId = normalizeSuiObjectId(object.objectId);
+  if (
+    normalizeSuiObjectId(parsed.id.id.bytes) !== objectId ||
+    parsed.share_bps.parent !== objectId ||
+    parsed.cap_id.parent !== objectId
+  ) {
+    throw new TypeError(`partner ${object.objectId} has a mismatched UID`);
+  }
+  return {
+    objectId,
+    initialSharedVersion: normalizePositiveU64(
+      "initialSharedVersion",
+      object.initialSharedVersion,
+    ),
+    recipient: parsed.recipient,
+    shareBps: parsed.share_bps,
+    capId: parsed.cap_id,
+  };
+}
+
+export async function getPartner(
+  client: ClientWithCoreApi,
+  objectId: string,
+  partnersPackageId: string,
+): Promise<PartnerState> {
+  const { object } = await client.core.getObject({
+    objectId,
+    include: { content: true },
+  });
+  if (object.owner.$kind !== "Shared") {
+    throw new TypeError(`partner ${object.objectId} is not a shared object`);
+  }
+  return decodePartnerObject(
+    {
+      objectId: object.objectId,
+      initialSharedVersion: object.owner.Shared.initialSharedVersion,
+      type: object.type,
+      content: object.content,
+    },
+    partnersPackageId,
+  );
+}
+
+/**
+ * Mirrors `blast_partners::pay`: the partner's applied share of `fee`
+ * (Blast's fee on one trade, in that coin's atoms), rounded down; Blast keeps
+ * the remainder.
+ */
+export function partnerPayment(
+  partner: Pick<PartnerTerms, "shareBps">,
+  fee: bigint,
+): bigint {
+  return mulDivDown(fee, partner.shareBps.value, BASIS_POINTS_DENOMINATOR);
+}
+
+/**
+ * BCS layout of `blast_partners::partner_list::PartnerList`, embedded in a
+ * product's configuration (`LaunchConfig.partners`,
+ * `CreationPolicy.partners`). `parent` is that configuration's ID; each
+ * accepted partner is an entry of the `acceptance_ends_at_ms` table.
+ */
+export const partnerListBcs = bcs.struct("PartnerList", {
+  parent: suiObjectIdBcs,
+  acceptance_ends_at_ms: tableBcs,
+});
+
+export type PartnerList = ReturnType<typeof partnerListBcs.parse>;
+
+/**
+ * Reads one entry of a `PartnerList`'s `acceptance_ends_at_ms` table (its
+ * `id`): the millisecond from which new sales stop naming `partnerId`, or
+ * `U64_MAX` while it is accepted without end. Null when the list never
+ * accepted the partner. A partner is accepted at `now` when `now` is before
+ * the returned time (`partner_list::is_accepted`).
+ */
+export async function getPartnerAcceptance(
+  client: ClientWithCoreApi,
+  listTableId: string,
+  partnerId: string,
+): Promise<bigint | null> {
+  try {
+    const { dynamicField } = await client.core.getDynamicField({
+      parentId: normalizeSuiObjectId(listTableId),
+      name: {
+        type: "0x2::object::ID",
+        bcs: suiObjectIdBcs.serialize(partnerId).toBytes(),
+      },
+    });
+    return u64Bcs.parse(dynamicField.value.bcs);
+  } catch (error) {
+    if (error instanceof ObjectError && error.reason === "notFound")
+      return null;
+    throw error;
+  }
+}

package/src/transactions.ts

@@ -0,0 +1,327 @@
+import type { AdminDeployment } from "@interest-protocol/blast-admin-sdk/transactions";
+import {
+  AdminCalls,
+  normalizeAdminDeployment,
+} from "@interest-protocol/blast-admin-sdk/transactions";
+import { requireBasisPoints } from "@interest-protocol/blast-core/integers";
+import type { SharedObjectReference } from "@interest-protocol/blast-core/sui";
+import { normalizeSharedObjectReference } from "@interest-protocol/blast-core/sui";
+import type {
+  TransactionObjectArgument,
+  TransactionObjectInput,
+  TransactionResult,
+} from "@mysten/sui/transactions";
+import { Transaction } from "@mysten/sui/transactions";
+import { normalizeSuiAddress, normalizeSuiObjectId } from "@mysten/sui/utils";
+
+/** The canonical `blast_partners` package (immutability deferred) and the ACL its `PartnerAdmin` signs in to. */
+export type PartnersDeployment = {
+  packageId: string;
+  admin: AdminDeployment;
+};
+
+/** `blast_partners::blast_partners` calls. */
+export class PartnersCalls {
+  readonly deployment: PartnersDeployment;
+  readonly admin: AdminCalls;
+
+  constructor(deployment: PartnersDeployment) {
+    this.deployment = {
+      packageId: normalizeSuiObjectId(deployment.packageId),
+      admin: normalizeAdminDeployment(deployment.admin),
+    };
+    this.admin = new AdminCalls(this.deployment.admin);
+  }
+
+  /** The `PartnerAdmin` role type, for `AdminCalls.grantRole`. */
+  roleType(): string {
+    return `${this.deployment.packageId}::blast_partners::PartnerAdmin`;
+  }
+
+  /** This PTB's `AdminWitness<PartnerAdmin>`. */
+  signIn(options: { adminCap: TransactionObjectInput }) {
+    return this.admin.signIn({
+      adminCap: options.adminCap,
+      role: this.roleType(),
+    });
+  }
+
+  /** `new_cap`: anyone may mint one; it controls nothing until a partner names it. */
+  newCap() {
+    return (tx: Transaction): TransactionResult =>
+      tx.moveCall({ target: this.#target("new_cap") });
+  }
+
+  /**
+   * `register` (`PartnerAdmin`): shares a partner managed by the cap
+   * `capId`, its share and cap in force at once.
+   */
+  register(options: {
+    adminWitness: TransactionObjectInput;
+    capId: string;
+    recipient: string;
+    shareBps: bigint;
+  }) {
+    const capId = normalizeSuiObjectId(options.capId);
+    const recipient = normalizeSuiAddress(options.recipient);
+    const shareBps = requireBasisPoints("shareBps", options.shareBps);
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("register"),
+        arguments: [
+          tx.object(options.adminWitness),
+          tx.pure.id(capId),
+          tx.pure.address(recipient),
+          tx.pure.u64(shareBps),
+        ],
+      });
+    };
+  }
+
+  /**
+   * `schedule_share` (`PartnerAdmin`): proposes the share, which `applyShare`
+   * applies once `PARTNER_DELAY_MS` has passed. A new proposal replaces a
+   * pending one and restarts the notice.
+   */
+  scheduleShare(options: {
+    partner: SharedObjectReference<true>;
+    adminWitness: TransactionObjectInput;
+    shareBps: bigint;
+  }) {
+    const shareBps = requireBasisPoints("shareBps", options.shareBps);
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("schedule_share"),
+        arguments: [
+          partner(tx, options.partner),
+          tx.object(options.adminWitness),
+          tx.pure.u64(shareBps),
+          tx.object.clock(),
+        ],
+      });
+    };
+  }
+
+  /**
+   * `schedule_cap` (`PartnerAdmin`): proposes moving the partner to the cap
+   * `capId`, which `applyCap` applies once `PARTNER_DELAY_MS` has passed.
+   */
+  scheduleCap(options: {
+    partner: SharedObjectReference<true>;
+    adminWitness: TransactionObjectInput;
+    capId: string;
+  }) {
+    const capId = normalizeSuiObjectId(options.capId);
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("schedule_cap"),
+        arguments: [
+          partner(tx, options.partner),
+          tx.object(options.adminWitness),
+          tx.pure.id(capId),
+          tx.object.clock(),
+        ],
+      });
+    };
+  }
+
+  /** `apply_share`: anyone applies the proposed share once its notice has passed. */
+  applyShare(options: { partner: SharedObjectReference<true> }) {
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("apply_share"),
+        arguments: [partner(tx, options.partner), tx.object.clock()],
+      });
+    };
+  }
+
+  /** `apply_cap`: anyone applies the proposed managing cap once its notice has passed. */
+  applyCap(options: { partner: SharedObjectReference<true> }) {
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("apply_cap"),
+        arguments: [partner(tx, options.partner), tx.object.clock()],
+      });
+    };
+  }
+
+  /** `cancel_share` (`PartnerAdmin`): discards the proposed share, even a ready one. */
+  cancelShare(options: {
+    partner: SharedObjectReference<true>;
+    adminWitness: TransactionObjectInput;
+  }) {
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("cancel_share"),
+        arguments: [
+          partner(tx, options.partner),
+          tx.object(options.adminWitness),
+        ],
+      });
+    };
+  }
+
+  /** `cancel_cap` (`PartnerAdmin`): discards the proposed managing cap, even a ready one. */
+  cancelCap(options: {
+    partner: SharedObjectReference<true>;
+    adminWitness: TransactionObjectInput;
+  }) {
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("cancel_cap"),
+        arguments: [
+          partner(tx, options.partner),
+          tx.object(options.adminWitness),
+        ],
+      });
+    };
+  }
+
+  /** `set_recipient`: the partner's applied cap sets where it is paid, at once. */
+  setRecipient(options: {
+    partner: SharedObjectReference<true>;
+    partnerCap: TransactionObjectInput;
+    recipient: string;
+  }) {
+    const recipient = normalizeSuiAddress(options.recipient);
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("set_recipient"),
+        arguments: [
+          partner(tx, options.partner),
+          tx.object(options.partnerCap),
+          tx.pure.address(recipient),
+        ],
+      });
+    };
+  }
+
+  destroyCap(options: { partnerCap: TransactionObjectInput }) {
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("destroy_cap"),
+        arguments: [tx.object(options.partnerCap)],
+      });
+    };
+  }
+
+  #target(functionName: string): string {
+    return `${this.deployment.packageId}::blast_partners::${functionName}`;
+  }
+}
+
+export class PartnersTransactions {
+  readonly call: PartnersCalls;
+
+  constructor(deployment: PartnersDeployment) {
+    this.call = new PartnersCalls(deployment);
+  }
+
+  /** Mints a `PartnerCap` and sends it to `recipient`. */
+  newCap(options: { recipient: string }): Transaction {
+    const tx = new Transaction();
+    const cap = tx.add(this.call.newCap());
+    tx.transferObjects([cap], normalizeSuiAddress(options.recipient));
+    return tx;
+  }
+
+  register(options: {
+    adminCapId: string;
+    capId: string;
+    recipient: string;
+    shareBps: bigint;
+  }): Transaction {
+    return this.#asPartnerAdmin(options.adminCapId, (adminWitness) =>
+      this.call.register({ ...options, adminWitness }),
+    );
+  }
+
+  scheduleShare(options: {
+    adminCapId: string;
+    partner: SharedObjectReference<true>;
+    shareBps: bigint;
+  }): Transaction {
+    return this.#asPartnerAdmin(options.adminCapId, (adminWitness) =>
+      this.call.scheduleShare({ ...options, adminWitness }),
+    );
+  }
+
+  scheduleCap(options: {
+    adminCapId: string;
+    partner: SharedObjectReference<true>;
+    capId: string;
+  }): Transaction {
+    return this.#asPartnerAdmin(options.adminCapId, (adminWitness) =>
+      this.call.scheduleCap({ ...options, adminWitness }),
+    );
+  }
+
+  applyShare(options: { partner: SharedObjectReference<true> }): Transaction {
+    const tx = new Transaction();
+    tx.add(this.call.applyShare(options));
+    return tx;
+  }
+
+  applyCap(options: { partner: SharedObjectReference<true> }): Transaction {
+    const tx = new Transaction();
+    tx.add(this.call.applyCap(options));
+    return tx;
+  }
+
+  cancelShare(options: {
+    adminCapId: string;
+    partner: SharedObjectReference<true>;
+  }): Transaction {
+    return this.#asPartnerAdmin(options.adminCapId, (adminWitness) =>
+      this.call.cancelShare({ ...options, adminWitness }),
+    );
+  }
+
+  cancelCap(options: {
+    adminCapId: string;
+    partner: SharedObjectReference<true>;
+  }): Transaction {
+    return this.#asPartnerAdmin(options.adminCapId, (adminWitness) =>
+      this.call.cancelCap({ ...options, adminWitness }),
+    );
+  }
+
+  setRecipient(options: {
+    partner: SharedObjectReference<true>;
+    partnerCapId: string;
+    recipient: string;
+  }): Transaction {
+    const tx = new Transaction();
+    tx.add(
+      this.call.setRecipient({ ...options, partnerCap: options.partnerCapId }),
+    );
+    return tx;
+  }
+
+  destroyCap(options: { partnerCapId: string }): Transaction {
+    const tx = new Transaction();
+    tx.add(this.call.destroyCap({ partnerCap: options.partnerCapId }));
+    return tx;
+  }
+
+  #asPartnerAdmin(
+    adminCapId: string,
+    call: (
+      adminWitness: TransactionObjectArgument,
+    ) => (tx: Transaction) => void,
+  ): Transaction {
+    const tx = new Transaction();
+    const adminWitness = tx.add(this.call.signIn({ adminCap: adminCapId }));
+    tx.add(call(adminWitness));
+    return tx;
+  }
+}
+
+function partner(
+  tx: Transaction,
+  reference: SharedObjectReference<true>,
+): TransactionObjectArgument {
+  return tx.sharedObjectRef(
+    normalizeSharedObjectReference("partner", reference, true),
+  );
+}