reapp-protocol-cli 0.1.0

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.
Files changed (3) hide show
  1. package/README.md +141 -0
  2. package/dist/reapp-cli.bundle.mjs +4340 -0
  3. package/package.json +40 -0
package/README.md ADDED
@@ -0,0 +1,141 @@
1
+ # reapp-protocol-cli
2
+
3
+ Run the REAPP payment flow from a terminal: scaffold config, create testnet
4
+ accounts, authorize an AP2 mandate, and make agent-signed payments through the
5
+ live MandateRegistry contract on Stellar.
6
+
7
+ `reapp-protocol-cli` is the command-line entry point for REAPP, a protocol for
8
+ agent-driven payments where the spending limit lives inside a Soroban smart
9
+ contract instead of the application. The CLI is deliberately thin: it prepares
10
+ inputs, signs with the correct testnet key, and sends transactions, but the
11
+ contract is the source of truth for scope, budget, expiry, replay protection, and
12
+ settlement.
13
+
14
+ Testnet only. Keys generated by the CLI are throwaway testnet burners, stored
15
+ outside your repo, and must never be reused on mainnet.
16
+
17
+ Current npm package: `reapp-protocol-cli@0.1.0`. Installed command: `reapp`.
18
+
19
+ ## Install
20
+
21
+ ```
22
+ npx reapp-protocol-cli --help
23
+ ```
24
+
25
+ For repeated use, install the package globally. The installed command is
26
+ `reapp`.
27
+
28
+ ```
29
+ npm install -g reapp-protocol-cli
30
+ reapp --help
31
+ ```
32
+
33
+ ## Quick start
34
+
35
+ The fastest way to see the full flow is one command:
36
+
37
+ ```
38
+ npx reapp-protocol-cli demo research-agent
39
+ ```
40
+
41
+ The demo starts cold, creates three ephemeral testnet accounts, registers a real
42
+ mandate, approves the contract allowance, and has an agent buy research sources
43
+ one at a time. Each purchase is a real on-chain `execute_payment`. The mandate
44
+ budget covers three purchases; the fourth is rejected by the contract.
45
+
46
+ No LLM key is required. The research framing is scripted so the payment path is
47
+ the thing under test.
48
+
49
+ ## Project flow
50
+
51
+ Use the step-by-step commands when you want a reusable local project instead of
52
+ an ephemeral demo run.
53
+
54
+ ```
55
+ reapp init
56
+ reapp setup
57
+ reapp mandate create
58
+ reapp pay
59
+ reapp pay 10.00
60
+ ```
61
+
62
+ `reapp init` writes a committable `reapp.config.json` with the network, contract
63
+ id, explorer, demo price, and budget. `reapp setup` writes testnet burner secrets
64
+ to `~/.reapp/credentials.json` using restrictive file permissions. `reapp
65
+ mandate create` stores the active mandate in `~/.reapp/mandate.json` so `reapp
66
+ pay` can rebuild the same mandate id.
67
+
68
+ The final `reapp pay 10.00` is expected to fail after a default 3 XLM budget. The
69
+ CLI surfaces that contract rejection as `BudgetExceeded`; it does not simulate
70
+ the failure locally.
71
+
72
+ ## Commands
73
+
74
+ | Command | What it does |
75
+ |---|---|
76
+ | `reapp init [-f]` | Writes `reapp.config.json` in the current directory. |
77
+ | `reapp setup [-f]` | Generates user, agent, and merchant testnet keys, then funds them through friendbot. |
78
+ | `reapp mandate create [-b <xlm>] [-e <seconds>] [-f]` | Registers an AP2 mandate on-chain and approves the SEP-41 allowance to the contract. |
79
+ | `reapp pay [amount]` | Makes an agent-signed payment against the active mandate. |
80
+ | `reapp demo research-agent` | Runs the complete budget-capped research-agent flow on testnet. |
81
+
82
+ ## How it works
83
+
84
+ The flow has three accounts and one contract.
85
+
86
+ 1. The user owns the funds and authorizes the mandate.
87
+ 2. The agent can request payment, but only by calling the contract.
88
+ 3. The merchant is the single allowed payee.
89
+ 4. The MandateRegistry validates the payment and transfers funds atomically.
90
+
91
+ The allowance goes to the **contract**, never to the agent or the CLI. If the
92
+ agent key is compromised, if the CLI has a bug, or if a developer tries to skip a
93
+ step, the contract still refuses out-of-scope payments, expired mandates,
94
+ overspending, revoked mandates, invalid amounts, and replayed sequence numbers.
95
+
96
+ ## Files written by the CLI
97
+
98
+ | File | Safe to commit? | Purpose |
99
+ |---|---:|---|
100
+ | `reapp.config.json` | Yes | Network, contract id, explorer, demo price, and default budget. |
101
+ | `~/.reapp/credentials.json` | No | Testnet burner secrets for the user, agent, and merchant accounts. |
102
+ | `~/.reapp/mandate.json` | No | The active mandate inputs and transaction hashes for local reuse. |
103
+
104
+ Set `REAPP_HOME` to relocate the private CLI state:
105
+
106
+ ```
107
+ REAPP_HOME=/tmp/reapp-demo reapp setup
108
+ ```
109
+
110
+ ## Network
111
+
112
+ The CLI defaults to Stellar testnet and reads the live MandateRegistry id from
113
+ `@reapp-sdk/stellar`.
114
+
115
+ ```
116
+ reapp init
117
+ cat reapp.config.json
118
+ ```
119
+
120
+ The current config points at the composite MandateRegistry build:
121
+
122
+ ```
123
+ CBALARHTO5D7JLWHZ5KST4QNIRC64JI5H3DQDHMIUBSRLLOVS6FCWOQX
124
+ ```
125
+
126
+ You can edit `reapp.config.json` to point at a different compatible
127
+ MandateRegistry contract without changing the CLI.
128
+
129
+ ## Relationship to the SDK
130
+
131
+ `reapp-protocol-cli` ships as a self-contained command bundle built on
132
+ [`@reapp-sdk/core`](https://www.npmjs.com/package/@reapp-sdk/core) and
133
+ [`@reapp-sdk/stellar`](https://www.npmjs.com/package/@reapp-sdk/stellar). Use
134
+ the CLI when you want to prove the protocol path from a terminal. Use the SDK
135
+ packages when you are building the same flow into an app, agent, or service.
136
+
137
+ See the browser demo at [reapp.live/cli](https://reapp.live/cli).
138
+
139
+ ## License
140
+
141
+ Apache-2.0.