@interest-protocol/blast-core 0.1.0 → 0.2.0

package/src/deployment.ts

@@ -0,0 +1,230 @@
+import type {
+  Transaction,
+  TransactionObjectInput,
+  TransactionResult,
+} from "@mysten/sui/transactions";
+import { normalizeStructTag, normalizeSuiObjectId } from "@mysten/sui/utils";
+import { MAX_VESTING_DURATION_MS, requireBps } from "./bps.ts";
+import type { Destination, FeeSplit } from "./fee-split.ts";
+import { normalizeFeeSplit } from "./fee-split.ts";
+import { requireU64 } from "./integers.ts";
+import type { VestingTerms } from "./payout.ts";
+import type { SharedObjectIdentity } from "./sui.ts";
+import { normalizeSharedObjectIdentity } from "./sui.ts";
+
+/**
+ * The `blast_core` package and its shared `blast_treasury::Treasury`. Calls
+ * target `packageId`; types and roles name `originalPackageId`.
+ */
+export type CoreDeployment = {
+  packageId: string;
+  originalPackageId: string;
+  treasury: SharedObjectIdentity;
+};
+
+export function normalizeCoreDeployment(
+  deployment: CoreDeployment,
+): CoreDeployment {
+  return {
+    packageId: normalizeSuiObjectId(deployment.packageId),
+    originalPackageId: normalizeSuiObjectId(deployment.originalPackageId),
+    treasury: normalizeSharedObjectIdentity(
+      "core.treasury",
+      deployment.treasury,
+    ),
+  };
+}
+
+/** `<core original>::<module>::<name>`, normalized. */
+export function coreType(
+  core: Pick<CoreDeployment, "originalPackageId">,
+  module: string,
+  name: string,
+): string {
+  return normalizeStructTag(
+    `${normalizeSuiObjectId(core.originalPackageId)}::${module}::${name}`,
+  );
+}
+
+/**
+ * `blast_core` value constructors and treasury calls. Each method returns a
+ * PTB step; the constructors return the value as a transaction result that
+ * the product or vault call consuming it takes by value.
+ */
+export class CoreCalls {
+  readonly deployment: CoreDeployment;
+
+  constructor(deployment: CoreDeployment) {
+    this.deployment = normalizeCoreDeployment(deployment);
+  }
+
+  /** `bps::new`: aborts above 10,000. */
+  bps(value: bigint) {
+    const bps = requireBps(value);
+    return (tx: Transaction): TransactionResult =>
+      tx.moveCall({
+        target: this.#target("bps", "new"),
+        arguments: [tx.pure.u64(bps)],
+      });
+  }
+
+  /**
+   * `fee_split::new` over one `fee_split::route` per route, each built from
+   * its `*_destination` constructor and `bps::new`, in the given order.
+   */
+  feeSplit(split: FeeSplit) {
+    const { routes } = normalizeFeeSplit(split);
+    return (tx: Transaction): TransactionResult => {
+      const elements = routes.map(({ destination, bps }) =>
+        tx.moveCall({
+          target: this.#target("fee_split", "route"),
+          arguments: [this.#destination(tx, destination), this.bps(bps)(tx)],
+        }),
+      );
+      return tx.moveCall({
+        target: this.#target("fee_split", "new"),
+        arguments: [
+          tx.makeMoveVec({
+            type: coreType(this.deployment, "fee_split", "Route"),
+            elements,
+          }),
+        ],
+      });
+    };
+  }
+
+  /**
+   * `payout::vesting_terms`; rejects terms the contract aborts on: positive
+   * steps whose total fits `MAX_VESTING_DURATION_MS` and a cliff within it.
+   */
+  vestingTerms(terms: VestingTerms) {
+    const cliff = requireU64("cliffDelayMs", terms.cliffDelayMs);
+    const period = requireU64("periodDurationMs", terms.periodDurationMs);
+    const periods = requireU64("periods", terms.periods);
+    if (
+      period === 0n ||
+      periods === 0n ||
+      period > MAX_VESTING_DURATION_MS / periods ||
+      cliff > period * periods
+    ) {
+      throw new RangeError(
+        "vesting needs positive steps whose total and cliff fit the bound",
+      );
+    }
+    return (tx: Transaction): TransactionResult =>
+      tx.moveCall({
+        target: this.#target("payout", "vesting_terms"),
+        arguments: [
+          tx.pure.u64(cliff),
+          tx.pure.u64(period),
+          tx.pure.u64(periods),
+        ],
+      });
+  }
+
+  /** `payout::recipient`: paid outright when `vestingTerms` is null. */
+  recipient(options: {
+    destination: string;
+    vestingTerms: VestingTerms | null;
+  }) {
+    const terms = options.vestingTerms
+      ? this.vestingTerms(options.vestingTerms)
+      : null;
+    const termsType = coreType(this.deployment, "payout", "VestingTerms");
+    return (tx: Transaction): TransactionResult =>
+      tx.moveCall({
+        target: this.#target("payout", "recipient"),
+        arguments: [
+          tx.pure.address(options.destination),
+          terms
+            ? tx.moveCall({
+                target: "0x1::option::some",
+                typeArguments: [termsType],
+                arguments: [terms(tx)],
+              })
+            : tx.moveCall({
+                target: "0x1::option::none",
+                typeArguments: [termsType],
+              }),
+        ],
+      });
+  }
+
+  /**
+   * `blast_treasury::schedule_destination`: a `TreasuryAdmin` witness
+   * schedules `destination` and the next change's `delayMs`.
+   */
+  scheduleDestination(options: {
+    adminWitness: TransactionObjectInput;
+    destination: string;
+    delayMs: bigint;
+  }) {
+    const delayMs = requireU64("delayMs", options.delayMs);
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("blast_treasury", "schedule_destination"),
+        arguments: [
+          this.#treasury(tx, true),
+          tx.object(options.adminWitness),
+          tx.pure.address(options.destination),
+          tx.pure.u64(delayMs),
+          tx.object.clock(),
+        ],
+      });
+    };
+  }
+
+  /** `blast_treasury::apply_destination`: anyone, once ready. */
+  applyDestination() {
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("blast_treasury", "apply_destination"),
+        arguments: [this.#treasury(tx, true), tx.object.clock()],
+      });
+    };
+  }
+
+  /** `blast_treasury::cancel_destination` with a `CancelAdmin` witness. */
+  cancelDestination(options: { adminWitness: TransactionObjectInput }) {
+    return (tx: Transaction): void => {
+      tx.moveCall({
+        target: this.#target("blast_treasury", "cancel_destination"),
+        arguments: [this.#treasury(tx, true), tx.object(options.adminWitness)],
+      });
+    };
+  }
+
+  #destination(tx: Transaction, destination: Destination) {
+    switch (destination.kind) {
+      case "Address":
+        return tx.moveCall({
+          target: this.#target("fee_split", "address_destination"),
+          arguments: [tx.pure.address(destination.address)],
+        });
+      case "Owner":
+        return tx.moveCall({
+          target: this.#target("fee_split", "owner_destination"),
+        });
+      case "AutoLp":
+        return tx.moveCall({
+          target: this.#target("fee_split", "auto_lp_destination"),
+        });
+      case "HolderRewards":
+        return tx.moveCall({
+          target: this.#target("fee_split", "holder_rewards_destination"),
+        });
+      case "Burn":
+        return tx.moveCall({
+          target: this.#target("fee_split", "burn_destination"),
+        });
+    }
+  }
+
+  #target(module: string, functionName: string): string {
+    return `${this.deployment.packageId}::${module}::${functionName}`;
+  }
+
+  #treasury(tx: Transaction, mutable: boolean) {
+    return tx.sharedObjectRef({ ...this.deployment.treasury, mutable });
+  }
+}

