feat: expose single-package SDK integration surface

Author: karagozemin

README.md

@@ -50,6 +50,7 @@ dependencies. Integrators normally need only the SDK:
 ```ts
 import {
   createAssetAuctionRound,
+  quicknet,
   sealAssetBid,
   SubRosaClient,
 } from "@sub-rosa/sdk";
@@ -60,6 +61,7 @@ const client = new SubRosaClient({
   contractId,
   secretKey,
 });
+const drand = quicknet();
 
 const roundId = await createAssetAuctionRound(client, {
   itemRef,

apps/web/src/pages/DocsPage.tsx

@@ -83,13 +83,11 @@ const client = new SubRosaClient({
 const auctionCreateCode = `import { createHash } from "node:crypto";
 import {
   createAssetAuctionRound,
-  SubRosaClient,
-} from "@sub-rosa/sdk";
-import {
   generateAuditorKeypair,
   quicknet,
   roundInSeconds,
-} from "@sub-rosa/tlock";
+  SubRosaClient,
+} from "@sub-rosa/sdk";
 
 const drand = quicknet();
 const chain = await drand.chain().info();
@@ -111,8 +109,7 @@ const roundId = await createAssetAuctionRound(sellerClient, {
   eligibleParticipants: collectorAddresses, // omit for an open round
 });`;
 
-const auctionBidCode = `import { sealAssetBid, SubRosaClient } from "@sub-rosa/sdk";
-import { quicknet } from "@sub-rosa/tlock";
+const auctionBidCode = `import { quicknet, sealAssetBid, SubRosaClient } from "@sub-rosa/sdk";
 
 const bidderClient = new SubRosaClient({
   rpcUrl,
@@ -199,7 +196,7 @@ const contract = new RoundContract({
   },
 });`;
 
-const lifecycleCode = `import { fetchRoundSignature, openPayload } from "@sub-rosa/tlock";
+const lifecycleCode = `import { fetchRoundSignature, openPayload } from "@sub-rosa/sdk";
 
 const signature = await fetchRoundSignature(drand, Number(round.reveal_round));
 await keeperClient.openRevealV2(roundId, signature);
@@ -388,7 +385,7 @@ export function DocsPage({ goHome }: { goHome: () => void }) {
           )}
         </div>
         <div className="docs-top-actions">
-          <span className="docs-version">SDK v0.2.0</span>
+          <span className="docs-version">SDK v0.2.1</span>
           <a href="https://github.com/karagozemin/Sub-Rosa" target="_blank" rel="noreferrer"><Code2 size={17} />GitHub</a>
           <a href="#/pilot" target="_blank" rel="noreferrer" className="docs-pilot-link">Open pilot<ArrowRight size={16} /></a>
           <button type="button" className="docs-mobile-menu" onClick={() => setMobileNav((value) => !value)} aria-label="Toggle documentation navigation">
