@bordrless/shared 0.2.0 → 0.3.0

package/dist/api.d.ts

@@ -145,6 +145,10 @@ export interface ConfigInspection {
     registryReady: boolean | null;
     /** The hook is Half-Life: the launch prepares it for the mint and lights its furnace itself. */
     halfLife?: boolean;
+    /** A listed config's author share of the creator fee (bps of it), paid on a launch by anyone but its author; 0 for a plain config. */
+    authorShareBps: number;
+    /** The hook was built and deployed by Studio: the launch prepares it for the mint itself (its standard `prepare`). */
+    studioHook?: boolean;
 }
 /** Live figures of a launch's token rules; each null when the launch lacks the rule or it is not tracked. */
 export interface RuleStats {

package/dist/index.d.ts

@@ -1,3 +1,4 @@
 export * from './api.ts';
 export * from './policy.ts';
 export * from './programs.ts';
+export * from './studio.ts';

package/dist/index.js

@@ -1,3 +1,4 @@
 export * from "./api.js";
 export * from "./policy.js";
 export * from "./programs.js";
+export * from "./studio.js";

package/dist/studio.d.ts

@@ -0,0 +1,333 @@
+/**
+ * Studio and the config marketplace: the shapes the site and the backend exchange.
+ *
+ * Studio is where anyone designs a launch config, and optionally a token hook of their own, with an
+ * assistant that knows the Bordrless programs; has it reviewed; pays the rent for Bordrless to build
+ * and deploy the hook (its upgrade authority then handed to them); makes the config; and may list it
+ * on the marketplace, where every launch someone else makes from it pays them their share of the
+ * creator fee (`create_listed_config`, docs/hooks-v2.md §5.7).
+ *
+ * A Studio hook is written against one template (`STUDIO_TEMPLATE`): an Anchor program with a fixed
+ * `Cargo.toml` and the standard `prepare` (`STUDIO_PREPARE`), so the site can prepare any Studio hook
+ * for a new mint without knowing its code. The backend refuses source that leaves the template's
+ * limits (`StaticCheck`) before it is built, reviewed or paid for.
+ */
+import type { Address, PreparedTx } from './api.ts';
+/** One source file of a hook. Only `src/**.rs` files; `Cargo.toml` is the template's and never sent. */
+export interface StudioFile {
+    /** Relative path, e.g. `src/lib.rs`. */
+    path: string;
+    content: string;
+}
+/** What a project becomes: a config of existing rules alone, or a config with its own hook program. */
+export type StudioKind = 'config' | 'hook';
+/** The launch config a project makes (the arguments of `create_config` / `create_listed_config`). */
+export interface StudioConfigDraft {
+    /** At most 32 bytes. */
+    label: string;
+    creatorFeeBps: number;
+    burnBuyBps: number;
+    burnSellBps: number;
+    /** Kit rules, for a `config` project only (a hook of one's own excludes them). */
+    holderFeeBuyBps: number;
+    holderFeeSellBps: number;
+    maxWalletBps: number;
+    creatorLockDays: number;
+    earlyWindowSecs: number;
+    earlyLockSecs: number;
+    /** `TOKEN_HOOK_FLAGS` the hook runs on, for a `hook` project; 0 for a `config` project. */
+    hookFlags: number;
+    /** List it on the marketplace (made with `create_listed_config`). */
+    listed: boolean;
+    /** The author's share of the creator fee on others' launches, bps of it: 1 to `MAX_AUTHOR_SHARE_BPS`. */
+    authorShareBps: number;
+}
+/** Where a project stands, in the order the Studio walks it. */
+export type StudioStage = 'draft' | 'reviewed' | 'built' | 'paid' | 'deploying' | 'deployed' | 'configured' | 'listed';
+export interface StudioProjectSummary {
+    id: string;
+    owner: Address;
+    name: string;
+    kind: StudioKind;
+    stage: StudioStage;
+    /** The deployed hook, once deployed. */
+    programId: Address | null;
+    /** The config made from it, once made. */
+    config: Address | null;
+    updatedAt: number;
+}
+export interface StudioProject extends StudioProjectSummary {
+    /** A one-paragraph description, shown on the marketplace when listed. */
+    description: string;
+    files: StudioFile[];
+    draft: StudioConfigDraft;
+    /** The last review of the current source; null when the source changed since. */
+    review: StudioReview | null;
+    /** The last build of the current source; null when the source changed since. */
+    build: StudioBuild | null;
+    deploy: StudioDeploy | null;
+    createdAt: number;
+}
+export interface StudioProjectCreateRequest {
+    name: string;
+    kind: StudioKind;
+    /** Start from a template (`STUDIO_STARTERS`), or blank. */
+    starter?: string;
+}
+/** A save: any of the fields; files replace the whole set. Changing files drops the review and the build. */
+export interface StudioProjectUpdateRequest {
+    name?: string;
+    description?: string;
+    files?: StudioFile[];
+    draft?: Partial<StudioConfigDraft>;
+}
+/** `POST /v1/studio/session`: the wallet signs `message` (from `studioSignInMessage`), the backend answers a session token. */
+export interface StudioSessionRequest {
+    wallet: Address;
+    /** The exact message signed. */
+    message: string;
+    /** Base58 ed25519 signature of the message's UTF-8 bytes. */
+    signature: string;
+}
+export interface StudioSessionResponse {
+    token: string;
+    wallet: Address;
+    expiresAt: number;
+    /** What the assistant still allows this wallet today. */
+    quota: StudioQuota;
+}
+export interface StudioQuota {
+    /** Assistant messages left today (UTC). */
+    messagesLeft: number;
+    messagesPerDay: number;
+    /** The assistant is off for everyone (no key, or today's budget spent). */
+    assistantOff: boolean;
+}
+/** The message a wallet signs to use Studio: no transaction, nothing moves. */
+export declare function studioSignInMessage(wallet: Address, nonce: string, issuedAt: string): string;
+/** The header the session token travels in, browser → site proxy → backend. */
+export declare const STUDIO_SESSION_HEADER = "x-studio-session";
+export interface StudioMessage {
+    id: string;
+    role: 'user' | 'assistant';
+    /** Markdown. An assistant message may carry proposals (below) as fenced blocks. */
+    content: string;
+    at: number;
+    /** For an assistant message: the changes it proposes, parsed from its fenced blocks. */
+    proposal: StudioProposal | null;
+}
+/**
+ * What an assistant reply proposes: whole files (```rust file=src/lib.rs fences) and config
+ * fields (a ```json studio-config fence). The Studio shows them as a diff to apply or dismiss.
+ */
+export interface StudioProposal {
+    files: StudioFile[];
+    draft: Partial<StudioConfigDraft> | null;
+    /** Applied by the user (the project's files or draft were replaced by it). */
+    applied: boolean;
+}
+/** `POST /v1/studio/projects/:id/chat`: one user message; the reply is produced in the background. */
+export interface StudioChatRequest {
+    content: string;
+}
+export interface StudioChatResponse {
+    job: string;
+    /** The user's message as stored. */
+    message: StudioMessage;
+    quota: StudioQuota;
+}
+/** `GET /v1/studio/chat/:job`: the reply so far; poll until `state` is not `running`. */
+export interface StudioChatJob {
+    job: string;
+    state: 'running' | 'done' | 'failed';
+    /** The reply's text so far (all of it once done). */
+    text: string;
+    /** Once done: the stored message, its proposal parsed. */
+    message: StudioMessage | null;
+    error: string | null;
+}
+/** One of the template's limits, checked on the source before anything else (no model involved). */
+export interface StaticCheck {
+    id: string;
+    ok: boolean;
+    /** What is checked, in words. */
+    label: string;
+    /** Where it failed: `src/lib.rs:42` and the offending text. */
+    detail: string | null;
+}
+export type FindingSeverity = 'critical' | 'high' | 'medium' | 'low' | 'info';
+export interface ReviewFinding {
+    severity: FindingSeverity;
+    title: string;
+    detail: string;
+    /** `src/lib.rs:42`, when it points at a line. */
+    location: string | null;
+}
+/** `POST /v1/studio/projects/:id/review`: the static checks, then the assistant's security review. */
+export interface StudioReview {
+    /** `fail`: a static check failed or a critical/high finding; deploy is refused. */
+    verdict: 'pass' | 'warn' | 'fail';
+    checks: StaticCheck[];
+    findings: ReviewFinding[];
+    /** A short paragraph: what the hook does, as the reviewer read it. */
+    summary: string;
+    /** sha256 of the source reviewed. */
+    sourceHash: string;
+    at: number;
+}
+/** `POST /v1/studio/projects/:id/build`: compiled by the build worker in the verifiable-build image. */
+export interface StudioBuild {
+    state: 'queued' | 'building' | 'ok' | 'failed';
+    /** The program id the source was built for (its `declare_id!`), reserved for this project. */
+    programId: Address;
+    /** sha256 of the program binary (what `solana-verify get-executable-hash` prints). */
+    hash: string | null;
+    bytes: number | null;
+    /** The compiler's output, its tail. */
+    log: string;
+    sourceHash: string;
+    at: number;
+}
+/** `POST /v1/studio/projects/:id/deploy/quote`: what deploying the built hook costs, in lamports. */
+export interface StudioDeployQuote {
+    /** Rent of the program's data account (the binary plus room to upgrade: `maxDataLen`). */
+    programDataRent: string;
+    /** Rent of the program account. */
+    programRent: string;
+    /** Transaction fees of writing and deploying it. */
+    fees: string;
+    /** Bordrless's service fee. */
+    service: string;
+    total: string;
+    maxDataLen: number;
+    /** The wallet the payment goes to (Studio's deployer). */
+    payTo: Address;
+    /** The payment transaction: a plain SOL transfer of `total` with a memo naming this deploy. */
+    transactions: PreparedTx[];
+    /** The quote holds until then (unix seconds). */
+    expiresAt: number;
+}
+export interface StudioDeployRequest {
+    /** The confirmed payment transaction. */
+    paymentSignature: string;
+    /** Hand the upgrade authority to the owner (default), or make the program final. */
+    authority: 'owner' | 'final';
+}
+export type StudioDeployState = 'awaiting_payment' | 'paid' | 'writing' | 'deploying' | 'handing_over' | 'deployed' | 'failed' | 'refunded';
+export interface StudioDeploy {
+    state: StudioDeployState;
+    programId: Address;
+    /** Lamports paid, and the payment. */
+    paid: string | null;
+    paymentSignature: string | null;
+    /** Bytes written of the binary, while writing. */
+    written: number;
+    bytes: number;
+    deploySignature: string | null;
+    /** Who can upgrade it now: the owner, or null once final. */
+    upgradeAuthority: Address | null;
+    error: string | null;
+    refundSignature: string | null;
+    at: number;
+}
+/** `POST /v1/studio/projects/:id/config/prepare`: `create_config` or `create_listed_config` for the draft. */
+export interface StudioConfigPrepareRequest {
+    /** A fresh keypair's address the browser made; it signs after the wallet. */
+    config: Address;
+}
+export interface StudioConfigPrepareResponse {
+    config: Address;
+    transactions: PreparedTx[];
+}
+export interface MarketplaceListing {
+    config: Address;
+    author: Address;
+    /** The config's on-chain label. */
+    label: string;
+    /** The author's title and description (from Studio), or the label alone. */
+    title: string;
+    description: string;
+    authorShareBps: number;
+    creatorFeeBps: number;
+    burnBuyBps: number;
+    burnSellBps: number;
+    holderFeeBuyBps: number;
+    holderFeeSellBps: number;
+    maxWalletBps: number;
+    customHook: Address | null;
+    customHookFlags: number;
+    /** The hook was built and deployed by Studio from source anyone can read. */
+    studioSource: boolean;
+    /** Who can upgrade the hook now (null: final, or no hook). */
+    hookUpgradeAuthority: Address | null;
+    /** The source passed review when it was deployed. */
+    reviewVerdict: 'pass' | 'warn' | null;
+    launches: number;
+    /** Paid to the author so far, lamports. */
+    authorEarned: string;
+    volumeUsd: number | null;
+    createdAt: number;
+}
+export interface MarketplaceListResponse {
+    listings: MarketplaceListing[];
+    total: number;
+}
+export interface MarketplaceDetail extends MarketplaceListing {
+    /** The hook's source when Studio built it. */
+    files: StudioFile[] | null;
+    buildHash: string | null;
+    review: StudioReview | null;
+    /** Launches made from it, newest first. */
+    recentLaunches: {
+        mint: Address;
+        symbol: string;
+        name: string;
+        image: string | null;
+        createdAt: number;
+    }[];
+}
+/** `POST /v1/author/prepare`: a config author's claims of their share, on up to four launches a transaction, paid as SOL. */
+export interface AuthorPrepareRequest {
+    author: Address;
+    /** The launches to claim on; all with something to claim when absent. */
+    mints?: Address[];
+}
+export interface AuthorEarnings {
+    author: Address;
+    /** Waiting to be claimed on each launch: the author's part of what the launch holds. */
+    launches: {
+        mint: Address;
+        symbol: string;
+        config: Address;
+        claimable: string;
+        paid: string;
+    }[];
+    claimable: string;
+    paid: string;
+}
+/** `bordrless_launch::constants::MAX_AUTHOR_SHARE_BPS`: half the creator fee. */
+export declare const MAX_AUTHOR_SHARE_BPS = 5000;
+/** The share the Studio suggests. */
+export declare const DEFAULT_AUTHOR_SHARE_BPS = 2000;
+/**
+ * The standard `prepare` of a Studio hook: `prepare()` (no arguments) with the accounts
+ * `[payer (signer, writable), mint, state = PDA(["state", mint], hook) (writable), registry =
+ * PDA(["bordrless-hook-accounts", mint], hook) (writable), system program]`. It creates the hook's
+ * state for the mint and writes its registry; anyone may send it, once per mint.
+ */
+export declare const STUDIO_PREPARE: {
+    readonly instruction: "prepare";
+    readonly stateSeed: "state";
+};
+/** Limits of a project's source. */
+export declare const STUDIO_LIMITS: {
+    readonly files: 8;
+    readonly bytes: 120000;
+    readonly messageChars: 8000;
+};
+/** Starters a new hook project can begin from (the template's `src/lib.rs` variants). */
+export declare const STUDIO_STARTERS: readonly {
+    id: string;
+    name: string;
+    blurb: string;
+}[];

package/dist/studio.js

@@ -0,0 +1,26 @@
+/** The message a wallet signs to use Studio: no transaction, nothing moves. */
+export function studioSignInMessage(wallet, nonce, issuedAt) {
+    return ['Sign in to Bordrless Studio', '', 'This signature proves you own this wallet. It does not move funds or approve any transaction.', '', `Wallet: ${wallet}`, `Nonce: ${nonce}`, `Issued: ${issuedAt}`].join('\n');
+}
+/** The header the session token travels in, browser → site proxy → backend. */
+export const STUDIO_SESSION_HEADER = 'x-studio-session';
+// ---- constants ----------------------------------------------------------------------------------------
+/** `bordrless_launch::constants::MAX_AUTHOR_SHARE_BPS`: half the creator fee. */
+export const MAX_AUTHOR_SHARE_BPS = 5_000;
+/** The share the Studio suggests. */
+export const DEFAULT_AUTHOR_SHARE_BPS = 2_000;
+/**
+ * The standard `prepare` of a Studio hook: `prepare()` (no arguments) with the accounts
+ * `[payer (signer, writable), mint, state = PDA(["state", mint], hook) (writable), registry =
+ * PDA(["bordrless-hook-accounts", mint], hook) (writable), system program]`. It creates the hook's
+ * state for the mint and writes its registry; anyone may send it, once per mint.
+ */
+export const STUDIO_PREPARE = { instruction: 'prepare', stateSeed: 'state' };
+/** Limits of a project's source. */
+export const STUDIO_LIMITS = { files: 8, bytes: 120_000, messageChars: 8_000 };
+/** Starters a new hook project can begin from (the template's `src/lib.rs` variants). */
+export const STUDIO_STARTERS = [
+    { id: 'blank', name: 'Blank hook', blurb: 'The template: every callback stubbed, nothing taken, nothing refused.' },
+    { id: 'sell-tax', name: 'Sell tax to a wallet', blurb: 'A cut of every sell sent to a wallet you choose; buys and transfers pass free.' },
+    { id: 'cooldown', name: 'Transfer cooldown', blurb: 'A holding that received tokens cannot send them on for a while, stamped in its hook data.' },
+];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bordrless/shared",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "description": "Bordrless policy (the same math as crates/bordrless-core), program addresses and the API types shared by the server and the site. No Solana dependencies.",
   "license": "Apache-2.0",