package/src/effects.ts

@@ -0,0 +1,247 @@
+import type { SuiClientTypes } from "@mysten/sui/client";
+import type { Transaction, TransactionResult } from "@mysten/sui/transactions";
+import {
+  normalizeStructTag,
+  normalizeSuiAddress,
+  normalizeSuiObjectId,
+  parseStructTag,
+  SUI_FRAMEWORK_ADDRESS,
+} from "@mysten/sui/utils";
+import type { SharedObjectIdentity, SharedObjectReference } from "./sui.ts";
+import { normalizeSharedObjectIdentity } from "./sui.ts";
+
+// Effects readers shared by every generated-package publication: a product's
+// coin package creates its currency through the product, which seals the
+// `TreasuryCap` under `blast_core::sealed_treasury_cap`, and sends the
+// `Currency` to the Coin Registry. Effects are the authority for created
+// objects, owners and versions; events never are.
+
+/**
+ * The parts of one executed transaction these readers need: its effects and
+ * the types of the objects they touched (Core API `include: { effects: true,
+ * objectTypes: true }`).
+ */
+export type TransactionEffectsInput = {
+  effects: SuiClientTypes.TransactionEffects;
+  objectTypes: Readonly<Record<string, string>>;
+};
+
+/** An owned or receiving object at one version. */
+export type ObjectVersionReference = {
+  objectId: string;
+  version: string;
+  digest: string;
+};
+
+/** `sui::object::sui_coin_registry_address()`. */
+export const COIN_REGISTRY_ID = normalizeSuiObjectId("0xc");
+
+/** The objects a successful transaction created. */
+export function createdObjects(
+  result: TransactionEffectsInput,
+): SuiClientTypes.ChangedObject[] {
+  if (!result.effects.status.success) {
+    throw new TypeError("transaction did not succeed");
+  }
+  return result.effects.changedObjects.filter(
+    (object) => object.idOperation === "Created",
+  );
+}
+
+/** The one package a publication created. */
+export function readPublishedPackage(
+  created: readonly SuiClientTypes.ChangedObject[],
+): string {
+  const packages = created.filter(
+    (object) => object.outputState === "PackageWrite",
+  );
+  if (packages.length !== 1) {
+    throw new TypeError("publication must create exactly one package");
+  }
+  return normalizeSuiObjectId(packages[0]!.objectId);
+}
+
+/** The parsed type of a touched object, or undefined for a package. */
+export function typeOf(
+  result: TransactionEffectsInput,
+  objectId: string,
+): ReturnType<typeof parseStructTag> | undefined {
+  const type =
+    result.objectTypes[normalizeSuiObjectId(objectId)] ??
+    result.objectTypes[objectId];
+  return type === undefined || type === "package"
+    ? undefined
+    : parseStructTag(type);
+}
+
+/** Whether the object is `0x2::coin_registry::Currency<coinType>`. */
+export function isCurrencyOf(
+  result: TransactionEffectsInput,
+  objectId: string,
+  coinType: string,
+): boolean {
+  const tag = typeOf(result, objectId);
+  const parameter = tag?.typeParams[0];
+  return (
+    tag?.address === normalizeSuiAddress(SUI_FRAMEWORK_ADDRESS) &&
+    tag.module === "coin_registry" &&
+    tag.name === "Currency" &&
+    tag.typeParams.length === 1 &&
+    parameter !== undefined &&
+    normalizeStructTag(parameter) === coinType
+  );
+}
+
+/**
+ * The `<core>::sealed_treasury_cap::SealedTreasuryCap<Coin>` objects a
+ * publication created, each with its sealed coin type, in effects order.
+ */
+export function sealedTreasuryCaps(
+  result: TransactionEffectsInput,
+  created: readonly SuiClientTypes.ChangedObject[],
+  coreOriginalPackageId: string,
+): { object: SuiClientTypes.ChangedObject; coinType: string }[] {
+  const core = normalizeSuiAddress(coreOriginalPackageId);
+  return created.flatMap((object) => {
+    const tag = typeOf(result, object.objectId);
+    const parameter = tag?.typeParams[0];
+    return tag?.address === core &&
+      tag.module === "sealed_treasury_cap" &&
+      tag.name === "SealedTreasuryCap" &&
+      parameter !== undefined &&
+      typeof parameter !== "string"
+      ? [{ object, coinType: normalizeStructTag(parameter) }]
+      : [];
+  });
+}
+
+/**
+ * The one sealed `TreasuryCap<coinType>` a publication sent to `owner`;
+ * `where` names the expectation in the error.
+ */
+export function readSealedTreasuryCap(
+  result: TransactionEffectsInput,
+  created: readonly SuiClientTypes.ChangedObject[],
+  coreOriginalPackageId: string,
+  coinType: string,
+  owner: string,
+  where: string,
+): ObjectVersionReference & { owner: string } {
+  const caps = sealedTreasuryCaps(result, created, coreOriginalPackageId)
+    .filter(
+      (cap) =>
+        cap.coinType === coinType &&
+        cap.object.outputOwner?.$kind === "AddressOwner" &&
+        normalizeSuiAddress(cap.object.outputOwner.AddressOwner) === owner,
+    )
+    .map(({ object }) => object);
+  const [cap] = caps;
+  if (caps.length !== 1 || !cap) {
+    throw new TypeError(
+      `publication must send exactly one SealedTreasuryCap<Coin> ${where}`,
+    );
+  }
+  return { ...versionReference(cap), owner };
+}
+
+/** The one `Currency<coinType>` a publication sent to the Coin Registry address. */
+export function readPendingCurrency(
+  result: TransactionEffectsInput,
+  created: readonly SuiClientTypes.ChangedObject[],
+  coinType: string,
+): ObjectVersionReference {
+  const currencies = created.filter(
+    (object) =>
+      isCurrencyOf(result, object.objectId, coinType) &&
+      object.outputOwner?.$kind === "AddressOwner" &&
+      normalizeSuiAddress(object.outputOwner.AddressOwner) === COIN_REGISTRY_ID,
+  );
+  if (currencies.length !== 1) {
+    throw new TypeError(
+      "publication must send exactly one Currency<Coin> to the Coin Registry",
+    );
+  }
+  return versionReference(currencies[0]!);
+}
+
+/**
+ * Reads the shared `Currency<coinType>` that
+ * `coin_registry::finalize_registration` created at its derived address;
+ * mutable for the product's `finalize`.
+ */
+export function readCurrencyRegistration(
+  result: TransactionEffectsInput,
+  coinType: string,
+): SharedObjectReference<true> {
+  const coin = normalizeStructTag(coinType);
+  const currencies = createdObjects(result).filter(
+    (object) =>
+      object.outputOwner?.$kind === "Shared" &&
+      isCurrencyOf(result, object.objectId, coin),
+  );
+  if (currencies.length !== 1) {
+    throw new TypeError("registration must share exactly one Currency<Coin>");
+  }
+  return sharedReference(currencies[0]!);
+}
+
+/**
+ * `0x2::coin_registry::finalize_registration<Coin>(registry, currency)`:
+ * shares a published coin's pending `Currency` from the Coin Registry
+ * address (`readPendingCurrency`). Anyone may run it; `coinRegistry` is the
+ * shared registry `0xc` with its initial shared version, so it builds
+ * offline.
+ */
+export function finalizeCurrencyRegistration(options: {
+  coinType: string;
+  currency: ObjectVersionReference;
+  coinRegistry: SharedObjectIdentity;
+}): (tx: Transaction) => TransactionResult {
+  const coinType = normalizeStructTag(options.coinType);
+  const currency = {
+    objectId: normalizeSuiObjectId(options.currency.objectId),
+    version: options.currency.version,
+    digest: options.currency.digest,
+  };
+  const coinRegistry = normalizeSharedObjectIdentity(
+    "coinRegistry",
+    options.coinRegistry,
+  );
+  return (tx) =>
+    tx.moveCall({
+      target: `${SUI_FRAMEWORK_ADDRESS}::coin_registry::finalize_registration`,
+      typeArguments: [coinType],
+      arguments: [
+        tx.sharedObjectRef({ ...coinRegistry, mutable: true }),
+        tx.receivingRef(currency),
+      ],
+    });
+}
+
+/** An owned object's ID, output version and digest. */
+export function versionReference(
+  object: SuiClientTypes.ChangedObject,
+): ObjectVersionReference {
+  if (object.outputVersion === null || object.outputDigest === null) {
+    throw new TypeError(`object ${object.objectId} has no output version`);
+  }
+  return {
+    objectId: normalizeSuiObjectId(object.objectId),
+    version: object.outputVersion,
+    digest: object.outputDigest,
+  };
+}
+
+/** A shared object's identity, borrowed mutably. */
+export function sharedReference(
+  object: SuiClientTypes.ChangedObject,
+): SharedObjectReference<true> {
+  if (object.outputOwner?.$kind !== "Shared") {
+    throw new TypeError(`object ${object.objectId} is not shared`);
+  }
+  return {
+    objectId: normalizeSuiObjectId(object.objectId),
+    initialSharedVersion: object.outputOwner.Shared.initialSharedVersion,
+    mutable: true,
+  };
+}

