@interest-protocol/blast-core 0.1.0 → 0.2.0

package/src/bcs.ts

@@ -1,3 +1,4 @@
+import type { BcsType } from "@mysten/sui/bcs";
 import { bcs } from "@mysten/sui/bcs";
 import {
   normalizeStructTag,
@@ -18,11 +19,22 @@ const asciiStringBcs = bcs.struct("AsciiString", {
   bytes: bcs.vector(bcs.u8()),
 });
 
+/**
+ * `std::type_name::TypeName`. Move stores the type with every address as 64
+ * hex digits and no `0x`; the SDK reads and writes normalized struct tags, so
+ * `serialize(parse(bytes))` returns the Move bytes.
+ */
 export const moveTypeNameBcs = bcs
   .struct("TypeName", { name: asciiStringBcs })
   .transform({
     input: (value: string) => ({
-      name: { bytes: Array.from(new TextEncoder().encode(value)) },
+      name: {
+        bytes: Array.from(
+          new TextEncoder().encode(
+            normalizeStructTag(value).replace(/0x([0-9a-f]{64})/g, "$1"),
+          ),
+        ),
+      },
     }),
     output: (value) =>
       normalizeStructTag(
@@ -35,7 +47,368 @@ export const u64Bcs = bcs.u64().transform({
   output: (value) => BigInt(value),
 });
 
+/** A `Balance<T>` decoded as its atomic amount. */
+export const balanceBcs = bcs.struct("Balance", { value: u64Bcs }).transform({
+  input: (value: bigint) => ({ value }),
+  output: (balance) => balance.value,
+});
+
 export const addressBcs = bcs.Address.transform({
   input: (value: string) => normalizeSuiAddress(value),
   output: (value) => normalizeSuiAddress(value),
 });
+
+/**
+ * A zero-field Move key such as `TradeFeesKey()`: Move gives it one
+ * `dummy_field: bool`, so it encodes as one byte.
+ */
+export const unitKeyBcs = bcs
+  .struct("Key", { dummy_field: bcs.bool() })
+  .transform({
+    input: (_: null) => ({ dummy_field: false }),
+    output: (): null => null,
+  });
+
+/** `0x2::vec_set::VecSet<E>`: its `contents` vector, decoded as the members. */
+export function vecSetBcs<E, Input>(element: BcsType<E, Input>) {
+  return bcs.struct("VecSet", { contents: bcs.vector(element) }).transform({
+    input: (members: Input[]) => ({ contents: members }),
+    output: (set): E[] => set.contents,
+  });
+}
+
+/** `0x2::table::Table<K, V>`: its UID and size; entries are dynamic fields of `id`. */
+export const tableBcs = bcs.struct("Table", {
+  id: suiObjectIdBcs,
+  size: u64Bcs,
+});
+
+/** `blast_admin::delayed::Proposal<T>`: the value and the delay in force once it applies. */
+export type Proposal<T> = { value: T; delay_ms: bigint; ready_at_ms: bigint };
+
+export function proposalBcs<T, Input>(value: BcsType<T, Input>) {
+  return bcs.struct("Proposal", {
+    value,
+    delay_ms: u64Bcs,
+    ready_at_ms: u64Bcs,
+  });
+}
+
+/** `blast_admin::delayed::Delayed<K, T>`: readiness never applies a value implicitly. */
+export type Delayed<K, T> = {
+  parent: string;
+  key: K;
+  value: T;
+  delay_ms: bigint;
+  pending: Proposal<T> | null;
+};
+
+/** Exact `blast_admin::delayed::Delayed<K, T>` field order. */
+export function delayedBcs<K, KeyInput, T, Input>(
+  key: BcsType<K, KeyInput>,
+  value: BcsType<T, Input>,
+) {
+  return bcs.struct("Delayed", {
+    parent: suiObjectIdBcs,
+    key,
+    value,
+    delay_ms: u64Bcs,
+    pending: bcs.option(proposalBcs(value)),
+  });
+}
+
+/** `blast_admin::delayed_action::Change<A>`: an action, or a change of delay only. */
+export type DelayedChange<A> =
+  | { kind: "Action"; action: A }
+  | { kind: "Delay" };
+
+export function delayedChangeBcs<A, Input>(action: BcsType<A, Input>) {
+  return bcs.enum("Change", { Action: action, Delay: null }).transform({
+    input: (change: DelayedChange<Input>) =>
+      change.kind === "Action"
+        ? { Action: change.action }
+        : { Delay: true as const },
+    output: (change): DelayedChange<A> =>
+      change.$kind === "Action"
+        ? { kind: "Action", action: change.Action as A }
+        : { kind: "Delay" },
+  });
+}
+
+/** `blast_admin::delayed_action::DelayedAction<K, A>`: a one-shot action slot. */
+export type DelayedAction<K, A> = {
+  parent: string;
+  key: K;
+  delay_ms: bigint;
+  pending: Proposal<DelayedChange<A>> | null;
+};
+
+export function delayedActionBcs<K, KeyInput, A, Input>(
+  key: BcsType<K, KeyInput>,
+  action: BcsType<A, Input>,
+) {
+  return bcs.struct("DelayedAction", {
+    parent: suiObjectIdBcs,
+    key,
+    delay_ms: u64Bcs,
+    pending: bcs.option(proposalBcs(delayedChangeBcs(action))),
+  });
+}
+
+/** `blast_admin::delayed::PendingDelay`: a proposed next delay, ready from `ready_at_ms`. */
+export type PendingDelay = { delay_ms: bigint; ready_at_ms: bigint };
+
+export const pendingDelayBcs = bcs.struct("PendingDelay", {
+  delay_ms: u64Bcs,
+  ready_at_ms: u64Bcs,
+});
+
+/**
+ * `blast_admin::delayed::Deadline`: a pending admission's or entry change's
+ * fixed deadline and the applied delay it was scheduled under; a later delay
+ * change never moves it.
+ */
+export type Deadline = { delay_ms: bigint; ready_at_ms: bigint };
+
+export const deadlineBcs = bcs.struct("Deadline", {
+  delay_ms: u64Bcs,
+  ready_at_ms: u64Bcs,
+});
+
+/** `blast_admin::delayed_set::DelayedSet<K, E>`: admissions wait; removals are immediate. */
+export type DelayedSet<K, E> = {
+  parent: string;
+  key: K;
+  members: E[];
+  delay_ms: bigint;
+  admissions: { member: E; deadline: Deadline }[];
+  pending_delay: PendingDelay | null;
+};
+
+/**
+ * `blast_admin::delayed::max_delay_ms`: no delayed value, action, set or map
+ * accepts a longer delay, in milliseconds (30 days); one aborts with
+ * `blast_admin` error 15 (`EInvalidDelay`).
+ */
+export const MAX_DELAY_MS = 2_592_000_000n;
+
+/**
+ * `delayed::is_guarded`: the applied delay is nonzero and no proposal would
+ * set it to zero. `package_admin::unpause` requires every policy guarded.
+ */
+export function isDelayedGuarded(self: Delayed<unknown, unknown>): boolean {
+  return self.delay_ms > 0n && (self.pending?.delay_ms ?? 1n) > 0n;
+}
+
+/** `delayed_action::is_guarded`, as `isDelayedGuarded`. */
+export function isDelayedActionGuarded(
+  self: DelayedAction<unknown, unknown>,
+): boolean {
+  return self.delay_ms > 0n && (self.pending?.delay_ms ?? 1n) > 0n;
+}
+
+/** `delayed_set::is_guarded`: also no admission scheduled earlier is pending. */
+export function isDelayedSetGuarded(
+  self: DelayedSet<unknown, unknown>,
+): boolean {
+  return (
+    self.delay_ms > 0n &&
+    self.admissions.length === 0 &&
+    (self.pending_delay?.delay_ms ?? 1n) > 0n
+  );
+}
+
+export function delayedSetBcs<K, KeyInput, E, Input>(
+  key: BcsType<K, KeyInput>,
+  member: BcsType<E, Input>,
+) {
+  return bcs
+    .struct("DelayedSet", {
+      parent: suiObjectIdBcs,
+      key,
+      members: bcs.struct("VecSet", { contents: bcs.vector(member) }),
+      delay_ms: u64Bcs,
+      admissions: bcs.struct("VecMap", {
+        contents: bcs.vector(
+          bcs.struct("Entry", { key: member, value: deadlineBcs }),
+        ),
+      }),
+      pending_delay: bcs.option(pendingDelayBcs),
+    })
+    .transform({
+      input: (set: {
+        parent: string;
+        key: KeyInput;
+        members: Input[];
+        delay_ms: bigint;
+        admissions: { member: Input; deadline: Deadline }[];
+        pending_delay: PendingDelay | null;
+      }) => ({
+        parent: set.parent,
+        key: set.key,
+        members: { contents: set.members },
+        delay_ms: set.delay_ms,
+        admissions: {
+          contents: set.admissions.map(({ member, deadline }) => ({
+            key: member,
+            value: deadline,
+          })),
+        },
+        pending_delay: set.pending_delay,
+      }),
+      output: (set): DelayedSet<K, E> => ({
+        parent: set.parent,
+        key: set.key,
+        members: set.members.contents,
+        delay_ms: set.delay_ms,
+        admissions: set.admissions.contents.map(({ key, value }) => ({
+          member: key,
+          deadline: value,
+        })),
+        pending_delay: set.pending_delay,
+      }),
+    });
+}
+
+/** `blast_admin::delayed_set::SetChange<E>`: an admission, or a delay change. */
+export type DelayedSetChange<E> =
+  | { kind: "Admission"; member: E }
+  | { kind: "Delay" };
+
+export function delayedSetChangeBcs<E, Input>(member: BcsType<E, Input>) {
+  return bcs.enum("SetChange", { Admission: member, Delay: null }).transform({
+    input: (change: DelayedSetChange<Input>) =>
+      change.kind === "Admission"
+        ? { Admission: change.member }
+        : { Delay: true as const },
+    output: (change): DelayedSetChange<E> =>
+      change.$kind === "Admission"
+        ? { kind: "Admission", member: change.Admission as E }
+        : { kind: "Delay" },
+  });
+}
+
+/** `blast_admin::delayed_map::EntryProposal<V>`: a value, or null to clear, and its fixed deadline. */
+export type EntryProposal<V> = { value: V | null; deadline: Deadline };
+
+export function entryProposalBcs<V, Input>(value: BcsType<V, Input>) {
+  return bcs.struct("EntryProposal", {
+    value: bcs.option(value),
+    deadline: deadlineBcs,
+  });
+}
+
+/** `blast_admin::delayed_map::MapChange<E, V>`: an entry change, or a delay change. */
+export type DelayedMapChange<E, V> =
+  | { kind: "Entry"; entry: E; value: V | null }
+  | { kind: "Delay" };
+
+export function delayedMapChangeBcs<E, EntryInput, V, Input>(
+  entry: BcsType<E, EntryInput>,
+  value: BcsType<V, Input>,
+) {
+  return bcs
+    .enum("MapChange", {
+      Entry: bcs.struct("Entry", { entry, value: bcs.option(value) }),
+      Delay: null,
+    })
+    .transform({
+      input: (change: DelayedMapChange<EntryInput, Input>) =>
+        change.kind === "Entry"
+          ? { Entry: { entry: change.entry, value: change.value } }
+          : { Delay: true as const },
+      output: (change): DelayedMapChange<E, V> =>
+        change.$kind === "Entry"
+          ? {
+              kind: "Entry",
+              entry: change.Entry.entry as E,
+              value: change.Entry.value as V | null,
+            }
+          : { kind: "Delay" },
+    });
+}
+
+/**
+ * `blast_admin::delayed_map::DelayedMap<K, E, V>`: applied entries in a
+ * `Table` (read by dynamic field), one delay, and inline pending changes.
+ */
+export type DelayedMap<K, E, V> = {
+  parent: string;
+  key: K;
+  entries: { id: string; size: bigint };
+  delay_ms: bigint;
+  pending: { entry: E; proposal: EntryProposal<V> }[];
+  pending_delay: PendingDelay | null;
+};
+
+export function delayedMapBcs<K, KeyInput, E, EntryInput, V, Input>(
+  key: BcsType<K, KeyInput>,
+  entry: BcsType<E, EntryInput>,
+  value: BcsType<V, Input>,
+) {
+  return bcs
+    .struct("DelayedMap", {
+      parent: suiObjectIdBcs,
+      key,
+      entries: tableBcs,
+      delay_ms: u64Bcs,
+      pending: bcs.struct("VecMap", {
+        contents: bcs.vector(
+          bcs.struct("Entry", { key: entry, value: entryProposalBcs(value) }),
+        ),
+      }),
+      pending_delay: bcs.option(pendingDelayBcs),
+    })
+    .transform({
+      input: (map: {
+        parent: string;
+        key: KeyInput;
+        entries: { id: string; size: bigint };
+        delay_ms: bigint;
+        pending: {
+          entry: EntryInput;
+          proposal: { value: Input | null; deadline: Deadline };
+        }[];
+        pending_delay: PendingDelay | null;
+      }) => ({
+        parent: map.parent,
+        key: map.key,
+        entries: map.entries,
+        delay_ms: map.delay_ms,
+        pending: {
+          contents: map.pending.map(({ entry, proposal }) => ({
+            key: entry,
+            value: proposal,
+          })),
+        },
+        pending_delay: map.pending_delay,
+      }),
+      output: (map): DelayedMap<K, E, V> => ({
+        parent: map.parent,
+        key: map.key,
+        entries: map.entries,
+        delay_ms: map.delay_ms,
+        pending: map.pending.contents.map(({ key, value }) => ({
+          entry: key,
+          proposal: value as EntryProposal<V>,
+        })),
+        pending_delay: map.pending_delay,
+      }),
+    });
+}
+
+/**
+ * A `DelayedSet` admission view: the admitted members, the applied delay, the
+ * proposed next delay, and each scheduled admission's deadline by member. Used
+ * for venue, witness and claim-signer allowlists alike.
+ */
+export function admission<E extends string>(set: DelayedSet<unknown, E>) {
+  return {
+    members: [...set.members],
+    delayMs: set.delay_ms,
+    pendingDelay: set.pending_delay,
+    pendingMembers: Object.fromEntries(
+      set.admissions.map(({ member, deadline }) => [member, deadline]),
+    ) as Readonly<Record<E, Deadline>>,
+  };
+}

package/src/bps.ts

@@ -0,0 +1,92 @@
+import { bcs } from "@mysten/sui/bcs";
+import { u64Bcs } from "./bcs.ts";
+import type { BasisPoints } from "./integers.ts";
+import {
+  BASIS_POINTS_DENOMINATOR,
+  mulDivUp,
+  requireBasisPoints,
+  requireU64,
+} from "./integers.ts";
+
+/** `blast_core::constants::max_lp_fee_bps`: Blast's largest LP-fee share of each asset. */
+export const MAX_LP_FEE_BPS = 3_000n;
+/** `blast_core::constants::max_routes`: the most routes one fee split holds. */
+export const MAX_ROUTES = 20;
+/** `blast_core::constants::max_vesting_duration_ms`: the technical bound on a schedule. */
+export const MAX_VESTING_DURATION_MS = 2n ** 63n;
+
+/** BCS layout of the positional `blast_core::bps::Bps(u64)`. */
+export const bpsBcs = bcs.struct("Bps", { value: u64Bcs }).transform({
+  input: (value: bigint) => ({ value: requireBps(value) }),
+  output: (value) => value.value,
+});
+
+/** Mirrors `bps::new`: a rate from zero through 10,000 basis points. */
+export function requireBps(value: bigint): BasisPoints {
+  return requireBasisPoints("bps", value);
+}
+
+/**
+ * Mirrors `bps::apply_up`: `ceil(amount * bps / 10,000)` over atomic units,
+ * at most `amount`.
+ */
+export function applyBpsUp(amount: bigint, bps: bigint): bigint {
+  return mulDivUp(
+    requireU64("amount", amount),
+    requireBps(bps),
+    BASIS_POINTS_DENOMINATOR,
+  );
+}
+
+/**
+ * Mirrors `bps::apportion`: largest-remainder apportionment of `total` atoms
+ * over `rates`, which must sum to exactly 10,000. The `roundedUp` part takes
+ * its ceiling and every other part its floor; the leftover atoms go one each
+ * to the largest remaining remainders, earlier parts first. The amounts sum
+ * to `total`. Throws where the contract aborts (`EInvalidApportionment`).
+ */
+export function apportionBps(
+  rates: readonly bigint[],
+  total: bigint,
+  roundedUp: number | null,
+): bigint[] {
+  requireU64("total", total);
+  rates.forEach(requireBps);
+  if (
+    rates.reduce((sum, rate) => sum + rate, 0n) !== BASIS_POINTS_DENOMINATOR ||
+    (roundedUp !== null &&
+      !(
+        Number.isInteger(roundedUp) &&
+        roundedUp >= 0 &&
+        roundedUp < rates.length
+      ))
+  ) {
+    throw new RangeError(
+      "apportioned rates must sum to 10,000 and name a rounded-up part inside them",
+    );
+  }
+  const products = rates.map((rate) => total * rate);
+  const amounts = products.map((product, index) =>
+    index === roundedUp
+      ? (product + BASIS_POINTS_DENOMINATOR - 1n) / BASIS_POINTS_DENOMINATOR
+      : product / BASIS_POINTS_DENOMINATOR,
+  );
+  const order = products
+    .map((product, index) => ({
+      index,
+      remainder: product % BASIS_POINTS_DENOMINATOR,
+    }))
+    .filter(({ index }) => index !== roundedUp)
+    .sort((left, right) =>
+      left.remainder === right.remainder
+        ? left.index - right.index
+        : left.remainder > right.remainder
+          ? -1
+          : 1,
+    );
+  const leftover = Number(total - amounts.reduce((sum, a) => sum + a, 0n));
+  for (const { index } of order.slice(0, leftover)) {
+    amounts[index] = (amounts[index] ?? 0n) + 1n;
+  }
+  return amounts;
+}

package/src/bytecode-template.ts

@@ -2,6 +2,12 @@ import initBytecodeTemplate, {
   deserialize,
 } from "@mysten/move-bytecode-template";
 import { bcs } from "@mysten/sui/bcs";
+import {
+  isValidSuiObjectId,
+  MOVE_STDLIB_ADDRESS,
+  normalizeSuiObjectId,
+  SUI_FRAMEWORK_ADDRESS,
+} from "@mysten/sui/utils";
 
 // Shared by every generated-package template: one WASM initialization, module
 // table checks, and constant patching by type and default value.
@@ -32,6 +38,12 @@ export type BytecodeTemplateInitOptions = {
   module_or_path?: unknown;
 };
 
+const SYSTEM_ADDRESSES = new Set([
+  normalizeSuiObjectId("0x0"),
+  MOVE_STDLIB_ADDRESS,
+  SUI_FRAMEWORK_ADDRESS,
+]);
+
 let initialization: Promise<void> | undefined;
 
 /**
@@ -54,6 +66,66 @@ export function initializeBytecodeTemplate(
   return initialization;
 }
 
+/** A deployed package's original ID that a generated package links: valid and not a system address. */
+export function requireDependencyPackageId(
+  name: string,
+  packageId: string,
+): string {
+  if (typeof packageId !== "string") {
+    throw new TypeError(`${name} must be a string`);
+  }
+  const normalized = normalizeSuiObjectId(packageId);
+  if (!isValidSuiObjectId(normalized)) {
+    throw new TypeError(`${name} must be a valid Sui package ID`);
+  }
+  if (SYSTEM_ADDRESSES.has(normalized)) {
+    throw new RangeError(`${name} must identify a deployed Blast package`);
+  }
+  return normalized;
+}
+
+/**
+ * Binds every non-system address of the template to the deployed package
+ * whose modules it names: `bindings` maps a module name to that package's
+ * original ID. Each placeholder address must be claimed by exactly one
+ * package through the modules it holds, and each binding must claim one, so
+ * a template that gains or loses a dependency fails here instead of linking
+ * a placeholder.
+ */
+export function patchDependencyAddresses(
+  label: string,
+  compiled: CompiledModule,
+  bindings: Readonly<Record<string, string>>,
+): void {
+  const claimed = new Set<string>();
+  compiled.address_identifiers.forEach((address, index) => {
+    if (SYSTEM_ADDRESSES.has(normalizeSuiObjectId(address))) return;
+    const packageIds = new Set(
+      compiled.module_handles.flatMap((handle) => {
+        const module = compiled.identifiers[handle.name];
+        const packageId =
+          handle.address === index && module !== undefined
+            ? bindings[module]
+            : undefined;
+        if (packageId !== undefined && module !== undefined) {
+          claimed.add(module);
+        }
+        return packageId === undefined ? [] : [packageId];
+      }),
+    );
+    if (packageIds.size !== 1) {
+      throw new TypeError(`${label} has an unbound dependency address`);
+    }
+    const [packageId] = packageIds as Set<string>;
+    compiled.address_identifiers[index] = (packageId as string).slice(2);
+  });
+  for (const module of Object.keys(bindings)) {
+    if (!claimed.has(module)) {
+      throw new TypeError(`${label} does not link ${module}`);
+    }
+  }
+}
+
 /** Deserializes a template module and checks the tables patching reads. */
 export function deserializeTemplate(
   label: string,
@@ -192,20 +264,20 @@ export function assertIdentifierSlots(
 }
 
 /**
- * Derives the module and one-time-witness names from a symbol, the same
- * transformation as Blast V1: the witness is the uppercased symbol and the
- * module its lowercase form, spaces becoming underscores.
+ * Defaults the module to the lowercased symbol, with spaces becoming underscores.
+ * Sui requires its one-time witness to be the uppercase module name, including
+ * when the caller overrides the module name.
  */
 export function deriveTemplateIdentifiers(
   symbol: string,
   requestedModuleName?: string,
 ): { moduleName: string; witnessName: string } {
   const normalizedSymbol = requireNonEmptyString("symbol", symbol);
-  const witnessName = normalizedSymbol.toUpperCase().replaceAll(" ", "_");
+  const symbolIdentifier = normalizedSymbol.toUpperCase().replaceAll(" ", "_");
   const moduleName =
     requestedModuleName ?? normalizedSymbol.toLowerCase().replaceAll(" ", "_");
 
-  if (!/^[A-Z][A-Z0-9_]*$/.test(witnessName)) {
+  if (!/^[A-Z][A-Z0-9_]*$/.test(symbolIdentifier)) {
     throw new RangeError(
       "symbol must produce an uppercase Move witness identifier",
     );
@@ -215,7 +287,7 @@ export function deriveTemplateIdentifiers(
       "moduleName must start with a lowercase letter and contain only lowercase letters, digits, or underscores",
     );
   }
-  return { moduleName, witnessName };
+  return { moduleName, witnessName: moduleName.toUpperCase() };
 }
 
 export function requireString(name: string, value: string): string {