> For the complete documentation index, see [llms.txt](https://argon-4.gitbook.io/argon-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://argon-4.gitbook.io/argon-docs/suresign/kernel-api.md). # Kernel API The interface a host uses to drive SureSign: the session object, the plan, review, authorize, sign cycle, JSON conventions, and the ABI marker. SureSign is a Rust crate (`suresign`) with an optional WebAssembly surface (`--features wasm`). A host, Enclave today, drives it through a single session object. This page describes that surface at the level a host author needs; the authoritative reference is the crate's own documentation and `core/src/wasm_bind.rs`. ## Shape One genuine dedicated worker constructs the extension's `WasmKernel`. Popup, sidebar and Studio use the asynchronous `AsyncKernel` facade through private MessagePorts authenticated against browser document identity. The offscreen supervisor can terminate the worker on lock even during Rust execution. The service worker transfers ports without reading them and handles bounded ciphertext storage; it never loads signing WASM. Passwords, PRFs and phrase ceremony bytes use the private port, never runtime JSON messaging. Rust retains keys, review state, journal and Desk state; TypeScript constructs no transaction and performs no private-key operation. ``` new() → session (locked, no vault) abi_version() → "suresign-15" (static; check before use) ``` The owner checks the exact ABI before constructing a session. ABI 9 adds encrypted Contacts and saved DAGmate matches, with `contacts_upsert`, `contacts_remove`, `game_import`, `plan_game_fund` and `plan_game_reclaim`. Game planning supports only the pinned escrow program, binds the saved match to its network and account, and uses fresh node observations. It does not expose an unrestricted raw signer. ABI 8 added `kcc20_local(snapshot_json?)`, which reconstructs supported owned cells from the encrypted signed-operation journal and counts balances only from exact current node rows. KCC20 creation uses `plan_covenant` with the exact qualified implementation and one to three fixed-supply allocations; name, ticker, precision and optional artwork claims are bound in the signed payload and review. ABI 7 added `kcc20_public(request_json)` for public cell inspection, owner selectors, maturity and exact amount conversion, and `sign(now, snapshot_json?)`. KCC20 signing requires the fresh snapshot; the cached-snapshot fallback refuses KCC20 plans. ABI 4 adds the byte-oriented credential wrappers required by the private owner; it refuses a stale artifact before initialization. The public facade returns Promises for every method. `loadKernel()` connects to the owner; it does not load a local signer into a UI document. ## Vault and session ABI 10 adds dotk consensus name proofs, registration packages, management and encrypted recovery history; native KRON market probes and quotes; and independently checked KaspaCom deployment evidence for Igra calls. These features use the existing review and authorization boundary. The public SDKs do not execute in the wallet. `markets_native_history` validates bounded historical genesis candidates against the bundled KRON constructor families. `markets_native_liquidity_requirements` sizes an LP deposit; it is a read, not authorization. The executable quote and plan independently verify the exact current inputs and outputs. `plan_markets_launch` reviews curve creation and token initialization together. `resume_markets_launch` requires fresh approval for an interrupted initialization. `markets_launch_pending`, `markets_launch_rebroadcast` and `markets_launch_note_completion` preserve account-bound encrypted recovery and exact signed bytes. Public listing is separate: `markets_launch_listing` reads the canonical record, `inspect_markets_launch_listing` creates a message review, and `markets_launch_sign_listing` requires its exact metadata and review hash. The initiating document may sign that review once. The host only posts the returned signed record after explicit approval. | Call | Purpose | | ------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------- | | `create_wallet(password)` / `create_wallet_with_passphrase(password, passphrase)` | New 24-word phrase; returns the phrase **once** and the sealed vault. | | `import_wallet(phrase, password)` / `…_with_passphrase` | Restore from 12 or 24 words. | | `load_vault_hex(hex)`, `vault_hex()` | Load or export the sealed vault envelope (ciphertext only). | | `unlock(password)`, `unlock_with_passkey(credential_id, prf)`, `lock()`, `is_unlocked()` | Session state. | | `add_passkey_slot(password, credential_id, prf)`, `has_passkey_slot()`, `change_password(old, new)` | Slot management; each re-wraps the data key. | | `export_mnemonic(password)` | Reveal the phrase after re-entering the password. | | `set_network(id)`, `network()`, `set_account_index(n)`, `account_index()` | Bind the session to a network and account. | | `derive_address(receive, index)`, `derive_igra_address()`, `desk_address()`, `public_key_hex(receive, index)` | Public derivation. | | `wallet_id_hex()` | The vault's identifier. | The extension calls `create_wallet_bytes`, `import_wallet_bytes`, `unlock_bytes`, `change_password_bytes`, `add_passkey_slot_bytes` and `export_mnemonic_bytes` inside the worker. The facade keeps the caller-facing names above and transfers bounded byte buffers, wiping prompt copies. `derive_addresses(receive, start, count)` batches at most 512 contiguous Rust derivations. Creation and import leave the new vault locked. Vault, journal and Desk persistence is acknowledged before dependent success; a write failure locks and preserves prior durable ciphertext. Recovery hydration belongs to the owner, not individual shells. ## Planning Every planner takes the host's **snapshot** (candidate Notes with outpoint, amount, script, DAA score, coinbase and frozen flags, covenant id, cluster; plus the network and virtual DAA score) and an intent, and returns the plan's UI JSON. | Call | Intent | | ----------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `plan_transfer(to, amount_sompi, snapshot, selected_csv, fee_sompi)` | One KAS payment, optional manual Notes and fee floor. | | `plan_payments(payments_json, snapshot, …)` | Batch of KAS payments. | | `plan_sweep(to, snapshot, …)` | Send max. | | `plan_asset(intent_json, snapshot)` | KRC-20, KRC-721, KNS operations (packages). | | `plan_covenant(intent_json, snapshot)` | Create or spend a catalog program. | | `plan_igra(intent_json, snapshot)` | Igra carrier, entry, unwrap / wrap / approve, sized automatic Entry and contract-call packages under one approval; `gas-topup` is a standalone funding review (host-sized, at least 10 KAS) with no EVM action. | | `quote_igra_costs(intent_json, snapshot, context_json)` | Read-only unsigned cost projection for a new qualified swap, exact reverted retry or saved native journey. The owner supplies time. Reuses package constructors without signing, replacing review authority or persisting observations. Separates fees, Entry funding, retained Notes and gas reserves. | | `max_native_market_buy(intent_json, snapshot)` | Read-only native-buy budget using qualified market state, wallet-owned funding and the ordinary unsigned constructor. Amount and minimum fields are zero sizing sentinels; Rust derives candidate economics. Returns budget facts without installing a plan, signing or persisting state. Requote the returned amount before review. | | `max_igra_market_input(intent_json, snapshot, budget_json)` | Read-only sizing for a new native-iKAS or WiKAS-input Markets swap. Uses real observed balances, gas bounds, the current automatic bridge limit and eligible Kaspa Notes. Returns a sompi-granularity input amount after ordinary unsigned funding checks. The owner supplies time. The host must obtain a fresh quote, simulate its complete package and verify costs before filling the form. | | `plan_igra_retry(id, expected_txid, intent_json, snapshot, receipt)` | Fresh approval of the same saved trade after an exact reverted receipt and positive Kaspa fee observation. The owner supplies time. | | `plan_markets_route(sell_json, target_json, snapshot)` | Bind a qualified native sale to a fixed, self-directed Igra purchase. This review authorizes the sale only. | | `plan_markets_route_entry(id, native_txid, intent_json, snapshot)`, `plan_markets_route_continue(id, native_txid, intent_json, snapshot)` | Separately review one permissionless funding Entry or the final purchase. The owner supplies time. A saved Entry is never recreated. | | `pending_igra_call()` | Exact next reviewed EVM call and gas bounds, or null for an actual L1-only step; never signs. | | `plan_game_fund(id, amount_sompi, snapshot)`, `plan_game_reclaim(id, snapshot)` | Fund the saved match's own escrow or reclaim its deposit after the verified deadline. | | `plan_desk_fund`, `plan_desk_withdraw`, `plan_desk_consolidate`, `plan_desk_handshake`, `plan_desk_post` | Deal Desk float and messages. Consolidate gathers every Desk Note, across identities, into one at the active Desk. | | `inspect_dapp_pskt` / `sign_dapp_pskt`, `inspect_dapp_message` / `sign_dapp_message`, `inspect_igra_message` / `sign_igra_message` | dApp requests, origin-bound. | | `apply_privacy_plan()`, `restore_original_plan()` | Switch between the planned selection and a cluster-preserving alternative. | | `set_preferred_coin_control(on)` | Strict versus preferred manual selection. | Planning never touches secrets except public derivation, and never signs. `plan_dotk_register(request, snapshot)` prepares both registration steps under one review. `resume_dotk_register(id, snapshot)` prepares fresh approval for an interrupted activation. Other name operations use `plan_covenant` with the pinned dotk pack. Native KRON trades also use `plan_covenant`; `markets_native_catalog`, `markets_native_probes` and `markets_native_quote` expose the exact qualified artifacts and candidate reads. Both native KRON and dotk signing require a fresh snapshot. `markets_route_pending()` and `igra_recovery_pending()` return public pointers to authenticated records for the current wallet, account and network. `observe_markets_route(id, expected_txid, snapshot)` and `observe_igra_fee(id, snapshot)` persist positive exact-output observations; absence does not undo a previous observation. `markets_route_rebroadcast` and `igra_rebroadcast` return only the exact saved signed transaction for the given record and transaction ID. They never construct a replacement or grant new signing authority. The owner persists signed records before releasing bytes. ABI 15 adds `igra_execution_pending()` and `igra_execution_rebroadcast(id, expected_txid)` for every signed Igra package slot, including dApp carriers and automatic Entry funding. Public rows contain only transaction locators. Exact bytes remain in the encrypted journal and are returned only for the matching unlocked wallet, account and network. Nonce reservations survive restart and apply across wallet and dApp plans. These records do not grant Markets retry fee credit. ## Review, authorize, sign ``` review() → ReviewPlan UI JSON (with review_hash) authorize(review_hash_hex, origin, request_id, now) sign(now) → { bytes_hex, tx_id, rpc_tx_json } advance_package(snapshot_json, now) → next slot signed, or "pending" ``` `review()` returns the plan the kernel holds, with amounts as decimal strings so the host cannot lose precision, the headline and findings in the kernel's words, and the review hash. `authorize` binds an approval to that hash for the session's origin and account, with a ten-minute expiry; it is single-use. `sign` requires a matching, unconsumed, unexpired authorization, revalidates against the snapshot, signs, checks post-sign equivalence, and returns the bytes with the transaction id and a node-ready JSON form. For packages, `advance_package` constructs, bounds-checks, signs, and returns each slot as the chain allows, or reports that the package is waiting. The owner binds a prepared review to its document, generation, wallet, account, network and revision. Another document cannot replace, approve or sign it while the original document remains live. `discard_plan(expectedReviewHash?)` releases only that document's current review; an optional mismatched hash preserves it. For delayed cleanup, `reviewWithLease` captures the exact reply context and `discardReview(lease)` checks that original revision, including when a newer review has identical contents. Local `inspect_message(text)` prepares a Rust-authored review for an explicit UI approval before `sign_message(text)`. Message and PSKT signatures must match the inspected text/bytes, origin and review hash. Raw `sign_pskt` is absent from the extension facade. ## Reading | Call | Purpose | | ----------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------- | | `decode_transaction(bytes, snapshot?)` | A ReviewPlan for arbitrary transaction bytes. The same decoder that checks signed output. | | `inspect_pskt(pskt)` | Which inputs the wallet would sign and which it would leave. | | `covenant_catalog()`, `inspect_covenants(snapshot)`, `identify_script(bytes)`, `covenant_identity_json(p2sh, snapshot)` | Catalog, covenant Notes on the snapshot, script recognition, and the identity of a lock. | | `inspect_kcc20_state`, `inspect_kcc20_transfer` | Covenant token inspection. | | `encode_*` (Lynx, Kaskad, Zealous, WiKAS, INS, ERC-20, ERC-721, bridge) | Calldata for pinned Igra reads and writes; `preview_igra_call` explains a call before planning. | | `kns_domain_fee(label)` | The KNS registration fee, in sompi, for a label as the pack would inscribe it — the same schedule the plan restates. | | `kns_primary_message`, `inspect_message` | Construct the KNS challenge text or inspect a local KIP-5 message for explicit review. | ## Journal and Desk `dotk_inspect`, `dotk_inspect_owned` and `dotk_verify` derive and prove name state against bundled deployment identities. `dotk_owner` validates an owner scheme and `dotk_controls` checks this account's ability to manage it. `dotk_pending` lists encrypted registration recovery records; `dotk_rebroadcast` returns only a previously signed, independently checked transaction. `dotk_note_completion` retains historical completion without deleting recovery bytes or restoring authorization. A historical completion is not a current chain proof. | Call | Purpose | | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | `contacts_upsert(json)`, `contacts_remove(id)` | Add, edit or remove a private multi-address contact; returns the updated Desk public JSON after owner persistence. | | `game_import(json)` | Verify and save a supported match in encrypted Desk state; does not fund it. | | `journal_hex()`, `load_journal_hex(hex)`, `journal_public_json()`, `mark_journal_revealed(...)` | The encrypted operation journal: in-flight packages and the wallet's covenants. | | `desk_hex()`, `load_desk_hex(hex)`, `merge_desk_hex(hex)`, `desk_ingest(records, now)`, `desk_public_json()`, `desk_thread_json(deal, peer)`, `desk_deal_json`, `desk_stage_json(deal, snapshot)`, `desk_card_json`, `desk_import_deal`, `desk_mark_read`, `desk_set_label`, `desk_block`, `desk_identity_create(label, now)`, `desk_identity_activate(index)`, `desk_identity_label(index, label)` | Deal Desk state, sealed under a vault-derived key; the kernel decrypts and verifies, the host renders. | ## Conventions * **Amounts** are integers in sompi, carried as decimal strings in JSON. * **Addresses** are Kaspa bech32 strings with network prefix; Igra addresses are checksummed `0x` strings. * **Bytes** are lowercase hex without prefix. * **Errors** are strings naming the reason; policy refusals name the invariant that failed. * **Time** is Unix seconds. Rust has no clock; the dedicated owner supplies its current clock for authorization and signing, ignoring caller timestamps as authority. * **Network access** is nil. The kernel receives snapshots and returns transactions; the host talks to nodes. ## Stability The ABI marker (`suresign-15`) is the compatibility contract between a kernel build and a host build. Within a marker, existing calls keep their meaning and JSON keys keep their names; new calls and keys may be added. A marker bump is a breaking change and is called out in release notes. ### Operation cancellation and error boundary (ABI 6) The dedicated owner additionally has `cancel_current_plan()`. It clears retained transaction authority while preserving the unlocked vault and recovery journal; ordinary UI command dispatch does not expose this raw export. Review dismissal and classified operation-refusal cleanup use it. Rust errors are JavaScript `Error` values named `SureSignRefusal` or `SureSignFault`; their message retains the original error. Only a finite Rust classification permits operation cleanup without session termination. No failed request yields signing permission or transaction bytes.