v0.1.0

Minor Changes

• c930585 Thanks @jwahdatehagh! - Initial release of @1001-digital/natspec — fetch and normalize NatSpec documentation from Sourcify for any verified smart contract.

  Features

  • createNatSpec(config?) — factory that returns a client with fetch, parse, and toMetadata methods
  • parse(userdoc, devdoc) — pure function that merges Solidity compiler userdoc (@notice) and devdoc (@dev, @param, @return) into a normalized, name-keyed structure
  • toMetadata(natspec) — converts parsed NatSpec to a shape compatible with the contract-metadata standard
  • Overloaded function handling — bare name for unique functions, full Solidity signature for overloads (e.g. safeTransferFrom(address,address,uint256,bytes))
  • State variable support — public state variable NatSpec from devdoc.stateVariables is merged into the functions output
  • Custom error classes — NatSpecNotFoundError and NatSpecFetchError with chain/address context
  • Zero runtime dependencies — only uses the Fetch API

Patch Changes

• aad2482 Thanks @jwahdatehagh! - Fix error handling and state variable getter signatures.

  Bug fixes

  • State variable getter signatures — no longer reconstructs signatures from parameter names (which are names, not Solidity types). State variables not already in methods now use name() instead of producing misleading signatures like balances(owner).
  • Partial Sourcify responses — missing userdoc or devdoc in the API response now defaults to { methods: {} } instead of crashing with a TypeError.
  • Network error wrapping — fetch rejections (DNS failure, timeout) and JSON parse errors are now wrapped in NatSpecFetchError with cause, so callers can catch all failures via NatSpecError.

  Housekeeping

  • Deduplicated DEFAULT_BASE_URL between sourcify.ts and index.ts

v0.0.1 — Initial Release

@1001-digital/natspec

Fetch and normalize NatSpec (userdoc/devdoc) documentation from Sourcify for any verified smart contract. Zero runtime dependencies.

Features

• createNatSpec(config?) — factory that returns a client with fetch, parse, and toMetadata methods
• parse(userdoc, devdoc) — pure function that merges Solidity compiler userdoc (@notice) and devdoc (@dev, @param, @return) into a normalized, name-keyed structure
• toMetadata(natspec) — converts parsed NatSpec to a shape compatible with the contract-metadata standard
• Overloaded function handling — bare name for unique functions, full Solidity signature for overloads (e.g. safeTransferFrom(address,address,uint256,bytes))
• State variable support — public state variable NatSpec from devdoc.stateVariables is merged into the functions output
• Custom error classes — NatSpecNotFoundError and NatSpecFetchError with chain/address context

Quick Start

pnpm add @1001-digital/natspec

import { createNatSpec } from '@1001-digital/natspec'

const natspec = createNatSpec()

// Fetch NatSpec for VV Checks Originals
const result = await natspec.fetch(1, '0x036721e5a769cc48b3189efbb9cce4471e8a48b1')

console.log(result.contract)
// { title: 'Checks', author: 'VisualizeValue', notice: 'This artwork is notable.' }

console.log(result.functions.composite.notice)
// 'Composite one token into another. This mixes the visual and reduces the number of checks.'

// Convert to contract-metadata format
const metadata = natspec.toMetadata(result)