[HN Gopher] Show HN: Numscript, a declarative language to model ...
___________________________________________________________________
Show HN: Numscript, a declarative language to model financial
transactions
Numscript is a simple, declarative language that helps you model
financial transactions. You can do quite a few things with it, such
as modeling: * Payments involving vouchers and a user's prepaid
balance * Complex funds destination scenario where the customer
gets cash back * Configurable user credit balance spending
transactions The main idea is to take the pain out of describing
of a system dealing with money movements should behave in
traditional languages such as JS/TS/Go/Ruby etc, landing an
expressive way to model these movements of value. It is
voluntarily broad in applicability--our customers use it today for
use-cases ranging from marketplaces funds orchestration to home-
grown loan management systems. Once those transactions are
modeled, they are to be picked up and committed to a system-of-
record, ledgering system or executed on a set of payments and
banking APIs. It was initially a DSL we bundled into our Core
Ledger product at Formance (YCS21) but we're giving it more
autonomy now and started to make it standalone, with the idea that
anyone could eventually bolt Numscript on top of their ledgering
system. We're also exploring to make it natively compatible with
other backends. As part of this un-bundling, we've just shipping a
playground which lets you fiddle with it without installing
anything at https://playground.numscript.org/ (it works best on
desktop). Happy to chime in on any questions!
Author : superzamp
Score : 197 points
Date : 2024-09-19 15:59 UTC (1 days ago)
(HTM) web link (playground.numscript.org)
(TXT) w3m dump (playground.numscript.org)
| robk wrote:
| This seems cool but what's the intention with the USD/2 notation?
| Is that for fractional sub-cent precision in rounding situations?
| superzamp wrote:
| It's indeed relative to cents in a sense, the idea is to force
| you to declare the precision of the monetary amount you're
| expressing.
|
| You can see various interpretation of what "USD" means in the
| wild, as some APIs will happily parse USD 100 as $1.00 while
| some others might parse USD 100 as $100.00.
|
| So we recommend this explicit [ASSET/SCALE AMOUNT] notation,
| where SCALE describes the negative power of ten to multiply the
| AMOUNT with to obtain the decimal value in the given ASSET.
|
| It makes subsequent interaction with external systems much
| easier. You can read a bit more about it here [1].
|
| [1] https://docs.formance.com/stack/unambiguous-monetary-
| notatio...
| flockonus wrote:
| What about units that cost sub-cent? For examples, I've seen
| private company stocks being $0.0001
|
| Not sure why you'd need to make a note in the internal
| representation, vs. leave adapters to handle conversions.
| bbor wrote:
| Not to speak for them, but I think you've understood the
| point exactly. You need to be able to support arbitrary
| precision, but that support needs to be _intentional_ to
| avoid errors. And you have to record that decision
| somewhere if adapters are to correctly handle your outputs;
| why not in the unit name?
| petesergeant wrote:
| If I understand their docs correctly, that's equivalent to
| [USD/4 1]
| tway_GdBRwW wrote:
| Used to work at a payments company. Yes, you need to be
| *very* explicit in how you model currency amounts and
| precision. See also earlier post about Canadian rounding
| rules. Some of the "logic" is regulatory/compliance driven.
|
| ref child post about stocks trading for 0.0001. Yes, those
| are real trades and (probably) fully legal etc, but I'm not
| sure the Fed recognizes currency amounts less than 1 US cent
| ($0.01), so the accounting rules and tax rules might not
| match expectations based on generalized floating point math.
| euroderf wrote:
| Doesn't the Fed recognise mills ? They are not extinct.
| girvo wrote:
| Just to add to this, having also implemented a production
| payment system, we did the same thing. One needs to be very
| explicit about the scale and how it should be rounded and
| dealt with, and how to operate on two different scale
| systems. Quite a fun challenge, though I do not miss the edge
| cases.
|
| Our system was a payment system for childcare management
| software, interfacing with banks and the government directly.
| o-o- wrote:
| I'm curious - what edge cases did you find?
| girvo wrote:
| Mostly bank specific: the parsing and rounding approach
| wasn't always consistent depending on what was being run.
| Still crazy to me that it was all CSV (with some special
| extra formatting/structure) via FTP to run transactions
| too at the time!
| vslira wrote:
| Super interesting and thanks for sharing. If I understood the
| license page on the repository correctly, the DSL is MIT-licensed
| since it's not within the enterprise directory, right?
| superzamp wrote:
| Yes exactly! There's actually two implementations, one tightly
| knit to our ledger product located at [1] and the new,
| standalone one (used by the playground) at [2]. In any case, in
| both implementations, the DSL is indeed MIT.
|
| [1]
| https://github.com/formancehq/stack/tree/main/components/led...
|
| [2] https://github.com/formancehq/numscript
| bbor wrote:
| To this noob, this seems like a problem that was pretty
| convincingly solved by double entry accounting ledgers, but from
| your post it sounds like this isn't a replacement-of but rather
| an addition-to that model. What's a situation where an imperative
| approach would be preferable to the traditional declarative
| approach? My depth of knowledge pretty much starts and ends with
| the below document, so apologies if this is obvious to experts!
|
| https://beancount.github.io/docs/the_double_entry_counting_m...
|
| E: the problem being "tracking transactions". Yes?
| superzamp wrote:
| That's a very good question. So the DSL here operates an
| agnostic source/dest transaction model, which is akin to the
| credit/debit model sans the semantic baggage. The goal of this
| model is indeed to be "tracking transactions" in the abstract
| sense, having the benefit of not forcing accounting decisions
| too early on when there is (still yet) none.
|
| For example, if you create a transaction moving money from
| "@stripe:main" to "@acct:123" and "@acct:234", you're merely
| representing the fact that you want this money to be moved.
| Wether the movement is clearing off a liability or generating
| revenue is another concern that you (in our model) want to take
| care of in a separate layer, that will also likely involve some
| intense intentionality and iterations from your accounting
| team.
|
| In a sense, it's as close to accounting than it is to
| warehousing money, moving unitary boxes of it from one location
| to another.
|
| These two models have the same amount of information per entry,
| so they can actually be converted from one to another, enabling
| you to also represent some accounting-ish transactions with
| this DSL, e.g. with a send [USD/2 100] from @ar:invoices:1234
| to @sales.
| bbor wrote:
| Fascinating, thanks for taking the time to educate! Makes
| sense to me -- it seems this tool is purpose built for
| situations where _tracking_ is complex enough to deserve
| decoupling from _annotating_ or _interpreting_ , to put it in
| my own kindergarten terms.
|
| I don't have a need for this personally but I'll definitely
| be bouncing this around in my head for a while, both
| technically (JS _ALL_ the things!) and methodologically.
| Accounting is pretty trivial when you don't have any income
| to track!
| mamidon wrote:
| I'm living this life right now; except we baked in notions of
| Assets/Liabilities/Income/Expenses into our ledger logic.
| Only to realize our customers don't care and just want to do
| whatever it is they've been doing.
| abdullahkhalids wrote:
| How would this handle Canadian guidelines for dealing with cents
| in cash, where you round to the nearest 5c [1]?
| Amounts ending in 1 cent and 2 cents are rounded down to the
| nearest 10 cents; Amounts ending in 3 cents and 4 cents
| are rounded up to the nearest 5 cents; Amounts ending in
| 6 cents and 7 cents are rounded down to the nearest 5 cents;
| Amounts ending in 8 cents and 9 cents are rounded up to the
| nearest 10 cents; Amounts ending in 0 cent and 5 cents
| remain unchanged.
|
| EDIT: I think if you send 12 cents, send
| [CADCASH/2 12] ( source = @user1 destination = @user2 )
|
| It should result in sending 10 cents.
| "postings": [{"source": "user1",
| "destination": "user2", "amount": 10,
| "asset": "CADCASH/2"}]
|
| Can this happen?
|
| [1] https://www.canada.ca/en/revenue-agency/programs/about-
| canad...
| superzamp wrote:
| Well that's definitely a good puzzle. I've tried to model it
| for a bit, but it indeed looks like we'd need to add something
| to the language to make it possible at all! Thanks for bringing
| this up.
| fallat wrote:
| Same thing with income tax brackets. You need conditional
| logic.
| superzamp wrote:
| For this particular case, I would say that tax-brackets
| sort of logic can be expressed in the destination block
| with ordered destinations.
|
| For example, you could have something like this:
| send [USD/2 *] ( source = @users:1234
| destination = { // first $1000 are taxed at 10%
| max [USD/2 100000] to { 10% to @taxes
| remaining kept } // Anything above
| that is, taxed at 20% remaining to {
| 20% to @taxes remaining kept }
| } )
|
| (You can test it on the playground, you'll just want to
| feed the "users:1234" account with an initial balance in
| the input section)
| euroderf wrote:
| The rules listed (1,2,6,7 round down; 3,4,8,9 round up). AFAIK
| these are also the official Eurozone cash rules for countries
| that choose not to circulate 1 and 2 eurocent coins. (Altho of
| course, electronic transactions are exact to the penny.) So you
| might want to cover this use case.
| o-o- wrote:
| So basically Math.round((x*20))/20?
| Silphendio wrote:
| Shouldn't it be `round(x/5)*5` ?
| shiandow wrote:
| Depends, are you working in cents or whole euros/dollars?
| falcor84 wrote:
| In all use-cases I encountered, working with integer
| cents is much cleaner than decimals
| wombatpm wrote:
| I'm assuming there are guidelines as to when this conversion
| happens and how often. Must make itemized invoices lots of fun.
| Specially when you have returns or cancellations
| abdullahkhalids wrote:
| This pretty much only happen when you buy something at
| checkout. Your printed bill says total comes to CAD 5.12, you
| pay CAD 5.10 in cash. If you do a return, they will return in
| cash as well, and pay you CAD 5.10, because of the above
| rules.
| jimbokun wrote:
| Are there converters to/from OFX for Numscript?
| superzamp wrote:
| Not as of today!
| OutOfHere wrote:
| Can this or Formance interact with credit card systems, checking
| accounts, and layer 2 crypto wallets? If not, how is the money
| even going to come in or out?
| henning wrote:
| Ah, what better input format than JSON, a poorly defined,
| ambiguous format that freely mixes integers and floating points
| and lacks supports for bigints and bigdecimals.
| darby_nine wrote:
| It's only ambiguous if you let it be. The rest is just
| implementation details.
| monero-xmr wrote:
| In cryptocurrency the decimals are often a range between 8 and
| 18 decimals, sometimes much larger. The solution is always to
| use strings, and have separate fields or data models that
| explain the precision. The amount of languages and libraries,
| for tradfi or anything, is so wide that actually trying to use
| something _other_ than strings for passing data between systems
| and applications would be self destructive
| bschmidt1 wrote:
| This is mindblowing. It's like the missing piece of blockchain
| that was needed for dev adoption. I can see it also being used
| for modern bank/payments apps including those in games and other
| simulated economies.
|
| Now let's see a "ContentScript" for posting content to ledgers :D
| send [Image "tacos.jpg", Text "taco 2sday!"] ( source =
| @bschmidt1 destination = @us-west-relay )
| gregwebs wrote:
| The CLI is only displaying a "check" command but I did figure out
| that there is a "run" command as well.
|
| go install github.com/formancehq/numscript@latest
| go: downloading github.com/formancehq/numscript v0.0.8
| go: downloading github.com/antlr4-go/antlr/v4 v4.13.1 go:
| downloading github.com/sourcegraph/jsonrpc2 v0.2.0 go:
| downloading golang.org/x/exp v0.0.0-20240707233637-46b078467d37
|
| numscript -h Numscript cli Usage:
| numscript [command] Available Commands:
| check Check a numscript file help Help
| about any command Flags: -h, --help
| help for numscript -v, --version version for
| numscript Use "numscript [command] --help" for more
| information about a command.
| ascandone wrote:
| Hello, I'm one of the Numscript devs. The Numscript CLI does
| have a `numscript run` command, which is hidden for now but
| will be released in the following days. It behaves in the same
| way as the playground, and you can take a look at it with
| `numscript run --help` command
| adius wrote:
| Nice! I tried to achieve a similar design with my plain text
| accounting tool Transity: https://github.com/ad-si/Transity
|
| But this seems to have more programming language like features if
| I understand correctly. What else is different?
| hum3hum3 wrote:
| You might like
| https://martin.kleppmann.com/2011/03/07/accounting-for-compu...
| which shows it as a directed graph.
| holloway wrote:
| Large sends seem to crash the playground with a JSON parse error.
| eg change the first example 'Simple send' to send
| `10000000000000000000` (`send [USD/2 10000000000000000000]`) and
| there's a crash
| superzamp wrote:
| Thanks for the heads up! While the Numscript backend itself
| uses big.Int, we're still using normal javascript numbers in
| the playground for now so that's where it's coming from. But we
| should definitely switch to BigInt in the playground code
| though and that would solve the issue.
| hum3hum3 wrote:
| You should never use floats for money. In python Decimal
| works well. TigerBeatle uses 128 bit accounts and amounts
| which I thought was interesting although more than needed gor
| many cases.
| neilwilson wrote:
| How do you model a bank making a loan, where the bank creates the
| money out of nothing and the accounting appears backwards?
|
| The equivalent of DR @my_bank:loans_made 10000, CR @my_bank:1234
| 10000
| superzamp wrote:
| Yeah that's a good question, you'll want to leverage the
| `overdraft` functionality for that, enabling the account end
| balance to go below zero.
|
| So you could do something like: send [USD/2
| 10000] ( source = @my_bank:loans_made allowing
| unbounded overdraft destination = @my_bank:1234
| )
|
| With the post-transaction balance of @my_bank:loans_made
| becoming [USD/2 -10000]. So that's for creating money out of
| nothing.
|
| There's a little bit more to it if you want to create
| accounting-perfect entries, but a simple way to map src/dest to
| cr/dr entries is to say that every credit becomes a
| destination, and every debit becomes a source.
|
| You can then consider debit normal accounts as having their
| debit balance being equivalent to the sum of entries where the
| account is source, their credit balance as the sum of entries
| where the account is destination--and do the opposite for
| credit normal accounts.
|
| We've written a bit more about it here [1].
|
| [1]
| https://docs.formance.com/ledger/advanced/accounting/credit-...
| throwaway81523 wrote:
| This is a pretty neat paper about a Haskell DSL for specifying
| financial contracts and calculating their values:
|
| https://www.microsoft.com/en-us/research/publication/composi...
|
| It is quite powerful and you might want to look at it for
| possible features to use.
| pjacotg wrote:
| Nice! I've worked with a few similar real world payoff
| languages. This paper discusses one of them:
| https://www.infoq.com/presentations/haskell-barclays/
___________________________________________________________________
(page generated 2024-09-20 23:01 UTC)