@attocash/n8n-nodes-atto 0.4.1 → 0.4.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +122 -108
- package/dist/package.json +2 -2
- package/package.json +2 -2
package/README.md
CHANGED
|
@@ -1,145 +1,162 @@
|
|
|
1
|
-
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://raw.githubusercontent.com/attocash/integrations-n8n/main/docs/images/atto-n8n-banner.png" alt="Atto nodes for n8n: payments, accounts, receivables, and live network events" width="100%">
|
|
3
|
+
</p>
|
|
2
4
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
5
|
+
<p align="center">
|
|
6
|
+
<a href="https://www.npmjs.com/package/@attocash/n8n-nodes-atto"><img src="https://img.shields.io/npm/v/@attocash/n8n-nodes-atto.svg" alt="npm version"></a>
|
|
7
|
+
<a href="https://www.npmjs.com/package/@attocash/n8n-nodes-atto"><img src="https://img.shields.io/npm/dw/@attocash/n8n-nodes-atto.svg" alt="npm weekly downloads"></a>
|
|
8
|
+
<a href="https://github.com/attocash/integrations-n8n/actions/workflows/n8n-node-package.yml"><img src="https://github.com/attocash/integrations-n8n/actions/workflows/n8n-node-package.yml/badge.svg" alt="n8n Atto Node CI"></a>
|
|
9
|
+
<a href="./LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license"></a>
|
|
10
|
+
</p>
|
|
6
11
|
|
|
7
|
-
|
|
12
|
+
# Atto for n8n
|
|
8
13
|
|
|
9
|
-
|
|
14
|
+
Use Atto in n8n workflows. The package can derive wallet addresses, read network data, sign payments, receive funds, change representatives, and start workflows from live Atto events.
|
|
10
15
|
|
|
11
|
-
|
|
16
|
+
It includes two nodes:
|
|
12
17
|
|
|
13
|
-
|
|
18
|
+
- **Atto** runs wallet, account, receivable, transaction, account-entry, and representative operations.
|
|
19
|
+
- **Atto Trigger** listens to receivable, account, transaction, and account-entry streams.
|
|
14
20
|
|
|
15
|
-
|
|
16
|
-
@attocash/n8n-nodes-atto
|
|
17
|
-
```
|
|
18
|
-
|
|
19
|
-
Restart n8n if the nodes do not appear right away.
|
|
21
|
+
## Contents
|
|
20
22
|
|
|
21
|
-
|
|
23
|
+
- [Installation](#installation)
|
|
24
|
+
- [Quick start](#quick-start)
|
|
25
|
+
- [Credentials](#credentials)
|
|
26
|
+
- [Nodes](#nodes)
|
|
27
|
+
- [Example workflows](#example-workflows)
|
|
28
|
+
- [Security](#security)
|
|
29
|
+
- [Compatibility](#compatibility)
|
|
30
|
+
- [Development](#development)
|
|
31
|
+
- [How Commons is used](#how-commons-is-used)
|
|
32
|
+
- [Support](#support)
|
|
22
33
|
|
|
23
|
-
|
|
34
|
+
## Installation
|
|
24
35
|
|
|
25
|
-
-
|
|
26
|
-
- **Atto Trigger**: start workflows from receivables, account updates, transactions, or account entries.
|
|
36
|
+
### Self-hosted n8n
|
|
27
37
|
|
|
28
|
-
|
|
38
|
+
1. Open **Settings > Community Nodes**.
|
|
39
|
+
2. Select **Install**.
|
|
40
|
+
3. Enter `@attocash/n8n-nodes-atto`.
|
|
41
|
+
4. Confirm the community-node warning and install the package.
|
|
29
42
|
|
|
30
|
-
-
|
|
31
|
-
- Send a payment from the address derived from your credential.
|
|
32
|
-
- Build a ping/pong flow that receives an incoming amount and sends the same amount back.
|
|
33
|
-
- Watch an address for account entries or transaction updates.
|
|
43
|
+
Restart n8n if the nodes do not appear in the node picker. The [n8n community-node installation guide](https://docs.n8n.io/integrations/community-nodes/installation/) covers other self-hosted installation methods.
|
|
34
44
|
|
|
35
|
-
##
|
|
45
|
+
## Quick start
|
|
36
46
|
|
|
37
|
-
Create an **Atto API** credential
|
|
47
|
+
1. Create an **Atto API** credential.
|
|
48
|
+
2. Set the Node Base URL for the Atto HTTP API.
|
|
49
|
+
3. Add an **Atto** or **Atto Trigger** node to a workflow.
|
|
50
|
+
4. Choose a resource and operation, then run the node.
|
|
38
51
|
|
|
39
|
-
|
|
52
|
+
Read operations and triggers use the Node Base URL. Sending, receiving, and changing representatives also require the Worker Base URL and wallet material.
|
|
40
53
|
|
|
41
|
-
|
|
42
|
-
-
|
|
54
|
+
<p align="center">
|
|
55
|
+
<img src="https://raw.githubusercontent.com/attocash/integrations-n8n/main/docs/images/receivable-workflow.png" alt="An n8n workflow that receives an Atto receivable" width="900">
|
|
56
|
+
</p>
|
|
43
57
|
|
|
44
|
-
|
|
58
|
+
The example above starts when a receivable appears and passes it to **Receivable > Receive**. Import [`examples/incoming-to-receive.json`](./examples/incoming-to-receive.json) to use the same layout.
|
|
45
59
|
|
|
46
|
-
|
|
47
|
-
- **API Key Header**
|
|
48
|
-
- **API Key Prefix**
|
|
60
|
+
## Credentials
|
|
49
61
|
|
|
50
|
-
|
|
62
|
+
Create an **Atto API** credential in n8n.
|
|
51
63
|
|
|
52
|
-
|
|
53
|
-
|
|
54
|
-
|
|
64
|
+
| Field | When it is needed |
|
|
65
|
+
| --- | --- |
|
|
66
|
+
| Node Base URL | Network reads, transaction publication, and triggers |
|
|
67
|
+
| Worker Base URL | Send, receive, and representative-change operations |
|
|
68
|
+
| API Key, Header, and Prefix | Optional authentication for Node and Worker requests |
|
|
69
|
+
| Wallet Secret Type and Wallet Secret | Signing and filters that derive an address from credentials |
|
|
70
|
+
| Key Index | Mnemonic-derived addresses; defaults to `0` |
|
|
55
71
|
|
|
56
|
-
The
|
|
72
|
+
The wallet secret can be a 24-word Atto mnemonic or a compatible hex private key. n8n encrypts credential values at rest.
|
|
57
73
|
|
|
58
|
-
|
|
74
|
+
The credential test sends `GET /` to the Node Base URL. It does not send the wallet secret or call the Worker Base URL.
|
|
59
75
|
|
|
60
76
|
## Nodes
|
|
61
77
|
|
|
62
78
|
### Atto
|
|
63
79
|
|
|
64
|
-
|
|
80
|
+
| Resource | Operations | What it does |
|
|
81
|
+
| --- | --- | --- |
|
|
82
|
+
| Address | Derive | Derives an address and public key from a mnemonic or private key |
|
|
83
|
+
| Account | Get | Reads balance, representative, height, and frontier |
|
|
84
|
+
| Receivable | Get, Receive | Lists pending receivables or publishes a receive transaction |
|
|
85
|
+
| Transaction | Get, Send | Reads transaction streams or publishes a send transaction |
|
|
86
|
+
| Account Entry | Get | Fetches entries by hash or reads a bounded entry stream |
|
|
87
|
+
| Representative | Change | Publishes a representative-change transaction |
|
|
65
88
|
|
|
66
|
-
|
|
67
|
-
- **Account > Get**: read balance, representative, height, and frontier for an address.
|
|
68
|
-
- **Receivable > Get**: collect receivables for the credential-derived address or manual addresses.
|
|
69
|
-
- **Receivable > Receive**: receive the receivable from the incoming item.
|
|
70
|
-
- **Transaction > Get**: fetch by hash or collect a bounded transaction stream.
|
|
71
|
-
- **Transaction > Send**: send from the credential-derived address.
|
|
72
|
-
- **Account Entry > Get**: fetch by hash or collect a bounded account-entry stream.
|
|
73
|
-
- **Representative > Change**: change the representative for the credential-derived address.
|
|
89
|
+
Send and receive wait up to 60 seconds for publication by default. Stream reads stop when they reach **Max Items** or **Timeout**.
|
|
74
90
|
|
|
75
|
-
|
|
91
|
+
<p align="center">
|
|
92
|
+
<img src="https://raw.githubusercontent.com/attocash/integrations-n8n/main/docs/images/atto-node-operations.png" alt="The Atto node resource and operation controls in n8n" width="900">
|
|
93
|
+
</p>
|
|
76
94
|
|
|
77
95
|
### Atto Trigger
|
|
78
96
|
|
|
79
|
-
|
|
97
|
+
| Event | Filters |
|
|
98
|
+
| --- | --- |
|
|
99
|
+
| Receivable | Credential-derived address, manual addresses, and minimum amount |
|
|
100
|
+
| Account Update | Credential-derived address, manual addresses, or all accounts |
|
|
101
|
+
| Transaction | Hash, credential-derived address, manual addresses, or all transactions |
|
|
102
|
+
| Account Entry | Hash, credential-derived address, manual addresses, or all entries |
|
|
80
103
|
|
|
81
|
-
|
|
82
|
-
- **Account Update**: fires when account state changes.
|
|
83
|
-
- **Transaction**: watches by hash, address stream, or all supported transactions.
|
|
84
|
-
- **Account Entry**: watches by hash, address stream, or all supported account entries.
|
|
104
|
+
Triggers use Atto's NDJSON endpoints. When a stream closes or fails, the node reconnects with exponential backoff from 1 to 30 seconds. Receiving an event resets the delay.
|
|
85
105
|
|
|
86
|
-
|
|
106
|
+
## Example workflows
|
|
87
107
|
|
|
88
|
-
|
|
108
|
+
The [`examples`](./examples) directory contains importable workflows:
|
|
89
109
|
|
|
90
|
-
|
|
110
|
+
- [`send-transaction.json`](./examples/send-transaction.json) sends Atto from a manual trigger.
|
|
111
|
+
- [`incoming-to-receive.json`](./examples/incoming-to-receive.json) receives an incoming receivable.
|
|
112
|
+
- [`ping-pong-receivable.json`](./examples/ping-pong-receivable.json) receives a payment and sends the same raw amount back.
|
|
113
|
+
- [`receivable-trigger.json`](./examples/receivable-trigger.json) starts a workflow when a receivable appears.
|
|
91
114
|
|
|
92
|
-
|
|
93
|
-
- [`incoming-to-receive.json`](./examples/incoming-to-receive.json): receivable trigger piped into **Receivable > Receive**.
|
|
94
|
-
- [`ping-pong-receivable.json`](./examples/ping-pong-receivable.json): receive an incoming amount and send the same raw amount back to the sender.
|
|
95
|
-
- [`receivable-trigger.json`](./examples/receivable-trigger.json): trigger-only receivable watcher.
|
|
115
|
+
Attach your **Atto API** credential after importing a workflow. Replace placeholder addresses before running a transaction operation.
|
|
96
116
|
|
|
97
|
-
|
|
117
|
+
## Security
|
|
98
118
|
|
|
99
|
-
|
|
119
|
+
Store wallet material in n8n credentials when working with real funds. The node also accepts wallet material as password-type node parameters for local derivation and controlled testing, but your n8n instance may retain node parameters in workflow or execution records.
|
|
120
|
+
|
|
121
|
+
The node does not log or return wallet secrets, seeds, private keys, or API keys. Review n8n execution-data retention and access controls before using signing operations in production.
|
|
122
|
+
|
|
123
|
+
## Compatibility
|
|
124
|
+
|
|
125
|
+
| Component | Requirement |
|
|
126
|
+
| --- | --- |
|
|
127
|
+
| n8n node metadata | Nodes API v1 |
|
|
128
|
+
| Node.js runtime and development | 22.22.0 or newer |
|
|
129
|
+
| Package manager | npm |
|
|
130
|
+
| Container integration tests | Docker or a local Podman socket |
|
|
131
|
+
|
|
132
|
+
The Node.js requirement is checked when npm installs the package. The official current n8n container image uses a compatible runtime; custom installations must provide Node.js 22.22.0 or newer.
|
|
133
|
+
|
|
134
|
+
## Development
|
|
100
135
|
|
|
101
136
|
Install dependencies and run the checks:
|
|
102
137
|
|
|
103
138
|
```bash
|
|
104
|
-
npm
|
|
139
|
+
npm ci --ignore-scripts
|
|
105
140
|
npm run build
|
|
106
|
-
npm test
|
|
107
141
|
npm run lint
|
|
142
|
+
npm test
|
|
108
143
|
```
|
|
109
144
|
|
|
110
|
-
`npm test`
|
|
111
|
-
|
|
112
|
-
Dependencies ship prebuilt, so lifecycle scripts are disabled to avoid transitive package-manager guard scripts.
|
|
113
|
-
|
|
114
|
-
To require the mock-container integration path:
|
|
145
|
+
`npm test` runs the integration, smoke, trigger, and unit test files in sequence. The integration file records a skip when neither Docker nor a local Podman socket is available. Require the container path with:
|
|
115
146
|
|
|
116
147
|
```bash
|
|
117
148
|
ATTO_TEST_INTEGRATION=1 npm run test:integration
|
|
118
149
|
```
|
|
119
150
|
|
|
120
|
-
|
|
121
|
-
|
|
122
|
-
From this package directory:
|
|
151
|
+
Start the n8n development environment with:
|
|
123
152
|
|
|
124
153
|
```bash
|
|
125
|
-
npm run
|
|
126
|
-
mkdir -p /tmp/n8n-atto-local/.n8n/nodes/node_modules
|
|
127
|
-
podman run --rm -it \
|
|
128
|
-
--user 0 \
|
|
129
|
-
-p 5678:5678 \
|
|
130
|
-
-e N8N_USER_FOLDER=/home/node \
|
|
131
|
-
-e N8N_COMMUNITY_PACKAGES_ENABLED=true \
|
|
132
|
-
-e N8N_SECURE_COOKIE=false \
|
|
133
|
-
-v /tmp/n8n-atto-local:/home/node:Z \
|
|
134
|
-
-v "$PWD:/home/node/.n8n/nodes/node_modules/@attocash/n8n-nodes-atto:ro,Z" \
|
|
135
|
-
docker.io/n8nio/n8n:latest
|
|
154
|
+
npm run dev
|
|
136
155
|
```
|
|
137
156
|
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
### Install From A Checkout Inside n8n
|
|
157
|
+
### Install from a checkout
|
|
141
158
|
|
|
142
|
-
If you have shell access inside
|
|
159
|
+
If you have shell access inside an n8n container:
|
|
143
160
|
|
|
144
161
|
```bash
|
|
145
162
|
cd /tmp
|
|
@@ -148,35 +165,32 @@ cd integrations-n8n
|
|
|
148
165
|
npm run install:n8n
|
|
149
166
|
```
|
|
150
167
|
|
|
151
|
-
The installer builds, validates, packs, and installs the generated
|
|
168
|
+
The installer builds, validates, packs, and installs the generated tarball. It uses these locations in order:
|
|
152
169
|
|
|
153
|
-
|
|
170
|
+
1. `N8N_NODES_DIR`, when set.
|
|
171
|
+
2. `${N8N_USER_FOLDER}/.n8n/nodes`, when `N8N_USER_FOLDER` is set.
|
|
172
|
+
3. `${HOME}/.n8n/nodes`.
|
|
154
173
|
|
|
155
|
-
|
|
156
|
-
N8N_NODES_DIR=/path/to/nodes npm run install:n8n
|
|
157
|
-
RUN_TESTS=1 npm run install:n8n
|
|
158
|
-
```
|
|
159
|
-
|
|
160
|
-
Restart n8n after the script finishes.
|
|
174
|
+
Set `RUN_TESTS=1` to run the full test suite before installation. Restart n8n when the installer finishes.
|
|
161
175
|
|
|
162
|
-
|
|
176
|
+
See [CONTRIBUTING.md](./CONTRIBUTING.md) for the release process and maintainer setup.
|
|
163
177
|
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
```bash
|
|
167
|
-
git commit -m "fix(n8n-node): describe the fix"
|
|
168
|
-
```
|
|
178
|
+
## How Commons is used
|
|
169
179
|
|
|
170
|
-
|
|
180
|
+
Atto Commons supplies the protocol models, address derivation, block construction, hashing, and signing.
|
|
171
181
|
|
|
172
|
-
|
|
182
|
+
| Package | Role in this repository | Published package |
|
|
183
|
+
| --- | --- | --- |
|
|
184
|
+
| `@attocash/commons-core` | Runtime protocol implementation | Bundled into the built protocol adapter |
|
|
185
|
+
| `@attocash/commons-test` | Node and Worker mocks for integration tests | Not used or installed at runtime |
|
|
186
|
+
| `n8n-workflow` | n8n types and runtime APIs | Provided by n8n as a peer dependency |
|
|
173
187
|
|
|
174
|
-
|
|
188
|
+
Network requests go through n8n's HTTP helpers. The npm package has no production dependencies; Commons Core is bundled once so n8n does not need a separate Commons installation.
|
|
175
189
|
|
|
176
|
-
|
|
190
|
+
## Support
|
|
177
191
|
|
|
178
|
-
|
|
192
|
+
- Read the operation notes in [USAGE.md](./USAGE.md).
|
|
193
|
+
- Open a bug or feature request in [GitHub Issues](https://github.com/attocash/integrations-n8n/issues).
|
|
194
|
+
- See the [n8n community-node documentation](https://docs.n8n.io/integrations/community-nodes/).
|
|
179
195
|
|
|
180
|
-
|
|
181
|
-
- Commons Core is bundled once into the built protocol adapter, so the published n8n package has no runtime dependencies beyond n8n.
|
|
182
|
-
- Hex private keys must use the format accepted by `AttoPrivateKey.Companion.parse`.
|
|
196
|
+
This package is available under the [MIT License](./LICENSE).
|
package/dist/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@attocash/n8n-nodes-atto",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "Atto cryptocurrency wallet, transaction, account, and trigger nodes for n8n, powered by Atto Commons",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"keywords": [
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
"validate:release-tag": "node scripts/validate-release-tag.mjs"
|
|
57
57
|
},
|
|
58
58
|
"engines": {
|
|
59
|
-
"node": ">=22.
|
|
59
|
+
"node": ">=22.22.0"
|
|
60
60
|
},
|
|
61
61
|
"devDependencies": {
|
|
62
62
|
"@attocash/commons-core": "7.0.2",
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@attocash/n8n-nodes-atto",
|
|
3
|
-
"version": "0.4.
|
|
3
|
+
"version": "0.4.2",
|
|
4
4
|
"description": "Atto cryptocurrency wallet, transaction, account, and trigger nodes for n8n, powered by Atto Commons",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"keywords": [
|
|
@@ -56,7 +56,7 @@
|
|
|
56
56
|
"validate:release-tag": "node scripts/validate-release-tag.mjs"
|
|
57
57
|
},
|
|
58
58
|
"engines": {
|
|
59
|
-
"node": ">=22.
|
|
59
|
+
"node": ">=22.22.0"
|
|
60
60
|
},
|
|
61
61
|
"devDependencies": {
|
|
62
62
|
"@attocash/commons-core": "7.0.2",
|