@basedone/core 0.0.1 → 0.0.6

package/index.ts

@@ -0,0 +1,6 @@
+export * from "./lib/cloid/cloid";
+export * from "./lib/fee";
+export * from "./lib/pup";
+export * from "./lib/constants/tokens";
+export * from "./lib/meta/metadata";
+export * from "./lib/utils/formatter";

package/lib/cloid/README.md

@@ -0,0 +1,233 @@
+# CLOID (Client Order ID) System
+
+## Overview
+
+CLOID (Client Order ID) is a 128-bit identifier system used for tracking clients, tenants, and orders/applications in the Based ecosystem. It provides a compact, efficient way to encode multiple pieces of information into a single hexadecimal string.
+
+## Structure
+
+A CLOID is a 128-bit (32 hex character) value with the following bit layout:
+
+```
+[ Prefix (24 bits) | Version (4 bits) | Slug (26 bits) | Client ID (5 bits) | isMiniApp (1 bit) | miniAppTriggered (1 bit) | Component ID (3 bits) | OID (64 bits) ]
+```
+
+### Components
+
+1. **Prefix (24 bits)**: `0xBA5ED1` - A fixed identifier for Based CLOIDs
+2. **Version (4 bits)**: Protocol version (currently version 1)
+3. **Slug (26 bits)**: Tenant/organization identifier (5 characters, uppercase alphanumeric)
+4. **Client ID (5 bits)**: Client type identifier (Web, App, Bot, etc.) - supports 32 client types
+5. **isMiniApp (1 bit)**: Boolean flag indicating if this is a mini-app order
+6. **miniAppTriggered (1 bit)**: Boolean flag indicating if the order was triggered by a mini-app
+7. **Component ID (3 bits)**: Component type (SidePanel, Widget, FloatingWidget, etc.) - supports 8 component types
+8. **OID (64 bits)**: Order ID or tracking identifier (supports both numeric and string encoding)
+
+## Example CLOID
+
+```
+0xba5ed11[version][encoded_slug][client_id][order_id]
+```
+
+## Usage
+
+### Creating a CLOID
+
+```typescript
+import { getCloid, CloidClientCode, CloidComponentCode } from './cloid';
+
+// Basic usage with defaults
+const cloid1 = getCloid();
+// Returns: CLOID with tenant="BASED", client=Unset, default OID
+
+// With tenant code
+const cloid2 = getCloid("ACME");
+
+// With tenant and client type
+const cloid3 = getCloid("ACME", "Web");
+
+// With all basic parameters including numeric OID
+const cloid4 = getCloid("ACME", "Web", 123456789n);
+
+// With string tracking ID (up to 12 characters)
+const cloid5 = getCloid("ACME", "App", "order-abc123");
+
+// With mini-app attribution
+const cloid6 = getCloid("ACME", CloidClientCode.Web, "order-123", {
+  isMiniApp: true,
+  miniAppTriggered: false,
+  component: CloidComponentCode.SidePanel
+});
+
+// Mini-app triggered from widget
+const cloid7 = getCloid("TRADER", CloidClientCode.App, "trade-456", {
+  isMiniApp: true,
+  miniAppTriggered: true,
+  component: CloidComponentCode.Widget
+});
+```
+
+### Parsing a CLOID
+
+```typescript
+import { parseCloid } from './cloid';
+
+const parsed = parseCloid("0xba5ed11...");
+// Returns:
+// {
+//   prefix: "0xba5ed1",
+//   version: 1,
+//   slug: "ACME",
+//   clientId: 1,
+//   isMiniApp: true,
+//   miniAppTriggered: false,
+//   widgetType: 1,
+//   oid: 123456789n,
+//   decodedOid: "order-abc123",
+//   clientName: "Web",
+//   widgetTypeName: "SidePanel"
+// }
+```
+
+### Validation Functions
+
+```typescript
+import {
+  isBasedCloid,
+  isTenantCloid,
+  isMiniAppCloid,
+  isMiniAppTriggeredCloid,
+  isComponentCode,
+  isClientCode
+} from './cloid';
+
+// Check if a hex string is a valid Based CLOID
+const isValid = isBasedCloid("0xba5ed11...");
+
+// Check if a CLOID belongs to a specific tenant
+const isTenant = isTenantCloid("ACME", "0xba5ed11...");
+
+// Check if a CLOID is from a mini-app
+const isMiniApp = isMiniAppCloid("0xba5ed11...");
+
+// Check if a CLOID was triggered by a mini-app
+const isTriggered = isMiniAppTriggeredCloid("0xba5ed11...");
+
+// Check if a CLOID has a specific component type
+const isSidePanel = isWidgetType(WidgetType.SidePanel, "0xba5ed11...");
+
+// Check if a CLOID has a specific client type
+const isWebClient = isClientCode(CloidClientCode.Web, "0xba5ed11...");
+```
+
+## Client Types
+
+The system supports the following client types (5-bit field supports 0-31):
+
+| Code | Name    | Description                    |
+|------|---------|--------------------------------|
+| 0    | Unset   | Default/unspecified client    |
+| 1    | Web     | Web application               |
+| 2    | App     | Mobile application            |
+| 3    | TgBot   | Telegram bot                  |
+| 4    | TSL     | Trailing Stop Loss system     |
+| 5    | Grid    | Grid trading system           |
+| 6    | Chase   | Chase trading system          |
+| 7    | Desktop | Desktop application           |
+| 8    | API     | Direct API access             |
+
+## Component Types
+
+The system supports the following component types (3-bit field supports 0-7):
+
+| Code | Name           | Description                           |
+|------|----------------|---------------------------------------|
+| 0    | Unset         | Default/unspecified component        |
+| 1    | SidePanel     | Side panel component                 |
+| 2    | Widget        | Widget component                     |
+| 3    | FloatingWidget| Floating widget component            |
+| 4-7  | Reserved      | Available for future component types |
+
+## Encoding Details
+
+### Tenant Slug Encoding
+- **Alphabet**: `A-Z0-9` (36 characters)
+- **Length**: 5 characters maximum
+- **Auto-padding**: Shorter slugs are padded with the last alphabet character
+- **Case**: Automatically converted to uppercase
+
+### OID String Encoding
+- **Alphabet**: `a-z0-9|_- ` (40 characters)
+- **Length**: 12 characters maximum
+- **Case**: Automatically converted to lowercase
+- **Usage**: Can encode order IDs, app IDs, or other tracking identifiers
+
+## Special Values
+
+### Legacy CLOID
+```typescript
+const LEGACY_CLOID = "0x62baee7262baee7262baee7262baee72";
+```
+Used for backward compatibility with older systems.
+
+### Default Values
+- **Default Tenant**: `"BASED"`
+- **Default OID**: `0xBA5ED10000BA5ED1`
+- **Default Client**: `Unset` (0)
+
+## Utility Functions
+
+### normaliseSlug(slug: string)
+Normalizes a tenant slug to the standard 5-character format.
+
+```typescript
+normaliseSlug("AXON") // Returns: "AXON9" (padded with 9)
+normaliseSlug("LONGNAME") // Returns: "LONGN" (truncated)
+```
+
+### normaliseTrackingId(trackingId: string)
+Normalizes a tracking ID to the standard 12-character format.
+
+```typescript
+normaliseTrackingId("order123") // Returns normalized 12-char string 
+```
+
+## Use Cases
+
+1. **Order Tracking**: Encode order IDs with tenant and client information
+2. **Multi-tenant Systems**: Identify which tenant/organization an order belongs to
+3. **Client Analytics**: Track orders by client type (Web, Mobile, API, etc.)
+4. **Mini-app Attribution**: Track orders originating from mini-apps with component-level granularity
+5. **Component Analytics**: Analyze user behavior across different UI components (SidePanel, Widget, FloatingWidget)
+6. **Trigger Analysis**: Distinguish between orders created directly in mini-apps vs. triggered by mini-app interactions
+7. **Cross-system Integration**: Compact identifier that can be passed between systems with full attribution data
+8. **A/B Testing**: Use component and mini-app flags for UI/UX experimentation tracking
+
+## Backward Compatibility
+
+The system maintains full backward compatibility with existing CLOIDs:
+
+- **Existing CLOIDs**: All previously generated CLOIDs can be parsed correctly
+- **Client ID Preservation**: Original client IDs (0-31) are preserved in the 5-bit field
+- **Mini-app Defaults**: Existing CLOIDs are interpreted with `isMiniApp=false`, `miniAppTriggered=false`, `widgetType=Unset`
+- **Identical Generation**: New CLOIDs without mini-app options generate identical hex values to old CLOIDs
+
+```typescript
+// These generate identical CLOIDs
+const oldStyleCloid = getCloid("BASED", "Web", "0xba5ed10000ba5ed1");
+const newStyleCloid = getCloid("BASED", "Web", "0xba5ed10000ba5ed1", {
+  isMiniApp: false,
+  miniAppTriggered: false,
+  component: CloidComponentCode.Unset
+});
+// oldStyleCloid === newStyleCloid (true)
+```
+
+## Implementation Notes
+
+- CLOIDs are always returned as `0x`-prefixed hex strings
+- The system is designed to be compact while maintaining readability
+- All encoding/decoding operations preserve data integrity
+- Invalid inputs fallback to safe defaults or legacy values
+- The bit layout ensures efficient storage and parsing
+- Mini-app attribution is optional and defaults to false/Unset when not specified

