@interest-protocol/blast-partners-sdk 0.1.0 → 0.2.0

package/src/state.ts

@@ -1,8 +1,12 @@
+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,
@@ -10,31 +14,33 @@ import {
   normalizePositiveU64,
 } from "@interest-protocol/blast-core/integers";
 import type { SharedObjectIdentity } from "@interest-protocol/blast-core/sui";
-import type { Timelocked } from "@interest-protocol/blast-core/timelock";
-import {
-  timelockedBcs,
-  timelockedValue,
-} from "@interest-protocol/blast-core/timelock";
 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`: every change Blast makes to a partner waits this long. */
+/**
+ * `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, scheduled share, and managing cap, as Move stores them. */
+/**
+ * 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: Timelocked<bigint>;
+  shareBps: Delayed<null, bigint>;
   /** The only `PartnerCap` that may set `recipient`. */
-  capId: Timelocked<string>;
+  capId: Delayed<null, string>;
 };
 
 export const partnerTermsBcs = {
   recipient: addressBcs,
-  share_bps: timelockedBcs(u64Bcs),
-  cap_id: timelockedBcs(suiObjectIdBcs),
+  share_bps: delayedBcs(unitKeyBcs, u64Bcs),
+  cap_id: delayedBcs(unitKeyBcs, suiObjectIdBcs),
 };
 
 /** BCS layout of `blast_partners::blast_partners::Partner`. */
@@ -64,7 +70,11 @@ export function decodePartnerObject(
   }
   const parsed = partnerBcs.parse(object.content);
   const objectId = normalizeSuiObjectId(object.objectId);
-  if (normalizeSuiObjectId(parsed.id.id.bytes) !== 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 {
@@ -103,18 +113,54 @@ export async function getPartner(
 }
 
 /**
- * Mirrors `blast_partners::pay`: the partner's share of `fee` (Blast's fee on
- * one trade, in that coin's atoms) at `nowMs`, rounded down; Blast keeps the
- * remainder.
+ * 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,
-  nowMs: bigint,
 ): bigint {
-  return mulDivDown(
-    fee,
-    timelockedValue(partner.shareBps, nowMs),
-    BASIS_POINTS_DENOMINATOR,
-  );
+  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

@@ -14,7 +14,7 @@ import type {
 import { Transaction } from "@mysten/sui/transactions";
 import { normalizeSuiAddress, normalizeSuiObjectId } from "@mysten/sui/utils";
 
-/** The immutable `blast_partners` package and the ACL its `PartnerAdmin` signs in to. */
+/** The canonical `blast_partners` package (immutability deferred) and the ACL its `PartnerAdmin` signs in to. */
 export type PartnersDeployment = {
   packageId: string;
   admin: AdminDeployment;
@@ -78,7 +78,11 @@ export class PartnersCalls {
     };
   }
 
-  /** `schedule_share` (`PartnerAdmin`): the share takes effect after the partner delay. */
+  /**
+   * `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;
@@ -98,7 +102,10 @@ export class PartnersCalls {
     };
   }
 
-  /** `schedule_cap` (`PartnerAdmin`): moves the partner to the cap `capId` after the delay. */
+  /**
+   * `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;
@@ -118,7 +125,59 @@ export class PartnersCalls {
     };
   }
 
-  /** `set_recipient`: the partner's live cap sets where it is paid, at once. */
+  /** `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;
@@ -132,7 +191,6 @@ export class PartnersCalls {
           partner(tx, options.partner),
           tx.object(options.partnerCap),
           tx.pure.address(recipient),
-          tx.object.clock(),
         ],
       });
     };
@@ -198,6 +256,36 @@ export class PartnersTransactions {
     );
   }
 
+  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;