@certen.io/cli 0.5.0 → 0.7.1

package/dist/payment-uri.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Turning a payment target into something a wallet can consume, and a wait into something a person
+ * can plan around.
+ *
+ * Funding asked someone to carry four values from a terminal into a wallet by hand: a token
+ * contract, a chain, a treasury address and an exact amount. **A mistyped recipient is the one
+ * error in this product that loses real money and cannot be reversed** — no retry, no support
+ * ticket, no proof to appeal to.
+ *
+ * Isolated in its own module because both functions here are pure arithmetic over values the
+ * gateway supplied, and both are wrong in ways that are invisible on screen: an off-by-one decimal
+ * looks like a plausible number, and a wait estimate that is silently zero looks like a fast chain.
+ */
+/**
+ * What the gateway sends back when a payment is opened. Only the fields a URI needs.
+ *
+ * Deliberately structural rather than importing the SDK type: this module must be callable with
+ * exactly the gateway's own values and nothing reformatted on the way in.
+ */
+export interface PaymentTargetFields {
+    chain_id: number;
+    token_address: string;
+    token_decimals: number;
+    deposit_address: string;
+}
+/**
+ * Convert a decimal amount string into the token's smallest unit, exactly.
+ *
+ * String arithmetic, not `Number(amount) * 10 ** decimals`. That expression is wrong for values
+ * this function will certainly see: `25.10 * 1e6` is `25099999.999999996` in IEEE-754, which
+ * truncates to 25099999 — a payment one unit short of the amount attribution matches on, so the
+ * deposit is received and never credited. The failure is silent on both sides.
+ *
+ * Throws rather than rounding when the amount carries more precision than the token can express.
+ * Quietly dropping a digit would change what the user pays.
+ */
+export declare function toSmallestUnit(amount: string, decimals: number): string;
+/**
+ * Build an EIP-681 payment request for an ERC-20 transfer.
+ *
+ * `ethereum:<token>@<chainId>/transfer?address=<recipient>&uint256=<amount>`
+ *
+ * The shape is counter-intuitive and worth stating: the address BEFORE the `@` is the **token
+ * contract**, and the recipient is the `address` parameter. Reversing them produces a URI that a
+ * wallet will happily open and that transfers nothing — or, worse, calls an unknown method on the
+ * treasury address.
+ *
+ * Every value comes from the gateway's response untouched. Nothing here re-derives a chain id from
+ * a slug or re-formats an address, because that is precisely the transcription this exists to
+ * eliminate.
+ */
+export declare function buildPaymentUri(target: PaymentTargetFields, amountUsd: string): string;
+export interface WaitEstimate {
+    seconds: number;
+    /** Rendered for a person: `about 24 seconds`, `about 2 minutes`. */
+    text: string;
+    /** The chain whose cadence produced this, so the estimate is checkable rather than magic. */
+    basis: string;
+}
+/**
+ * How long `min_confirmations` is likely to take on this chain.
+ *
+ * Returns null for a chain with no known cadence rather than guessing. A wrong estimate on the
+ * command someone is already waiting on is worse than no estimate: it is the number they decide to
+ * interrupt against, and interrupting a funding flow is how people send twice.
+ */
+export declare function estimateWait(chain: string, confirmations: number): WaitEstimate | null;
+/** `95` -> `about 2 minutes`. Coarse by design: false precision reads as a promise. */
+export declare function humanDuration(totalSeconds: number): string;
+/**
+ * `252` -> `4m 12s`. Exact, unlike `humanDuration`.
+ *
+ * Used for a quote's remaining validity, where the caller is deciding whether to act NOW and a
+ * rounded "about 4 minutes" on a quote with 20 seconds left would be actively misleading.
+ */
+export declare function preciseDuration(totalSeconds: number): string;

package/dist/payment-uri.js

