linkup-stacks-sdk 1.0.1

package/README.md

@@ -0,0 +1,55 @@
+# @linkup/stacks-sdk
+
+> SDK for interacting with LinkUp smart contracts on Stacks/Bitcoin
+
+[![npm](https://img.shields.io/npm/v/linkup-stacks-sdk)](https://www.npmjs.com/package/linkup-stacks-sdk)
+
+## Install
+
+```bash
+npm install linkup-stacks-sdk
+```
+
+## Contracts (Stacks Mainnet)
+
+| Contract | Address |
+|---|---|
+| `linkup-factory` | `SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7.linkup-factory` |
+| `linkup-custody` | `SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7.linkup-custody` |
+| `linkup-posts` | `SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7.linkup-posts` |
+
+## Usage
+
+```ts
+import { getStats, isRegistered, remainingAllowance, getPost } from '@linkup/stacks-sdk';
+
+// Read global stats (no key needed)
+const stats = await getStats();
+console.log(stats); // { totalUsers, totalPosts, totalTips }
+
+// Check if address is registered
+const registered = await isRegistered('SP...');
+
+// Check remaining daily STX allowance
+const allowance = await remainingAllowance('SP...');
+
+// Get a post
+const post = await getPost(1);
+```
+
+### Write operations (requires private key)
+
+```ts
+import { register, sendStx, createPost, toUstx } from '@linkup/stacks-sdk';
+
+const config = { network: 'mainnet', privateKey: 'your-private-key-hex' };
+
+// Register user
+await register('username', 'https://hub.hiro.so/read/SP.../linkup/profile.json', config);
+
+// Send STX (enforces 1000 STX/day limit)
+await sendStx('SP_RECIPIENT', toUstx(1.5), config); // send 1.5 STX
+
+// Create post
+await createPost(contentHashBuffer, 'https://hub.hiro.so/...', config);
+```

package/dist/custody.d.ts

@@ -0,0 +1,9 @@
+import { type LinkUpConfig } from './types';
+/** Send STX via the linkup-custody contract (enforces daily 1000 STX limit) */
+export declare function sendStx(recipient: string, amountUstx: bigint, config: Required<LinkUpConfig>): Promise<string>;
+/** Get remaining daily STX allowance for an address (in micro-STX) */
+export declare function remainingAllowance(address: string, config?: LinkUpConfig): Promise<bigint>;
+/** Convert STX to micro-STX */
+export declare const toUstx: (stx: number) => bigint;
+/** Convert micro-STX to STX */
+export declare const fromUstx: (ustx: bigint | number) => number;

package/dist/custody.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fromUstx = exports.toUstx = void 0;
+exports.sendStx = sendStx;
+exports.remainingAllowance = remainingAllowance;
+const transactions_1 = require("@stacks/transactions");
+const types_1 = require("./types");
+/** Send STX via the linkup-custody contract (enforces daily 1000 STX limit) */
+async function sendStx(recipient, amountUstx, config) {
+    const tx = await (0, transactions_1.makeContractCall)({
+        ...types_1.CONTRACTS.custody,
+        functionName: 'send-stx',
+        functionArgs: [(0, transactions_1.standardPrincipalCV)(recipient), (0, transactions_1.uintCV)(amountUstx)],
+        senderKey: config.privateKey,
+        network: config.network,
+        anchorMode: transactions_1.AnchorMode.Any,
+    });
+    const result = await (0, transactions_1.broadcastTransaction)(tx, config.network);
+    if ('error' in result)
+        throw new Error(result.error);
+    return result.txid;
+}
+/** Get remaining daily STX allowance for an address (in micro-STX) */
+async function remainingAllowance(address, config = {}) {
+    const result = await (0, transactions_1.callReadOnlyFunction)({
+        ...types_1.CONTRACTS.custody,
+        functionName: 'remaining-allowance',
+        functionArgs: [(0, transactions_1.standardPrincipalCV)(address)],
+        network: config.network ?? 'mainnet',
+        senderAddress: address,
+    });
+    return BigInt((0, transactions_1.cvToValue)(result)?.value ?? 0);
+}
+/** Convert STX to micro-STX */
+const toUstx = (stx) => BigInt(Math.round(stx * 1000000));
+exports.toUstx = toUstx;
+/** Convert micro-STX to STX */
+const fromUstx = (ustx) => Number(ustx) / 1000000;
+exports.fromUstx = fromUstx;

package/dist/factory.d.ts

@@ -0,0 +1,15 @@
+import { type LinkUpConfig } from './types';
+/** Register a new user on LinkUp */
+export declare function register(username: string, gaiaUrl: string, config: Required<LinkUpConfig>): Promise<string>;
+/** Update a user's Gaia profile URL */
+export declare function updateProfile(gaiaUrl: string, config: Required<LinkUpConfig>): Promise<string>;
+/** Check if an address is registered */
+export declare function isRegistered(address: string, config?: LinkUpConfig): Promise<boolean>;
+/** Get a user's profile */
+export declare function getUser(address: string, config?: LinkUpConfig): Promise<any>;
+/** Get global LinkUp stats */
+export declare function getStats(config?: LinkUpConfig): Promise<{
+    totalUsers: number;
+    totalPosts: number;
+    totalTips: number;
+}>;

package/dist/factory.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.register = register;
+exports.updateProfile = updateProfile;
+exports.isRegistered = isRegistered;
+exports.getUser = getUser;
+exports.getStats = getStats;
+const transactions_1 = require("@stacks/transactions");
+const types_1 = require("./types");
+/** Register a new user on LinkUp */
+async function register(username, gaiaUrl, config) {
+    const tx = await (0, transactions_1.makeContractCall)({
+        ...types_1.CONTRACTS.factory,
+        functionName: 'register',
+        functionArgs: [(0, transactions_1.stringUtf8CV)(username), (0, transactions_1.stringUtf8CV)(gaiaUrl)],
+        senderKey: config.privateKey,
+        network: config.network,
+        anchorMode: transactions_1.AnchorMode.Any,
+    });
+    const result = await (0, transactions_1.broadcastTransaction)(tx, config.network);
+    if ('error' in result)
+        throw new Error(result.error);
+    return result.txid;
+}
+/** Update a user's Gaia profile URL */
+async function updateProfile(gaiaUrl, config) {
+    const tx = await (0, transactions_1.makeContractCall)({
+        ...types_1.CONTRACTS.factory,
+        functionName: 'update-profile',
+        functionArgs: [(0, transactions_1.stringUtf8CV)(gaiaUrl)],
+        senderKey: config.privateKey,
+        network: config.network,
+        anchorMode: transactions_1.AnchorMode.Any,
+    });
+    const result = await (0, transactions_1.broadcastTransaction)(tx, config.network);
+    if ('error' in result)
+        throw new Error(result.error);
+    return result.txid;
+}
+/** Check if an address is registered */
+async function isRegistered(address, config = {}) {
+    const result = await (0, transactions_1.callReadOnlyFunction)({
+        ...types_1.CONTRACTS.factory,
+        functionName: 'is-registered',
+        functionArgs: [(0, transactions_1.standardPrincipalCV)(address)],
+        network: config.network ?? 'mainnet',
+        senderAddress: address,
+    });
+    return (0, transactions_1.cvToValue)(result);
+}
+/** Get a user's profile */
+async function getUser(address, config = {}) {
+    const result = await (0, transactions_1.callReadOnlyFunction)({
+        ...types_1.CONTRACTS.factory,
+        functionName: 'get-user',
+        functionArgs: [(0, transactions_1.standardPrincipalCV)(address)],
+        network: config.network ?? 'mainnet',
+        senderAddress: address,
+    });
+    return (0, transactions_1.cvToValue)(result);
+}
+/** Get global LinkUp stats */
+async function getStats(config = {}) {
+    const result = await (0, transactions_1.callReadOnlyFunction)({
+        ...types_1.CONTRACTS.factory,
+        functionName: 'get-stats',
+        functionArgs: [],
+        network: config.network ?? 'mainnet',
+        senderAddress: types_1.CONTRACTS.factory.contractAddress,
+    });
+    const val = (0, transactions_1.cvToValue)(result);
+    return {
+        totalUsers: Number(val['total-users']?.value ?? 0),
+        totalPosts: Number(val['total-posts']?.value ?? 0),
+        totalTips: Number(val['total-tips']?.value ?? 0),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @linkup/stacks-sdk
+ * SDK for interacting with LinkUp smart contracts on Stacks/Bitcoin mainnet.
+ *
+ * Contracts deployed at: SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7
+ *   - linkup-factory  (user registry)
+ *   - linkup-custody  (STX transfers with daily limit)
+ *   - linkup-posts    (on-chain posts, likes, tips)
+ */
+export * from './factory';
+export * from './custody';
+export * from './posts';
+export * from './types';

package/dist/index.js

@@ -0,0 +1,29 @@
+"use strict";
+/**
+ * @linkup/stacks-sdk
+ * SDK for interacting with LinkUp smart contracts on Stacks/Bitcoin mainnet.
+ *
+ * Contracts deployed at: SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7
+ *   - linkup-factory  (user registry)
+ *   - linkup-custody  (STX transfers with daily limit)
+ *   - linkup-posts    (on-chain posts, likes, tips)
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./factory"), exports);
+__exportStar(require("./custody"), exports);
+__exportStar(require("./posts"), exports);
+__exportStar(require("./types"), exports);

package/dist/posts.d.ts

@@ -0,0 +1,11 @@
+import { type LinkUpConfig } from './types';
+/** Create a post on-chain. contentHash = SHA-256 of post JSON; full content in Gaia. */
+export declare function createPost(contentHash: Buffer, gaiaUrl: string, config: Required<LinkUpConfig>): Promise<string>;
+/** Like a post */
+export declare function likePost(postId: number, config: Required<LinkUpConfig>): Promise<string>;
+/** Tip a post with STX */
+export declare function tipPost(postId: number, amountUstx: bigint, config: Required<LinkUpConfig>): Promise<string>;
+/** Get post metadata from chain */
+export declare function getPost(postId: number, config?: LinkUpConfig): Promise<any>;
+/** Check if an address has liked a post */
+export declare function hasLiked(postId: number, address: string, config?: LinkUpConfig): Promise<boolean>;

package/dist/posts.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createPost = createPost;
+exports.likePost = likePost;
+exports.tipPost = tipPost;
+exports.getPost = getPost;
+exports.hasLiked = hasLiked;
+const transactions_1 = require("@stacks/transactions");
+const types_1 = require("./types");
+/** Create a post on-chain. contentHash = SHA-256 of post JSON; full content in Gaia. */
+async function createPost(contentHash, gaiaUrl, config) {
+    const tx = await (0, transactions_1.makeContractCall)({
+        ...types_1.CONTRACTS.posts,
+        functionName: 'create-post',
+        functionArgs: [(0, transactions_1.bufferCV)(contentHash), (0, transactions_1.stringUtf8CV)(gaiaUrl)],
+        senderKey: config.privateKey,
+        network: config.network,
+        anchorMode: transactions_1.AnchorMode.Any,
+    });
+    const result = await (0, transactions_1.broadcastTransaction)(tx, config.network);
+    if ('error' in result)
+        throw new Error(result.error);
+    return result.txid;
+}
+/** Like a post */
+async function likePost(postId, config) {
+    const tx = await (0, transactions_1.makeContractCall)({
+        ...types_1.CONTRACTS.posts,
+        functionName: 'like-post',
+        functionArgs: [(0, transactions_1.uintCV)(postId)],
+        senderKey: config.privateKey,
+        network: config.network,
+        anchorMode: transactions_1.AnchorMode.Any,
+    });
+    const result = await (0, transactions_1.broadcastTransaction)(tx, config.network);
+    if ('error' in result)
+        throw new Error(result.error);
+    return result.txid;
+}
+/** Tip a post with STX */
+async function tipPost(postId, amountUstx, config) {
+    const tx = await (0, transactions_1.makeContractCall)({
+        ...types_1.CONTRACTS.posts,
+        functionName: 'tip-post',
+        functionArgs: [(0, transactions_1.uintCV)(postId), (0, transactions_1.uintCV)(amountUstx)],
+        senderKey: config.privateKey,
+        network: config.network,
+        anchorMode: transactions_1.AnchorMode.Any,
+    });
+    const result = await (0, transactions_1.broadcastTransaction)(tx, config.network);
+    if ('error' in result)
+        throw new Error(result.error);
+    return result.txid;
+}
+/** Get post metadata from chain */
+async function getPost(postId, config = {}) {
+    const result = await (0, transactions_1.callReadOnlyFunction)({
+        ...types_1.CONTRACTS.posts,
+        functionName: 'get-post',
+        functionArgs: [(0, transactions_1.uintCV)(postId)],
+        network: config.network ?? 'mainnet',
+        senderAddress: types_1.CONTRACTS.posts.contractAddress,
+    });
+    return (0, transactions_1.cvToValue)(result);
+}
+/** Check if an address has liked a post */
+async function hasLiked(postId, address, config = {}) {
+    const result = await (0, transactions_1.callReadOnlyFunction)({
+        ...types_1.CONTRACTS.posts,
+        functionName: 'has-liked',
+        functionArgs: [(0, transactions_1.uintCV)(postId), (0, transactions_1.standardPrincipalCV)(address)],
+        network: config.network ?? 'mainnet',
+        senderAddress: address,
+    });
+    return (0, transactions_1.cvToValue)(result);
+}

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+export declare const DEPLOYER = "SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7";
+export declare const CONTRACTS: {
+    readonly factory: {
+        readonly contractAddress: "SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7";
+        readonly contractName: "linkup-factory";
+    };
+    readonly custody: {
+        readonly contractAddress: "SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7";
+        readonly contractName: "linkup-custody";
+    };
+    readonly posts: {
+        readonly contractAddress: "SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7";
+        readonly contractName: "linkup-posts";
+    };
+};
+export type Network = 'mainnet' | 'testnet';
+export interface LinkUpConfig {
+    network?: Network;
+    /** Private key hex (for write operations) */
+    privateKey?: string;
+}

package/dist/types.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CONTRACTS = exports.DEPLOYER = void 0;
+exports.DEPLOYER = 'SP2F5Q3JWH4P5YV2S056W4PHZN2CWN00TDQRBX4J7';
+exports.CONTRACTS = {
+    factory: { contractAddress: exports.DEPLOYER, contractName: 'linkup-factory' },
+    custody: { contractAddress: exports.DEPLOYER, contractName: 'linkup-custody' },
+    posts: { contractAddress: exports.DEPLOYER, contractName: 'linkup-posts' },
+};

package/package.json

@@ -0,0 +1,26 @@
+{
+  "name": "linkup-stacks-sdk",
+  "version": "1.0.1",
+  "description": "LinkUp SDK — interact with LinkUp smart contracts on Stacks/Bitcoin",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["stacks", "bitcoin", "clarity", "social", "payments", "linkup", "web3"],
+  "author": "LinkUp",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/jajafwangshak86-ops/LinkUp.git"
+  },
+  "homepage": "https://github.com/jajafwangshak86-ops/LinkUp#readme",
+  "dependencies": {
+    "@stacks/transactions": "^6.17.0"
+  },
+  "devDependencies": {
+    "typescript": "~5.9.2"
+  }
+}