@radiant-core/sdk 0.1.0 → 0.2.0

package/README.md

@@ -186,6 +186,18 @@ const status = await client.subscribe(me.address, (newStatus) => {
 | Units | `rxdToPhotons`, `photonsToRxd` |
 | Errors | `RadiantSdkError`, `InsufficientFundsError`, `TokenBurnGuardError`, `ElectrumError`, `ValidationError` |
 
+See **[docs/API.md](docs/API.md)** for the full reference (every export, options,
+and return types), and the hosted guide at
+**[radiantcore.org/docs/sdk.html](https://radiantcore.org/docs/sdk.html)**.
+
+---
+
+## Documentation
+
+- **[API reference](docs/API.md)** — every export, with options and return types.
+- **[Hosted guide](https://radiantcore.org/docs/sdk.html)** — narrative walkthrough on radiantcore.org.
+- **[Changelog](CHANGELOG.md)** · **[Contributing](CONTRIBUTING.md)**
+
 ---
 
 ## Design notes

package/dist/index.cjs

@@ -49,6 +49,11 @@ var MIN_RELAY_FEE_RATE = {
   testnet: 1000n,
   regtest: 1000n
 };
+var MAX_REASONABLE_FEE_RATE = {
+  mainnet: MIN_RELAY_FEE_RATE.mainnet * 2n,
+  testnet: MIN_RELAY_FEE_RATE.testnet * 2n,
+  regtest: MIN_RELAY_FEE_RATE.regtest * 2n
+};
 var DUST_LIMIT = 1000n;
 var TOKEN_OUTPUT_VALUE = 1n;
 var DEFAULT_ELECTRUM_ENDPOINT = {
@@ -247,6 +252,25 @@ function unpackRef(ref) {
   const vout = buf.readUInt32LE(32);
   return { txid, vout };
 }
+function parseP2pkhScript(scriptHex) {
+  const [, addressHash] = scriptHex.toLowerCase().match(/^76a914([0-9a-f]{40})88ac$/) || [];
+  return { addressHash };
+}
+function parseNftScript(scriptHex) {
+  const pattern = /^(?:d1[0-9a-f]{72}20[0-9a-f]{64}6d)*(?:bd)?d8([0-9a-f]{72})7576a914([0-9a-f]{40})88ac$/;
+  const [, ref, addressHash] = scriptHex.toLowerCase().match(pattern) || [];
+  return { ref, addressHash };
+}
+function parseFtScript(scriptHex) {
+  const pattern = /^76a914([0-9a-f]{40})88acbdd0([0-9a-f]{72})dec0e9aa76e378e4a269e69d$/;
+  const [, addressHash, ref] = scriptHex.toLowerCase().match(pattern) || [];
+  return { ref, addressHash };
+}
+function tokenScriptKind(scriptHex) {
+  if (parseNftScript(scriptHex).ref) return "nft";
+  if (parseFtScript(scriptHex).ref) return "ft";
+  return null;
+}
 
 // src/client.ts
 var WS_OPEN = 1;
@@ -652,6 +676,17 @@ function sumValue(utxos) {
 }
 
 // src/tx.ts
+function assertSaneFee(tx, network) {
+  const sizeBytes = BigInt(tx.toString().length / 2);
+  const reference = MAX_REASONABLE_FEE_RATE[network];
+  const ceiling = sizeBytes * reference * 12n / 10n;
+  const actual = BigInt(tx.getFee?.() ?? 0);
+  if (actual > ceiling) {
+    throw new ValidationError(
+      `buildTx: fee ${actual} photons is above the sanity ceiling ${ceiling} for a ${sizeBytes}-byte tx (${network} reference ${reference} photons/byte). Refusing to build \u2014 this is almost always a units mistake or an over-funded change-less tx, and the excess would be paid to miners irrecoverably.`
+    );
+  }
+}
 function bn(value) {
   return new crypto.BN(value.toString());
 }
@@ -726,6 +761,7 @@ function buildTx(params) {
   }
   tx.sign(privKeys[0]);
   if (typeof tx.seal === "function") tx.seal();
+  assertSaneFee(tx, network);
   const hex = tx.toString();
   const resolvedOutputs = tx.outputs.map((o) => ({
     script: o.script.toHex(),
@@ -809,16 +845,14 @@ function parseTokenRef(scriptHex) {
   }
   return null;
 }
-function rebindOwner(scriptHex, toAddress, network) {
-  const newPkh = Address.fromString(toAddress).hashBuffer.toString("hex");
-  const re = /76a914[0-9a-f]{40}88ac/i;
-  const matches = scriptHex.match(new RegExp(re, "gi"));
-  if (!matches || matches.length !== 1) {
-    throw new ValidationError(
-      "rebindOwner: expected exactly one owner P2PKH in the token script"
-    );
-  }
-  return scriptHex.replace(re, `76a914${newPkh}88ac`);
+function tokenTransferScript(scriptHex, toAddress, network) {
+  const nft = parseNftScript(scriptHex);
+  if (nft.ref) return nftScript(toAddress, nft.ref, network);
+  const ft = parseFtScript(scriptHex);
+  if (ft.ref) return ftScript(toAddress, ft.ref, network);
+  throw new ValidationError(
+    "transferToken: tokenUtxo.script is not a recognised NFT or FT output script"
+  );
 }
 async function commitReveal(base, payload, refType, buildRevealOutputScript, tokenOutputValue) {
   const network = base.network ?? "mainnet";
@@ -932,8 +966,8 @@ async function transferToken(params) {
       "transferToken: tokenUtxo.script is required to rebuild the token output"
     );
   }
-  const newScript = rebindOwner(tokenUtxo.script, params.toAddress);
-  const ref = parseTokenRef(tokenUtxo.script);
+  const newScript = tokenTransferScript(tokenUtxo.script, params.toAddress, network);
+  const ref = parseNftScript(tokenUtxo.script).ref ?? parseFtScript(tokenUtxo.script).ref ?? null;
   const selection = selectRxdFunding(params.fundingUtxos, 0n, feeRate, {
     baseOutputCount: 1,
     // the token output
@@ -967,6 +1001,76 @@ async function transferToken(params) {
   await params.client.broadcastTx(built.hex);
   return { txid: built.txid, hex: built.hex, ref };
 }
+async function transferFungible(params) {
+  const network = params.network ?? "mainnet";
+  const feeRate = params.feeRate ?? MIN_RELAY_FEE_RATE[network];
+  const { amount, tokenUtxos } = params;
+  if (amount <= 0n) {
+    throw new ValidationError("transferFungible: amount must be positive");
+  }
+  if (!tokenUtxos.length) {
+    throw new ValidationError("transferFungible: no token UTXOs given");
+  }
+  let ref;
+  for (const u of tokenUtxos) {
+    const parsed = u.script ? parseFtScript(u.script) : {};
+    if (!parsed.ref) {
+      throw new ValidationError(
+        `transferFungible: ${u.txid}:${u.vout} is not an FT output (its script must be the on-chain ftScript)`
+      );
+    }
+    if (ref && parsed.ref !== ref) {
+      throw new ValidationError(
+        "transferFungible: token UTXOs are for different tokens \u2014 refusing to mix refs, it would burn one of them"
+      );
+    }
+    ref = parsed.ref;
+  }
+  const sorted = [...tokenUtxos].sort((a, b) => a.value < b.value ? 1 : a.value > b.value ? -1 : 0);
+  const spend = [];
+  let sum = 0n;
+  for (const u of sorted) {
+    spend.push(u);
+    sum += u.value;
+    if (sum >= amount) break;
+  }
+  if (sum < amount) {
+    throw new ValidationError(
+      `transferFungible: insufficient token balance \u2014 have ${sum}, need ${amount}`
+    );
+  }
+  const change = sum - amount;
+  const outputs = [{ script: ftScript(params.toAddress, ref, network), value: amount }];
+  if (change > 0n) {
+    outputs.push({ script: ftScript(params.address, ref, network), value: change });
+  }
+  const selection = selectRxdFunding(params.fundingUtxos, 0n, feeRate, {
+    baseOutputCount: outputs.length,
+    extraInputBytes: BigInt(148 * spend.length),
+    // the token inputs we add below
+    withChange: true
+  });
+  const inputs = [
+    ...spend.map((u) => ({ txid: u.txid, vout: u.vout, value: u.value, script: u.script })),
+    ...selection.inputs.map((u) => ({
+      txid: u.txid,
+      vout: u.vout,
+      value: u.value,
+      script: u.script || void 0
+    }))
+  ];
+  const built = buildTx({
+    address: params.address,
+    wif: params.wif,
+    inputs,
+    outputs,
+    addChange: true,
+    feeRate,
+    network
+  });
+  await params.client.broadcastTx(built.hex);
+  return { txid: built.txid, hex: built.hex, ref, sent: amount, change };
+}
 
 // src/wave.ts
 function waveLabel(name) {
@@ -1016,12 +1120,68 @@ async function waveResolveAddress(name, options = {}) {
   return r.registered ? r.address ?? null : null;
 }
 
+// src/discovery.ts
+var GLYPH_TOKEN_TYPE = {
+  UNKNOWN: 0,
+  FT: 1,
+  NFT: 2,
+  DAT: 3,
+  DMINT: 4,
+  WAVE: 5,
+  CONTAINER: 6,
+  AUTHORITY: 7
+};
+async function fetchTokenPage(path, params, options, fnName) {
+  const base = (options.restBase ?? DEFAULT_REST_BASE).replace(/\/+$/, "");
+  const doFetch = options.fetchImpl ?? globalThis.fetch;
+  if (typeof doFetch !== "function") {
+    throw new ValidationError(
+      `${fnName}: no fetch implementation available; pass options.fetchImpl`
+    );
+  }
+  const query = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v !== void 0) query.set(k, String(v));
+  }
+  const qs = query.toString();
+  const url = `${base}${path}${qs ? `?${qs}` : ""}`;
+  const res = await doFetch(url, { signal: options.signal });
+  if (!res.ok) {
+    throw new ValidationError(`${fnName}: HTTP ${res.status} ${res.statusText}`);
+  }
+  const data = await res.json();
+  return {
+    tokens: Array.isArray(data?.tokens) ? data.tokens : [],
+    nextCursor: data?.next_cursor ?? null
+  };
+}
+async function getRecentTokens(options = {}) {
+  return fetchTokenPage(
+    "/glyphs/recent",
+    { limit: options.limit, cursor: options.cursor, type_id: options.typeId },
+    options,
+    "getRecentTokens"
+  );
+}
+async function getTokensByType(typeId, options = {}) {
+  if (!Number.isInteger(typeId) || typeId < 0 || typeId > 7) {
+    throw new ValidationError(`getTokensByType: invalid typeId ${typeId}`);
+  }
+  return fetchTokenPage(
+    `/glyphs/by-type/${typeId}`,
+    { limit: options.limit, cursor: options.cursor, order: options.order },
+    options,
+    "getTokensByType"
+  );
+}
+
 exports.DEFAULT_ELECTRUM_ENDPOINT = DEFAULT_ELECTRUM_ENDPOINT;
 exports.DEFAULT_REST_BASE = DEFAULT_REST_BASE;
 exports.DUST_LIMIT = DUST_LIMIT;
 exports.ElectrumClient = ElectrumClient;
 exports.ElectrumError = ElectrumError;
 exports.GLYPH_PROTOCOL = GLYPH_PROTOCOL;
+exports.GLYPH_TOKEN_TYPE = GLYPH_TOKEN_TYPE;
 exports.HDWallet = HDWallet;
 exports.InsufficientFundsError = InsufficientFundsError;
 exports.Keys = Keys;
@@ -1040,6 +1200,8 @@ exports.encodeGlyph = encodeGlyph;
 exports.estimateFee = estimateFee;
 exports.filterFundingCandidates = filterFundingCandidates;
 exports.ftScript = ftScript;
+exports.getRecentTokens = getRecentTokens;
+exports.getTokensByType = getTokensByType;
 exports.isFundingSafe = isFundingSafe;
 exports.isTokenBearing = isTokenBearing;
 exports.mintFT = mintFT;
@@ -1047,6 +1209,9 @@ exports.mintNFT = mintNFT;
 exports.nftScript = nftScript;
 exports.p2pkhScript = p2pkhScript;
 exports.packRef = packRef;
+exports.parseFtScript = parseFtScript;
+exports.parseNftScript = parseNftScript;
+exports.parseP2pkhScript = parseP2pkhScript;
 exports.parseTokenRef = parseTokenRef;
 exports.photonsToRxd = photonsToRxd;
 exports.radiantjs = radiantjs;
@@ -1054,6 +1219,8 @@ exports.rxdToPhotons = rxdToPhotons;
 exports.scriptHash = scriptHash;
 exports.selectRxdFunding = selectRxdFunding;
 exports.sumValue = sumValue;
+exports.tokenScriptKind = tokenScriptKind;
+exports.transferFungible = transferFungible;
 exports.transferToken = transferToken;
 exports.unpackRef = unpackRef;
 exports.waveLabel = waveLabel;