Gulliant SDK

Open-source TypeScript SDK for the Gulliant V1 on-chain primitive on Solana.

Character state (NFT-bound)  → transfers with the asset on sale
Player state   (wallet-bound) → remains with the original wallet
The boundary is enforced at the program level.

Program ID: DyQAWvMytpgRiE2T9bhzSFCe9b9actobfHFB7RVReX7g · Devnet · Upgrade Authority: none

Install

# After public release:
npm install @gulliant/sdk

Quick Start

import { Connection, clusterApiUrl, Keypair } from '@solana/web3.js';
import { GulliantClient } from '@gulliant/sdk';

const gulliant = new GulliantClient(
  new Connection(clusterApiUrl('devnet'), 'confirmed')
);

const authority  = Keypair.generate();
const protocolId = Keypair.generate().publicKey;
const seller     = Keypair.generate();
const buyer      = Keypair.generate();

await gulliant.initializeProtocolConfig(authority.publicKey, protocolId, authority);
await gulliant.initializeUserLog(authority.publicKey, protocolId, seller.publicKey, authority);
await gulliant.appendActivityEvent(authority.publicKey, protocolId, seller.publicKey, 1, 100, Date.now(), authority);
await gulliant.authorizeExport(authority.publicKey, protocolId, seller.publicKey, buyer.publicKey, authority);
await gulliant.migrateState(authority.publicKey, protocolId, seller.publicKey, buyer.publicKey, authority);

See docs/QUICK_START.md for the full walkthrough.

Tests

# Unit tests
npm test

# Devnet integration
export RUN_DEVNET_TESTS=1
export DEVNET_PAYER_KEYPAIR=/path/to/keypair.json
npx vitest run tests/devnet.integration.test.ts

# Performance benchmark
export RUN_PERFORMANCE_TESTS=1
export DEVNET_PAYER_KEYPAIR=/path/to/keypair.json
npm run test:performance

Documentation

| Document | Description | | -------- | ----------- | | docs/QUICK_START.md | Full quickstart, SDK surface, PDA helpers | | docs/ARCHITECTURE.md | Account model, state flow, design properties, error reference | | docs/GAMEFI_INTEGRATION_GUIDE.md | Step-by-step GameFi integration guide | | docs/DEVNET_DEMO.md | How to run the demo and verify the deployment | | docs/COST_BASELINE.md | Cost, compute, and storage measurements | | docs/PERFORMANCE.md | How to run the performance benchmark |

Links

• Demo video: https://www.youtube.com/watch?v=hTYoH46X5dg
• Primitive repository: https://github.com/gulliant/gulliant-primitive
• Site: https://gulliant.com

License

MIT — see LICENSE.