@@ -0,0 +1,135 @@
+/**
+ * Turning a payment target into something a wallet can consume, and a wait into something a person
+ * can plan around.
+ *
+ * Funding asked someone to carry four values from a terminal into a wallet by hand: a token
+ * contract, a chain, a treasury address and an exact amount. **A mistyped recipient is the one
+ * error in this product that loses real money and cannot be reversed** — no retry, no support
+ * ticket, no proof to appeal to.
+ *
+ * Isolated in its own module because both functions here are pure arithmetic over values the
+ * gateway supplied, and both are wrong in ways that are invisible on screen: an off-by-one decimal
+ * looks like a plausible number, and a wait estimate that is silently zero looks like a fast chain.
+ */
+/**
+ * Convert a decimal amount string into the token's smallest unit, exactly.
+ *
+ * String arithmetic, not `Number(amount) * 10 ** decimals`. That expression is wrong for values
+ * this function will certainly see: `25.10 * 1e6` is `25099999.999999996` in IEEE-754, which
+ * truncates to 25099999 — a payment one unit short of the amount attribution matches on, so the
+ * deposit is received and never credited. The failure is silent on both sides.
+ *
+ * Throws rather than rounding when the amount carries more precision than the token can express.
+ * Quietly dropping a digit would change what the user pays.
+ */
+export function toSmallestUnit(amount, decimals) {
+    const clean = String(amount).trim();
+    if (!/^\d+(\.\d+)?$/.test(clean)) {
+        throw new Error(`"${amount}" is not a positive decimal amount.`);
+    }
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+        throw new Error(`${decimals} is not a usable token decimal count.`);
+    }
+    const [whole, fraction = ''] = clean.split('.');
+    if (fraction.length > decimals) {
+        // Only ever raised by trailing zeros beyond the token's precision, which are safe to drop —
+        // anything else would silently alter the amount.
+        const significant = fraction.slice(decimals).replace(/0+$/, '');
+        if (significant.length > 0) {
+            throw new Error(`${amount} has more precision than this token supports (${decimals} decimals). `
+                + 'Rounding it would change what you pay.');
+        }
+    }
+    const padded = (fraction + '0'.repeat(decimals)).slice(0, decimals);
+    // BigInt, so a large amount cannot lose its low digits the way a float would.
+    const units = BigInt(whole) * 10n ** BigInt(decimals) + BigInt(padded || '0');
+    return units.toString();
+}
+/**
+ * Build an EIP-681 payment request for an ERC-20 transfer.
+ *
+ * `ethereum:<token>@<chainId>/transfer?address=<recipient>&uint256=<amount>`
+ *
+ * The shape is counter-intuitive and worth stating: the address BEFORE the `@` is the **token
+ * contract**, and the recipient is the `address` parameter. Reversing them produces a URI that a
+ * wallet will happily open and that transfers nothing — or, worse, calls an unknown method on the
+ * treasury address.
+ *
+ * Every value comes from the gateway's response untouched. Nothing here re-derives a chain id from
+ * a slug or re-formats an address, because that is precisely the transcription this exists to
+ * eliminate.
+ */
+export function buildPaymentUri(target, amountUsd) {
+    for (const [name, value] of Object.entries({
+        token_address: target.token_address,
+        deposit_address: target.deposit_address,
+    })) {
+        if (!/^0x[0-9a-fA-F]{40}$/.test(String(value ?? ''))) {
+            throw new Error(`${name} is not an address: ${String(value)}`);
+        }
+    }
+    if (!Number.isInteger(target.chain_id) || target.chain_id <= 0) {
+        throw new Error(`chain_id is not a numeric EVM chain id: ${String(target.chain_id)}`);
+    }
+    const units = toSmallestUnit(amountUsd, target.token_decimals);
+    return `ethereum:${target.token_address}@${target.chain_id}`
+        + `/transfer?address=${target.deposit_address}&uint256=${units}`;
+}
+/**
+ * Seconds per block, for turning a confirmation count into a wait somebody can plan around.
+ *
+ * Approximate on purpose, and every caller must present the result as an estimate. These are the
+ * observed cadences of the testnets this CLI targets; an L2 that batches will occasionally be much
+ * faster or much slower than its nominal block time.
+ */
+const BLOCK_SECONDS = {
+    'ethereum-sepolia': 12,
+    'base-sepolia': 2,
+    'arbitrum-sepolia': 0.25,
+};
+/**
+ * How long `min_confirmations` is likely to take on this chain.
+ *
+ * Returns null for a chain with no known cadence rather than guessing. A wrong estimate on the
+ * command someone is already waiting on is worse than no estimate: it is the number they decide to
+ * interrupt against, and interrupting a funding flow is how people send twice.
+ */
+export function estimateWait(chain, confirmations) {
+    const perBlock = BLOCK_SECONDS[chain];
+    if (perBlock === undefined)
+        return null;
+    if (!Number.isFinite(confirmations) || confirmations <= 0)
+        return null;
+    const seconds = Math.max(1, Math.round(perBlock * confirmations));
+    return { seconds, text: humanDuration(seconds), basis: chain };
+}
+/** `95` -> `about 2 minutes`. Coarse by design: false precision reads as a promise. */
+export function humanDuration(totalSeconds) {
+    const s = Math.max(0, Math.round(totalSeconds));
+    if (s < 60)
+        return `about ${s} second${s === 1 ? '' : 's'}`;
+    const minutes = Math.round(s / 60);
+    if (minutes < 60)
+        return `about ${minutes} minute${minutes === 1 ? '' : 's'}`;
+    const hours = Math.round(minutes / 60);
+    return `about ${hours} hour${hours === 1 ? '' : 's'}`;
+}
+/**
+ * `252` -> `4m 12s`. Exact, unlike `humanDuration`.
+ *
+ * Used for a quote's remaining validity, where the caller is deciding whether to act NOW and a
+ * rounded "about 4 minutes" on a quote with 20 seconds left would be actively misleading.
+ */
+export function preciseDuration(totalSeconds) {
+    const s = Math.max(0, Math.floor(totalSeconds));
+    if (s < 60)
+        return `${s}s`;
+    const minutes = Math.floor(s / 60);
+    const rest = s % 60;
+    if (minutes < 60)
+        return rest === 0 ? `${minutes}m` : `${minutes}m ${rest}s`;
+    const hours = Math.floor(minutes / 60);
+    const mins = minutes % 60;
+    return mins === 0 ? `${hours}h` : `${hours}h ${mins}m`;
+}
+//# sourceMappingURL=payment-uri.js.map