@@ -424,7 +421,7 @@ export function DocsPage({ goHome }: { goHome: () => void }) {
               <button type="button" onClick={() => jump("auction")}><Code2 size={17} />Auction guide</button>
             </div>
             <div className="docs-proof-strip">
-              <div><Package size={18} /><span>Public package</span><strong>@sub-rosa/sdk@0.2.0</strong></div>
+              <div><Package size={18} /><span>Public package</span><strong>@sub-rosa/sdk@0.2.1</strong></div>
               <div><Server size={18} /><span>Live contract</span><strong>Core v2 testnet</strong></div>
               <div><FileCheck2 size={18} /><span>Live proofs</span><strong>Rounds #2 and #3</strong></div>
             </div>
@@ -539,7 +536,7 @@ export function DocsPage({ goHome }: { goHome: () => void }) {
               <div className="head" role="row"><span>Method</span><span>Purpose</span><span>Returns</span></div>
               {API_ROWS.map(([method, purpose, returns]) => <div role="row" key={method}><code>{method}</code><span>{purpose}</span><code>{returns}</code></div>)}
             </div>
-            <div className="docs-package-row"><div><Package size={18} /><span>@sub-rosa/sdk</span><code>0.2.0</code></div><div><Package size={18} /><span>@sub-rosa/tlock</span><code>0.2.0</code></div><div><Package size={18} /><span>@sub-rosa/round-bindings</span><code>0.2.0</code></div></div>
+            <div className="docs-package-row"><div><Package size={18} /><span>@sub-rosa/sdk</span><code>0.2.1</code></div><div><Package size={18} /><span>@sub-rosa/tlock</span><code>0.2.0</code></div><div><Package size={18} /><span>@sub-rosa/round-bindings</span><code>0.2.0</code></div></div>
           </section>
 
           <section className="docs-section" id="errors">

docs/INTEGRATION.md

@@ -10,9 +10,11 @@ the reviewed templates.
 npm install @sub-rosa/sdk
 ```
 
-`@sub-rosa/sdk` depends on version-matched releases of `@sub-rosa/tlock` and
-`@sub-rosa/round-bindings`. Install those packages directly only when using
-their lower-level APIs.
+`@sub-rosa/sdk` exposes the complete partner integration surface, including
+Drand timing, seal/open helpers, auditor keys, and generated contract types. It
+depends on version-matched releases of `@sub-rosa/tlock` and
+`@sub-rosa/round-bindings`; install those packages directly only when building
+custom low-level cryptography or contract tooling.
 
 ## Client configuration
 
@@ -39,10 +41,13 @@ asset.
 ```ts
 import {
   createAssetAuctionRound,
+  quicknet,
   sealAssetBid,
   SubRosaClient,
 } from "@sub-rosa/sdk";
 
+const drand = quicknet();
+
 const roundId = await createAssetAuctionRound(client, {
   itemRef,
   paymentAsset: usdcSac,

packages/sdk/README.md

@@ -51,15 +51,22 @@ that amount.
 ```ts
 import {
   createSealedProposalRound,
+  generateAuditorKeypair,
+  quicknet,
+  roundInSeconds,
   sealProposal,
 } from "@sub-rosa/sdk";
 
+const drand = quicknet();
+const revealRound = await roundInSeconds(drand, 5 * 60);
+const auditor = generateAuditorKeypair();
+
 const roundId = await createSealedProposalRound(client, {
   itemRef,
   revealRound,
   commitDeadline,
   revealDeadline,
-  auditorPubkey,
+  auditorPubkey: auditor.publicKey,
   eligibleParticipants: [providerA, providerB], // optional
 });
 
@@ -109,9 +116,10 @@ simulate every state-changing call before signing.
 
 ## Low-level packages
 
-`@sub-rosa/sdk` installs compatible `@sub-rosa/tlock` and
-`@sub-rosa/round-bindings` versions automatically. Install either package
-directly only when building custom crypto, indexing, or contract tooling.
+`@sub-rosa/sdk` exposes the complete partner integration surface and installs
+compatible `@sub-rosa/tlock` and `@sub-rosa/round-bindings` versions
+automatically. Install either package directly only when building custom
+cryptography, indexing, or contract tooling.
 
 ## Security boundary
 

packages/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sub-rosa/sdk",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "private": false,
   "type": "module",
   "description": "TypeScript SDK for integrating Sub Rosa sealed auctions and receipt-only proposal rounds on Stellar.",

packages/sdk/src/index.ts

@@ -182,3 +182,33 @@ export {
   type Status,
   type DataKey,
 } from "@sub-rosa/round-bindings";
+
+// Partner-facing cryptography and Drand helpers. Keep this list explicit so
+// the SDK stays a stable facade without exposing every tlock implementation detail.
+export {
+  generateAuditorKeypair,
+  auditorPublicKey,
+  sealIdentity,
+  openIdentity,
+  quicknet,
+  chainInfo,
+  currentRound,
+  roundInSeconds,
+  fetchRoundBeacon,
+  fetchRoundSignature,
+  QUICKNET_HASH,
+  generateNonce,
+  encodePayloadEnvelope,
+  decodePayloadEnvelope,
+  payloadCommitment,
+  sealPayload,
+  openPayload,
+  PAYLOAD_ENVELOPE_VERSION,
+  PAYLOAD_HEADER_BYTES,
+  MAX_APPLICATION_PAYLOAD_BYTES,
+  type AuditorKeypair,
+  type DrandClient,
+  type PayloadEnvelope,
+  type SealPayloadParams,
+  type SealedPayload,
+} from "@sub-rosa/tlock";

packages/sdk/src/public-api-snapshot.test.ts

@@ -14,9 +14,13 @@ const EXPECTED_EXPORTS = [
   "MAINNET_DEPLOY_MIN_XLM_STROOPS",
   "MAINNET_MICRO_MAX_ESCROW",
   "MAINNET_MIN_FEE_RESERVE_STROOPS",
+  "MAX_APPLICATION_PAYLOAD_BYTES",
   "MAX_AUDITOR_BLOB_BYTES",
   "MAX_CIPHERTEXT_BYTES",
   "MAX_V2_PARTICIPANTS",
+  "PAYLOAD_ENVELOPE_VERSION",
+  "PAYLOAD_HEADER_BYTES",
+  "QUICKNET_HASH",
   "RECEIPT_VERSION",
   "SEALED_PROPOSAL_SCHEMA_ID",
   "SEALED_PROPOSAL_SCHEMA_REF",
@@ -35,31 +39,47 @@ const EXPECTED_EXPORTS = [
   "assertMicroAmounts",
   "assertReadinessForExecute",
   "assetAuctionRound",
+  "auditorPublicKey",
+  "chainInfo",
   "contractErrorCode",
   "createOzChannelsSubmitter",
   "createOzChannelsSubmitterFromEnv",
   "createSacBalanceReader",
   "createAssetAuctionRound",
   "createSealedProposalRound",
+  "currentRound",
+  "decodePayloadEnvelope",
   "decodeSealedProposal",
   "defaultMainnetReadinessInput",
   "evaluatePreflight",
   "encodeSealedProposal",
+  "encodePayloadEnvelope",
   "fetchContractWasmHash",
   "fetchKeeperStatus",
+  "fetchRoundBeacon",
+  "fetchRoundSignature",
   "formatReadinessReport",
+  "generateAuditorKeypair",
+  "generateNonce",
   "hasBlockingFailures",
   "nativeXlmSacId",
   "networkFingerprint",
   "normalizeRoundId",
   "normalizeSorobanContractId",
+  "openIdentity",
+  "openPayload",
   "parseReceipt",
   "parseReceiptV2",
+  "payloadCommitment",
+  "quicknet",
   "redactReceipt",
+  "roundInSeconds",
   "runMainnetReadiness",
   "serializeReceipt",
   "serializeReceiptV2",
   "sealAssetBid",
+  "sealIdentity",
+  "sealPayload",
   "sealProposal",
   "sealedProposalRound",
   "tryDecodeBase64",

scripts/verify-public-packages.mjs

@@ -60,6 +60,8 @@ try {
       `expected ${packages.length} tarballs, found ${tarballs.length}`,
     );
   }
+  const sdkTarball = tarballs.find((entry) => entry.includes("sub-rosa-sdk"));
+  if (!sdkTarball) throw new Error("missing tarball for @sub-rosa/sdk");
 
   writeFileSync(
     join(consumerDir, "package.json"),
@@ -69,14 +71,9 @@ try {
         version: "1.0.0",
         private: true,
         type: "module",
-        dependencies: Object.fromEntries(
-          packages.map((pkg) => {
-            const slug = pkg.name.replace("@sub-rosa/", "sub-rosa-");
-            const tarball = tarballs.find((entry) => entry.includes(slug));
-            if (!tarball) throw new Error(`missing tarball for ${pkg.name}`);
-            return [pkg.name, `file:${tarball}`];
-          }),
-        ),
+        dependencies: {
+          "@sub-rosa/sdk": `file:${sdkTarball}`,
+        },
       },
       null,
       2,
@@ -85,13 +82,11 @@ try {
 
   writeFileSync(
     join(consumerDir, "verify.mjs"),
-    `import { ASSET_AUCTION_SCHEMA_ID, SubRosaClient } from "@sub-rosa/sdk";\n` +
-      `import { payloadCommitment } from "@sub-rosa/tlock";\n` +
-      `import { Errors } from "@sub-rosa/round-bindings";\n` +
+    `import { ASSET_AUCTION_SCHEMA_ID, RoundErrors, SubRosaClient, openPayload, quicknet } from "@sub-rosa/sdk";\n` +
       `if (!ASSET_AUCTION_SCHEMA_ID || typeof SubRosaClient !== "function") throw new Error("sdk exports missing");\n` +
-      `if (typeof payloadCommitment !== "function") throw new Error("tlock exports missing");\n` +
-      `if (!Errors[1]) throw new Error("bindings exports missing");\n` +
-      `console.log("public package imports verified");\n`,
+      `if (typeof openPayload !== "function" || typeof quicknet !== "function") throw new Error("tlock facade exports missing");\n` +
+      `if (!RoundErrors[1]) throw new Error("bindings facade exports missing");\n` +
+      `console.log("single-package SDK imports verified");\n`,
   );
 
   run(