@kassealhq/sdk 0.2.0 → 1.0.0

package/docs/partner-tag.md

@@ -0,0 +1,134 @@
+# Wallets: adding your partner tag
+
+A wallet partner's trades on Kasseal are recognised by a **partner tag**: 6 bytes in the transaction's payload that
+name the partner and the channel the trade came through. Tagged trades are credited to the partner under its partner
+agreement with Kasseal. This page covers the format, what a wallet has to do for each channel, and how to add and
+check the tag with the SDK.
+
+Only trades of Kasseal tokens (a curve buy or sell, or a swap on a Kasseal pool) are credited: the share is a part of
+Kasseal's own fee. An imported coin (a token whose `venue` field is set, see [api.md](api.md)) pays Kasseal no fee, so
+its trades earn no share, tagged or not.
+
+## The tag
+
+The tag is the transaction's whole payload, exactly 6 bytes:
+
+| Bytes | Field | Value |
+|---|---|---|
+| 0..1 | Magic | `4B 53` (`"KS"`) |
+| 2 | Version | `01` |
+| 3..4 | Partner id | u16, big-endian |
+| 5 | Channel | u8 |
+
+For example, KasWare (partner 1) on the in-wallet channel (3) is `4B 53 01 00 01 03`, or `4b5301000103` in hex.
+
+A payload is a tag only when it is exactly these 6 bytes with a known partner and a known channel. Anything else,
+including a valid tag followed by more bytes, is not a tag, and the trade is untagged.
+
+The payload is part of the transaction id and of every input's signature hash, so the user's signature commits to the
+tag. The contracts never read it: a tagged trade executes exactly as an untagged one, and costs only the network fee
+of 6 more bytes, which the SDK includes in its fee.
+
+Only curve buys, curve sells and pool swaps carry a tag. Liquidity, fee payouts (sweeps) and the other builders always
+build an empty payload.
+
+## Partner ids and channels
+
+| Partner id | Partner | SDK constant |
+|---|---|---|
+| 1 | KasWare | `PARTNER_IDS.kasware` |
+| 2 | Kaspire | `PARTNER_IDS.kaspire` |
+| 3 | Reserved for Kastle | `PARTNER_IDS.kastle` |
+| 1000 | BraidSwap (an app, not a wallet: its own app builds every trade, so it uses channel 3 only) | `PARTNER_IDS.braidswap` |
+| 1001 and up | Future integrators | |
+
+| Channel | Name | SDK constant | Who adds the tag |
+|---|---|---|---|
+| 1 | Extension: a trade on the Kasseal website, signed with the partner's browser extension | `PARTNER_CHANNELS.extension` | The Kasseal website |
+| 2 | WalletConnect: a trade on the Kasseal website, signed with the partner's mobile wallet over WalletConnect | `PARTNER_CHANNELS.walletconnect` | The Kasseal website |
+| 3 | In-wallet: a swap inside the partner's own app | `PARTNER_CHANNELS.embedded` | The partner's app |
+
+Partner ids are assigned by Kasseal; do not pick one yourself. An id is never reused or given a new meaning. A newly
+assigned id is added to `PARTNER_IDS` in an SDK minor release; until the SDK version you use knows your id, the
+builders and `encodePartnerTag` refuse it with a `RangeError` rather than write a tag nobody can read.
+
+## Connected trades (channels 1 and 2): sign the payload unchanged
+
+When a user trades on the Kasseal website with your extension or over WalletConnect, the website builds the
+transaction with your tag already in the payload. Your wallet does not need any Kasseal code. It only has to:
+
+- sign the transaction it was given, with its payload unchanged;
+- never strip, rewrite, re-encode or append to the payload, and never rebuild the transaction from its parts in a way
+  that loses the payload.
+
+Changing the payload changes the transaction id. The website checks that the signed transaction has the id it built
+(`finalize` and `signBuilt` refuse anything else), so a wallet that drops or alters the payload does not just lose the
+tag: the trade fails and nothing is submitted.
+
+## In-wallet trades (channel 3): add the tag with the SDK
+
+A swap screen inside your own app builds the trade itself, so your code adds the tag. Pass `partner` to the builder
+from `createTxBuilder`. It takes a `PartnerTag`, `{ partner, channel }`, on all four trade builders:
+
+```ts
+import type { BuiltTx, LaunchProofVerdict, PartnerTag, PublicTxBuilder } from '@kassealhq/sdk/web';
+
+const PARTNER: PartnerTag = { partner: 1, channel: 3 };   // your id from Kasseal, channel 3 (in-wallet)
+
+declare const builder: PublicTxBuilder;                   // createTxBuilder({ sources, networkId })
+declare const tokenId: string, poolId: string, address: string, xOnly: Uint8Array, proofVerdict: LaunchProofVerdict;
+
+// Curve buy and sell
+const buy: BuiltTx = await builder.buildBuy({ covenantId: tokenId, tokenId, buyer: address, buyerXOnlyPubkey: xOnly, lots: 10n, proofVerdict, partner: PARTNER });
+const sell: BuiltTx = await builder.buildSell({ covenantId: tokenId, tokenId, seller: address, sellerXOnlyPubkey: xOnly, lots: 10n, proofVerdict, partner: PARTNER });
+
+// Pool swap, either side
+const swap: BuiltTx = await builder.buildSwap({ poolId, expectedPoolId: poolId, tokenId, trader: address, traderXOnlyPubkey: xOnly, side: 'kas->tok', amountIn: 100_000_000n, partner: PARTNER });
+
+// Pool sell of a script-held token cell
+declare const payout: string, redeem: Uint8Array, signerXOnly: Uint8Array, scriptAddress: string;
+const scriptSell: BuiltTx = await builder.buildScriptSell({ poolId, expectedPoolId: poolId, tokenId, payout, redeem, signerXOnly, scriptAddress, partner: PARTNER });
+```
+
+The synchronous shapes take the same tag as `partnerTag`: `buildBuy`, `buildSell`, `buildSwapKasForTokens` and
+`buildSwapTokensForKas` (`{ ...params, partnerTag: PARTNER }`).
+
+- Pass the same tag on every build and rebuild of the same trade (a retry, a replacement, a build on a newer pending
+  state), so every attempt is credited alike.
+- Leave `partner` out and the payload stays empty: the transaction is byte for byte what an untagged build gives.
+- Use channel 3 only for trades your own app builds. Trades your users make on the Kasseal website are tagged by the
+  website (channels 1 and 2).
+
+[examples/partner-tag.ts](../examples/partner-tag.ts) has these builders as functions, with the checks below.
+
+## Building the tag by hand
+
+If your app builds Kasseal transactions without the SDK's builders, write the payload with `encodePartnerTag` and set
+it as the transaction's whole payload:
+
+```ts
+import { encodePartnerTag } from '@kassealhq/sdk';
+
+const payload: Uint8Array = encodePartnerTag({ partner: 1, channel: 3 });   // 4b 53 01 00 01 03
+```
+
+`encodePartnerTag` throws a `RangeError` on a partner id or channel it does not know. The format constants are
+exported too: `PARTNER_TAG_MAGIC_0` (`0x4B`), `PARTNER_TAG_MAGIC_1` (`0x53`), `PARTNER_TAG_VERSION` (`1`) and
+`PARTNER_TAG_BYTES` (`6`). Remember the network fee of the 6 payload bytes when you compute your fee.
+
+## Checking a transaction carries the tag
+
+`decodePartnerTagHex` reads a payload in lowercase hex, the form `built.txJson` and the Kaspa node use, and returns
+the tag or `null` (lowercase a payload from another source first). `decodePartnerTag` does the same for bytes.
+
+```ts
+import { decodePartnerTagHex, type BuiltTx } from '@kassealhq/sdk';
+
+declare const built: BuiltTx;
+const payloadHex: string = (JSON.parse(built.txJson) as { payload?: string }).payload ?? '';
+const tag = decodePartnerTagHex(payloadHex);        // { partner: 1, channel: 3 }, or null when untagged
+if (tag === null || tag.partner !== 1) throw new Error('not tagged as ours');
+```
+
+Run this check on a built trade before you show the signing prompt, and in your tests. `isPartnerId` and
+`isPartnerChannel` tell whether a number is a known id or channel.

