@artblocks/abx-cli 0.7.3 → 0.8.0

package/skill/reference/services.md

@@ -112,52 +112,44 @@ the API key or account. A creator can always opt out by setting their own `ABX_R
 
 ## Creator wallet and sponsorship
 
-An account with a verified email can use one persistent ABX creator wallet. The
-`ABX_SERVICES_API_KEY` identifies the account but cannot sign. `--sponsor` discovers the provider's
-`abx-creator-wallet/v1` endpoint and reuses the wallet created during login. `abx auth wallet`
-provisions or shows it explicitly when needed. The first sponsored command
-asks the human to match one code and approve a Privy agent grant. The CLI keeps the rotating grant in
-the operating system's credential store and reuses it for up to 30 days, unless the creator revokes
-it first. The request-signing key remains memory-only. A reused grant removes another browser step; it does
-not remove the dry run, transaction summary, or production confirmation.
-
-The approval is authority for the agent to use the creator wallet, not approval of one displayed
-transaction. Review each exact network and transaction plan in the terminal. The creator can inspect
-and revoke active grants at `https://services.abx.io/authorize`.
-
-Treat the live descriptor and account capabilities as the authority for sponsored networks. The
-public [network table](https://docs.abx.io/docs/reference/deployments) is the human-readable summary,
-but it does not guarantee sponsorship for an account or moment. When the creator has not selected
-another signer, prefer this lane for an eligible testnet operation. For production, prove the flow on
-the paired testnet and repeat the production warning before confirmation. Before using it:
-
-1. run `abx auth login` if the account has no API key;
-2. inspect `abx capabilities --json` and the command help;
-3. run the same command with `--dry-run --json`;
-4. summarize the network, creator-wallet address, transaction group, zero value, permanent choices,
-   and any experimental or beta status;
-5. repeat with `--sponsor`; if no usable grant exists, give the human the verified URL and code and
-   resume the same command after approval.
-
-The lane accepts zero-value calls and receipt-dependent staged content groups up to the live network
-and provider policy. ABX does not impose an additional per-transaction gas ceiling. Use
-`abx deploy-contract` for exact already-compiled creation bytecode; its sponsored path calls the
-keyless CREATE2 proxy because provider-backed raw creation is unsupported. The constructor therefore
-sees the proxy as `msg.sender`; use explicit constructor arguments for ownership. ABX does not
-compile or audit it. Never add retries around a sponsored write. An `unknown` outcome means the
-provider may have submitted it: preserve the operation ID and reconcile status before any new send.
-Use `abx auth operation <operation-id>` for that read-only reconciliation. If Services has confirmed
-an operation but a public RPC cannot return its receipt, the confirmation and transaction hash still
-stand; switch RPCs or inspect the hash, never replay the write.
-
-Sponsorship is optional service policy, not protocol support. `--send`, `--sign`, and `--unsigned`
-remain first-class bring-your-own alternatives. Honor an explicit choice of any of them. If the
-provider does not advertise the chain, the account is ineligible, or the transaction group exceeds
-policy, select one of those lanes rather than refusing the underlying operation. Do not use
-sponsorship on a production network unless the live descriptor, account capabilities, and command
-all explicitly support it. Never infer eligibility merely because the CLI recognizes the lane.
-During a network rollout, the descriptor may advertise a chain before every account is entitled.
-Check account capabilities too; a test-account grant does not establish general availability.
+An account with a verified email has one persistent creator wallet. Its API key cannot sign.
+`--embedded` discovers `abx-creator-wallet/v1` and reuses that wallet. `--sponsor` is a legacy alias
+for this same automatic lane. Use `abx auth wallet` to provision/show the address before a dry run.
+
+The default payment policy is automatic: when the provider advertises self-payment on the active
+network and the wallet can cover native transaction value plus quoted fees, it pays its own gas.
+Otherwise, eligible zero-value calls use sponsorship. Non-zero native value always requires enough
+funds for value plus fees. Balances belong to each network; never infer funding from another chain
+or from ERC-20 balances. Older providers retain sponsored-only behavior until they advertise self-payment.
+
+One Privy agent grant authorizes wallet use, including transfers and gas spending. The CLI stores
+its rotating grant in the OS credential store for up to 30 days unless revoked. Do not ask for a
+separate grant when payment changes, or another browser approval when a grant is reusable. Manage
+or revoke grants at `https://services.abx.io/authorize`. Review exact actions before sending; an agent
+grant is not a per-transaction human approval.
+
+Before sending, inspect live descriptor/account capabilities, run command help and a JSON dry run,
+and summarize the active chain, creator-wallet address, native value, transaction group, estimated
+fees and permanent choices. Honor an explicit bring-your-own signer choice. Repeat production risks
+and prove the same flow on the paired testnet before production.
+
+The CLI independently checks the service-returned payload against its local intent, including the
+wallet, chain, recipient, calldata, value, gas limit, payer and native fee ceilings. A mismatch must
+stop before signing. Fees on Base include estimated L1/operator charges in the funding reserve;
+these rollup fees can change. The chosen payer and fee bounds are shown before submission.
+
+Receipt-dependent staged content uses the same wallet serially, quoting each transaction before it
+is prepared. `deploy-contract` routes exact creation bytecode through the keyless CREATE2 proxy;
+pass ownership explicitly because the constructor caller is the proxy. ABX does not compile or audit it.
+
+Once prepared, payment mode and fee ceilings cannot change. Never retry an uncertain result or
+switch payers after submission. Preserve the operation ID and use `abx auth operation <operation-id>`
+for read-only reconciliation. A provider-confirmed transaction remains submitted even if another
+RPC cannot find its receipt; inspect the hash rather than replaying it.
+
+`--send`, `--sign`, and `--unsigned` remain first-class alternatives. Funding cannot bypass a disabled
+wallet, revoked authorization, unsupported network or provider policy. Sponsorship eligibility is
+separate from network/protocol support and wallet self-payment.
 
 ## Feedback targets
 

package/skill/reference/setup.md

@@ -136,17 +136,16 @@ Every write uses one of four lanes:
 
 | Lane | Select | Use when |
 |---|---|---|
-| Sponsored | `--sponsor` | The live remote advertises sponsorship for this chain and command |
+| Creator wallet | `--embedded` (alias `--sponsor`) | The live provider enables self-payment or sponsorship on this chain |
 | Hot | `--send` or default | An environment key may sign unattended |
 | Wallet | `--sign --for 0x…` | A human approves in their browser wallet |
 | Cold | `--unsigned --for 0x…` | A multisig/offline signer needs prepared transactions |
 
 Honor an explicit creator choice. Otherwise run `abx capabilities --json`, the command help, and
-`abx remote abx`. Prefer `--sponsor` when the provider advertises the active chain, the command and
-transaction group are eligible, and sponsorship is enabled—especially on a testnet, where it removes
-wallet and faucet setup. Sponsorship is provider policy, not protocol support: if it is unavailable,
-paused, or ineligible, fall back to the appropriate bring-your-own lane rather than treating the ABX
-operation as unsupported.
+`abx remote abx`. Prefer `--embedded` when the provider advertises the wallet on the active chain.
+It self-pays when native funds cover value plus quoted fees; otherwise eligible zero-value calls
+use sponsorship. Non-zero-value transactions need funds. Honor live wallet/payment capabilities;
+if unavailable, choose a bring-your-own lane. Never switch an explicitly chosen signer.
 
 Select the lane before the JSON dry run. The signer can affect ownership, salts, and predicted
 addresses. If the lane changes, rerun the dry run and summarize the revised plan before execution.
@@ -216,10 +215,9 @@ human confirmation authorizes execution.
 8. Run command help, then a JSON dry run.
 9. Confirm the plan and only then execute.
 
-For an eligible first-party account, `--sponsor` replaces local key and faucet setup with an
-account-bound creator wallet. The first use opens a Privy agent grant; later commands reuse that
-grant for up to 30 days, unless the creator revokes it first. Do not ask for another browser approval when the
-CLI resumes an existing grant. Use sponsorship only when the live descriptor and account
-capabilities advertise the active chain. Test the exact flow on the reported paired testnet before
-production. Read [services.md](services.md) before using it. Sponsorship is zero-value and never a
-reason to skip the dry run or transaction summary.
+For an eligible first-party account, `--embedded` uses the account-bound wallet without a local key.
+One reusable agent grant covers both native self-payment and sponsorship. Do not request another
+grant when the payer changes. The provider must advertise the network/payment capabilities; fund
+the same address on the active chain when self-payment is needed. Read [services.md](services.md),
+prove the paired testnet flow and review the dry run before sending. Only sponsored calls must
+have zero native value; self-paid calls may carry value when the wallet covers value plus fees.