Welcome to Newton SDK

TypeScript SDK for the Newton Protocol — a decentralized policy engine for onchain transaction authorization, built as an EigenLayer AVS.

Documentation

• Quickstart — simulate your first policy evaluation in 5 minutes
• Integration Guide — full end-to-end integration with policy, contract, and frontend
• SDK Reference — complete API documentation
• Core Concepts — policies, intents, tasks, and attestations

Prerequisites

• Node.js >= 20

Installation

# Install dependencies
npm install @magicnewton/newton-protocol-sdk viem

Exports

The SDK provides several entry points:

// Public Client Actions
import { newtonPublicClientActions } from '@magicnewton/newton-protocol-sdk';
import { createPublicClient, webSocket } from 'viem';
import { sepolia } from 'viem/chains';

const newtonPublicClient = createPublicClient({
  chain: sepolia,
  transport: webSocket('wss://eth-sepolia.g.alchemy.com/v2/YOUR_KEY'),
}).extend(
  newtonPublicClientActions({
    policyContractAddress: '0xpolicyContractAddress',
  }),
);

newtonPublicClient.getTaskStatus({ taskId: '0x...' });

// Wallet Client Actions
import { newtonWalletClientActions } from '@magicnewton/newton-protocol-sdk';
import { createWalletClient, webSocket } from 'viem';
import { sepolia } from 'viem/chains';
import { privateKeyToAccount } from 'viem/accounts';

const newtonWalletClient = createWalletClient({
  chain: sepolia,
  transport: webSocket('wss://alchemyWebsocketUrl'),
  account: privateKeyToAccount('0xYOUR_PRIVATE_KEY'),
}).extend(newtonWalletClientActions({ apiKey: '<YOUR_API_KEY>' }));

newtonWalletClient.evaluateIntentDirect({...})

Development

Building the SDK

The SDK uses Rollup for bundling and supports both CommonJS and ES modules.

# Build the SDK
pnpm build

This will generate the following output in the dist/ directory:

• dist/cjs/ - CommonJS modules
• dist/es/ - ES modules
• dist/types/ - TypeScript declaration files

Development Build

For development with watch mode:

# Build and watch for changes
pnpm build --watch

Type Checking

The project includes TypeScript configuration for type checking:

# Type check without building
npx tsc --noEmit

Linting

# Lint and auto-fix code
pnpm lint

Privacy Module

The SDK includes a privacy module for client-side HPKE encryption used in privacy-preserving policy evaluation. Key exports:

• createSecureEnvelope — HPKE encrypt plaintext into a SecureEnvelope (offline, zero network calls)
• getPrivacyPublicKey — fetch the gateway's X25519 HPKE public key
• uploadEncryptedData — encrypt and upload data to the gateway in one call
• uploadSecureEnvelope — upload a pre-built SecureEnvelope to the gateway
• generateSigningKeyPair — generate Ed25519 key pair for privacy signatures
• storeEncryptedSecrets — upload KMS-encrypted secrets for PolicyData
• signPrivacyAuthorization — compute dual Ed25519 signatures for privacy-enabled tasks

See the SDK Reference for full API documentation.

Identity Module

The SDK includes an identity module for registering identity data and managing identity-to-PolicyClient links on the IdentityRegistry. Key exports:

• registerIdentityData -- store identity data reference on-chain with gateway co-signature
• identityDomainHash -- compute the bytes32 domain identifier from a name (e.g., identityDomainHash("kyc"))
• linkIdentityAsSignerAndUser -- link identity when caller is both owner and user
• linkIdentityAsSigner -- link identity as owner with counterparty signature
• linkIdentityAsUser -- link identity as user with counterparty signature
• linkIdentity -- link identity as 3rd party with dual signatures
• unlinkIdentityAsSigner -- unlink identity as owner
• unlinkIdentityAsUser -- unlink identity as user

Testing

The project uses Vitest for unit testing:

# Run tests
pnpm test

# Run tests in watch mode
pnpm test:watch

# Run tests with coverage
pnpm test:coverage

Testing Locally Built SDK

To test the locally built SDK from a different local project, you can use one of these methods:

Method 1: Using pnpm link (Recommended)

1. In the Newton SDK project directory:

   # Build the SDK first
   pnpm build
   
   # Create a global link
   pnpm link --global

2. In your test project directory:

   # Link to the globally linked SDK
   pnpm link --global @magicnewton/newton-protocol-sdk

3. Import and use in your test project:

   import { newtonWalletClientActions } from '@magicnewton/newton-protocol-sdk';
   // Your test code here

4. When you make changes to the SDK:

   # In the SDK directory, rebuild
   pnpm build
   
   # The changes will be immediately available in your linked test project

Method 2: Using local file path

1. In your test project's package.json, add:

   {
     "dependencies": {
       "@magicnewton/newton-protocol-sdk": "file:../path/to/newton-protocol-sdk"
     }
   }

2. Install dependencies:

   pnpm install

3. Import and use normally:

   import { newtonWalletClientActions } from '@magicnewton/newton-protocol-sdk';

Method 3: Using npm link (Alternative)

If you prefer npm over pnpm:

1. In the Newton SDK project directory:

   npm run build
   npm link

2. In your test project directory:

   npm link @magicnewton/newton-protocol-sdk

Unlinking

When you're done testing:

# In your test project directory
pnpm unlink @magicnewton/newton-protocol-sdk

# In the SDK directory
pnpm unlink --global

Development Workflow with Local Testing

1. Set up the link (one-time setup)
2. Make changes to the SDK source code
3. Rebuild: pnpm build (or pnpm build --watch for auto-rebuild)
4. Test immediately in your linked project
5. Iterate on changes
6. Unlink when done testing

Troubleshooting Local Testing

• Module not found errors: Ensure the SDK is built (pnpm build) before linking
• Type errors: The TypeScript declarations are generated in dist/types/
• Import issues: Make sure your test project can resolve the linked package
• Version conflicts: Unlink and reinstall if you encounter dependency conflicts

Build Output

The build process generates multiple module formats:

• CommonJS: dist/cjs/ - For Node.js environments
• ES Modules: dist/es/ - For modern bundlers and browsers
• TypeScript: dist/types/ - For development and IDE support

Development Workflow

1. Install dependencies: pnpm install
2. Make changes to source files in src/
3. Build: pnpm build (or pnpm build --watch for development)
4. Lint: pnpm lint to check code quality
5. Type check: pnpm typecheck for TypeScript validation
6. Quality checks: pnpm check:all to validate exports and bundle size

Troubleshooting

Clean Build

If you encounter build issues, try cleaning and rebuilding:

pnpm clean
pnpm install
pnpm build

TypeScript Issues

Ensure TypeScript is properly configured:

npx tsc --noEmit

Linting Issues

Auto-fix common linting problems:

pnpm lint

Release Process

This repository uses automated releases with the auto tool for both production releases (master branch) and canary releases (pull requests).

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Ensure linting passes: pnpm lint
5. Ensure types check: pnpm typecheck
6. Ensure the build passes: pnpm build
7. Run quality checks: pnpm check:all
8. Run tests: pnpm test
9. Submit a pull request

License

Apache License 2.0 - see LICENSE file for details.