npm package: @invariance/common
Description: Shared types and constants for Invariance Protocol
Latest version: 0.1.1

# @invariance/common

Shared types and constants for Invariance Protocol.

## Installation

```bash
pnpm add @invariance/common
```

## Usage

```typescript
import {
  // Types
  type AgentId,
  type ActionId,
  type Action,
  type Policy,
  type SpendingCapPolicy,
  type PolicyConfig,
  type AnyContractEvent,

  // Custom Permission Marketplace Types
  type CustomPermissionId,
  type CustomPermissionMetadata,
  type CustomPermissionConfig,

  // Constants
  BASE_MAINNET,
  BASE_SEPOLIA,
  getChainConfig,
  getContractAddresses,

  // Helpers
  createAgentId,
  createActionId,
  createCustomPermissionId,

  // Defaults
  DEFAULT_POLICY_VALUES,
  applyPolicyDefaults,
} from '@invariance/common';
```

## Types

### Actions
- `AgentId` - Branded type for agent identifiers
- `ActionId` - Branded type for action identifiers
- `TaskId` - Branded type for task identifiers
- `IntentHash` - Branded type for intent hashes
- `Action` - Represents an action to execute
- `ActionInput` - Input for creating actions
- `ActionResult` - Result of action execution
- `ActionResultWithProvenance` - Result with full execution context

### Policies (Execution Rules)
- `Policy` - Base policy interface
- `SpendingCapPolicy` - Limits spending per tx/day
- `TimeWindowPolicy` - Restricts execution hours
- `ActionWhitelistPolicy` - Allows specific actions
- `VotingPolicy` - Requires consensus (multi-sig, DAO, threshold)
- `HumanApprovalPolicy` - Human-in-the-loop confirmation
- `PolicyConfig` - Agent policy configuration
- `PolicyCheckResult` - Result of policy check

### Custom Permission Marketplace
- `CustomPermissionId` - Branded type for custom permission IDs
- `CustomPermissionMetadata` - Permission metadata from marketplace
- `CustomPermissionConfig` - Configuration for enabling permissions
- `AgentPermissionConfig` - Agent-specific permission settings
- `ListPermissionsOptions` - Query options for listing permissions
- `CustomPermissionCheckResult` - Result of custom permission check
- `DeployPermissionOptions` - Options for deploying permissions
- `DeployPermissionResult` - Result of permission deployment
- `BuiltInTemplateType` - Available template types

### Template System
- `InvarianceTemplate` - Full template definition
- `TemplateId` - Branded type for template IDs
- `TemplateOptions` - Template configuration options
- `TemplateCheckResult` - Result of template verification
- `AuthorizationRule` - Authorization requirements
- `StateCondition` - State conditions to check
- `TimingRule` - Timing constraints
- `RateLimitRule` - Rate limiting rules
- `StakingRule` - Staking requirements

### Events
- `ContractEvent` - Base event interface
- `AgentRegisteredEvent` - New agent registered
- `ActionLoggedEvent` - Action logged on-chain
- `PolicyDeniedEvent` - Policy check failed
- `EscrowDepositedEvent` - Funds deposited
- `EscrowReleasedEvent` - Funds released
- `EscrowRefundedEvent` - Funds refunded
- `DisputeOpenedEvent` - Dispute opened
- `DisputeResolvedEvent` - Dispute resolved
- `PermissionRegisteredEvent` - Custom permission registered
- `PermissionEnabledEvent` - Permission enabled for agent
- `PermissionDisabledEvent` - Permission disabled for agent

## Constants

### Chains
- `BASE_MAINNET` - Base mainnet config (chain ID: 8453)
- `BASE_SEPOLIA` - Base Sepolia config (chain ID: 84532)

### Contracts
- `getContractAddresses(chainId)` - Get contract addresses for a chain

### Policy Defaults
- `DEFAULT_POLICY_VALUES` - Default values for policy fields
- `MAX_UINT256` - Maximum uint256 value
- `applyPolicyDefaults(policy)` - Apply defaults to a policy

## Backward Compatibility

The following deprecated aliases are provided for backward compatibility:

| Deprecated | Use Instead |
|------------|-------------|
| `Permission` | `Policy` |
| `PermissionConfig` | `PolicyConfig` |
| `SpendingCapPermission` | `SpendingCapPolicy` |
| `TimeWindowPermission` | `TimeWindowPolicy` |
| `ActionWhitelistPermission` | `ActionWhitelistPolicy` |
| `VotingPermission` | `VotingPolicy` |
| `HumanApprovalPermission` | `HumanApprovalPolicy` |
| `PermissionCheckResult` | `PolicyCheckResult` |
| `PermissionDeniedEvent` | `PolicyDeniedEvent` |