71 lines
2.8 KiB
Markdown
71 lines
2.8 KiB
Markdown
# @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)
|