impact-x-sdk

TypeScript SDK for the Impact-X crowdfunding app on Stacks. It wraps the Impact-X campaign registry contract, IPFS metadata flows, campaign aggregation, and USDC to USDCx bridge helpers.

Install

npm install impact-x-sdk @stacks/connect @stacks/transactions viem

Quick Start

import { ImpactXCampaignService, ImpactXStacksClient } from 'impact-x-sdk';

const stacks = new ImpactXStacksClient({
  network: 'testnet',
});

const campaign = await stacks.fetchCampaign(1);
console.log(campaign);

const campaigns = new ImpactXCampaignService({ network: 'testnet' });
const fullCampaign = await campaigns.getFullCampaign(1);
console.log(fullCampaign?.title, fullCampaign?.endorsements);

Configuration

import { ImpactXStacksClient } from 'impact-x-sdk';

const client = new ImpactXStacksClient({
  network: 'mainnet',
  contract: {
    address: 'SP...',
    name: 'campaign-registry-v2',
  },
});

The SDK defaults to Impact-X testnet values. Mainnet requires a campaign registry address until the production contract is finalized.

Contract Writes

Write calls use @stacks/connect by default. In a browser app with a connected Stacks wallet:

import { ImpactXStacksClient } from 'impact-x-sdk';

const client = new ImpactXStacksClient({ network: 'testnet' });

await client.createCampaign({
  ipfsHash: 'Qm...',
  goalInUSDC: 100,
  durationInDays: 30,
});

await client.donate(1, 10);
await client.endorseCampaign(1);
await client.postCampaignUpdate(1, 'Qm...');

For tests or custom wallet adapters, inject stacksRequest:

const client = new ImpactXStacksClient({
  stacksRequest: async (_method, params) => {
    console.log(params.functionName, params.functionArgs);
    return { txid: '0xabc' };
  },
});

IPFS Helpers

import { uploadCampaignMetadata, uploadJSONToIPFS, fetchFromIPFS } from 'impact-x-sdk';

const cid = await uploadCampaignMetadata({
  title: 'Open source builder fund',
  description: 'Funding public goods builders.',
  story: '<p>Long-form campaign story.</p>',
  imageUrl: 'https://example.com/image.png',
  category: 'Technology',
  targetAmount: 1000,
  createdAt: Date.now(),
}, { jwt: process.env.PINATA_JWT! });

const metadata = await fetchFromIPFS(cid);

const updateCid = await uploadJSONToIPFS({
  title: 'Milestone 1 shipped',
  body: 'We completed the first milestone.',
  createdAt: Date.now(),
}, { jwt: process.env.PINATA_JWT!, name: 'impact-x-update' });

Bridge Helpers

The bridge helpers wrap Circle xReserve style USDC deposits from Ethereum/Sepolia to USDCx on Stacks.

import { bridgeUSDCToStacks, checkMintStatus } from 'impact-x-sdk';

const result = await bridgeUSDCToStacks({
  amount: '10',
  recipientStacksAddress: 'ST...',
  walletClient,
  publicClient,
  network: 'sepolia',
});

const status = await checkMintStatus(result.hookData, 'testnet');

Main Exports

• ImpactXStacksClient: contract reads and writes.
• ImpactXCampaignService: hydrated campaign reads with IPFS metadata and social stats.
• uploadCampaignMetadata, uploadJSONToIPFS, uploadImageToIPFS, fetchFromIPFS.
• bridgeUSDCToStacks, checkMintStatus, getUSDCBalance, validateBridgeAmount.
• filterCampaigns, usdcToMicro, microToUsdc, encodeStacksAddress.

Publish

npm run typecheck
npm test
npm run build
npm pack --dry-run
npm publish --access public

License

MIT