Source: HANDCASH-DESKTOP/docs/asset-actions-and-permissions.md · sha256 20ef8d6aaad3

Asset actions and permissions

Every permission an app can hold, and every item, token, market and BSV action the wallet performs, with the module that owns it. The last sections cover what is still missing and the state of countersigned (issuer-accepted) assets.

Related: brc-wallet-feature-map.md (feature → BRC), bnt-tokens.md, wallet-p2p-messagebox.md.

Specs: market listings are BRC-254 (draft); tokens and issuer items are BNT, BRC-255 (draft), planned in bnt-tokens.md. BRC-162 (BSV-21) and BRC-253 are not supported. This page and the drafts are published at https://brc-cloud.bcryderman.workers.dev/docs; paste that address into Apps → Open a web app to read them inside the wallet.

0. Asset profiles

Profiles are specified in BRC-214 (docs/bsva/brcs/coins/0214.md, held back, not submitted); apps read them with listAssetProfiles. Five are coin profiles that share the per-app payment budget: bsv (createAction), coin:ltc, coin:bch, coin:btc and coin:doge (BRC-213, docs/bsva/brcs/coins/0213.md: native coins, spendable once buried on the wallet's own header chain — 6 confirmations on Litecoin and Bitcoin Cash, 3 on Bitcoin, 20 on Dogecoin — apps use getCoinAddress / listCoins / sendCoins with chain: "ltc", "bch", "btc" or "doge"; sendCoins takes an identityKey in place of address when the recipient's signed record names the chain, BRC-213 §7). The four asset profiles below are always per-action.

Every asset the wallet holds belongs to exactly one profile. A profile is a storage basket, an app permission scheme, a tag prefix and a set of actions. Granting one profile never grants another, and no asset changes profile.

1. Bridge methods

The bridge listens on https://127.0.0.1:2121, with an HTTP fallback on http://127.0.0.1:3321 (electron/httpServer.ts). Gate sets live in src/contracts/brc100.ts. A method must also be in the handler manifest src/contracts/brc100Handlers.ts, or the bridge answers 404.

Origin-limited HandCash methods:

• Market (isMarketListingOrigin, marketListing.ts): HandCash hosts plus market-v2.handcash.io, handcash-market-v2.pages.dev and brc-cloud.bcryderman.workers.dev. Covers create, cancel and purchase of listings, purchase intents, provenance checks, receipts, status and publish marks. Duplicate in-flight list, cancel or purchase calls for one item return 409 ACTION_IN_PROGRESS.
• Handle claim: claimCloudHandle and clearClaimedCloudHandle are limited to HandCash hosts.
• Admin: createAdminIdentityProof is limited to HandCash and BRC-CLOUD hosts, with a handcash-ops-login challenge that expires in 5 minutes.

Bridge-wide rules:

• The browser Origin header beats the originator header.
• Protocol account and self-linkage are reserved (BRC-208).
• createAction checks every held-row spend label against exactly one held row that is also an input.
• Index-expansion methods and the retired fungible protocol are refused by name.

2. Permissions

All grants are stored per account (accountLocalKey). Grants, prompts and activity name the caller's own host; no host is ever shown or granted as another. View grants alone are shared across the market hosts under handcash.io (viewGrantOriginAliases), never with a domain HandCash does not own.

Always prompted, never covered by a grant: item and token sends, mints, identity-signed issuance, every market write, createSignature, encryption and key linkage. Prompt wording comes from summarizeAction (permissions.ts). Market prompts show the item and "Total includes the 5% market fee".

Not implemented: BRC-73 protocol, basket, certificate and counterparty grants. Calls that would use them prompt each time. Persisted grants never expire.

Revocation: revokeOrigin removes the app and clears its auto-pay, spending authorization and session grants (AppDetailsPanel.tsx, Disconnect).

Scopes refused by name: a bare 1sat (USE_P1SAT_SCOPE), a bare bntft, a bare iptft or iptnft (USE_COUNTERSIGNED_SCOPE), any app write into either or a p iptft|iptnft input id label (COUNTERSIGNED_WALLET_ONLY), and any unknown p scheme (UNSUPPORTED_P_BASKET).

3. Item actions (1Sat)

4. Token actions (BNT, open mode)

Filing bntft (tokens) or bntnft (items), tags <filing> and <filing>:<40-hex asset id>. Details in bnt-tokens.md.

Keys follow BRC-251 Custody. Every value output a transfer writes gets a fresh BRC-29 child (protocol [2,"3241645161d8"], key ID "<prefix> <suffix>", counterparty the other party; brc29Keys.ts). A BRC-100 wallet never signs with its root key, so no new output locks to an identity address:

• the payee's own child, when the transfer is delivered to it by identity key: tokens and items (single and batch);
• this wallet's own child, for change, a self-send, burn change and the burn inscription's sat, imported item sweeps, the market listing lot, its payout, offer key and change, the buyer's received item, ordinal pads and the Sigma issuer anchor.

The remittance strings are stored in each output's customInstructions, so BRC-39 backs them up with the rest of local state. Item, pad and fee-coin rows also carry them as a brc29:<hex prefix>.<hex suffix>.<sender> tag, so the 1sat listing finds each tip's key without reading every row's customInstructions. The delivery carries the payee's strings in meta.asset.remittance (DeliveryRemittance, one row per output), and receive derives the key from them. A payee known only by a bare address keeps that address; an identity key is never turned into its address. Outputs earlier releases wrote to the identity address still resolve and spend (heldP2pkhSigningKey). Every token and item input signs with tipSigningKey (tipKeys.ts), and every ownership check uses lockHolder: a derived lock is never on the address scan, so its absence there never rejects a send or ghost-drops the tip. identityAddressRatchet.test.ts holds the identity-address sites to recognition only.

5. Market actions

Specified in BRC-254 §1–§9. A listing is a 1SAT-MARKET PushDrop offer: the asset at vout 0, the offer at vout 1. At list time the seller signs both inputs of the buyer's settlement SIGHASH_SINGLE|ANYONECANPAY|FORKID (settlement v2, marketSettlementLayout.ts). Each signature commits to the output at its own input index: the asset to the seller payment, the offer to the market fee. The asset cannot move without paying the seller, and withdrawing someone else's advert costs the fee.

An ordinal follows its satoshi. Output 0 returns exactly the two pads' satoshis, so the item's satoshi lands in output 1 while its signature binds output 2. Pads are root-key P2PKH outputs in basket market-pads (marketPads.ts). The toolbox never funds with them, and the first ordinal buy mints two.

Version 1 signed the asset NONE|ANYONECANPAY, and the index served that signature to anyone, so anyone could move a listed asset to themselves. Cancel spent only the offer, which left the signature live. Now:

• the wallet completes only v2 unlocks (unlocksBindSellerPayment);
• the index refuses v1 at admission (settlement-unlocks-unbound) and never serves it;
• cancel spends the asset back to the seller along with the offer.

Minimum price 20 sats. Fee 5% (MARKET_FEE_BASIS_POINTS).

6. BSV actions

7. Missing

8. Countersigned assets

Not built. The BRC-253 engine, direct offers and token listings were removed with BRC-162. Countersigned assets come back as BRC-255 countersigned mode (bnt-tokens.md phase 4), filed in iptft / iptnft. Until then the wallet issues and moves open assets only (unsupported-mode), apps may view those filings but never write or spend there (COUNTERSIGNED_WALLET_ONLY), and a countersigned delivery waits unacknowledged in box bnt.