package/lib/cloid/cloid.ts

@@ -0,0 +1,368 @@
+// Client Order ID (cloid) is an optional 128 bit hex string
+// 32 hex characters or 16 utf8 characters
+// Bit layout:
+// [ Prefix (24) | Version (4) | Slug (26) | Client ID (5) | MiniApp Attribution (5) | OID (64) ]
+
+import { decodeValue, encodeValue } from "./encoder";
+
+const LEGACY_CLOID = "0x62baee7262baee7262baee7262baee72";
+const BASED_VERSION = 1;
+
+const DEFAULT_TENANT_CODE = "BASED";
+const DEFAULT_OID = 0xba5ed10000ba5ed1n;
+
+// CloID bit layout (128 bits total):
+// [ Prefix (24) | Version (4) | Slug (26) | Client ID (5) | isMiniApp (1) | miniAppTriggered (1) | Widget Type ID (3) | OID (64) ]
+
+// Constants
+const BASED_HEX_PREFIX = 0xba5ed1; // 24-bit prefix
+const BASED_HEX_PREFIX_STR = "0xba5ed1"; // 24-bit prefix
+const PREFIX_BITS = 24n;
+const VERSION_BITS = 4n;
+const SLUG_BITS = 26n;
+const CLIENT_BITS = 5n;
+const IS_MINI_APP_BITS = 1n;
+const MINI_APP_TRIGGERED_BITS = 1n;
+const WIDGET_TYPE_BITS = 3n;
+const OID_BITS = 64n;
+const TOTAL_BITS = 128n;
+
+// Encoding charsets, do not modify
+// Slug alphabet [A-Z0-9] (36 symbols)
+const SLUG_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789";
+
+// Extended OID alphabet [a-z0-9|_- ] (40 symbols)
+const OID_ALPHABET = "abcdefghijklmnopqrstuvwxyz0123456789|_- ";
+
+// Utility: mask for n bits
+const mask = (bits: bigint) => (1n << bits) - 1n;
+
+// Encode a 5-char slug into a 26-bit integer
+export function encodeSlug(slug: string): bigint {
+  if (!slug) slug = DEFAULT_TENANT_CODE;
+
+  return encodeValue(slug, SLUG_BITS, SLUG_ALPHABET);
+}
+
+// Decode a n-bit integer back into a x-char slug
+export function decodeSlug(value: bigint): string {
+  return decodeValue(value, SLUG_BITS, SLUG_ALPHABET);
+}
+
+// Build a CloID as a 0x-prefixed 32-char hex string
+export function buildCloid(
+  version: number,
+  slug: string,
+  clientId: number,
+  oid: bigint | string, // bitint for oid, string for encoded string slug (12 characters max)
+  options?: {
+    isMiniApp?: boolean;
+    miniAppTriggered?: boolean;
+    widgetType?: WidgetType | number;
+  },
+): `0x${string}` {
+  if (version > 0xf) version = BASED_VERSION;
+  if (clientId > Number(mask(CLIENT_BITS))) {
+    clientId = CloidClientCode.Unset;
+  }
+
+  const isMiniApp = options?.isMiniApp ? 1 : 0;
+  const miniAppTriggered = options?.miniAppTriggered ? 1 : 0;
+  const widgetType =
+    typeof options?.widgetType === "number"
+      ? options.widgetType
+      : WidgetType[options?.widgetType ?? "Unset"];
+
+  if (widgetType > Number(mask(WIDGET_TYPE_BITS))) {
+    throw new Error(
+      `Component ID ${widgetType} exceeds maximum value ${Number(mask(WIDGET_TYPE_BITS))}`,
+    );
+  }
+  let oidBigInt: bigint;
+  if (typeof oid === "string") {
+    // is string hex or numeric?
+    if (oid.startsWith("0x") || !isNaN(Number(oid))) {
+      oidBigInt = BigInt(oid);
+    } else {
+      // Encode string into number
+      oidBigInt = encodeValue(oid.toLowerCase(), OID_BITS, OID_ALPHABET);
+    }
+  } else {
+    oidBigInt = oid;
+  }
+  if (oidBigInt > mask(OID_BITS)) {
+    oidBigInt = DEFAULT_OID;
+  }
+
+  const slugVal = encodeSlug(slug.toUpperCase());
+
+  let cloid = BigInt(BASED_HEX_PREFIX) << (TOTAL_BITS - PREFIX_BITS); // 0xba5ed10000000000000000000000000000000000
+  cloid |= BigInt(version & 0xf) << (TOTAL_BITS - PREFIX_BITS - VERSION_BITS); // 0xba5ed10000000000000000000000000000000000
+  cloid |=
+    BigInt(slugVal) << (TOTAL_BITS - PREFIX_BITS - VERSION_BITS - SLUG_BITS);
+  cloid |= BigInt(clientId) << OID_BITS;
+  cloid |= BigInt(isMiniApp) << (OID_BITS + CLIENT_BITS);
+  cloid |=
+    BigInt(miniAppTriggered) << (OID_BITS + CLIENT_BITS + IS_MINI_APP_BITS);
+  cloid |=
+    BigInt(widgetType) <<
+    (OID_BITS + CLIENT_BITS + IS_MINI_APP_BITS + MINI_APP_TRIGGERED_BITS);
+  cloid |= oidBigInt & mask(OID_BITS);
+
+  return `0x${cloid.toString(16)}`;
+}
+
+// Parse a CloID hex string back into fields
+export function parseCloid(cloidHex: `0x${string}`) {
+  if (cloidHex === LEGACY_CLOID) {
+    return {
+      prefix: LEGACY_CLOID,
+      version: 0,
+      slug: "BASED",
+      clientId: CloidClientCode.Unset,
+      isMiniApp: false,
+      miniAppTriggered: false,
+      widgetTypeId: WidgetType.Unset,
+      oid: 0xba5ed10000ba5ed1n,
+      decodedOid: decodeValue(0xba5ed10000ba5ed1n, OID_BITS, OID_ALPHABET),
+      clientName: "Unset",
+      widgetTypeName: "Unset",
+    };
+  }
+  try {
+    const cloid = BigInt(cloidHex);
+
+    const prefix = Number(cloid >> (TOTAL_BITS - PREFIX_BITS));
+    const version = Number(
+      (cloid >> (TOTAL_BITS - PREFIX_BITS - VERSION_BITS)) & mask(VERSION_BITS),
+    );
+    const slugVal = Number(
+      (cloid >>
+        (OID_BITS +
+          WIDGET_TYPE_BITS +
+          MINI_APP_TRIGGERED_BITS +
+          IS_MINI_APP_BITS +
+          CLIENT_BITS)) &
+        mask(SLUG_BITS),
+    );
+    const clientId = Number((cloid >> OID_BITS) & mask(CLIENT_BITS));
+    const isMiniApp =
+      Number((cloid >> (OID_BITS + CLIENT_BITS)) & mask(IS_MINI_APP_BITS)) ===
+      1;
+    const miniAppTriggered =
+      Number(
+        (cloid >> (OID_BITS + CLIENT_BITS + IS_MINI_APP_BITS)) &
+          mask(MINI_APP_TRIGGERED_BITS),
+      ) === 1;
+    const widgetType = Number(
+      (cloid >>
+        (OID_BITS + CLIENT_BITS + IS_MINI_APP_BITS + MINI_APP_TRIGGERED_BITS)) &
+        mask(WIDGET_TYPE_BITS),
+    );
+    const oid = cloid & mask(OID_BITS);
+
+    return {
+      prefix: `0x${prefix.toString(16)}`, // should equal 0xBA5ED1
+      version,
+      slug: decodeSlug(BigInt(slugVal)),
+      clientId,
+      isMiniApp,
+      miniAppTriggered,
+      widgetTypeId: widgetType,
+      oid,
+      decodedOid: decodeValue(oid, OID_BITS, OID_ALPHABET),
+      clientName: getClientCodeNameById(clientId),
+      widgetTypeName: getWidgetTypeById(widgetType),
+    };
+  } catch (error) {
+    console.error("Invalid cloid", { cloidHex });
+    return null;
+  }
+}
+
+export type CloidData = ReturnType<typeof parseCloid>;
+
+// Quick prefix check
+export function isBasedCloid(cloidHex?: `0x${string}` | null): boolean {
+  if (!cloidHex) return false;
+  if (cloidHex === LEGACY_CLOID) return true;
+  return cloidHex.toLowerCase().startsWith(BASED_HEX_PREFIX_STR);
+}
+
+export function isTenantCloid(
+  tenantTrackingSlug: string,
+  cloidHex?: `0x${string}` | null,
+): boolean {
+  if (!cloidHex || !isBasedCloid(cloidHex)) return false;
+  const cloidData = parseCloid(cloidHex);
+  if (!cloidData) return false;
+  const { slug } = cloidData;
+  if (tenantTrackingSlug.length > 5) {
+    tenantTrackingSlug = tenantTrackingSlug.slice(0, 5);
+  }
+
+  // Normalise the tenant tracking slug to 5 characters (eg. AXON -> AAXON)
+  const normalisedSlug = decodeSlug(encodeSlug(tenantTrackingSlug));
+  return slug === normalisedSlug;
+}
+
+export function isTrackingIdCloid(
+  trackingId: bigint | string,
+  cloidHex?: `0x${string}` | null,
+): boolean {
+  if (!cloidHex || !isBasedCloid(cloidHex)) return false;
+  const cloidData = parseCloid(cloidHex);
+  if (!cloidData) return false;
+
+  if (typeof trackingId === "string") {
+    const encodedTrackingId = normaliseTrackingId(trackingId);
+    return encodedTrackingId === cloidData.decodedOid;
+  } else {
+    const { oid } = cloidData;
+    return oid === trackingId;
+  }
+}
+
+export function normaliseSlug(slug: string): string {
+  if (!slug) return "";
+  return decodeSlug(encodeSlug(slug.toUpperCase()));
+}
+
+/**
+ * Normalise a tracking id to 12 characters
+ * @param trackingId - The tracking id to normalise
+ * @returns The normalised tracking id
+ */
+export function normaliseTrackingId(trackingId: string): string {
+  if (!trackingId) return "";
+  return decodeValue(
+    encodeValue(trackingId.toLowerCase(), OID_BITS, OID_ALPHABET),
+    OID_BITS,
+    OID_ALPHABET,
+  );
+}
+
+type ClientCode = string;
+
+// Client code type 0 - 10 reserved
+export const CloidClientCode = {
+  Unset: 0, // 0x00
+  Web: 1,
+  App: 2,
+  TgBot: 3,
+  TSL: 4, // Trailing Stop Loss
+  Grid: 5,
+  Chase: 6,
+  Desktop: 7,
+  API: 8,
+} as const;
+type ClientCodeType = keyof typeof CloidClientCode;
+
+// Inverted map: number -> name
+export type CloidClientCodeId = (typeof CloidClientCode)[ClientCodeType];
+export const CloidClientCodeNameById: Record<number, ClientCodeType> = {
+  [CloidClientCode.Unset]: "Unset",
+  [CloidClientCode.Web]: "Web",
+  [CloidClientCode.App]: "App",
+  [CloidClientCode.TgBot]: "TgBot",
+  [CloidClientCode.TSL]: "TSL",
+  [CloidClientCode.Grid]: "Grid",
+  [CloidClientCode.Chase]: "Chase",
+  [CloidClientCode.Desktop]: "Desktop",
+  [CloidClientCode.API]: "API",
+};
+
+export function getClientCodeNameById(id: number): string {
+  return CloidClientCodeNameById[id] ?? `client_${id}`;
+}
+
+// Component code type 0 - 7 (3 bits max)
+export const WidgetType = {
+  Unset: 0, // 0x00
+  SidePanel: 1,
+  Widget: 2,
+  FloatingWidget: 3,
+} as const;
+type WidgetType = keyof typeof WidgetType;
+
+// Inverted map: number -> name
+export type WidgetTypeId = (typeof WidgetType)[WidgetType];
+export const WidgetTypeById: Record<number, WidgetType> = {
+  [WidgetType.Unset]: "Unset",
+  [WidgetType.SidePanel]: "SidePanel",
+  [WidgetType.Widget]: "Widget",
+  [WidgetType.FloatingWidget]: "FloatingWidget",
+};
+
+export function getWidgetTypeById(id: number): string {
+  return WidgetTypeById[id] ?? `widget_${id}`;
+}
+
+/**
+ * @param tenantCode - The tenant code (max 5 characters, truncated if longer) default: "BASED"
+ * @param clientCode CloidClientCode - The client code (max 5 characters, truncated if longer) default: "Unset"
+ * @param oid - The oid (64 bits) used for identifying unique orders, default: 0xBA5ED10000BA5ED1 or string for encoded string slug (12 characters max)
+ * @param attribution - Mini-app and component options
+ * @returns The cloid
+ */
+export function getCloid(
+  tenantCode?: ClientCode | null,
+  clientCode?: ClientCodeType | number,
+  oid?: bigint | string,
+  attribution?: {
+    isMiniApp?: boolean;
+    miniAppTriggered?: boolean;
+    widgetType?: WidgetType | number;
+  },
+): `0x${string}` {
+  try {
+    const clientIdx =
+      typeof clientCode === "number"
+        ? clientCode
+        : CloidClientCode[clientCode ?? "Unset"];
+    return buildCloid(
+      BASED_VERSION,
+      tenantCode ?? DEFAULT_TENANT_CODE,
+      clientIdx,
+      oid ?? DEFAULT_OID,
+      attribution,
+    );
+  } catch (error) {
+    console.error(
+      "Invalid cloid parameters, defaulting to legacy cloid",
+      error,
+      { tenantCode, clientCode, oid, options: attribution },
+    );
+    return LEGACY_CLOID;
+  }
+}
+
+export function isClientCode(
+  clientCode: ClientCodeType | number,
+  cloidHex: `0x${string}`,
+): boolean {
+  const cloidData = parseCloid(cloidHex);
+  if (!cloidData) return false;
+  return cloidData.clientId === clientCode;
+}
+
+export function isWidgetType(
+  widgetType: WidgetType | number,
+  cloidHex: `0x${string}`,
+): boolean {
+  const cloidData = parseCloid(cloidHex);
+  if (!cloidData) return false;
+  return cloidData.widgetTypeId === widgetType;
+}
+
+export function isMiniAppCloid(cloidHex: `0x${string}`): boolean {
+  const cloidData = parseCloid(cloidHex);
+  if (!cloidData) return false;
+  return cloidData.isMiniApp;
+}
+
+export function isMiniAppTriggeredCloid(cloidHex: `0x${string}`): boolean {
+  const cloidData = parseCloid(cloidHex);
+  if (!cloidData) return false;
+  return cloidData.miniAppTriggered;
+}

