@blockula/sdk 0.3.0 → 0.5.1

package/dist/tx.d.ts

@@ -1,7 +1,7 @@
 export type KeyRole = {
     type: "owner";
 }
-/** Transfers only, at most `limit` drops (amount + fee) per `period_blocks`, until block `expires_at`. */
+/** Transfers only, at most `limit` drops (amount + charged fee) per `period_blocks`, until block `expires_at`. */
  | {
     type: "session";
     limit: string;
@@ -15,11 +15,20 @@ export type Action = {
 } | {
     type: "register_name";
     name: string;
-} | {
+}
+/**
+ * Authorize a key on this account (owner keys only). The added key consents: `public_key` is its
+ * hex ML-DSA-65 public key (`key_id` is its BLAKE3) and `pop` its signature over
+ * `keyPopMessage(chain_id, genesis_hash, account, key_id)` with context `KEY_POP_CONTEXT`. Build
+ * it from a `KeyGrant` (`Wallet.keyGrant`, `addOwnerKey`, `addSessionKey`).
+ */
+ | {
     type: "add_key";
     key_id: string;
     label: string;
     role: KeyRole;
+    public_key: string;
+    pop: string;
 } | {
     type: "remove_key";
     key_id: string;
@@ -83,13 +92,344 @@ export type Action = {
     type: "register_familiar";
     key_id: string;
     label: string;
+}
+/** Season 0 admins: put a repo in the contribution pool (weight 1–100; 0 removes it). */
+ | {
+    type: "set_repo";
+    repo: string;
+    weight: number;
+}
+/** Season 0 admins: bootstrap Soul, in milli-Soul (≤ 100 Soul per grant). */
+ | {
+    type: "grant_soul";
+    to: string;
+    amount: number;
+    reason: string;
+}
+/** Stake 10 FANG on a newcomer `account` being a real, distinct person (needs 10 Soul). */
+ | {
+    type: "vouch";
+    account: string;
+}
+/** The voucher withdraws (after the lock), or the newcomer declines (any time). */
+ | {
+    type: "unvouch";
+    account: string;
+} | {
+    type: "flag_sybil";
+    account: string;
+    reason: string;
+}
+/** Claim a merged PR by your linked GitHub handle. Registered Familiars may sign this. */
+ | {
+    type: "submit_claim";
+    repo: string;
+    pr: number;
+    familiar_key?: string;
+}
+/** Validators only (nodes do this automatically). */
+ | {
+    type: "attest_claim";
+    claim_id: number;
+    ok: boolean;
+    merge_sha: string;
+    note: string;
+} | {
+    type: "reject_claim";
+    claim_id: number;
+    reason: string;
+} | {
+    type: "join_jury";
+    bond: string;
+} | {
+    type: "leave_jury";
+}
+/**
+ * A juror's sealed judgment: `seanceCommitment(...)`, and `seancePairsDigest(...)` of the pairs
+ * (and their claims' PRs) the juror compared: other pairs on chain refuse it (audit gap-7-6).
+ */
+ | {
+    type: "commit_votes";
+    seance_id: number;
+    commitment: string;
+    pairs_digest: string;
+}
+/** One of "a", "b", "=" per assigned pair, claim ids flagged as spam, and the salt. */
+ | {
+    type: "reveal_votes";
+    seance_id: number;
+    votes: string;
+    spam: number[];
+    salt: string;
+} | {
+    type: "fund_pool";
+    amount: string;
+} | {
+    type: "withdraw_vested";
+} | {
+    type: "clawback";
+    account: string;
+    reason: string;
+}
+/** Stake `amount` drops in a validator's pool (validators are named by address). */
+ | {
+    type: "delegate";
+    validator: string;
+    amount: string;
+}
+/**
+ * Start unbonding stake in a pool: exactly `shares`, or (with `shares` "0") the shares worth
+ * `amount` drops at the pool's price when the tx runs (rounded up: at least `amount` unbonds).
+ * One of the two is set. Naming an amount, a wallet never converts FANG to shares at a price
+ * some node reported (audit gap-7-5). `withdraw_unbonded` pays it out after the unbonding period.
+ */
+ | {
+    type: "undelegate";
+    validator: string;
+    shares: string;
+    amount?: string;
+} | {
+    type: "redelegate";
+    from_validator: string;
+    to_validator: string;
+    shares: string;
+} | {
+    type: "withdraw_unbonded";
+}
+/** A validator's owner: commission (bps) and, when non-empty, new addresses. */
+ | {
+    type: "update_validator";
+    commission_bps: number;
+    p2p_addr: string;
+    http_addr: string;
+} | {
+    type: "unjail";
+    validator: string;
+}
+/** Two conflicting signed votes, hex (at most 16 KiB decoded). */
+ | {
+    type: "report_equivocation";
+    evidence: string;
+}
+/** A validator's commitment to its secret for the randomness beacon of `epoch`: `beaconCommitment(...)`. */
+ | {
+    type: "beacon_commit";
+    epoch: number;
+    commitment: string;
+} | {
+    type: "beacon_reveal";
+    epoch: number;
+    secret: string;
+}
+/** Put `kind` to a vote, bonding `deposit` drops; `url` (https) links the full text. */
+ | {
+    type: "propose";
+    kind: ProposalKind;
+    deposit: string;
+    title: string;
+    url?: string;
+}
+/** Lock `amount` drops for `conviction` (0–6) lock periods: weight 0.1× with no lock, then 1×–6× for 1, 2, 4, 8, 16, 32 periods. */
+/** `proposal_digest`: `proposalDigest(kind, title, url)` of the proposal the voter was shown; a vote on other content is refused (audit gap-7-6). */
+ | {
+    type: "vote";
+    proposal_id: number;
+    aye: boolean;
+    amount: string;
+    conviction: number;
+    proposal_digest: string;
+}
+/** Release expired vote locks. */
+ | {
+    type: "unlock";
+}
+/** Make this account an M-of-N multisig of its owner keys (key ids). */
+ | {
+    type: "multisig_create";
+    owners: string[];
+    threshold: number;
+}
+/** Propose an action for a multisig account (never another multisig proposal or approval). */
+ | {
+    type: "multisig_propose";
+    action: Action;
+}
+/** `action_digest`: `actionDigest(action)` of the action the approver was shown; approving anything else is refused (audit gap-7-6). */
+ | {
+    type: "multisig_approve";
+    id: number;
+    action_digest: string;
+} | {
+    type: "renew_name";
+    name: string;
+    years: number;
+} | {
+    type: "transfer_name";
+    name: string;
+    to: string;
+} | {
+    type: "release_name";
+    name: string;
+}
+/** `proof`: hex 32-byte hashes from the leaf (distribution_id, address, amount) to the distribution's Merkle root. */
+ | {
+    type: "claim_distribution";
+    distribution_id: number;
+    amount: string;
+    proof: string[];
+}
+/** Validators: a matured claim's PR was reverted by commit `revert_sha` (40 hex). */
+ | {
+    type: "attest_revert";
+    claim_id: number;
+    revert_sha: string;
+}
+/** Move `amount` drops into the shielded pool as the bundle's output notes. Signed; also burns the chain's `ghost_verify_fee`. */
+ | {
+    type: "shield";
+    amount: string;
+    bundle: GhostBundle;
+}
+/** Unsigned (the proof authorizes it): send it with `from`, `memo`, `public_key`, `signature` empty and `nonce` 0. Its `fee` leaves the pool. */
+ | {
+    type: "private_transfer";
+    bundle: GhostBundle;
+}
+/** Unsigned: pay `amount` drops out of the pool to `to` (address or name), plus the fee. */
+ | {
+    type: "unshield";
+    to: string;
+    amount: string;
+    bundle: GhostBundle;
+}
+/** Publish this account's 1,216-byte Ghost Mode address (hex) so wallets find it under the account's names. */
+ | {
+    type: "set_ghost_address";
+    address: string;
+}
+/** Validators: vote to pause Ghost Mode (it pauses once f + 1 of the epoch's validators have). */
+ | {
+    type: "ghost_pause";
+}
+/** A candidate's consensus key: its node is running, in the last tenth of `epoch` (the epoch the tx lands in). Changes nothing but the readiness record; refused until the members admitted it. Nodes send it themselves. */
+ | {
+    type: "validator_ready";
+    epoch: number;
+}
+/** An active member's consensus key admits candidate `validator` (an address) into the set at the end of `epoch` (the epoch the tx lands in): its operator's decision, once an epoch. */
+ | {
+    type: "admit_validator";
+    validator: string;
+    epoch: number;
+};
+/**
+ * What a ghost action carries (node/src/types.rs `GhostBundle`), every field lowercase hex: the
+ * chain `instance` (from `/api/ghost`), the `anchor` root, two 32-byte `nullifiers` and
+ * `commitments`, two note ciphertexts `enc` (1,401 bytes each) and outgoing ciphertexts `out`
+ * (80 bytes each), and the Action `proof`. Proofs come from the `blockula-ghost` prover; this SDK
+ * only encodes.
+ */
+export interface GhostBundle {
+    instance: string;
+    anchor: string;
+    nullifiers: [string, string];
+    commitments: [string, string];
+    enc: [string, string];
+    out: [string, string];
+    proof: string;
+}
+/** What a `propose` asks for (node/src/types.rs `ProposalKind`): every former admin lever, parameters, spending, upgrades and features. */
+export type ProposalKind = 
+/** Set a governance parameter (a key of node/src/params.rs `ChainParams`, e.g. "max_validators"), within its bounds. */
+{
+    type: "param_change";
+    key: string;
+    value: string;
+} | {
+    type: "treasury_spend";
+    to: string;
+    amount: string;
+}
+/** Open a community distribution of `total` drops, claimable with Merkle proofs until block `claim_until`. `distribution_id` is the id its tree was built for, one no distribution has yet (the node's `next_distribution_id`; at most its `max_distribution_id`). */
+ | {
+    type: "distribution";
+    distribution_id: number;
+    merkle_root: string;
+    total: string;
+    claim_until: number;
+} | {
+    type: "set_repo";
+    repo: string;
+    weight: number;
+}
+/** milli-Soul, at most 100 Soul. */
+ | {
+    type: "grant_soul";
+    to: string;
+    amount: number;
+    reason: string;
+} | {
+    type: "flag_sybil";
+    account: string;
+    reason: string;
+} | {
+    type: "reject_claim";
+    claim_id: number;
+    reason: string;
+} | {
+    type: "clawback";
+    account: string;
+    reason: string;
+} | {
+    type: "unlink_github";
+    handle: string;
+} | {
+    type: "refund_hunt";
+    hunt_id: number;
+} | {
+    type: "schedule_upgrade";
+    version: number;
+    activation_height: number;
+} | {
+    type: "activate_feature";
+    feature: string;
+} | {
+    type: "deactivate_feature";
+    feature: string;
+}
+/** No on-chain effect: a signal. */
+ | {
+    type: "text";
+}
+/** Lift a sybil flag (`flag_sybil`'s appeal path): the account can earn again; nothing the flag took comes back. */
+ | {
+    type: "unflag_sybil";
+    account: string;
+    reason: string;
+}
+/** Withdraw the upgrade to `version` scheduled at `activation_height` (and any after it) before it activates (a supermajority, no timelock). Tag 15. */
+ | {
+    type: "cancel_upgrade";
+    version: number;
+    activation_height: number;
 };
 export interface UnsignedTx {
     chain_id: string;
+    /**
+     * The chain instance the tx is for: hex BLAKE3 digest of its genesis block (`genesis_hash` in
+     * `/api/status`). Signed right after `chain_id`, so the tx can't replay on another chain that
+     * reuses the id (e.g. a relaunched testnet). `Wallet.build` fills it in; offline signers pass it.
+     */
+    genesis_hash: string;
     /** The account acting; the signing key must be authorized on it. */
     from: string;
     nonce: number;
+    /** The most the sender will pay, in drops. The tx is charged its block's base fee + `tip` (see `txCharge`). */
     fee: string;
+    /** Drops paid to the block's proposer on top of the burned base fee (default "0"). Blocks take the highest tip per byte first. */
+    tip?: string;
+    /** Last block height at which the tx may execute (at most an hour of blocks ahead). After it, the tx can never execute. */
+    valid_until: number;
     action: Action;
     memo: string;
 }
@@ -99,14 +439,129 @@ export interface Tx extends UnsignedTx {
 }
 export declare const PUBLIC_KEY_LEN = 1952;
 export declare const SIGNATURE_LEN = 3309;
+/** Domain of the unsigned ghost wire form (`private_transfer`, `unshield`). */
+export declare const GHOST_TX_DOMAIN = "BLOCKULA_GHOST_V1";
+export declare const GHOST_ENC_BYTES = 1401;
+export declare const GHOST_OUT_BYTES = 80;
+export declare const GHOST_ADDRESS_BYTES = 1216;
+/** The Action circuit the node verifies proofs against (blockula-ghost `CIRCUIT_ID`). */
+export declare const GHOST_CIRCUIT_ID = 1;
 export declare const DROPS_PER_FANG = 1000000000n;
+/**
+ * The largest value of a whole-number field a tx carries as a JSON number, not a string (ids,
+ * heights, PR numbers, the nonce): 2^53 − 1, what a JavaScript number holds exactly
+ * (node/src/types.rs `MAX_JSON_INT`). The chain refuses larger ones, so every stored proposal
+ * kind and multisig action reads back exactly here, and its digest can be computed.
+ */
+export declare const MAX_JSON_INT: bigint;
+/**
+ * An unsigned integer field as the node reads it from JSON (node/src/types.rs: a JSON number,
+ * or for amounts a decimal string), checked to be in `0 ..= max`. Anything the node's JSON
+ * parser would refuse is refused here, so `signingBytes`/`txBytes` never encode a value other
+ * than the one in the tx object (no wrapping of negative or oversized numbers).
+ */
+export declare function uintField(v: unknown, max: bigint, what?: string): bigint;
+/** A u64 field (`uintField` up to 2^64 − 1). */
+export declare const u64Field: (v: unknown, what?: string) => bigint;
+/** A chain's genesis hash as its 32 bytes (`/api/status` `genesis_hash`, lowercase hex). */
+export declare function genesisHashBytes(genesisHash: string): Uint8Array;
+/** Unsigned ghost txs (`private_transfer`, `unshield`): no key signs them, their proof authorizes them. */
+export declare function isUnsignedAction(a: Action): boolean;
+/**
+ * The bytes a key signs (node/src/types.rs `Tx::signing_bytes`). For an unsigned ghost tx this is
+ * its whole wire form instead: `BLOCKULA_GHOST_V1 ‖ chain_id ‖ genesis hash ‖ fee ‖ tip ‖ valid_until ‖ action`.
+ */
 export declare function signingBytes(tx: UnsignedTx): Uint8Array;
+/**
+ * What a ghost tx's Action proof is bound to (node/src/types.rs `Tx::ghost_sighash`):
+ * BLAKE3-KDF("blockula ghost v1 tx sighash", chain_id ‖ genesis hash ‖ tag ‖ valid_until ‖ fee ‖
+ * tip ‖ the tag's own fields (shield: from, nonce, amount; unshield: to, amount) ‖ the bundle
+ * without its proof ‖ circuit id). A wallet proves with this as the witness's sighash, then fills
+ * in the proof.
+ */
+export declare function ghostSighash(tx: UnsignedTx): Uint8Array;
+/**
+ * What a Séance juror seals before revealing (node/src/types.rs `seance_commitment`): hex
+ * BLAKE3 of the Séance id, the juror's account, the votes, spam flags and a secret salt.
+ */
+export declare function seanceCommitment(seanceId: number, juror: string, votes: string, spam: number[], salt: string): string;
+/**
+ * A validator's randomness-beacon commitment (node/src/beacon.rs `commitment`): hex BLAKE3 in
+ * derive-key mode ("blockula beacon commitment v1") over the chain id, the target epoch, the
+ * validator's address and its 32-byte hex secret. Strings are u64-length-prefixed, integers
+ * u64 little-endian.
+ */
+export declare function beaconCommitment(chainId: string, epoch: number, validator: string, secret: string): string;
+/** "2.5" Soul → 2500 milli-Soul. */
+export declare function parseSoul(soul: string | number): number;
+/**
+ * What a `multisig_approve` binds (node/src/types.rs `action_digest`): BLAKE3 (derive-key mode,
+ * context "blockula multisig action v1") of the action's encoding, as inside the signing bytes.
+ * Compute it from the action you show the approver (`client.multisig(account)` `pending[].action`).
+ */
+export declare function actionDigest(action: Action): string;
+/**
+ * What a `vote` binds (node/src/types.rs `proposal_digest`): the proposal's kind (accounts as
+ * stored, resolved), title and link. Compute it from the proposal you show the voter.
+ */
+export declare function proposalDigest(kind: ProposalKind, title: string, url?: string): string;
+/** One claim of a Séance pair, as the juror judged it. */
+export interface SeanceClaimRef {
+    id: number;
+    repo: string;
+    pr: number;
+}
+/**
+ * What a `commit_votes` binds (node/src/types.rs `seance_pairs_digest`): the Séance, the juror and,
+ * per assigned pair in order, both claims' ids, repos and PR numbers.
+ */
+export declare function seancePairsDigest(seanceId: number, juror: string, pairs: [SeanceClaimRef, SeanceClaimRef][]): string;
+/** FIPS 204 context string for a key's proof of possession in `add_key` (node/src/types.rs `KEY_POP_CONTEXT`). */
+export declare const KEY_POP_CONTEXT: Uint8Array<ArrayBuffer>;
+/**
+ * What a key signs to consent to being added to `account` (node/src/types.rs `key_pop_message`):
+ * the chain instance, the account and the key's own id (audit gap-7-2).
+ */
+export declare function keyPopMessage(chainId: string, genesisHash: string, account: string, keyId: string): Uint8Array;
 /** FIPS 204 context string for validator proofs of possession (node/src/types.rs `POP_CONTEXT`). */
 export declare const POP_CONTEXT: Uint8Array<ArrayBuffer>;
 /** What a validator's consensus key signs to register (node/src/types.rs `pop_message`). */
 export declare function popMessage(chainId: string, owner: string, p2pAddr: string, httpAddr: string): Uint8Array;
-/** Mirrors `min_fee` in node/src/types.rs: base fee is priced per byte and burned. */
+/** Wire size in bytes (node/src/types.rs `Tx::size`): signing bytes plus the key and signature (none for an unsigned ghost tx). Fees are priced on it. */
+export declare function txSize(tx: UnsignedTx): number;
+/**
+ * A block's base fee (node/src/econ.rs `FeeSlot`): `flat` drops per tx plus `rate` milli-drops per
+ * byte. It moves with block fullness and is fixed 17 blocks ahead; `/api/fees` serves the upcoming
+ * ones and `suggested`, the highest of them (what `Wallet.build` prices txs at).
+ */
+export interface BaseFee {
+    flat: string | bigint;
+    rate: string | bigint;
+}
+/** The base fee at its genesis floor: 10,000 drops + 10 per byte (`min_fee`). */
+export declare const FLOOR_BASE_FEE: BaseFee;
+/** Mirrors `FeeSlot::fee` in node/src/econ.rs: `flat + rate × size / 1000`, rounded down. Burned. */
+export declare function baseFee(tx: UnsignedTx, fee?: BaseFee): bigint;
+/** Mirrors `min_fee` in node/src/types.rs: the base fee at its floor (an idle chain's). */
 export declare function minFee(tx: UnsignedTx): bigint;
+/** The chain's default `tip_cap_multiple` (node/src/params.rs): a tip may be at most this many times the base fee of the block that includes it. */
+export declare const DEFAULT_TIP_CAP_MULTIPLE = 20;
+/**
+ * The most this tx may tip in a block with this base fee (node/src/econ.rs `max_tip`): `multiple` × its base fee. Nodes refuse
+ * a bigger tip. `/api/fees` serves the chain's `tip_cap_multiple` and `lowest`, the base fee a tip fits under in any upcoming block.
+ * Tips are also paid only from transferable FANG (locks hold them), and a multisig's owner keys or a validator's consensus key
+ * acting for its owner can't tip at all.
+ */
+export declare function maxTip(tx: UnsignedTx, fee?: BaseFee, multiple?: number | bigint): bigint;
+/** What the tx is charged in a block with this base fee (node/src/econ.rs `charge`): base fee + tip. Its `fee` must cover it; nothing more is debited. */
+export declare function txCharge(tx: UnsignedTx, fee?: BaseFee): bigint;
+/**
+ * Wire form (node/src/types.rs `Tx::to_bytes`): signing bytes ‖ public key (1,952 B) ‖ signature (3,309 B), or just the
+ * unsigned form for an unsigned ghost tx. Blocks and gossip carry this; `POST /api/tx` takes it as `application/octet-stream`.
+ */
+export declare function txBytes(tx: Tx): Uint8Array;
+/** A tx's id (node/src/types.rs `Tx::id`): hex BLAKE3 of the signing bytes and the signature. Known before submitting. */
+export declare function txId(tx: Tx): string;
 /** "1.5" → 1500000000n drops. Accepts numbers, decimal strings or bigint drops. */
 export declare function parseFang(amount: string | number | bigint): bigint;
 export declare function formatFang(drops: bigint | string): string;