npm package: @oneforge/sdk
Description: Protocol SDK for OneForge — atomic token issuance on Solana
Latest version: 0.1.1

# @oneforge/sdk

[![npm](https://img.shields.io/npm/v/@oneforge/sdk)](https://www.npmjs.com/package/@oneforge/sdk)

Protocol SDK for **OneForge** — a specification for atomic, trustless token issuance on Solana.

OneForge bundles all seven steps of a token launch into a single `VersionedTransaction`. Either every step succeeds or none do. There is no intermediate state in which a deployer retains administrative control.

**[Read the whitepaper](https://crxcible.io/oneforge)** · **[Reference implementation](https://crxcible.io)**

---

## What OneForge guarantees

A token launched via the OneForge protocol satisfies the following invariants, enforced atomically:

| Invariant | How it's enforced |
|---|---|
| Mint authority permanently revoked | `setAuthority(null)` in the same transaction as mint creation |
| Freeze authority never set | Initialised as `null` — no wallet can ever be frozen |
| Metadata permanently on Arweave | URI uploaded before the transaction is built, embedded in the atomic tx |
| 2% of supply burned at mint | `burn` instruction in the same transaction |
| LP distribution enforced | Burn or lock applied atomically — no window between pool creation and LP lock |

If the token exists on-chain, all seven operations completed. No trust in the platform, the deployer, or this document is required.

---

## Installation

```bash
npm install @oneforge/sdk
```

Peer dependencies (must be installed by the consumer):

```bash
npm install @solana/web3.js @solana/spl-token
```

---

## Usage

### Check if a token is OneForge-compliant

```ts
import { Connection } from '@solana/web3.js';
import { isOneForgeCompliant } from '@oneforge/sdk';

const connection = new Connection('https://api.mainnet-beta.solana.com');

const report = await isOneForgeCompliant(
  '4mR2s7NroXHYc8CSiToqJKnZexEXjeiq49YxVuUjmBzY',
  connection,
);

console.log(report.compliant);        // true
console.log(report.metadataUri);      // https://arweave.net/...
console.log(report.violations);       // []
```

The compliance check inspects on-chain state only:
- Mint account (mint authority, freeze authority)
- Metaplex metadata PDA (URI, immutability)

No API calls to Crxcible or any other platform are made.

### Protocol constants

```ts
import { LP_SPLIT, SWAP_FEE_RATE, SUPPLY_BURN_PCT } from '@oneforge/sdk';

LP_SPLIT.quick   // { burned: 70, locked: 0,  creator: 10, platform: 20 }
LP_SPLIT.safe    // { burned: 0,  locked: 75, creator: 15, platform: 10 }

SWAP_FEE_RATE.quick  // 20_000 (2%)
SWAP_FEE_RATE.safe   // 10_000 (1%)

SUPPLY_BURN_PCT      // 2
```

### TypeScript types

```ts
import type {
  OneForgeTier,
  OneForgeParams,
  OneForgeResult,
  OneForgeComplianceReport,
  LpSplit,
} from '@oneforge/sdk';
```

---

## Compliance report shape

```ts
interface OneForgeComplianceReport {
  compliant:              boolean;   // true only if all invariants are satisfied
  mintAuthorityRevoked:   boolean;
  freezeAuthorityRevoked: boolean;
  metadataUri:            string | null;
  metadataOnArweave:      boolean;
  violations:             string[];  // human-readable list of failed checks
}
```

---

## LP distribution

### Quick tier

| Recipient | Share |
|---|---|
| Burned (permanent) | 70% |
| Creator wallet | 10% |
| Platform | 20% |

70% of LP tokens are sent to a burn address. The liquidity they represented stays in the pool permanently — nobody can ever claim it.

### Safe tier

| Recipient | Share |
|---|---|
| Locked via Raydium lock program | 75% |
| Creator wallet | 15% |
| Platform | 10% |

75% of LP tokens are locked permanently via Raydium's on-chain lock program. The lock is irrevocable.

---

## Protocol specification

The OneForge protocol is defined by the following invariants. Any implementation that satisfies all of them is a valid OneForge launch.

1. All seven operations execute within a single `VersionedTransaction` (v0 format).
2. Mint authority is set to `null` via `setAuthority` within that transaction.
3. Freeze authority is initialised as `null` — never set.
4. 2% of total supply is burned within that transaction.
5. Token metadata is created via the Metaplex Token Metadata program, referencing an Arweave URI.
6. The Arweave URI is uploaded and confirmed before the transaction is constructed.
7. LP distribution (burn or lock) is applied within the same atomic pipeline.

**The atomicity guarantee:** Solana transactions are atomic by definition. If any instruction fails, the entire transaction reverts. OneForge exploits this property — there is no partial execution state possible.

---

## Reference implementation

**Crxcible** ([crxcible.io](https://crxcible.io)) is the first production deployment of the OneForge protocol. It has processed multiple launches across both tiers on Solana mainnet since March 2026.

Crxcible is a product that implements this protocol. The guarantees defined here derive from the protocol specification, not from Crxcible's codebase. Any platform can implement OneForge — the on-chain compliance check works against any compliant launch regardless of which platform produced it.

---

## License

MIT