@outofgas/bounce-core

Database-free protocol primitives for independent Bounce dividend workers. The package owns the contract and subgraph compatibility boundary. Your worker owns scheduling, secrets, persistence, retries, monitoring, and public APIs.

Install

bun add @outofgas/bounce-core viem

viem is a peer dependency. Keep its version aligned with the version required by this package.

What is included

Included capabilities:

• Dividend Vault discovery through the deployed subgraph.
• Historical holder-accumulator snapshots.
• Time-weighted Merkle reward trees and claim proofs.
• V3 Locker versus V4 direct-fee detection.
• V3 fee preview, collector authorization, and transaction preparation.
• Epoch publication and launch-token burn transaction preparation.

The package never reads environment variables, opens a database connection, starts a timer, stores a private key, sends a transaction, or serves HTTP.

Build a worker

A consumer supplies its own RPC client, signer, storage, and execution policy:

import {
  buildTimeWeightedRewardEpochTree,
  fetchHolderAccumulatorSnapshot,
  preparePublishEpoch,
  readDividendVaultState,
} from "@outofgas/bounce-core";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

const publicClient = createPublicClient({ transport: http(process.env.RPC_URL) });
const account = privateKeyToAccount(process.env.OPERATOR_KEY);
const walletClient = createWalletClient({
  account,
  chain: yourChain,
  transport: http(process.env.RPC_URL),
});

const vault = await readDividendVaultState({
  client: publicClient,
  vaultAddress,
  blockNumber: snapshotBlock,
});
const [startHolders, endHolders] = await Promise.all([
  fetchHolderAccumulatorSnapshot(subgraphUrl, vault.launchToken, startBlock),
  fetchHolderAccumulatorSnapshot(subgraphUrl, vault.launchToken, snapshotBlock),
]);
const tree = buildTimeWeightedRewardEpochTree({
  epoch: vault.currentEpoch + 1n,
  allocation,
  minimumHolding: vault.minimumHolding,
  startTimestamp,
  endTimestamp,
  startHolders,
  endHolders,
});
const simulation = await preparePublishEpoch({
  account,
  allocation,
  client: publicClient,
  merkleRoot: tree.merkleRoot,
  snapshotBlock,
  vaultAddress,
});
const transactionHash = await walletClient.writeContract(simulation.request);

The sketch intentionally leaves finality selection, epoch timing, allocation calculation, durable claim storage, distributed locking, transaction receipt handling, retries, and proof-serving APIs to the consuming service.

Publishing

From this package directory, authenticate to npm and publish a fixed version:

npm publish

The prepack hook runs linting, type checking, tests, and the distributable build. Consumers should pin a released version instead of importing files from this repository.