package/lib/cloid/encoder.ts

@@ -0,0 +1,60 @@
+const mask = (bits: bigint) => (1n << bits) - 1n;
+
+function getEncodingLength(nbits: bigint, alphabet: string): number {
+  return Math.floor(Number(nbits) / Math.log2(Number(alphabet.length)));
+}
+
+// Encode a string value into a n-bit integer
+export function encodeValue(
+  value: string,
+  nbits: bigint,
+  alphabet: string,
+): bigint {
+  const encodingLength = getEncodingLength(nbits, alphabet);
+  if (value.length > encodingLength) {
+    // truncate the value
+    value = value.slice(0, encodingLength);
+  }
+
+  if (value.length < encodingLength) {
+    // pad the value with last character
+    value = value.padEnd(encodingLength, alphabet[alphabet.length - 1]);
+  }
+
+  const base = BigInt(alphabet.length);
+  let encoded = 0n;
+  for (const ch of value) {
+    const idx = alphabet.indexOf(ch);
+    if (idx === -1) throw new Error(`Invalid slug character: ${ch}`);
+    encoded = encoded * base + BigInt(idx);
+  }
+  if (encoded > Number(mask(nbits))) {
+    throw new Error(`Encoded value exceeds ${nbits} bits`);
+  }
+  return encoded;
+}
+
+/**
+ * Decode a n-bit integer back into a x-char slug
+ * @param value - The numeric value to decode
+ * @param nbits - The number of bits
+ * @param alphabet - The alphabet to use for decoding
+ * @returns The decoded value
+ */
+export function decodeValue(
+  value: bigint,
+  nbits: bigint,
+  alphabet: string,
+): string {
+  if (value < 0 || value > Number(mask(nbits))) {
+    throw new Error(`Slug value out of range (must fit in ${nbits} bits)`);
+  }
+  const base = BigInt(alphabet.length);
+  let decoded = "";
+  for (let i = 0; i < getEncodingLength(nbits, alphabet); i++) {
+    const idx = value % base;
+    decoded = alphabet[Number(idx)] + decoded;
+    value = value / base;
+  }
+  return decoded.trim();
+}

