TypeScript type definitions and utilities for Clarity smart contract ABIs
npm install @secondlayer/clarity-typesTypeScript type definitions and utilities for Clarity smart contract ABIs. Provides compile-time type inference and runtime validation for Clarity contracts on the Stacks blockchain.
- 🎯 Full type inference - Automatically infer TypeScript types from Clarity contract ABIs
- 🔒 Type safety - Catch type errors at compile time, not runtime
- 📦 Zero dependencies - Pure TypeScript with no runtime dependencies
- 🚀 Lightweight - Tree-shakeable and minimal bundle impact
- ✅ Runtime validation - Optional runtime type guards for safety
- 🔧 Integration ready - Designed to work with @stacks/connect
``bash`
npm install clarity-typesor
yarn add clarity-typesor
bun add clarity-types
`typescript
import type { ClarityContract, ExtractFunctionArgs } from "clarity-types";
// Define your contract ABI with const assertion
const contractAbi = {
functions: [
{
name: "transfer",
access: "public",
args: [
{ name: "amount", type: "uint128" },
{ name: "sender", type: "principal" },
{ name: "recipient", type: "principal" },
],
outputs: { response: { ok: "bool", error: "uint128" } },
},
],
} as const satisfies ClarityContract;
// Extract typed function arguments
type TransferArgs = ExtractFunctionArgs
// Result: { amount: bigint, sender: string, recipient: string }
// Use with @stacks/connect
const transfer = (args: TransferArgs) => ({
contractAddress: "SP2PABAF9FTAJYNFZH93XENAJ8FVY99RRM50D2JG9",
contractName: "my-token",
functionName: "transfer",
functionArgs: [args.amount, args.sender, args.recipient],
});
`
| Clarity Type | TypeScript Type |
| ------------------- | ---------------------------- |
| uint128 | bigint |int128
| | bigint |bool
| | boolean |principal
| | string |trait_reference
| | string |(string-ascii N)
| | string |(string-utf8 N)
| | string |(buff N)
| | Uint8Array |(optional T)
| | T \| null |(response OK ERR)
| | { ok: OK } \| { err: ERR } |(list N T)
| | T[] |{tuple}
| | object with typed fields |
`typescript
// Extract all function names
type Functions = ExtractFunctionNames
// Extract function arguments as object
type Args = ExtractFunctionArgs
// Extract function return type
type Output = ExtractFunctionOutput
// Extract only public functions
type PublicFunctions = ExtractPublicFunctions
// Extract only read-only functions
type ReadOnlyFunctions = ExtractReadOnlyFunctions
// Extract private functions
type PrivateFunctions = ExtractPrivateFunctions
`
`typescript
// Extract map types for typed map operations
type MapNames = ExtractMapNames
type BalanceKey = ExtractMapKey
type BalanceValue = ExtractMapValue
// Extract variable types
type VarNames = ExtractVariableNames
type OwnerType = ExtractVariableType
// Filter by access
type Constants = ExtractConstants
type DataVars = ExtractDataVars
`
`typescript
// Get token names
type FTNames = ExtractFungibleTokenNames
type NFTNames = ExtractNonFungibleTokenNames
// Get NFT asset identifier type
type NFTAsset = ExtractNFTAssetType
`
`typescript
// Get defined trait names
type DefinedTraits = ExtractDefinedTraitNames
// Get implemented trait identifiers
type ImplementedTraits = ExtractImplementedTraits
`
`typescript
import { isUint128, isPrincipal, isOkResponse } from "clarity-types";
// Validate values at runtime
if (isUint128(value)) {
// value is bigint between 0 and 2^128-1
}
if (isPrincipal(address)) {
// address is a valid Stacks principal
}
if (isOkResponse(result)) {
console.log("Success:", result.ok);
} else {
console.log("Error:", result.err);
}
`
`typescript
import { jsToClarity, validateArgs } from "clarity-types";
// Validate and convert JS values to Clarity types
const validated = jsToClarity("uint128", 123n); // Returns 123n or throws
// Validate function arguments
validateArgs(functionAbi, {
amount: 100n,
recipient: "SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7",
});
`
`typescript
const complexAbi = {
functions: [
{
name: "create-proposal",
access: "public",
args: [
{
name: "details",
type: {
tuple: [
{ name: "title", type: { "string-utf8": { length: 100 } } },
{ name: "amount", type: "uint128" },
{
name: "recipients",
type: {
list: {
type: "principal",
length: 10,
},
},
},
],
},
},
],
outputs: {
response: {
ok: "uint128",
error: { "string-ascii": { length: 100 } },
},
},
},
],
} as const satisfies ClarityContract;
type ProposalArgs = ExtractFunctionArgs
// Result: {
// details: {
// title: string
// amount: bigint
// recipients: string[]
// }
// }
`
This library provides types for generating parameters compatible with @stacks/connect and @stacks/transactions:
`typescript
import { openContractCall, callReadOnlyFunction } from "@stacks/connect";
import type { ContractInterface } from "clarity-types";
// Generated contract interface (usually created by @stacks/cli)
const contract: ContractInterface
// Write functions return ContractCallParams
transfer: (args) => ({
contractAddress: "SP...",
contractName: "my-token",
functionName: "transfer",
functionArgs: [args.amount, args.sender, args.recipient],
}),
// Read-only functions return ReadOnlyCallParams
getBalance: (args) => ({
contractAddress: "SP...",
contractName: "my-token",
functionName: "get-balance",
functionArgs: [args.address],
}),
};
// Use with @stacks/connect for write operations
await openContractCall({
...contract.transfer({
amount: 1000n,
sender: "SP...",
recipient: "SP...",
}),
onFinish: (data) => {
console.log("Transaction:", data);
},
});
// Use with @stacks/transactions for read operations
const result = await fetchCallReadOnlyFunction({
...contract.getBalance({ address: "SP..." }),
senderAddress: "SP...", // any address works for read-only
});
``
- No network calls - This is a type-only library
- No transaction building - Use @stacks/transactions
- No wallet interaction - Use @stacks/connect
- No code generation - Use @stacks/cli (coming soon)
This library focuses solely on providing type safety for Clarity contract ABIs.
MIT