@occa/sdk 0.4.0

package/dist/pda.d.cts

@@ -0,0 +1,116 @@
+import { PublicKey } from '@solana/web3.js';
+import { OperationsKind } from './constants.cjs';
+
+/**
+ * Encode a u32 as little-endian 4 bytes (matches Anchor / Borsh on-chain
+ * representation when using a u32 in a PDA seed).
+ */
+declare function u32LeBytes(value: number): Buffer;
+/**
+ * CompanyAccount PDA.
+ *
+ *   seeds = ["company", owner, nonce_le_u32]
+ *
+ * Wallet-bound seed: a wallet's companies can be enumerated directly
+ * from chain by probing `(owner, nonce=0..N)`. The owner is also the
+ * sole authority for state-changing ix on this account.
+ */
+declare function deriveCompanyPda(owner: PublicKey, nonce: number, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * AgentIdentity PDA.
+ *
+ *   seeds = ["agent_identity", agent_pubkey]
+ *
+ * `agent_pubkey` is a stable identity key chosen by the caller (typically
+ * a fresh keypair generated client-side). Identity is independent of any
+ * company — the same identity may be deployed multiple times across the
+ * same owner's companies.
+ */
+declare function deriveAgentIdentityPda(agentPubkey: PublicKey, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * Deployment PDA.
+ *
+ *   seeds = ["deployment", company_pda, deployment_index_le_u32]
+ *
+ * `deployment_index` is a per-company u32 counter. Maintained by the
+ * caller — pick the next free index. Same `agent_identity` may have
+ * multiple deployments under the same company (e.g. retired then
+ * re-deployed); each deployment gets its own index.
+ */
+declare function deriveDeploymentPda(companyPda: PublicKey, deploymentIndex: number, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * TreasuryAccount PDA — owned by Treasury program.
+ *
+ *   seeds = ["treasury", company_pda]
+ *
+ * Initialized atomically with PolicyAccount via Registry's `create_company`
+ * CPI to `treasury::init_treasury` (design doc §6).
+ */
+declare function deriveTreasuryPda(companyPda: PublicKey, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * PolicyAccount PDA — owned by Treasury program.
+ *
+ *   seeds = ["policy", company_pda]
+ *
+ * Initialized atomically with TreasuryAccount via the same `create_company`
+ * CPI flow.
+ */
+declare function derivePolicyPda(companyPda: PublicKey, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * ProtocolFeeAccount PDA — owned by Treasury program. Singleton: one
+ * per program deployment, collects the Agent Operating Fee from every
+ * intra-company agent disbursement.
+ *
+ *   seeds = ["protocol_fees"]
+ */
+declare function deriveProtocolFeePda(programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * OperationsAccount PDA — owned by Treasury program. One per
+ * (company, kind) pair, so Disbursement and Anchor capabilities never
+ * share a key.
+ *
+ *   seeds = ["operations", company_pda, kind_byte]
+ *
+ * `kind_byte` is the single-byte discriminator from `OPERATIONS_KIND`
+ * (Disbursement=0, Anchor=1). Order MUST NOT change once any account
+ * exists.
+ */
+declare function deriveOperationsPda(companyPda: PublicKey, kind: OperationsKind, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * DailyAnchorAccount PDA — owned by Registry program. One per
+ * (deployment, UTC day) — captures the Merkle root over that day's
+ * task hashes.
+ *
+ *   seeds = ["daily_anchor", deployment_pda, day_unix_le_i64]
+ *
+ * `dayUnix` must be aligned to 00:00:00 UTC (multiple of 86400). The
+ * on-chain handler enforces alignment; passing an unaligned value will
+ * fail with a constraint error.
+ */
+declare function deriveDailyAnchorPda(deploymentPda: PublicKey, dayUnix: bigint, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+
+export { deriveAgentIdentityPda, deriveCompanyPda, deriveDailyAnchorPda, deriveDeploymentPda, deriveOperationsPda, derivePolicyPda, deriveProtocolFeePda, deriveTreasuryPda, u32LeBytes };

package/dist/pda.d.ts

@@ -0,0 +1,116 @@
+import { PublicKey } from '@solana/web3.js';
+import { OperationsKind } from './constants.js';
+
+/**
+ * Encode a u32 as little-endian 4 bytes (matches Anchor / Borsh on-chain
+ * representation when using a u32 in a PDA seed).
+ */
+declare function u32LeBytes(value: number): Buffer;
+/**
+ * CompanyAccount PDA.
+ *
+ *   seeds = ["company", owner, nonce_le_u32]
+ *
+ * Wallet-bound seed: a wallet's companies can be enumerated directly
+ * from chain by probing `(owner, nonce=0..N)`. The owner is also the
+ * sole authority for state-changing ix on this account.
+ */
+declare function deriveCompanyPda(owner: PublicKey, nonce: number, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * AgentIdentity PDA.
+ *
+ *   seeds = ["agent_identity", agent_pubkey]
+ *
+ * `agent_pubkey` is a stable identity key chosen by the caller (typically
+ * a fresh keypair generated client-side). Identity is independent of any
+ * company — the same identity may be deployed multiple times across the
+ * same owner's companies.
+ */
+declare function deriveAgentIdentityPda(agentPubkey: PublicKey, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * Deployment PDA.
+ *
+ *   seeds = ["deployment", company_pda, deployment_index_le_u32]
+ *
+ * `deployment_index` is a per-company u32 counter. Maintained by the
+ * caller — pick the next free index. Same `agent_identity` may have
+ * multiple deployments under the same company (e.g. retired then
+ * re-deployed); each deployment gets its own index.
+ */
+declare function deriveDeploymentPda(companyPda: PublicKey, deploymentIndex: number, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * TreasuryAccount PDA — owned by Treasury program.
+ *
+ *   seeds = ["treasury", company_pda]
+ *
+ * Initialized atomically with PolicyAccount via Registry's `create_company`
+ * CPI to `treasury::init_treasury` (design doc §6).
+ */
+declare function deriveTreasuryPda(companyPda: PublicKey, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * PolicyAccount PDA — owned by Treasury program.
+ *
+ *   seeds = ["policy", company_pda]
+ *
+ * Initialized atomically with TreasuryAccount via the same `create_company`
+ * CPI flow.
+ */
+declare function derivePolicyPda(companyPda: PublicKey, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * ProtocolFeeAccount PDA — owned by Treasury program. Singleton: one
+ * per program deployment, collects the Agent Operating Fee from every
+ * intra-company agent disbursement.
+ *
+ *   seeds = ["protocol_fees"]
+ */
+declare function deriveProtocolFeePda(programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * OperationsAccount PDA — owned by Treasury program. One per
+ * (company, kind) pair, so Disbursement and Anchor capabilities never
+ * share a key.
+ *
+ *   seeds = ["operations", company_pda, kind_byte]
+ *
+ * `kind_byte` is the single-byte discriminator from `OPERATIONS_KIND`
+ * (Disbursement=0, Anchor=1). Order MUST NOT change once any account
+ * exists.
+ */
+declare function deriveOperationsPda(companyPda: PublicKey, kind: OperationsKind, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+/**
+ * DailyAnchorAccount PDA — owned by Registry program. One per
+ * (deployment, UTC day) — captures the Merkle root over that day's
+ * task hashes.
+ *
+ *   seeds = ["daily_anchor", deployment_pda, day_unix_le_i64]
+ *
+ * `dayUnix` must be aligned to 00:00:00 UTC (multiple of 86400). The
+ * on-chain handler enforces alignment; passing an unaligned value will
+ * fail with a constraint error.
+ */
+declare function deriveDailyAnchorPda(deploymentPda: PublicKey, dayUnix: bigint, programId?: PublicKey): {
+    pda: PublicKey;
+    bump: number;
+};
+
+export { deriveAgentIdentityPda, deriveCompanyPda, deriveDailyAnchorPda, deriveDeploymentPda, deriveOperationsPda, derivePolicyPda, deriveProtocolFeePda, deriveTreasuryPda, u32LeBytes };

package/dist/pda.js

@@ -0,0 +1,24 @@
+import {
+  deriveAgentIdentityPda,
+  deriveCompanyPda,
+  deriveDailyAnchorPda,
+  deriveDeploymentPda,
+  deriveOperationsPda,
+  derivePolicyPda,
+  deriveProtocolFeePda,
+  deriveTreasuryPda,
+  u32LeBytes
+} from "./chunk-X6FBCGHU.js";
+import "./chunk-YCSBYRSH.js";
+export {
+  deriveAgentIdentityPda,
+  deriveCompanyPda,
+  deriveDailyAnchorPda,
+  deriveDeploymentPda,
+  deriveOperationsPda,
+  derivePolicyPda,
+  deriveProtocolFeePda,
+  deriveTreasuryPda,
+  u32LeBytes
+};
+//# sourceMappingURL=pda.js.map

package/dist/pda.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@occa/sdk",
+  "version": "0.4.0",
+  "description": "OCCA on-chain protocol SDK — PDA helpers, instruction builders, and types for the OCCA Registry + Treasury programs on Solana.",
+  "license": "MIT",
+  "author": "OCCA",
+  "homepage": "https://github.com/Occa-Labs/occa-core/tree/main/packages/occa-sdk#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Occa-Labs/occa-core.git",
+    "directory": "packages/occa-sdk"
+  },
+  "bugs": {
+    "url": "https://github.com/Occa-Labs/occa-core/issues"
+  },
+  "keywords": [
+    "solana",
+    "anchor",
+    "occa",
+    "agent",
+    "agent-identity",
+    "ai-agents",
+    "registry",
+    "deployment",
+    "web3"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./pda": {
+      "types": "./dist/pda.d.ts",
+      "import": "./dist/pda.js",
+      "require": "./dist/pda.cjs"
+    },
+    "./constants": {
+      "types": "./dist/constants.d.ts",
+      "import": "./dist/constants.js",
+      "require": "./dist/constants.cjs"
+    },
+    "./instructions": {
+      "types": "./dist/instructions.d.ts",
+      "import": "./dist/instructions.js",
+      "require": "./dist/instructions.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {
+    "@solana/web3.js": "^1.98.4"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsup": "^8.0.0",
+    "tsx": "^4.0.0",
+    "typescript": "^5.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "sync-idl": "cp ../../../occa-programs/target/idl/registry.json src/idl/registry.json && cp ../../../occa-programs/target/idl/treasury.json src/idl/treasury.json",
+    "devnet-smoke": "tsx scripts/devnet-smoke.ts"
+  }
+}

package/src/constants.ts

@@ -0,0 +1,93 @@
+import { PublicKey } from "@solana/web3.js";
+
+// Registry program ID. The vanity-grinded program keypair lives at
+// `occa-programs/programs/registry/registry-keypair.json` (gitignored,
+// sibling repo). Public key is committed here so clients (server +
+// web) can derive PDAs without loading the keypair.
+//
+// NOTE: this is the devnet program ID. Mainnet will likely have a
+// different program ID — when that day comes, swap via env or config.
+export const REGISTRY_PROGRAM_ID_BASE58 =
+  "occaTHMv5eYG5aZ85jimxTvHkBfsDCvndXC6J2k8kxr";
+
+export const REGISTRY_PROGRAM_ID = new PublicKey(REGISTRY_PROGRAM_ID_BASE58);
+
+// Treasury program ID — devnet. Registry's `create_company` CPIs into
+// `treasury::init_treasury` to atomically initialize the company's
+// TreasuryAccount + PolicyAccount PDAs (per design doc §6).
+export const TREASURY_PROGRAM_ID_BASE58 =
+  "occaxyVLnurdjedWCBPrvDCCto8wGYadtTZ3nAmcVzh";
+
+export const TREASURY_PROGRAM_ID = new PublicKey(TREASURY_PROGRAM_ID_BASE58);
+
+// PDA seed prefixes. Must match `occa-programs/programs/registry/src/lib.rs` exactly.
+export const COMPANY_SEED = Buffer.from("company");
+export const AGENT_IDENTITY_SEED = Buffer.from("agent_identity");
+export const DEPLOYMENT_SEED = Buffer.from("deployment");
+// Treasury PDA seeds (owned by treasury program). Must match
+// `occa-programs/programs/treasury/src/lib.rs`.
+export const TREASURY_SEED = Buffer.from("treasury");
+export const POLICY_SEED = Buffer.from("policy");
+export const PROTOCOL_FEES_SEED = Buffer.from("protocol_fees");
+export const OPERATIONS_SEED = Buffer.from("operations");
+// DailyAnchor PDA seed (owned by registry program). Seeds:
+// ["daily_anchor", deployment_pda, day_unix_le_i64_8bytes].
+export const DAILY_ANCHOR_SEED = Buffer.from("daily_anchor");
+
+// OperationsKind discriminator byte — must match the Rust enum order in
+// `treasury/src/lib.rs`. Used as the 3rd seed byte of an OperationsAccount
+// PDA and as a u8 wire arg to `register_company_operations`.
+export const OPERATIONS_KIND = {
+  /** Disbursement Wallet — operator-held only, signs `disburse_routine`. */
+  Disbursement: 0,
+  /** Anchor Wallet — operator+OCCA shared, signs `commit_daily_anchor`. */
+  Anchor: 1,
+} as const;
+export type OperationsKind =
+  (typeof OPERATIONS_KIND)[keyof typeof OPERATIONS_KIND];
+
+// SOL has no real SPL mint — lamports live directly on accounts. The
+// treasury program uses the default (all-zero) pubkey as the SOL marker
+// in accepted-asset lists and disbursement mint args.
+export const SOL_PSEUDO_MINT = new PublicKey(new Uint8Array(32));
+
+// On-chain bounds — must match `occa-programs/programs/registry/src/lib.rs`.
+export const MAX_NAME_LEN = 64;
+export const MAX_LOCALE_LEN = 8;
+export const MAX_ROLE_LEN = 32;
+export const MAX_METADATA_URI_LEN = 200;
+export const MAX_REPUTATION_URI_LEN = 200;
+
+// Status encodings — must match the on-chain constants.
+export const COMPANY_STATUS = {
+  Active: 0,
+  Paused: 1,
+} as const;
+export type CompanyStatus =
+  (typeof COMPANY_STATUS)[keyof typeof COMPANY_STATUS];
+
+export const DEPLOYMENT_STATUS = {
+  Active: 0,
+  Paused: 1,
+  /** Terminal — retired deployments cannot be reactivated. */
+  Retired: 2,
+} as const;
+export type DeploymentStatus =
+  (typeof DEPLOYMENT_STATUS)[keyof typeof DEPLOYMENT_STATUS];
+
+// Account discriminators (Anchor sha256("account:<Name>")[..8]).
+export const ACCOUNT_DISCRIMINATOR = {
+  AgentIdentity: Buffer.from([11, 149, 31, 27, 186, 76, 241, 72]),
+  CompanyAccount: Buffer.from([37, 215, 171, 200, 8, 141, 69, 96]),
+  Deployment: Buffer.from([66, 90, 104, 89, 183, 130, 64, 178]),
+  DailyAnchorAccount: Buffer.from([218, 106, 107, 94, 194, 48, 111, 254]),
+} as const;
+
+// Treasury program account discriminators — from
+// `occa-programs/target/idl/treasury.json`.
+export const TREASURY_ACCOUNT_DISCRIMINATOR = {
+  TreasuryAccount: Buffer.from([204, 140, 18, 173, 90, 152, 134, 123]),
+  PolicyAccount: Buffer.from([218, 201, 183, 164, 156, 127, 81, 175]),
+  ProtocolFeeAccount: Buffer.from([5, 171, 24, 9, 150, 135, 135, 201]),
+  OperationsAccount: Buffer.from([185, 55, 148, 90, 151, 227, 104, 158]),
+} as const;