@inkd/sdk 0.9.0

package/README.md

@@ -0,0 +1,288 @@
+# @inkd/sdk
+
+[![npm](https://img.shields.io/npm/v/@inkd/sdk?color=blue&logo=npm)](https://www.npmjs.com/package/@inkd/sdk)
+[![CI](https://github.com/inkdprotocol/inkd-protocol/actions/workflows/ci.yml/badge.svg)](https://github.com/inkdprotocol/inkd-protocol/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](../LICENSE)
+[![Built on Base](https://img.shields.io/badge/Built%20on-Base-0052ff?logo=ethereum)](https://base.org)
+
+TypeScript SDK for the **Inkd Protocol** — permanent on-chain project registry on Base. Lock 1 `$INKD` to register. Pay 0.001 ETH to push a version. Own your work forever.
+
+---
+
+## Installation
+
+```bash
+npm install @inkd/sdk viem
+# or
+pnpm add @inkd/sdk viem
+# or
+yarn add @inkd/sdk viem
+```
+
+> **Peer dependency:** [`viem`](https://viem.sh) ≥ 2.0.0 must be installed in your project.
+
+---
+
+## Quick Start
+
+```typescript
+import { InkdClient } from '@inkd/sdk'
+import { createWalletClient, http } from 'viem'
+import { privateKeyToAccount } from 'viem/accounts'
+import { base } from 'viem/chains'
+
+const account = privateKeyToAccount('0x...')
+const wallet = createWalletClient({ account, chain: base, transport: http() })
+
+const inkd = new InkdClient({ walletClient: wallet, network: 'mainnet' })
+
+// 1. Approve $INKD spend (one-time per project)
+await inkd.approveToken()
+
+// 2. Register your project on-chain
+const hash = await inkd.createProject({
+  name: 'my-awesome-tool',
+  description: 'An AI tool for doing amazing things',
+  license: 'MIT',
+  isPublic: true,
+  isAgent: true,
+  agentEndpoint: 'https://api.myawesometool.xyz',
+})
+
+console.log('Project registered! tx:', hash)
+```
+
+---
+
+## API Reference
+
+### `new InkdClient(options)`
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `walletClient` | `WalletClient` | required | viem wallet client |
+| `network` | `'mainnet' \| 'testnet'` | `'testnet'` | Target network |
+| `rpcUrl` | `string` | viem default | Custom RPC URL |
+
+---
+
+### Token Methods
+
+#### `approveToken(amount?)`
+Approve the registry contract to spend `$INKD` tokens. Call before `createProject()`.
+
+```typescript
+await inkd.approveToken()              // approve 1 INKD (default)
+await inkd.approveToken(parseEther('5')) // approve 5 INKD
+```
+
+#### `tokenBalance(address?)`
+Get `$INKD` balance for an address (defaults to connected wallet).
+
+```typescript
+const balance = await inkd.tokenBalance()
+// → 1000000000000000000n (1 INKD in wei)
+```
+
+---
+
+### Project Methods
+
+#### `createProject(opts)`
+Register a new project. Requires 1 `$INKD` locked permanently.
+
+```typescript
+const hash = await inkd.createProject({
+  name: 'my-project',            // unique, immutable, lowercase
+  description: 'What it does',
+  license: 'MIT',                // MIT | GPL-3.0 | Apache-2.0 | Proprietary
+  readmeHash: 'ar://abc123',     // Arweave hash of README
+  isPublic: true,
+  isAgent: false,
+  agentEndpoint: '',
+})
+```
+
+#### `pushVersion(projectId, opts)`
+Push a new version. Costs 0.001 ETH.
+
+```typescript
+const hash = await inkd.pushVersion(1n, {
+  arweaveHash: 'ar://QmXyz...',
+  versionTag: '1.2.0',
+  changelog: 'Fixed critical bug in payment processor',
+})
+```
+
+#### `getProject(projectId)`
+Fetch project metadata from the registry.
+
+```typescript
+const project = await inkd.getProject(1n)
+// → { id, name, description, license, owner, isAgent, versionCount, ... }
+```
+
+#### `getVersions(projectId)`
+List all versions of a project.
+
+```typescript
+const versions = await inkd.getVersions(1n)
+// → [{ arweaveHash, versionTag, changelog, pushedBy, pushedAt }, ...]
+```
+
+#### `transferProject(projectId, newOwner)`
+Transfer project ownership. Costs 0.005 ETH.
+
+```typescript
+await inkd.transferProject(1n, '0xNewOwner...')
+```
+
+#### `getAgentProjects(offset?, limit?)`
+List all AI agent projects registered on-chain.
+
+```typescript
+const ids = await inkd.getAgentProjects(0n, 50n)
+// → [1n, 4n, 7n, ...]
+```
+
+---
+
+### Fee Methods
+
+#### `getVersionFee()`
+Current fee to push a version (in wei).
+
+```typescript
+const fee = await inkd.getVersionFee()
+// → 1000000000000000n (0.001 ETH)
+```
+
+---
+
+## React Hooks
+
+The SDK ships optional React hooks (requires `react` ≥ 18):
+
+```typescript
+import { useInkdProject, useInkdVersions, useInkdStats } from '@inkd/sdk/hooks'
+
+function ProjectCard({ id }: { id: bigint }) {
+  const { project, loading, error } = useInkdProject(client, id)
+
+  if (loading) return <Spinner />
+  if (error) return <Error message={error.message} />
+
+  return (
+    <div>
+      <h2>{project.name}</h2>
+      <p>{project.description}</p>
+      <span>{project.versionCount.toString()} versions</span>
+    </div>
+  )
+}
+```
+
+Available hooks:
+- `useInkdProject(client, projectId)` — fetch project metadata
+- `useInkdVersions(client, projectId)` — fetch all versions
+- `useInkdStats(client)` — protocol-wide stats
+
+---
+
+## Error Handling
+
+All SDK errors extend `InkdError`:
+
+```typescript
+import { InkdError, ProjectNotFound, InsufficientAllowance, InsufficientBalance } from '@inkd/sdk'
+
+try {
+  await inkd.createProject({ name: 'exists', ... })
+} catch (err) {
+  if (err instanceof ProjectNotFound) {
+    console.log('Project does not exist')
+  } else if (err instanceof InsufficientAllowance) {
+    console.log('Need to approve $INKD first')
+    await inkd.approveToken()
+  } else if (err instanceof InkdError) {
+    console.log('Protocol error:', err.message, err.code)
+  } else {
+    throw err // re-throw unexpected errors
+  }
+}
+```
+
+| Error Class | Code | When thrown |
+|-------------|------|-------------|
+| `InkdError` | — | Base class |
+| `ProjectNotFound` | `PROJECT_NOT_FOUND` | Project ID doesn't exist |
+| `ProjectNameTaken` | `PROJECT_NAME_TAKEN` | Name already registered |
+| `Unauthorized` | `UNAUTHORIZED` | Not owner/collaborator |
+| `InsufficientBalance` | `INSUFFICIENT_BALANCE` | Not enough $INKD |
+| `InsufficientAllowance` | `INSUFFICIENT_ALLOWANCE` | Token not approved |
+| `InvalidArweaveHash` | `INVALID_ARWEAVE_HASH` | Bad hash format |
+| `VersionAlreadyExists` | `VERSION_ALREADY_EXISTS` | Tag already pushed |
+| `ClientNotConnected` | `CLIENT_NOT_CONNECTED` | No wallet connected |
+| `ArweaveNotConnected` | `ARWEAVE_NOT_CONNECTED` | Arweave client missing |
+| `EncryptionError` | `ENCRYPTION_ERROR` | Encryption/decryption failed |
+
+---
+
+## AI Agent Usage
+
+Register your AI agent's capabilities on-chain:
+
+```typescript
+const hash = await inkd.createProject({
+  name: 'my-agent-v1',
+  description: 'Autonomous coding agent — builds and deploys software',
+  license: 'Proprietary',
+  isAgent: true,
+  agentEndpoint: 'https://api.myagent.xyz/v1',
+  isPublic: true,
+})
+```
+
+Query all registered agents:
+
+```typescript
+const agentIds = await inkd.getAgentProjects(0n, 100n)
+const agents = await Promise.all(agentIds.map(id => inkd.getProject(id)))
+```
+
+---
+
+## Network Addresses
+
+| Contract | Mainnet (Base) | Testnet (Base Sepolia) |
+|----------|---------------|------------------------|
+| `InkdToken` | TBD | TBD |
+| `InkdRegistry` | TBD | TBD |
+| `InkdTreasury` | TBD | TBD |
+
+> Addresses will be populated after mainnet deployment.
+
+---
+
+## Contributing
+
+See [`CONTRIBUTING.md`](../CONTRIBUTING.md) in the monorepo root.
+
+**Dev setup:**
+```bash
+cd sdk
+npm install
+npm test           # run 42 unit tests
+npm run typecheck  # TypeScript check
+npm run build      # compile to dist/
+```
+
+---
+
+## License
+
+MIT — see [LICENSE](../LICENSE)
+
+---
+
+*Made by [Inkd Protocol](https://inkdprotocol.xyz)*

package/dist/InkdClient.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @file InkdClient.ts
+ * @description Main client class for interacting with the Inkd Protocol.
+ *              Handles InkdToken minting, InkdVault inscriptions, and InkdRegistry operations.
+ */
+import type { PublicClient, WalletClient, Account, Chain, Transport } from "viem";
+import { type IEncryptionProvider } from "./encryption";
+import type { Address, InkdClientConfig, InkdTokenData, Inscription, ProtocolStats, MintOptions, InscribeOptions, InscribeResult, InscribeCostEstimate, TransactionResult } from "./types";
+/**
+ * The main Inkd Protocol client.
+ *
+ * @example
+ * ```ts
+ * import { InkdClient } from "@inkd/sdk";
+ * import { createWalletClient, createPublicClient, http } from "viem";
+ * import { baseSepolia } from "viem/chains";
+ * import { privateKeyToAccount } from "viem/accounts";
+ *
+ * const inkd = new InkdClient({
+ *   tokenAddress: "0x...",
+ *   vaultAddress: "0x...",
+ *   registryAddress: "0x...",
+ *   chainId: 84532,
+ * });
+ *
+ * inkd.connect(walletClient, publicClient);
+ * await inkd.connectArweave("private-key");
+ *
+ * // Mint an InkdToken
+ * const { tokenId } = await inkd.mintToken();
+ *
+ * // Inscribe data on it
+ * const result = await inkd.inscribe(tokenId, Buffer.from("agent brain data"), {
+ *   contentType: "application/json",
+ *   name: "brain.json",
+ * });
+ * ```
+ */
+export declare class InkdClient {
+    private config;
+    private walletClient;
+    private publicClient;
+    private arweave;
+    private encryption;
+    constructor(config: InkdClientConfig);
+    /** Connect wallet and public clients for on-chain interaction. */
+    connect(walletClient: WalletClient<Transport, Chain, Account>, publicClient: PublicClient): void;
+    /** Connect Arweave storage client for file uploads. */
+    connectArweave(privateKey: string, irysUrl?: string, gateway?: string): Promise<void>;
+    /** Set a custom encryption provider (for Lit Protocol integration). */
+    setEncryptionProvider(provider: IEncryptionProvider): void;
+    /** Mint a single InkdToken. Returns the new token ID. */
+    mintToken(options?: MintOptions): Promise<TransactionResult>;
+    /** Batch mint multiple InkdTokens (max 10). */
+    private batchMintTokens;
+    /** Inscribe data onto your InkdToken. Uploads to Arweave first. */
+    inscribe(tokenId: bigint, data: Buffer | Uint8Array | string, options?: InscribeOptions): Promise<InscribeResult>;
+    /** Get all inscriptions on a token. */
+    getInscriptions(tokenId: bigint): Promise<Inscription[]>;
+    /** Remove (soft-delete) an inscription. */
+    removeInscription(tokenId: bigint, index: number): Promise<TransactionResult>;
+    /** Update an inscription with new data (creates a new version). */
+    updateInscription(tokenId: bigint, index: number, newData: Buffer | Uint8Array | string, contentType?: string): Promise<TransactionResult>;
+    /** Grant temporary read access to a wallet. */
+    grantAccess(tokenId: bigint, wallet: Address, durationSeconds: number): Promise<TransactionResult>;
+    /** Revoke read access from a wallet. */
+    revokeAccess(tokenId: bigint, wallet: Address): Promise<TransactionResult>;
+    /** List an InkdToken for sale on the marketplace. */
+    listForSale(tokenId: bigint, price: bigint): Promise<TransactionResult>;
+    /** Buy an InkdToken from the marketplace. */
+    buyToken(tokenId: bigint): Promise<TransactionResult>;
+    /** Get token data for a specific InkdToken. */
+    getToken(tokenId: bigint): Promise<InkdTokenData>;
+    /** Get all InkdTokens owned by an address. */
+    getTokensByOwner(address: Address): Promise<InkdTokenData[]>;
+    /** Check if an address holds at least one InkdToken. */
+    hasInkdToken(address: Address): Promise<boolean>;
+    /** Estimate the cost of inscribing data. */
+    estimateInscribeCost(fileSize: number): Promise<InscribeCostEstimate>;
+    /** Get protocol-wide statistics from the registry. */
+    getStats(): Promise<ProtocolStats>;
+    private requireWallet;
+    private requirePublic;
+    private requireArweave;
+    private extractTokenIdFromLogs;
+    private extractAllTokenIdsFromLogs;
+    private extractInscriptionIndexFromLogs;
+}
+//# sourceMappingURL=InkdClient.d.ts.map

package/dist/InkdClient.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"InkdClient.d.ts","sourceRoot":"","sources":["../src/InkdClient.ts"],"names":[],"mappings":"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"}