package/src/fee-split.ts

@@ -0,0 +1,103 @@
+import { bcs } from "@mysten/sui/bcs";
+import { normalizeSuiAddress } from "@mysten/sui/utils";
+import { addressBcs } from "./bcs.ts";
+import { apportionBps, bpsBcs, MAX_ROUTES, requireBps } from "./bps.ts";
+import { BASIS_POINTS_DENOMINATOR } from "./integers.ts";
+
+/**
+ * `blast_core::fee_split::Destination`: where one route's part of each
+ * LP-fee collection goes. The vault decides what each special kind does.
+ */
+export type Destination =
+  | { kind: "Address"; address: string }
+  | { kind: "Owner" }
+  | { kind: "AutoLp" }
+  | { kind: "HolderRewards" }
+  | { kind: "Burn" };
+
+/** `blast_core::fee_split::Route`: one destination and its positive share. */
+export type Route = { destination: Destination; bps: bigint };
+
+/** `blast_core::fee_split::FeeSplit`: routes summing to exactly 10,000. */
+export type FeeSplit = { routes: Route[] };
+
+/** BCS of `Destination`, in Move variant order. */
+export const destinationBcs = bcs
+  .enum("Destination", {
+    Address: addressBcs,
+    Owner: null,
+    AutoLp: null,
+    HolderRewards: null,
+    Burn: null,
+  })
+  .transform({
+    input: (destination: Destination) =>
+      destination.kind === "Address"
+        ? { Address: destination.address }
+        : ({ [destination.kind]: true } as
+            | { Owner: true }
+            | { AutoLp: true }
+            | { HolderRewards: true }
+            | { Burn: true }),
+    output: (destination): Destination =>
+      destination.$kind === "Address"
+        ? { kind: "Address", address: destination.Address }
+        : { kind: destination.$kind },
+  });
+
+export const routeBcs = bcs.struct("Route", {
+  destination: destinationBcs,
+  bps: bpsBcs,
+});
+
+export const feeSplitBcs = bcs.struct("FeeSplit", {
+  routes: bcs.vector(routeBcs),
+});
+
+/**
+ * Checks `split` as far as `fee_split::new` would reject it: at most 20
+ * routes, each positive (and an address route nonzero), no destination
+ * twice, summing to exactly 10,000. Returns the routes with normalized
+ * addresses, in the given order (the order `apportion` pays them).
+ */
+export function normalizeFeeSplit(split: FeeSplit): FeeSplit {
+  if (split.routes.length > MAX_ROUTES) {
+    throw new RangeError(`a fee split holds at most ${MAX_ROUTES} routes`);
+  }
+  const routes = split.routes.map(({ destination, bps }): Route => {
+    if (requireBps(bps) === 0n) {
+      throw new RangeError("a fee-split route needs a positive share");
+    }
+    if (destination.kind !== "Address") return { destination, bps };
+    const address = normalizeSuiAddress(destination.address);
+    if (address === normalizeSuiAddress("0x0")) {
+      throw new RangeError("a fee-split route cannot pay the zero address");
+    }
+    return { destination: { kind: "Address", address }, bps };
+  });
+  const keys = routes.map(({ destination }) =>
+    destination.kind === "Address" ? destination.address : destination.kind,
+  );
+  if (new Set(keys).size !== keys.length) {
+    throw new RangeError("a fee split names each destination at most once");
+  }
+  if (
+    routes.reduce((sum, route) => sum + route.bps, 0n) !==
+    BASIS_POINTS_DENOMINATOR
+  ) {
+    throw new RangeError("fee-split routes must sum to 10,000 basis points");
+  }
+  return { routes };
+}
+
+/**
+ * Mirrors `fee_split::apportion`: `total` atoms split across the routes
+ * exactly, in route order, by `bps::apportion` with no rounded-up part.
+ */
+export function apportionFeeSplit(split: FeeSplit, total: bigint): bigint[] {
+  return apportionBps(
+    split.routes.map(({ bps }) => bps),
+    total,
+    null,
+  );
+}

