# @xo-cash/utils

Utility functions for XO

- Template parsing, serialization, validation and schema generation
- Script identifier generation
- Template identifier generation
- Extended JSON

> ⚠️ This project is in **early development phase**. Use it only if you understand what you are doing and accept the risks. **Do not use funds you are not willing to lose.** Minor version bumps may introduce **breaking changes**

## Installation

```bash
npm install @xo-cash/utils
```

## Usage

```typescript
import { parseTemplate, scriptToScriptHash, generateTemplateIdentifier } from '@xo-cash/utils';
```

## Scripts

| Command                            | Description                                            |
| ---------------------------------- | ------------------------------------------------------ |
| `npm run build`                    | Compile TypeScript to `dist/`                          |
| `npm run generate-schema`          | Generate `xo-template.schema.json` from the Zod schema |
| `npm run test`                     | Run tests with coverage                                |
| `npm run style`                    | Lint with ESLint (read-only)                           |
| `npm run syntax`                   | Type-check without emitting (`tsc --noEmit`)           |
| `npm run format`                   | Auto-fix formatting and linting                        |
| `npm run docs`                     | Generate TypeDoc API docs to `public/`                 |
| `npm run spellcheck`               | Spell-check source and test files                      |
| `npm audit --audit-level=moderate` | Performs npm audit                                     |

## Templates

### Parsing

`parseTemplate` accepts any string OR XOTemplate object and returns a validated `XOTemplate` object. It rejects unknown
properties, missing required fields, and incorrect value types. Native bigint is accepted in satoshi
fields; string encoding is also accepted for values sourced from JSON where bigint is unavailable.

### How validation works

Validation uses a Zod schema defined in `source/template/schemas.ts`. The schema mirrors the
`XOTemplate` TypeScript type and rejects unknown keys at every level. When validation fails, a
`TemplateInvalidError` is thrown with a message that lists every failing field and the reason it
failed, so all problems are visible in one pass.

### JSON Schema export

A JSON Schema representation of the template can be generated by running:

```bash
npm run generate-schema
```

This writes `source/template/xo-template.schema.json`, which can be consumed by other tools. However, it's recommended to use functions provided by this library for XO template development thanks to the extended JSON support.

## Links

- [Repository](https://gitlab.com/GeneralProtocols/xo/utils)
- [Issues](https://gitlab.com/GeneralProtocols/xo/utils/issues)

## License

[MIT](LICENSE)