package/lib/constants/fee.ts

@@ -0,0 +1,2 @@
+export const BASED_FEE_WALLET = "0x1924b8561eeF20e70Ede628A296175D358BE80e5";
+export const BASED_REFERRAL_CODE = "SHIFU";

package/lib/constants/tokens.ts

@@ -0,0 +1,28 @@
+import { SpotToken } from "@nktkas/hyperliquid";
+
+export const USDC_SPOT_TOKEN: SpotToken = {
+  name: "USDC",
+  szDecimals: 8,
+  weiDecimals: 8,
+  index: 0,
+  tokenId: "0x6d1e7cde53ba9467b783cb7c530ce054",
+  isCanonical: true,
+  evmContract: null,
+  fullName: null,
+  deployerTradingFeeShare: "0.0",
+};
+
+export const TESTNET_USDC_SPOT_TOKEN: SpotToken = {
+  name: "USDC",
+  szDecimals: 8,
+  weiDecimals: 8,
+  index: 0,
+  tokenId: "0xeb62eee3685fc4c43992febcd9e75443",
+  isCanonical: true,
+  evmContract: {
+    address: "0xd9cbec81df392a88aeff575e962d149d57f4d6bc",
+    evm_extra_wei_decimals: 0,
+  },
+  fullName: null,
+  deployerTradingFeeShare: "0.0",
+};