Fluidic TypeScript SDK

The easiest way to build on the Fluidic blockless wave-field mesh.

Install

npm install @fluidic-foundation/sdk

One-minute example

import { FluidicWallet, waveUnits } from "@fluidic-foundation/sdk";

const wallet = FluidicWallet.create({
  apiUrl: "https://api.testnet.fluidic.foundation",
});

await wallet.register();
console.log("balance", await wallet.balance());

// Transfer 10 WAVE
await wallet.transfer({
  to: "RECIPIENT_ACCOUNT_ID_HEX",
  amount: waveUnits(10),
});

// Swap 5 WAVE for USDC
await wallet.swap({ direction: "WAVE_TO_USDC", amount: waveUnits(5) });

Wallet API

FluidicWallet combines an Ed25519 keypair and a node client. It handles registration, token-account derivation, vector-clock fetching, signing, and finalization polling for you.

Creating a wallet

// Random wallet
const wallet = FluidicWallet.create({ apiUrl });

// From a 32-byte seed (hex string or Uint8Array)
const wallet = FluidicWallet.fromSeed(seed, { apiUrl });

// From a raw 32-byte Ed25519 secret key
const wallet = FluidicWallet.fromSecretKey(secretKey, { apiUrl });

Common operations

await wallet.register();
const { wave, usdc } = await wallet.balance();
const state = await wallet.state();

await wallet.transfer({ to: accountId, amount: waveUnits(1.5) });
await wallet.swap({ direction: "USDC_TO_WAVE", amount: waveUnits(100) });

const quote = wallet.quoteSwap("WAVE_TO_USDC", waveUnits(5), state);

Intents

const currentTick = await wallet.client.currentTick();
const intent = await wallet.submitIntent({
  deadlineTick: BigInt(currentTick + 100),
  constraint: {
    kind: "transfer",
    to: recipient.accountId,
    minAmount: waveUnits(1),
  },
  solverReward: waveUnits(0.01),
});

// A solver fills it
await solver.fillIntent(intent.intent_id, waveUnits(1));

Agents

const agent = FluidicKeypair.generate();
const { agentId } = await wallet.registerAgent(agent.publicKeyHex, BigInt(currentTick + 1000));

Causal Agent Entanglements

const entanglement = await wallet.createEntanglement({
  subject: agent.accountId,
  witnesses: [witness1.accountId, witness2.accountId],
  threshold: 2n,
  expiryTick: BigInt(currentTick + 500),
  // Revocation policy, fixed at creation:
  //   "creator_only"       — agent custody: the subject's own key CANNOT break
  //                          the entanglement (only the creator's cold key can)
  //   "witness_threshold"  — break executes after `threshold` witness breaks
  //   "any_party"          — default; creator, subject, or any witness
  breakPolicy: "creator_only",
});

await witness1.attestEntanglement(entanglement.id);

// Revoke (creator key, under "creator_only"):
await wallet.breakEntanglement(entanglement.id); // → { status: "broken" }
// Under "witness_threshold" a break returns { status: "pending" } until
// enough witness break approvals accumulate.

DePIN physical attestations

const attestation = await wallet.attestPhysical({
  resourceType: "compute",
  location: "prague",
  capacity: waveUnits(10),
  pricePerUnit: waveUnits(0.001),
  availableUntilTick: BigInt(currentTick + 1000),
});

Low-level client

If you need full control, use FluidicClient directly:

import { FluidicClient, FluidicKeypair, buildStatefulShift } from "@fluidic-foundation/sdk";

const client = new FluidicClient({ apiUrl });
const kp = FluidicKeypair.generate();

Running the demo locally

Start a node on http://localhost:8080 (see the main repo README), then:

cd sdk/typescript/examples/demo
node demo.mjs

Units

Fluidic uses 12 decimals for WAVE and USDC. Use waveUnits(whole) to convert from human-readable amounts to raw units.

waveUnits(1);      // 1000000000000n
waveUnits(0.001);  // 1000000000n

License

MIT