package/src/index.ts

@@ -1,13 +1,22 @@
+export * from "./aborts.ts";
 export * from "./arrays.ts";
 export * from "./bcs.ts";
+export * from "./bps.ts";
 export * from "./bytecode-template.ts";
 export * from "./cetus.ts";
 export * from "./coins.ts";
+export * from "./deployment.ts";
+export * from "./effects.ts";
 export * from "./events.ts";
+export * from "./fee-split.ts";
 export * from "./gas.ts";
 export * from "./integers.ts";
 export * from "./merkle.ts";
+export * from "./migration.ts";
 export * from "./migration-math.ts";
+export * from "./payout.ts";
+export * from "./protocol-fees.ts";
 export * from "./ptb.ts";
+export * from "./roles.ts";
 export * from "./sui.ts";
-export * from "./timelock.ts";
+export * from "./treasury.ts";

package/src/integers.ts

@@ -45,6 +45,21 @@ export function requireBasisPoints(name: string, value: bigint): BasisPoints {
   return value as BasisPoints;
 }
 
+/** Requires a basis-point value no greater than a contract's compiled maximum. */
+export function requireBasisPointsAtMost(
+  name: string,
+  value: bigint,
+  maximum: bigint,
+): BasisPoints {
+  const bps = requireBasisPoints(name, value);
+  if (bps > maximum) {
+    throw new RangeError(
+      `${name} exceeds ${maximum.toLocaleString("en-US")} basis points`,
+    );
+  }
+  return bps;
+}
+
 /** Adds two values and requires the result to remain a Move `u64`. */
 export function checkedAddU64(name: string, left: bigint, right: bigint): U64 {
   return requireU64(name, left + right);

package/src/merkle.ts

@@ -4,7 +4,17 @@ export function blake2b256(bytes: Uint8Array): Uint8Array {
   return blake2b(bytes, { dkLen: 32 });
 }
 
-/** Mirrors the contracts' Merkle `node`: `blake2b256(0x01 || left || right)`. */
+/**
+ * Mirrors `blast_core::merkle::leaf`: `blake2b256(0x00 || domain || payload)`,
+ * `domain` naming the tree's purpose (UTF-8) and `payload` the leaf's BCS.
+ */
+export function merkleLeaf(domain: string, payload: Uint8Array): Uint8Array {
+  return blake2b256(
+    new Uint8Array([0, ...new TextEncoder().encode(domain), ...payload]),
+  );
+}
+
+/** Mirrors `blast_core::merkle::node`: `blake2b256(0x01 || left || right)`. */
 export function merkleNode(left: Uint8Array, right: Uint8Array): Uint8Array {
   return blake2b256(new Uint8Array([1, ...left, ...right]));
 }