@v3finance/core-sdk 0.2.1 → 0.2.3

package/src/resources/approvals.ts

@@ -79,6 +79,28 @@ export class ApprovalsResource {
    *
    * Read `finalized` with `applyError`: a vote can finalize a request AND
    * fail to apply it, and then the money has not moved.
+   *
+   * On a transfer request the approve that completes the threshold EXECUTES
+   * the transfer inside this call, and `status` is `APPROVED` whatever
+   * happened to the transfer:
+   *
+   *   finalized, no applyError     — executed by this call;
+   *   applyError                   — `TRANSFER_EXECUTION_FAILED`, not executed
+   *                                  (usually `failed`, reserve returned);
+   *   not finalized, no applyError — the outcome is NOT established by this
+   *                                  answer: the signing service gave no
+   *                                  definite answer (the transaction may
+   *                                  have left; an administrator's
+   *                                  reconciliation settles it), another call
+   *                                  is executing the transfer, or the
+   *                                  execution broke off. Read the outcome
+   *                                  from the transfer (`transfers.get`), and
+   *                                  never resubmit it.
+   *
+   * Repeating the same decision on a request that is still open finishes what
+   * an earlier call left undone (it recorded the vote and broke off) — a veto,
+   * or an approval once the threshold is met — instead of 409
+   * `ALREADY_VOTED`.
    */
   vote(requestId: string, input: VoteBody): Promise<RequestVoteResult> {
     return this.#http.request<RequestVoteResult>(

package/src/resources/transfers.ts

@@ -21,7 +21,10 @@ export interface VoteInput {
  * The result of sending is `Gated`, and that is the main thing to understand
  * here. The same `{transaction}` body comes back in three situations:
  *
- *   applied (201)  — executed, the money left;
+ *   applied (201)  — executed, the money left (rarely the status is still
+ *                    `pending` with a `txHash`: it went out, but its
+ *                    accounting was not recorded, and an administrator's
+ *                    reconciliation finishes it — do not send it again);
  *   pending (202)  — awaiting signatures, funds RESERVED but not sent;
  *   replayed (200) — a transfer with this `idempotencyKey` already existed,
  *                    and this is that transfer as it stands NOW.
@@ -34,7 +37,10 @@ export interface VoteInput {
  *
  *   confirmed, submitted     — it left;
  *   awaiting_approval        — waiting for signatures, funds reserved;
- *   pending                  — still executing;
+ *   pending                  — still executing, or its outcome is unknown
+ *                              (the first answer was 502
+ *                              `TRANSFER_OUTCOME_UNKNOWN`) until an
+ *                              administrator reconciles it;
  *   failed, rejected,
  *   cancelled                — it did not leave.
  */
@@ -53,6 +59,12 @@ export class TransfersResource {
    * On `outcome: 'replayed'` read `data.transaction.status` before telling
    * anyone anything — a replay of an attempt that failed, or that is still
    * waiting for signatures, comes back the same way as one that went out.
+   *
+   * A thrown 502 `TRANSFER_OUTCOME_UNKNOWN` is not a failure: the signing
+   * service gave no definite answer, the transaction may have left, and the
+   * transfer stays `pending` with its funds reserved (`details.transactionId`).
+   * Retry it only with the SAME key — that returns the transfer without
+   * executing it again; a new key can send the money twice.
    */
   async send(
     input: CreateTransferBody,
@@ -72,7 +84,9 @@ export class TransfersResource {
   /**
    * One transfer in full. Note the shape: this is the transaction itself, not
    * the `{ transaction }` wrapper that `send()` returns — and it carries more,
-   * including `amlLevel`, `approvers`, `usdRate` and `failureReason`.
+   * including `amlLevel`, `approvers`, `usdRate` and `failureReason` — the
+   * last only on `failed`, `rejected` and `cancelled`, `null` on any other
+   * status.
    */
   get(transferId: string): Promise<TransactionDetail> {
     return this.#http.request<TransactionDetail>('GET', `${this.#base}/${seg(transferId)}`)
@@ -91,11 +105,30 @@ export class TransfersResource {
    *   awaiting_approval — counted, more signatures still needed;
    *   rejected          — a `reject` is a veto, and the reserve is released;
    *   confirmed/failed  — this vote completed the threshold, so execution ran
-   *                       INSIDE this request (gas, then broadcast, ~10s).
+   *                       INSIDE this request (gas, then broadcast, ~10s);
+   *   pending           — with no `executionError`: the outcome is NOT
+   *                       established by this answer. The signing service
+   *                       gave no definite answer (the transaction may have
+   *                       left; an administrator's reconciliation settles
+   *                       it), another call is executing the transfer, or
+   *                       the execution broke off. Re-read the transfer:
+   *                       `confirmed`/`failed` is the outcome, `pending` for
+   *                       over 10 minutes by `updatedAt` is waiting for
+   *                       reconciliation. Never send it again.
    *
    * `failed` means the money is back: execution broke after approval and the
    * reserve was released, with the reason in `executionError`. Treating the
-   * call as "approved, done" hides both the success and that failure.
+   * call as "approved, done" hides both the success and that failure. The
+   * exception is a `failed` transfer that has a `txHash`: it went out after
+   * reconciliation had already returned the reserve, and an administrator has
+   * to correct the ledger. `executionError` beside `rejected` or `cancelled`
+   * means the transfer was no longer waiting for signatures when approved,
+   * and nothing was executed.
+   *
+   * Repeating the same decision while the transfer is still waiting finishes
+   * what an earlier call left undone (it recorded the vote and broke off) — a
+   * veto, or execution once the threshold is met — instead of 409
+   * `ALREADY_VOTED`.
    */
   vote(transferId: string, input: VoteInput): Promise<VoteResult> {
     return this.#http.request<VoteResult>(
@@ -124,19 +157,34 @@ export class TransfersResource {
   }
 
   /**
-   * Settles a transfer stuck in `pending` — the case where the worker died
-   * mid-execution, so cancelling does not apply. Administrators only.
+   * Settles a transfer nothing else can close. Administrators only.
+   *
+   *   pending            — execution died, or its outcome is unknown (the
+   *                        send answered 502 `TRANSFER_OUTCOME_UNKNOWN`);
+   *   awaiting_approval  — with no live approval request to vote on;
+   *   failed, rejected,
+   *   cancelled          — closed, but the reserve is still held: it is
+   *                        returned, and the status stays.
+   *
+   * A pending transfer is decided by the HASH: send `txHash` and it is driven
+   * to `confirmed`; send none and the reserve is returned (`failed`). Sending
+   * none is YOUR statement that nothing was broadcast — the server does not
+   * check it, so look on the chain first: returning the reserve of a
+   * transaction that did go out creates money. If the transfer already holds
+   * a hash from the signing service, only that hash, sent explicitly, settles
+   * it — 409 `TRANSFER_BROADCAST` without one, `TXHASH_MISMATCH` with another,
+   * the saved hash in `details.txHash`. The other two cases never executed
+   * and take no hash.
    *
-   * The decision is made by the HASH: send `txHash` and the transfer is
-   * driven to `confirmed`, because the signing service did put it on the
-   * chain; send none and the reserve is returned, because there was no
-   * broadcast. A FRESH pending transfer is refused on purpose — while
-   * execution may still be in flight, intervening risks a SECOND broadcast,
-   * which costs more than waiting.
+   * A FRESH transfer is refused on purpose — while execution may still be in
+   * flight, intervening risks a SECOND broadcast, which costs more than
+   * waiting.
    *
-   * Pass `fee` along with the hash if you know it: this is the only moment
-   * it can be recorded on a transfer settled this way, and it stays null
-   * otherwise. The answer says which way it went — `confirmed` or `failed`.
+   * Pass `fee` along with the hash if you know it: this is the only moment it
+   * can be recorded on a transfer settled this way; otherwise it stays as it
+   * is, null unless the signing service reported one. The answer says which
+   * way it went — `confirmed`, `failed`, or the unchanged `rejected` /
+   * `cancelled` of a closed transfer.
    */
   reconcile(
     transferId: string,

package/src/version.ts

@@ -1,5 +1,5 @@
 /** SDK version, sent in the `user-agent` header. */
-export const SDK_VERSION = '0.2.1'
+export const SDK_VERSION = '0.2.3'
 
 /** Default API base URL. */
 export const DEFAULT_BASE_URL = 'https://policy-engine-rest.ezig.workers.dev'