package/docs/wallets.md

@@ -149,6 +149,11 @@ After the wallet answers, `signBuilt`:
 
 Anything else is refused with `FinalizeError` and nothing is submitted.
 
+**Trades made in your own app.** A wallet partner that builds Kasseal trades in its own app passes its partner id and
+the `embedded` channel as the builder's `partner` option, on every build and every rebuild of a trade. The tag is the
+transaction's 6-byte payload, covered by the txid, so the check above also refuses a signed transaction whose tag
+was removed or changed. See [Wallets: adding your partner tag](partner-tag.md).
+
 **Before you show a signing prompt**, show the user what the SDK computed: the tokens or KAS they receive, the
 all-in cost (`maxAllIn`) or the net amount (`minNetOut`), the cell deposit and the network fee. The builder refuses
 to build when those bounds are not met (`NetBoundExceeded`).

package/examples/README.md

@@ -12,6 +12,7 @@ Run them with Node 22.6 or later (`node --experimental-strip-types examples/<fil
 | [`pool-buy.ts`](pool-buy.ts) | The full flow: proof, build on the latest state, sign, submit, safe retry | Yes (`KEY`) |
 | [`swap-and-deposit.ts`](swap-and-deposit.ts) | A pool buy delivered to a key-locked script | Yes (`KEY`) |
 | [`pool-sell-wallet.ts`](pool-sell-wallet.ts) | A pool sell signed by a browser wallet (module for a web page) | Wallet |
+| [`partner-tag.ts`](partner-tag.ts) | A wallet's own swap screen: every trade builder with the wallet's partner tag, and the tag checks | Wallet |
 | [`lib/api.ts`](lib/api.ts) | A minimal REST client: reads, submission and status (the builder's sources are the SDK's `createApiSources`) | |
 | [`lib/proof.ts`](lib/proof.ts) | Launch-proof check with the public Kaspa API graduation check | |
 

package/examples/partner-tag.ts

@@ -0,0 +1,58 @@
+/**
+ * A wallet's own swap screen: every Kasseal trade it builds carries the wallet's partner tag (docs/partner-tag.md).
+ *
+ * This file is a module for a wallet. It assumes the wallet has loaded the SDK's web entry once (`initWeb`) and has a
+ * builder from `createTxBuilder`, as in pool-sell-wallet.ts. The tag below is KasWare's (partner 1) on the in-wallet
+ * channel (3); use the partner id Kasseal assigned to you.
+ */
+import {
+  PARTNER_TAG_BYTES,
+  decodePartnerTagHex,
+  encodePartnerTag,
+  type BuiltTx,
+  type LaunchProofVerdict,
+  type PartnerTag,
+  type PublicTxBuilder,
+} from '@kassealhq/sdk/web';
+
+/** Your partner id and the in-wallet channel. Pass the same tag on every build and rebuild of a trade. */
+export const PARTNER: PartnerTag = { partner: 1, channel: 3 };
+
+/** A curve buy of `lots` lots, tagged. */
+export function curveBuy(builder: PublicTxBuilder, tokenId: string, address: string, xOnly: Uint8Array, lots: bigint, maxAllIn: bigint, proofVerdict: LaunchProofVerdict): Promise<BuiltTx> {
+  return builder.buildBuy({ covenantId: tokenId, tokenId, buyer: address, buyerXOnlyPubkey: xOnly, lots, maxAllIn, proofVerdict, partner: PARTNER });
+}
+
+/** A curve sell of `lots` lots, tagged. */
+export function curveSell(builder: PublicTxBuilder, tokenId: string, address: string, xOnly: Uint8Array, lots: bigint, minNetOut: bigint, proofVerdict: LaunchProofVerdict): Promise<BuiltTx> {
+  return builder.buildSell({ covenantId: tokenId, tokenId, seller: address, sellerXOnlyPubkey: xOnly, lots, minNetOut, proofVerdict, partner: PARTNER });
+}
+
+/** A pool swap either way, tagged: `amountIn` is the KAS leg (kas->tok) or the token amount (tok->kas). */
+export function poolSwap(builder: PublicTxBuilder, poolId: string, tokenId: string, address: string, xOnly: Uint8Array, side: 'kas->tok' | 'tok->kas', amountIn: bigint): Promise<BuiltTx> {
+  return builder.buildSwap({ poolId, expectedPoolId: poolId, tokenId, trader: address, traderXOnlyPubkey: xOnly, side, amountIn, partner: PARTNER });
+}
+
+/** A pool sell of a token cell held by a key-locked script, tagged. */
+export function scriptSell(builder: PublicTxBuilder, poolId: string, tokenId: string, payout: string, redeem: Uint8Array, signerXOnly: Uint8Array, scriptAddress: string): Promise<BuiltTx> {
+  return builder.buildScriptSell({ poolId, expectedPoolId: poolId, tokenId, payout, redeem, signerXOnly, scriptAddress, partner: PARTNER });
+}
+
+/** The 6 payload bytes by hand, for a wallet that builds its transactions without the SDK's builders. */
+export function partnerPayload(): Uint8Array {
+  const payload = encodePartnerTag(PARTNER); // 4b 53 01 00 01 03
+  if (payload.length !== PARTNER_TAG_BYTES) throw new Error('unexpected tag length');
+  return payload;
+}
+
+/** Whether a transaction's payload (lowercase hex, as the node and `built.txJson` give it) carries your tag. */
+export function carriesOurTag(payloadHex: string): boolean {
+  const tag = decodePartnerTagHex(payloadHex);
+  return tag !== null && tag.partner === PARTNER.partner && tag.channel === PARTNER.channel;
+}
+
+/** Check a built trade before you show the signing prompt. */
+export function assertTagged(built: BuiltTx): void {
+  const payload = (JSON.parse(built.txJson) as { payload?: string }).payload ?? '';
+  if (!carriesOurTag(payload)) throw new Error(`trade ${built.txid} does not carry the partner tag`);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kassealhq/sdk",
-  "version": "0.2.0",
+  "version": "1.0.0",
   "description": "Quotes, transaction builders, launch-proof verification and wallet adapters for Kasseal tokens on Kaspa.",
   "license": "MIT",
   "type": "module",
@@ -71,6 +71,7 @@
     "docs/errors.md",
     "docs/explorers.md",
     "docs/launch-proof.md",
+    "docs/partner-tag.md",
     "docs/trading-bots.md",
     "docs/wallets.md",
     "examples/"