suprafx-agent-sdk 0.3.1

package/dist/src/event-bcs.d.ts

@@ -0,0 +1,341 @@
+/**
+ * BCS encoders for user-originated `Event` variants.
+ *
+ * Mirrors the Rust struct schemas in
+ * `council-rust/crates/protocol/src/events.rs` byte-for-byte.
+ * Cross-language fixture
+ * (`lib/council/__fixtures__/user-event-envelope-fixtures.json`)
+ * proves equivalence; any drift is caught by
+ * `tests/unit/council-event-bcs.test.ts`.
+ *
+ * ## Why we encode client-side (not server-side)
+ *
+ * The user signs `event_bcs` directly. If the server encoded those
+ * bytes, a malicious or compromised server could mutate the event
+ * (UI shows "Withdraw 100 USDC", server encodes "Withdraw 1M USDC")
+ * and the user's wallet would sign the malicious bytes without the
+ * user knowing — chain accepts the sig as valid because the math
+ * works. Client-side encoding makes the bytes-the-user-signs equal
+ * the bytes-the-UI-rendered, since both come from the same auditable
+ * open-source TS code.
+ *
+ * Standard practice — Aptos, Sui, Solana, Ethereum all encode user
+ * transactions client-side for the same reason.
+ *
+ * ## Variant index (must match Rust `Event` enum order)
+ *
+ * BCS encodes a Rust enum as `ULEB128(discriminant) + fields`. The
+ * discriminant is the variant's declaration order in the enum:
+ *
+ *   0  DepositCredited           (validator-attested; not signed by user)
+ *   1  WithdrawRequested         ← user
+ *   2  WithdrawFinalized         (validator-attested)
+ *   3  WithdrawCancelled         (lifecycle)
+ *   4  SubmitRfq                 ← user
+ *   5  CancelRfq                 ← user
+ *   6  PlaceQuote                ← user (maker)
+ *   7  AcceptQuote               ← user (taker)
+ *   8  WithdrawQuote             ← user (maker)
+ *   9  SlashMaker                (lifecycle)
+ *  10..19  validator/governance
+ *  20  DelegatePolicyCreated     ← user (master)
+ *  21  DelegatePolicyUpdated     ← user (master)
+ *  22  DelegatePolicyRevoked     ← user (master)
+ *  23..30 other (not user-signed)
+ *
+ * If any of these indices change in Rust, the cross-language fixture
+ * will fail at the next `cargo run --example
+ * gen_user_event_envelope_fixture` and the TS test will catch it.
+ *
+ * ## Type sizes (locked at the protocol level)
+ *
+ *   AccountId    [u8; 32]
+ *   AssetId      [u8; 32]
+ *   PairId       [u8; 32]
+ *   RfqId        [u8; 16]
+ *   QuoteId      [u8; 16]
+ *   TradeId      [u8; 16]
+ *   Hash         [u8; 32]
+ *   Amount       u128 (16 LE bytes; BCS does NOT use ULEB128 for u128)
+ *   SequenceNumber  u64 (8 LE bytes)
+ */
+/** Settlement mode: Platform=0, OnChain=1. Matches Rust `SettlementMode`. */
+export type SettlementMode = "Platform" | "OnChain";
+/** Delegate role: Maker=0, Taker=1, Agent=2. Matches Rust `DelegateRole`. */
+export type DelegateRole = "Maker" | "Taker" | "Agent";
+/**
+ * `SubmitRfq` payload. Field order MUST match
+ * `council_protocol::events::SubmitRfq` struct declaration.
+ */
+/**
+ * `DepositCredited` payload — validator-attested L1-deposit credit.
+ * Layout matches Rust `council_protocol::events::DepositCredited`
+ * field order; BCS is positional so any reorder there must mirror
+ * here or the cross-language fixture round-trip breaks.
+ */
+export interface DepositCreditedEvent {
+    user: Uint8Array;
+    asset: Uint8Array;
+    amount: bigint;
+    source_chain: string;
+    source_tx: Uint8Array;
+    deposit_id: bigint;
+    source_block: bigint;
+    attesting_validators: Uint8Array[];
+    attestations: Uint8Array[];
+}
+export interface SubmitRfqEvent {
+    user: Uint8Array;
+    pair: Uint8Array;
+    base_asset: Uint8Array;
+    quote_asset: Uint8Array;
+    size: bigint;
+    reference_price: bigint;
+    auto_accept: boolean;
+    auto_accept_target_rate: bigint;
+    allow_partial_fills: boolean;
+    min_fill_size: bigint;
+    expires_at_ms: bigint;
+    rfq_id: Uint8Array;
+    user_sequence_number: bigint;
+    settlement_mode: SettlementMode;
+}
+/** `CancelRfq` payload. */
+export interface CancelRfqEvent {
+    user: Uint8Array;
+    rfq_id: Uint8Array;
+    reason: string;
+}
+/** `PlaceQuote` payload. Note: `maker`, NOT `user`. */
+export interface PlaceQuoteEvent {
+    maker: Uint8Array;
+    rfq_id: Uint8Array;
+    quote_id: Uint8Array;
+    rate: bigint;
+    fill_size: bigint;
+    user_sequence_number: bigint;
+}
+/** `AcceptQuote` payload. Note: `taker` field, plus `trade_id` (NOT `rfq_id`). */
+export interface AcceptQuoteEvent {
+    taker: Uint8Array;
+    quote_id: Uint8Array;
+    trade_id: Uint8Array;
+    user_sequence_number: bigint;
+}
+/** `WithdrawQuote` payload. */
+export interface WithdrawQuoteEvent {
+    maker: Uint8Array;
+    quote_id: Uint8Array;
+}
+/** `WithdrawRequested` payload. */
+export interface WithdrawRequestedEvent {
+    user: Uint8Array;
+    asset: Uint8Array;
+    amount: bigint;
+    /**
+     * AssetId the protocol withdrawal fee is paid in. v1: always SUPRA
+     * (matches the Rust constant in `protocol/src/fees.rs`). Future
+     * USD-pegged variants may switch per chain config.
+     *
+     * Wire position: AFTER `amount`, BEFORE `withdrawal_id` — must
+     * match Rust `events::WithdrawRequested` exactly. Existing BCS
+     * fixtures from before this field was added will fail to decode
+     * (the explorer reader returns null for them, which the renderer
+     * already handles as "unknown event").
+     */
+    fee_asset: Uint8Array;
+    /**
+     * Fee amount in `fee_asset` micro-units. dApp computes via
+     * `computeWithdrawalFee(amount, asset)`; validator re-computes
+     * and rejects on mismatch.
+     */
+    fee_amount: bigint;
+    withdrawal_id: bigint;
+    dest_chain: string;
+    dest_address: Uint8Array;
+    deadline_ms: bigint;
+    user_sequence_number: bigint;
+}
+/**
+ * One entry of a delegate's per-asset cap map (Option B). Mirrors the
+ * Rust `policy::AssetCap` keyed by its `AssetId`.
+ *
+ * ═══ ZERO SEMANTICS — VERIFIED AGAINST THE CONTRACT, 2026-09-15 ═══
+ *
+ *   `0n` means **NO TRADES ALLOWED** for this asset (fail-closed).
+ *   It does NOT mean "unlimited".
+ *   An asset with NO ENTRY is also not tradeable (deny-by-absence),
+ *   and an empty map authorizes nothing.
+ *   For "effectively unlimited", use `MAX_CAP` (u64::MAX) below.
+ *
+ * The validator ORIGINALLY treated `0` as unlimited — fail-OPEN, a
+ * whitehat confirmed it exploitable, and it was fixed in
+ * `council-rust/crates/protocol/src/policy.rs` on 2026-06-07. This
+ * comment kept saying "0n = authorized, unlimited" long after the
+ * contract stopped behaving that way, and an onboarding review read it
+ * and concluded a zero cap grants unlimited authority. It does the
+ * opposite. Keep this comment in step with the contract.
+ */
+export interface AssetCapEntry {
+    /** 32-byte AssetId. */
+    asset: Uint8Array;
+    /**
+     * Per-trade cap (Amount, micro-units). `0n` = NO TRADES for this
+     * asset. Use `MAX_CAP` for effectively unlimited.
+     */
+    maxTradeSize: bigint;
+    /** Cumulative open-earmark cap. Same zero semantics. */
+    maxEarmarkTotal: bigint;
+}
+/**
+ * The canonical "effectively unlimited" cap sentinel: `u64::MAX`.
+ *
+ * NOT `u128::MAX` — the validator's `checked_add(earmarks, size)`
+ * overflows there. NOT `0n`, which is fail-closed (see above).
+ */
+export declare const MAX_CAP: bigint;
+/** `DelegatePolicyCreated` payload. Used for session bootstrap. */
+export interface DelegatePolicyCreatedEvent {
+    master: Uint8Array;
+    delegate: Uint8Array;
+    label: string;
+    allowed_roles: DelegateRole[];
+    allowed_pairs: Uint8Array[];
+    /**
+     * Per-asset caps — a BCS `BTreeMap<AssetId, AssetCap>`. DENY
+     * semantics: an asset absent from this list is not tradeable.
+     * See `docs/handoffs/option-b-per-asset-caps-design.md`.
+     */
+    asset_caps: AssetCapEntry[];
+    /**
+     * Batch number at which this delegation EXPIRES — the on-chain
+     * session bound (#25 H10). `0n` = never expires. Once consensus
+     * reaches this batch, `check_delegate_policy` rejects every
+     * delegated action, so a leaked delegate key is time-bounded even
+     * if the master never submits a revoke. Carried in the signed
+     * envelope so the master cryptographically commits to the lifetime.
+     * Wire position: AFTER `asset_caps`, BEFORE `user_sequence_number`
+     * — must match Rust `events::DelegatePolicyCreated` exactly.
+     */
+    expires_at_batch: bigint;
+    user_sequence_number: bigint;
+}
+/** Taker on-chain settlement claim. Bumps taker's sequence number;
+ *  no balance change (claim only — bridge attesters verify later). */
+export interface TakerTxPendingEvent {
+    trade_id: Uint8Array;
+    taker: Uint8Array;
+    source_chain: string;
+    source_tx: Uint8Array;
+    user_sequence_number: bigint;
+}
+/** Maker on-chain settlement claim. Bumps maker's sequence number. */
+export interface MakerTxPendingEvent {
+    trade_id: Uint8Array;
+    maker: Uint8Array;
+    source_chain: string;
+    source_tx: Uint8Array;
+    user_sequence_number: bigint;
+}
+/** Master-signed delegate-policy update. Same shape as Created plus
+ *  an `active` flag inserted between max_earmark_total + sequence. */
+export interface DelegatePolicyUpdatedEvent {
+    master: Uint8Array;
+    delegate: Uint8Array;
+    label: string;
+    allowed_roles: DelegateRole[];
+    allowed_pairs: Uint8Array[];
+    /** Per-asset caps — see `AssetCapEntry`. BCS `BTreeMap<AssetId, AssetCap>`. */
+    asset_caps: AssetCapEntry[];
+    active: boolean;
+    user_sequence_number: bigint;
+}
+/** Master-signed delegate-policy revocation. Removes the policy
+ *  entirely; in-flight earmarks are NOT auto-cleared. */
+export interface DelegatePolicyRevokedEvent {
+    master: Uint8Array;
+    delegate: Uint8Array;
+    user_sequence_number: bigint;
+}
+/** Master-signed link revocation. Removes (chain, address) from the
+ *  user's linked_addresses + clears the address_to_master reverse index. */
+export interface LinkedAddressRevokedEvent {
+    /** Master account (32 bytes). */
+    user: Uint8Array;
+    /** Foreign chain id ("eth-sepolia", "supra-testnet", ...). */
+    chain: string;
+    /** Foreign address bytes (variable length per chain). */
+    address: Uint8Array;
+    /** Strict-next sequence number for the master. */
+    user_sequence_number: bigint;
+}
+/**
+ * Tagged-union shape for the user-event encoder. Each `kind` maps
+ * 1-1 to a Rust `Event` variant we support; the discriminator
+ * determines the BCS variant tag and which struct schema is used
+ * for the body.
+ */
+export type UserEvent = {
+    kind: "DepositCredited";
+    payload: DepositCreditedEvent;
+} | {
+    kind: "SubmitRfq";
+    payload: SubmitRfqEvent;
+} | {
+    kind: "CancelRfq";
+    payload: CancelRfqEvent;
+} | {
+    kind: "PlaceQuote";
+    payload: PlaceQuoteEvent;
+} | {
+    kind: "AcceptQuote";
+    payload: AcceptQuoteEvent;
+} | {
+    kind: "WithdrawQuote";
+    payload: WithdrawQuoteEvent;
+} | {
+    kind: "WithdrawRequested";
+    payload: WithdrawRequestedEvent;
+} | {
+    kind: "TakerTxPending";
+    payload: TakerTxPendingEvent;
+} | {
+    kind: "MakerTxPending";
+    payload: MakerTxPendingEvent;
+} | {
+    kind: "DelegatePolicyCreated";
+    payload: DelegatePolicyCreatedEvent;
+} | {
+    kind: "DelegatePolicyUpdated";
+    payload: DelegatePolicyUpdatedEvent;
+} | {
+    kind: "DelegatePolicyRevoked";
+    payload: DelegatePolicyRevokedEvent;
+} | {
+    kind: "LinkedAddressRevoked";
+    payload: LinkedAddressRevokedEvent;
+};
+/**
+ * BCS-encode a user-originated `Event`. Returns the bytes the user
+ * signs (becomes `event_bcs` in the `SignedEventEnvelope`).
+ *
+ * Pure function. Same input → same bytes, every time.
+ */
+export declare function encodeUserEvent(ev: UserEvent): Uint8Array;
+/**
+ * Decode a BCS-encoded `Event` into the corresponding `UserEvent`
+ * variant. Reads the variant tag (ULEB128) from the front of the
+ * buffer + dispatches.
+ *
+ * Returns `null` for variants this module doesn't know about
+ * (validator-attested events like `DepositCredited`, governance, etc.) —
+ * callers should treat that as "decoding deferred to a future
+ * version" rather than an error.
+ *
+ * Throws on truly malformed BCS bytes (truncated, invalid bools, etc).
+ *
+ * After decoding, `reader.remaining()` should be 0; if not, the
+ * payload had trailing bytes (caller-supplied buffer too long, or
+ * a struct-field-mismatch bug).
+ */
+export declare function decodeUserEvent(bcs: Uint8Array): UserEvent | null;