Skip to main content

Get started with Atto Commons

Use Commons when you want Atto inside your own application. It provides the protocol types and client libraries behind addresses, transactions, network monitoring, and wallet operations. You choose the modules your application needs.

Commons is available for TypeScript and JavaScript through npm, and for Java and Kotlin on the JVM. See Commons capabilities and supported languages to find the right starting point for your application.

For a ready-made agent connection, terminal interface, or workflow node, start with MCP, CLI, or N8N instead.

Start with exact amounts​

This first example runs locally. It does not create keys, connect to a node, or move funds.

Use Node.js 24 or newer for this example. Install Core in your JavaScript project:

npm install @attocash/commons-core@8.0.0

Save this as amount.mjs, then run node amount.mjs:

import {AttoAmount, AttoUnit} from '@attocash/commons-core';

const amount = AttoAmount.from(AttoUnit.ATTO, '0.0001');

console.log(amount.toString());                  // 100000 raw units
console.log(amount.toFormattedString(AttoUnit.ATTO)); // 0.0001 ATTO

The amount enters as a decimal string, not a JavaScript floating-point number. One ATTO is 1,000,000,000 raw units. Use Commons value types, decimal strings, or bigint when handling amounts and other large protocol integers.

You can also explore these conversions in Encoding & Values.

Choose your modules​

The packages are split by responsibility. Start with the smallest set that supports your application; a read-only integration does not need a wallet or signer.

NeedModule
Amounts, keys, addresses, blocks, serialization, validationcommons-core
Node operations and account/transaction monitorscommons-node
HTTP node client and network streamscommons-node-remote
Wallet operations and automatic receivingcommons-wallet
External signingcommons-signer-remote
CPU proof-of-workcommons-worker
Browser WebGPU/WebGL proof-of-workcommons-worker-web
JVM OpenCL proof-of-workcommons-worker-opencl
Remote proof-of-work servicecommons-worker-remote
Shared HTTP transportcommons-transport
Spring Boot integrationcommons-spring-boot-starter
Mock services and test utilitiescommons-test

Working in Java? The maintained Java client example walks through a wallet flow against local mock services, with its own setup instructions.

Kotlin/JVM, JavaScript, and Wasm support varies by module. Check the module README for its supported targets. JavaScript packages use the @attocash/ scope; Gradle dependencies use the cash.atto group. Prefer the individual packages over the deprecated @attocash/commons-js aggregate.

Connect an application​

For JavaScript node access, install Core, the node interfaces, and the remote client at matching versions:

npm install @attocash/commons-core@8.0.0 \
  @attocash/commons-node@8.0.0 \
  @attocash/commons-node-remote@8.0.0

Use the remote-client guide for connection setup and the Node API for endpoint contracts. The maintained JavaScript example shows a fuller wallet flow against mock services; it requires Node.js 24 or newer and a container runtime. Treat its generated keys as disposable demo material, not production wallet credentials.

Keep reads separate from writes. An account query needs a public address; publishing a transaction also needs a valid signed block and proof-of-work. Wallet and worker modules support that workflow, but your application still owns authorization, key storage, and payment limits.

Keep the protocol boundary intact​

  • Feed raw JSON strings to the relevant Commons fromJson method. Parsing large unquoted integers through JSON.parse() or response.json() can round them before Commons sees them.
  • Parsing a transaction is not cryptographic verification. Use its validate() or isValid() method when verification is required.
  • Cryptographic operations may return promises in JavaScript. Follow the generated declarations for your installed release rather than copying older synchronous examples.
  • Cancel subscriptions when their owner stops, and close clients when finished. Monitor consumers should persist and acknowledge progress deliberately.
  • Keep private keys out of logs, browser persistence, and agent prompts. Adding Commons does not provide the CLI/MCP approval policy automatically.

Continue building​

The local amount example above was checked with Commons Core 8.0.0. Keep related modules on matching releases and consult the release notes before upgrading across major versions.