# HFSP

## String Formats

Mind different networks: mainnet, testnet, regtest, signet.

Some useful info about formats:
* https://lightning.money/spec
* [LNURL Playground](https://lnurl.fiatjaf.com)
* https://bolt.fun/guide/web-services/lnurl/withdraw
* https://bootstrap.bolt12.org/examples
* https://paxful.zendesk.com/hc/en-us/articles/360013076679-Bitcoin-address-types
* https://shiftcrypto.ch/blog/what-are-bitcoin-address-types/

### Lightning Related

1. [BOLT-11: LN invoice](https://github.com/lightning/bolts/blob/master/11-payment-encoding.md#human-readable-part) (tolerate `lightning:` prefix)
3. LN address [spec](https://github.com/andrerfneves/lightning-address/blob/master/README.md)
5. LNURL https://coincharge.io/en/lnurl-for-lightning-wallets/
* request
* withdraw
* auth
7. BOLT-12 http://bolt12.org

### [Data](https://docs.google.com/spreadsheets/d/1ik4shP9G5IXOIRi6eZPi91eHxWIFM0aZfNBQo96aAXk/edit#gid=0)

### On-Chain Related

1. BIP-21 URI https://github.com/bitcoin/bips/blob/master/bip-0021.mediawiki
1. On-chain addresses (Legacy, SegWit, Taproot, ...)

### Others

1. custom data (up to the lib user, e.g. lipa invitation codes)
1. URL
* some customisations for BeachWallet?
* mind different URL schemes (http://, app-xy://)

The library might be extendable by additional (custom) formats (e.g. lipa invitations).

# Data Schema

* name (translatable)
* example
* link to spec
* validation regex
* network (mainnet, testnet, regtest, signet)
* description (explains what the string represents)
* hint (what can the user do with it?)
* next possible action (e.g. query the url if the string represents a url)
* translations (other natural human languages)

# How To Handle Errors
1. String is valid, but not for the use case
Example: user should scan an on-chain address, but scanned a lightning invoice
1. String is not valid
Example: An on-chain address with an invalid checksum (e.g. user lost the last character)
* isn't this the case when:
* the regex matches
* but the actual parsing fails

## Questions

* How / Where do we handle transaltions?
* "You have scanned a {scannedType} code. However, we would have expected a {excpectedType} code."
* Better wording for "scanned" in order to also work for string paste?
* Could implementations expect more than one type in specific scenarios?
* How do we handle different networks (testnet / mainnet)?
* as type? -> MainnetAddress, TestnetAddress
* as parameter to types (naming? "validators"?)
* parse type Address with validator Mainnet or Testnet
* scheme could also be a validator for URL types (http:// v.s. some-app://)
* Do we abstract away handling of some types which could be "nested"?
* wallet expects a BOLT-11 invoice, but user scans a LNRUL
* we could resolve the LNURL to a BOLT-11 invoice and return this
* each type could define converters defining the conversion to another supported type
* Can we inject logic per type in order to parse any QR code and handle it depending on what is scanned?
* parser.register(Address::PARSER, (address: Address) -> {// handle})

## API

ExpectedType parsed = parse(string, ExpectedType.class);

// e.g.
MainnetAddress parsed = parse(string, MainnetAddress.class);

// e.g. with validators
Address parsed = parse(string, Address.class, Address.MAINNET);

// e.g. with multiple validators
Address parsed = parse(string, Address.class, Address.MAINNET, Validators.oneOf(Address.P2SH, Address.P2WSH));