package/dist/payment-uri.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-uri.js","sourceRoot":"","sources":["../src/payment-uri.ts"],"names":[],"mappings":"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"}

package/dist/signer.js

@@ -1,5 +1,6 @@
 import { getKeyInfo, signHash } from './keystore.js';
 import { resolvePassphrase } from './passphrase.js';
+import { UsageError } from './errors.js';
 export async function resolveSigner(name) {
     const info = getKeyInfo(name);
     const passphrase = await resolvePassphrase(info.encrypted, name);
@@ -18,18 +19,20 @@ export async function resolveSigner(name) {
  * another. `--sign-with` is the convenience path, not the replacement.
  */
 export async function resolveSignature(opts) {
+    // These are wrong invocations and must exit 2, not 1. As bare Errors they were indistinguishable
+    // from a rejected request, which is the exact confusion the exit-code taxonomy exists to prevent.
     if (opts.signWith) {
         if (opts.signature) {
-            throw new Error('Pass either --sign-with or --signature, not both.');
+            throw new UsageError('Pass either --sign-with or --signature, not both.', 'CONFLICTING_SIGNING_FLAGS');
         }
         if (!opts.hash) {
-            throw new Error('--sign-with needs the hash to sign; this command did not supply one.');
+            throw new UsageError('--sign-with needs the hash to sign; this command did not supply one. Pass --hash <hex>.', 'MISSING_HASH');
         }
         const signer = await resolveSigner(opts.signWith);
         return { signature: signer.sign(opts.hash), publicKey: signer.publicKey };
     }
     if (!opts.signature || !opts.publicKey) {
-        throw new Error('Provide --sign-with <key>, or both --signature <hex> and --public-key <hex>.');
+        throw new UsageError('Provide --sign-with <key>, or both --signature <hex> and --public-key <hex>.', 'MISSING_SIGNATURE');
     }
     return { signature: opts.signature, publicKey: opts.publicKey };
 }

package/dist/signer.js.map

@@ -1 +1 @@
-{"version":3,"file":"signer.js","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAgBpD,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,IAAI,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAKtC;IACC,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,KAAK,CAAC,sEAAsE,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClD,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC5E,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACvC,MAAM,IAAI,KAAK,CAAC,8EAA8E,CAAC,CAAC;IAClG,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;AAClE,CAAC"}
+{"version":3,"file":"signer.js","sourceRoot":"","sources":["../src/signer.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACpD,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAgBzC,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAY;IAC9C,MAAM,IAAI,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC;IAC9B,MAAM,UAAU,GAAG,MAAM,iBAAiB,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IACjE,OAAO;QACL,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,aAAa,EAAE,IAAI,CAAC,aAAa;QACjC,IAAI,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,CAAC;KAC/D,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAKtC;IACC,iGAAiG;IACjG,kGAAkG;IAClG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;QAClB,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,IAAI,UAAU,CAAC,mDAAmD,EAAE,2BAA2B,CAAC,CAAC;QACzG,CAAC;QACD,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;YACf,MAAM,IAAI,UAAU,CAClB,yFAAyF,EACzF,cAAc,CACf,CAAC;QACJ,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAClD,OAAO,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,CAAC;IAC5E,CAAC;IAED,IAAI,CAAC,IAAI,CAAC,SAAS,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,CAAC;QACvC,MAAM,IAAI,UAAU,CAClB,8EAA8E,EAC9E,mBAAmB,CACpB,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;AAClE,CAAC"}

package/dist/solidity-args.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Parse a Solidity function signature and check arguments against it.
+ *
+ * This exists so a wrong argument fails HERE, naming the flag the user typed, rather than
+ * travelling to the proof service and coming back as a decoding failure with no visible
+ * connection to `--arg`. The check is deliberately shallow — it validates the shapes a human
+ * gets wrong at the command line (an address that is not 20 bytes, a bytes32 that is 31, a
+ * negative uint, a malformed bool) and does not attempt to be an ABI encoder. Encoding is the
+ * gateway's job and duplicating it here would be a second implementation to keep in sync.
+ */
+export interface ParsedSignature {
+    name: string;
+    types: string[];
+}
+/**
+ * `confirm(bytes32)` → `{ name: 'confirm', types: ['bytes32'] }`.
+ *
+ * Nested tuples are rejected rather than half-supported: `--arg` is a flat list of strings, so a
+ * tuple has no unambiguous spelling at the command line. Someone who needs one should build the
+ * intent JSON and pass `--intent`, and saying so is more useful than accepting a value that will
+ * be encoded wrongly.
+ */
+export declare function parseSignature(signature: string): ParsedSignature;
+/**
+ * Check that the supplied `--arg` values match the signature, and return them.
+ *
+ * Values are returned as the strings they arrived as. Converting `uint256` to a JS number here
+ * would silently lose precision past 2^53 — the exact bug the rest of this codebase takes care to
+ * avoid by keeping amounts as strings.
+ */
+export declare function checkArgs(signature: ParsedSignature, args: string[]): string[];

package/dist/solidity-args.js

@@ -0,0 +1,111 @@
+import { UsageError } from './errors.js';
+/**
+ * `confirm(bytes32)` → `{ name: 'confirm', types: ['bytes32'] }`.
+ *
+ * Nested tuples are rejected rather than half-supported: `--arg` is a flat list of strings, so a
+ * tuple has no unambiguous spelling at the command line. Someone who needs one should build the
+ * intent JSON and pass `--intent`, and saying so is more useful than accepting a value that will
+ * be encoded wrongly.
+ */
+export function parseSignature(signature) {
+    const trimmed = signature.trim();
+    const match = trimmed.match(/^([A-Za-z_$][A-Za-z0-9_$]*)\s*\((.*)\)$/s);
+    if (!match) {
+        throw new UsageError(`"${signature}" is not a Solidity function signature. `
+            + 'Write it as name(type,type) — for example: confirm(bytes32) or transfer(address,uint256)', 'INVALID_FUNCTION_SIGNATURE');
+    }
+    const [, name, rawTypes] = match;
+    const inner = rawTypes.trim();
+    if (inner.includes('(')) {
+        throw new UsageError('Tuple arguments cannot be expressed with --arg. Build the intent as JSON and pass '
+            + '--intent @file.json instead.', 'TUPLE_NOT_SUPPORTED');
+    }
+    // Split WITHOUT filtering, so an empty entry survives to be reported. Filtering first — which
+    // this did — silently swallowed `transfer(address,)` into a one-parameter signature, which is
+    // exactly the shift-every-argument-by-one bug the check below exists to prevent.
+    const types = inner.length === 0 ? [] : inner.split(',').map((t) => t.trim());
+    // `transfer(address, )` and friends: a stray comma means the caller thinks there is a parameter
+    // there, and silently dropping it would shift every later argument by one position.
+    if (types.some((t) => t.length === 0)) {
+        throw new UsageError(`"${signature}" has an empty parameter. Remove the stray comma.`, 'INVALID_FUNCTION_SIGNATURE');
+    }
+    return { name, types };
+}
+const ADDRESS = /^0x[0-9a-fA-F]{40}$/;
+const HEX = /^0x[0-9a-fA-F]*$/;
+function checkOne(type, value, position) {
+    const where = `argument ${position + 1} (${type})`;
+    // Arrays: the element type is checked, the bracket syntax is not further interpreted. A
+    // comma-separated list is the only spelling available at the command line.
+    if (type.endsWith('[]')) {
+        const element = type.slice(0, -2);
+        for (const [i, item] of value.split(',').entries()) {
+            checkOne(element, item.trim(), position + i);
+        }
+        return;
+    }
+    if (type === 'address') {
+        if (!ADDRESS.test(value)) {
+            throw new UsageError(`${where}: "${value}" is not an address. Expected 0x followed by 40 hex characters.`, 'INVALID_ARGUMENT');
+        }
+        return;
+    }
+    if (type === 'bool') {
+        if (!['true', 'false'].includes(value)) {
+            throw new UsageError(`${where}: "${value}" is not a bool. Use true or false.`, 'INVALID_ARGUMENT');
+        }
+        return;
+    }
+    const bytesN = type.match(/^bytes(\d+)$/);
+    if (bytesN) {
+        const want = Number(bytesN[1]) * 2;
+        if (!HEX.test(value) || value.length - 2 !== want) {
+            throw new UsageError(`${where}: expected 0x followed by ${want} hex characters (${bytesN[1]} bytes), `
+                + `got ${Math.max(0, value.length - 2)}.`, 'INVALID_ARGUMENT');
+        }
+        return;
+    }
+    if (type === 'bytes') {
+        if (!HEX.test(value) || value.length % 2 !== 0) {
+            throw new UsageError(`${where}: expected 0x followed by an even number of hex characters.`, 'INVALID_ARGUMENT');
+        }
+        return;
+    }
+    const intType = type.match(/^(u?)int(\d*)$/);
+    if (intType) {
+        const unsigned = intType[1] === 'u';
+        // Decimal only. A hex integer at the command line is far more often a mistyped bytes32 than a
+        // deliberate choice, and BigInt would happily accept it.
+        if (!/^-?\d+$/.test(value)) {
+            throw new UsageError(`${where}: "${value}" is not a whole number. Pass it in base units, as digits.`, 'INVALID_ARGUMENT');
+        }
+        if (unsigned && value.startsWith('-')) {
+            throw new UsageError(`${where}: ${type} cannot be negative.`, 'INVALID_ARGUMENT');
+        }
+        const bits = intType[2] ? Number(intType[2]) : 256;
+        const limit = unsigned ? 2n ** BigInt(bits) - 1n : 2n ** BigInt(bits - 1) - 1n;
+        if (BigInt(value) > limit) {
+            throw new UsageError(`${where}: ${value} does not fit in ${type}.`, 'INVALID_ARGUMENT');
+        }
+        return;
+    }
+    // `string` and anything this function does not model are passed through. Rejecting an unknown
+    // type would make the CLI the thing that limits which contracts can be called, which is a much
+    // worse failure than letting the gateway decode it.
+}
+/**
+ * Check that the supplied `--arg` values match the signature, and return them.
+ *
+ * Values are returned as the strings they arrived as. Converting `uint256` to a JS number here
+ * would silently lose precision past 2^53 — the exact bug the rest of this codebase takes care to
+ * avoid by keeping amounts as strings.
+ */
+export function checkArgs(signature, args) {
+    if (args.length !== signature.types.length) {
+        throw new UsageError(`${signature.name}(${signature.types.join(',')}) takes ${signature.types.length} argument(s), `
+            + `but ${args.length} --arg value(s) were given.`, 'ARGUMENT_COUNT_MISMATCH');
+    }
+    signature.types.forEach((type, i) => checkOne(type, args[i], i));
+    return args;
+}
+//# sourceMappingURL=solidity-args.js.map

package/dist/solidity-args.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solidity-args.js","sourceRoot":"","sources":["../src/solidity-args.ts"],"names":[],"mappings":"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"}

package/dist/wait.d.ts

@@ -0,0 +1,79 @@
+import type { CertenClient, Identity } from '@certen.io/sdk';
+/**
+ * Waiting for asynchronous work to finish.
+ *
+ * Two of this product's central operations return before they are usable — `POST /v1/identity`
+ * answers 202 while provisioning continues, and a transaction intent takes a 60–110 second proof
+ * cycle to reach a terminal state. Every document in the repo warns about both. The CLI
+ * nonetheless printed the interim response and exited, leaving each user to write the same poll
+ * loop, and leaving anyone who did not write one holding an identity that fails at the last step
+ * of every flow with an error that never mentions provisioning.
+ *
+ * The polling shape here is lifted from `certen fund`, which got it right first: speak only when
+ * something changes, treat a timeout as neither success nor failure, and never exit 0 on an
+ * outcome a script would misread as done.
+ */
+/** `certen fund`'s defaults are 60 min / 5 s; these are per-operation because the work differs. */
+export declare const IDENTITY_WAIT: {
+    timeoutMin: number;
+    intervalSec: number;
+};
+/**
+ * A proof cycle is 60–110 seconds of real validator work and `execute.wait()` budgets 360s. Seven
+ * minutes leaves room for a queue without being an unbounded hang. Do NOT shorten this to make a
+ * test faster — it is not a tunable delay.
+ */
+export declare const TX_WAIT: {
+    timeoutMin: number;
+    intervalSec: number;
+};
+/**
+ * Should this invocation wait?
+ *
+ * Human mode waits by default, because "it is not ready yet" is an implementation detail nobody
+ * asked to manage. JSON mode does NOT, because scripts already written against the old
+ * fire-and-forget behaviour must not silently start blocking for minutes. Either default is
+ * overridden by saying so explicitly.
+ *
+ * Read from `process.argv` rather than commander's parsed value: declaring `--no-wait` makes
+ * commander default `opts.wait` to true, which erases the distinction between "defaulted" and
+ * "asked for" — and that distinction is the whole rule.
+ */
+export declare function resolveWait(argv?: string[]): boolean;
+export interface WaitBudget {
+    timeoutMs: number;
+    intervalMs: number;
+}
+/**
+ * Validate `--timeout` and `--poll-interval` BEFORE any network call.
+ *
+ * Checking after would mean a typo'd timeout had already opened an intent that the user then has
+ * to wait out or abandon — the same reasoning `certen fund` applies to its own options.
+ */
+export declare function parseWaitBudget(timeout: string | undefined, pollInterval: string | undefined, defaults: {
+    timeoutMin: number;
+    intervalSec: number;
+}): WaitBudget;
+/**
+ * Poll an identity until it is genuinely usable.
+ *
+ * "Usable" is `status` terminal AND `can_sign === true`, and those are two separate conditions
+ * that fail for different reasons:
+ *
+ * - `can_sign === false` — provisioning finished but the key on the on-chain key page is not
+ *   yours. The identity exists, consumes quota, and can never sign.
+ * - `can_sign === null` — the key page could not be READ. That is unknown, not a soft yes; an
+ *   Accumulate outage is exactly when this distinction matters most. Reporting it as ready would
+ *   be the one wrong answer, so this keeps polling and, if the budget runs out, says plainly that
+ *   it could not determine the answer.
+ */
+export declare function waitForIdentity(client: CertenClient, id: string, budget: WaitBudget): Promise<Identity>;
+/**
+ * Poll a transaction intent to a terminal state.
+ *
+ * Delegates to the SDK's `execute.wait()` rather than re-implementing the loop, so the CLI and an
+ * SDK caller agree on which statuses are terminal. The SDK signals both failure and timeout by
+ * throwing a plain `Error`; those are translated here into typed CLI errors so the exit code and
+ * the `--json` envelope carry a code a caller can branch on.
+ */
+export declare function waitForTransaction(client: CertenClient, intentId: string, budget: WaitBudget): Promise<Record<string, unknown>>;