@0xward/cultos-utils

Shared utility layer for CultOS — an AI-powered memetic identity engine that permanently inscribes cultural identity vectors onto Bitcoin via Stacks L2. This package provides the fee calculation, token field sanitization, viral score rating, and SIP-010 metadata generation that the CultOS V2 web app runs before every on-chain deployment.

Note: this package does not sign or broadcast transactions. It handles the client-side logic layer — computing fees, sanitizing Oracle output, and shaping token metadata — before the user's wallet (Leather / Xverse) signs the actual contract call via @stacks/connect.

---

Installation

# npm
npm install @0xward/cultos-utils

# yarn
yarn add @0xward/cultos-utils

# pnpm
pnpm add @0xward/cultos-utils

Prerequisites: Node.js >= 18.0.0

Peer context: If you're integrating into a Stacks app, you'll typically also use @stacks/connect for wallet connection and @stacks/transactions for constructing contract call arguments.

---

What this package actually does

• Fee calculation — calcDeployFee(viralScore) computes the STX deployment fee using the same formula as CultOS V2's handleDeploy(): 0.05 + (viralScore / 100) * 0.1. Returns feeSTX, microSTX, and the clamped score, ready to pass directly to openContractCall().

• Field sanitization — sanitizeField(str, field) strips non-ASCII characters and enforces character limits (name: 64, ticker: 8, lore: 490), identical to the guard in CultOS V2 before every on-chain call. sanitizeOracleResult(oracleResult) sanitizes all three fields at once and returns { safeName, safeTicker, safeLore }.

• Viral score rating — getViralRating(viralScore) maps a numeric Oracle score to the display label and color used throughout CultOS V2: >= 80 → Viral (green), >= 50 → Growing (amber), < 50 → Niche (red).

• SIP-010 metadata generation — generateMemeMetadata(name, ticker, options) shapes a complete token metadata object — including ecosystem, network, archetype, tokenomics, fee estimate, and viral rating — for previewing a sub-cult before the user confirms deployment.

What this package does not do

• It does not call the Groq API or the CultOS Oracle. Oracle invocation happens server-side in CultOS V2's Vercel function (/api/oracle).
• It does not sign or broadcast Stacks transactions.
• It does not interact with Firebase or any real-time database.

---

Quick Start

const { CultOSUtils } = require("@0xward/cultos-utils");

const utils = new CultOSUtils({ network: "mainnet" });

// 1. Sanitize Oracle output before passing to openContractCall()
const { safeName, safeTicker, safeLore } = utils.sanitizeOracleResult({
  upgradedName: "ENTROPIC VEIL",
  ticker:       "XVRL",
  lore:         "A sovereign signal cast across the memetic substrate...",
});

// 2. Calculate the deployment fee from the Oracle's viralScore
const { feeSTX, microSTX } = utils.calcDeployFee(78);
console.log(`Fee: ${feeSTX} STX (${microSTX} microSTX)`);
// → Fee: 0.128 STX (128000 microSTX)

// 3. Get the display rating for the viralScore
const { rating, color } = utils.getViralRating(78);
console.log(`${rating}`); // → Growing

// 4. Generate a full SIP-010 metadata preview
const metadata = utils.generateMemeMetadata("ENTROPIC VEIL", "XVRL", {
  archetype:  "oracle",
  tokenomics: "fair",
});
console.log(metadata);

---

API Reference

new CultOSUtils(options?)

Option	Type	Default	Description
network	"mainnet" | "testnet" | "devnet"	"mainnet"	Stacks network context. Throws if unsupported.
ecosystem	string	"Stacks Bitcoin L2"	Ecosystem label included in metadata output.
standard	string	"SIP-010"	Token standard label included in metadata output.

Methods

Method	Parameters	Returns	Description
sanitizeField	str: string, field: "name"|"ticker"|"lore"	string	Strips non-ASCII, enforces field character limit. Mirrors CultOS V2's pre-deploy guard.
sanitizeOracleResult	oracleResult: { upgradedName, ticker, lore }	{ safeName, safeTicker, safeLore }	Sanitizes all three required fields at once.
calcDeployFee	viralScore: number	{ feeSTX, microSTX, viralScore }	Computes STX fee from viralScore using the CultOS V2 formula.
getViralRating	viralScore: number	{ rating, color }	Returns the display label and hex color for a viralScore.
generateMemeMetadata	name: string, ticker: string, options?: Object	Object	Returns a full SIP-010 token metadata object with fee estimate and viral rating.
getCultArchetypes	—	Array	Lists all supported cult archetypes with their viral multipliers.
getTokenomicsPresets	—	Array	Lists all tokenomics distribution presets.
getSupportedNetworks	—	Array	Lists mainnet, testnet, and devnet config (chainId, apiUrl, currency).
getVersion	—	string	Returns the package version string.

---

Used by

This package is the shared utility layer behind CultOS V2 — the AI-powered cult identity engine on Stacks. CultOS V2 uses sanitizeOracleResult(), calcDeployFee(), and getViralRating() from this package in its deployment flow before every on-chain register-cult contract call.

---

License

This project is licensed under the terms of the MIT License.