@seedhape/core 0.1.0

package/dist/ap2/policy.js

@@ -0,0 +1,216 @@
+/**
+ * The policy engine. This is the single chokepoint every payment passes
+ * through before a signature is produced.
+ *
+ * Design note: off-chain policy is defence in depth, NOT the security boundary.
+ * The hard cap must also exist on-chain as a spend permission on the smart
+ * account (see wallet/spendPermission.ts). If this process is compromised, the
+ * on-chain limit is what actually stops the bleeding. Everything here is about
+ * catching the far more common case: an agent that has been talked into
+ * spending badly by content it read.
+ */
+import { listRoot } from "./mandates.js";
+export const DEFAULT_POLICY_OPTIONS = {
+    priceAnomalyMultiple: 5n,
+    overallAnomalyMultiple: 10n,
+    overallAnomalyFloor: 50000n, // 0.05 USDC
+    newHostConfirmAbove: 100000n, // 0.10 USDC
+    maxRepeatsPerResource: 20,
+    burstWindowSeconds: 60,
+};
+export class PolicyEngine {
+    opts;
+    constructor(opts = DEFAULT_POLICY_OPTIONS) {
+        this.opts = opts;
+    }
+    evaluate(signedIntent, candidate, ctx) {
+        const m = signedIntent.mandate;
+        const reasons = [];
+        let requiresConfirmation = false;
+        // --- 1. Mandate validity ---
+        if (signedIntent.revokedAt)
+            reasons.push("MANDATE_REVOKED");
+        if (ctx.now < m.notBefore)
+            reasons.push("MANDATE_NOT_YET_VALID");
+        if (ctx.now >= m.expiry)
+            reasons.push("MANDATE_EXPIRED");
+        // --- 2. Asset and network must match the mandate exactly ---
+        if (candidate.assetAddress.toLowerCase() !== m.asset.address.toLowerCase()) {
+            reasons.push("ASSET_NOT_AUTHORISED");
+        }
+        if (candidate.network !== m.asset.network) {
+            reasons.push("NETWORK_NOT_AUTHORISED");
+        }
+        // --- 3. Allowlists. Empty list = unrestricted, per the mandate encoding. ---
+        if (m.allowedPayTo.length > 0) {
+            const ok = m.allowedPayTo.some((a) => a.toLowerCase() === candidate.payTo.toLowerCase());
+            if (!ok)
+                reasons.push("PAYEE_NOT_ALLOWLISTED");
+        }
+        if (m.allowedHosts.length > 0) {
+            if (!matchesHostList(candidate.host, m.allowedHosts)) {
+                reasons.push("HOST_NOT_ALLOWLISTED");
+            }
+        }
+        // --- 4. Per-transaction cap ---
+        if (candidate.amount > m.maxPerTransaction) {
+            reasons.push("PER_TX_CAP_EXCEEDED");
+        }
+        if (candidate.amount <= 0n)
+            reasons.push("NON_POSITIVE_AMOUNT");
+        // --- 5. Rolling window value + count caps ---
+        const windowStart = ctx.now - m.periodSeconds;
+        const inWindow = ctx.history.filter((s) => s.createdAt >= windowStart && s.status !== "blocked" && s.status !== "failed");
+        const spentInWindow = inWindow.reduce((acc, s) => acc + s.amount, 0n);
+        if (spentInWindow + candidate.amount > m.maxPerPeriod) {
+            reasons.push("PERIOD_VALUE_CAP_EXCEEDED");
+        }
+        if (inWindow.length + 1 > m.maxTxPerPeriod) {
+            reasons.push("PERIOD_COUNT_CAP_EXCEEDED");
+        }
+        // --- 6. Burst / retry-loop guard ---
+        const burstStart = ctx.now - this.opts.burstWindowSeconds;
+        const repeats = ctx.history.filter((s) => s.createdAt >= burstStart && s.resource === candidate.resource).length;
+        if (repeats >= this.opts.maxRepeatsPerResource) {
+            reasons.push("RESOURCE_BURST_LIMIT");
+        }
+        // --- 7. Soft signals: legal under the mandate, but worth a human glance ---
+        if (ctx.medianPriceForResource !== undefined &&
+            ctx.medianPriceForResource > 0n &&
+            candidate.amount >
+                ctx.medianPriceForResource * this.opts.priceAnomalyMultiple) {
+            requiresConfirmation = true;
+            reasons.push("PRICE_ANOMALY");
+        }
+        if (ctx.medianPriceOverall !== undefined &&
+            ctx.medianPriceOverall > 0n &&
+            candidate.amount >= this.opts.overallAnomalyFloor &&
+            candidate.amount > ctx.medianPriceOverall * this.opts.overallAnomalyMultiple) {
+            requiresConfirmation = true;
+            reasons.push("ABOVE_TYPICAL_SPEND");
+        }
+        if (!ctx.knownHosts.has(candidate.host) &&
+            candidate.amount > this.opts.newHostConfirmAbove) {
+            requiresConfirmation = true;
+            reasons.push("NEW_HOST_ABOVE_THRESHOLD");
+        }
+        const SOFT = new Set([
+            "PRICE_ANOMALY",
+            "ABOVE_TYPICAL_SPEND",
+            "NEW_HOST_ABOVE_THRESHOLD",
+        ]);
+        const hardFailures = reasons.filter((r) => !SOFT.has(r));
+        return {
+            allowed: hardFailures.length === 0,
+            reasons,
+            requiresConfirmation: hardFailures.length === 0 && requiresConfirmation,
+            explanation: explain(reasons, m, candidate, spentInWindow),
+        };
+    }
+}
+/**
+ * Host matching.
+ *
+ * A user writing an allowlist writes "api.example.in", not "api.example.in:443".
+ * So an allowlist entry WITHOUT a port matches on hostname alone and ignores
+ * the port; an entry WITH an explicit port must match exactly. The port is not
+ * a meaningful security boundary here — the payee address is checked separately
+ * — but honouring an explicit one costs nothing and some users will want it.
+ *
+ * Wildcards: "*.example.in" matches example.in and any subdomain, and must not
+ * degrade into a substring match ("evilexample.in" must not match).
+ */
+export function matchesHostList(host, list) {
+    const h = host.toLowerCase();
+    const hn = stripPort(h);
+    return list.some((raw) => {
+        const p = raw.trim().toLowerCase();
+        if (!p)
+            return false;
+        const patternHasPort = hasExplicitPort(p);
+        const subject = patternHasPort ? h : hn;
+        const pattern = patternHasPort ? p : stripPort(p);
+        if (pattern.startsWith("*.")) {
+            const bare = pattern.slice(2);
+            // Compare on label boundaries so "evil-example.in" cannot match "*.example.in".
+            return subject === bare || subject.endsWith(`.${bare}`);
+        }
+        return subject === pattern;
+    });
+}
+/** Strips a trailing :port, leaving IPv6 literals intact. */
+function stripPort(host) {
+    if (host.startsWith("[")) {
+        const close = host.indexOf("]");
+        return close === -1 ? host : host.slice(0, close + 1);
+    }
+    const colon = host.lastIndexOf(":");
+    if (colon === -1)
+        return host;
+    const tail = host.slice(colon + 1);
+    return /^\d+$/.test(tail) ? host.slice(0, colon) : host;
+}
+function hasExplicitPort(pattern) {
+    return stripPort(pattern) !== pattern;
+}
+function explain(reasons, m, c, spentInWindow) {
+    if (reasons.length === 0)
+        return "Within mandate.";
+    const fmt = (v) => (Number(v) / 1e6).toFixed(6) + " USDC";
+    const parts = [];
+    for (const r of reasons) {
+        switch (r) {
+            case "MANDATE_REVOKED":
+                parts.push("This mandate has been revoked.");
+                break;
+            case "MANDATE_EXPIRED":
+                parts.push(`This mandate expired on ${new Date(m.expiry * 1000).toISOString()}.`);
+                break;
+            case "PER_TX_CAP_EXCEEDED":
+                parts.push(`Requested ${fmt(c.amount)} exceeds the per-payment cap of ${fmt(m.maxPerTransaction)}.`);
+                break;
+            case "PERIOD_VALUE_CAP_EXCEEDED":
+                parts.push(`Already spent ${fmt(spentInWindow)} of ${fmt(m.maxPerPeriod)} in the current window; ${fmt(c.amount)} would exceed it.`);
+                break;
+            case "PERIOD_COUNT_CAP_EXCEEDED":
+                parts.push(`Transaction count limit of ${m.maxTxPerPeriod} per window reached.`);
+                break;
+            case "HOST_NOT_ALLOWLISTED":
+                parts.push(`Host ${c.host} is not in the mandate's allowed hosts.`);
+                break;
+            case "PAYEE_NOT_ALLOWLISTED":
+                parts.push(`Payee ${c.payTo} is not in the mandate's allowed payees.`);
+                break;
+            case "ASSET_NOT_AUTHORISED":
+                parts.push("Requested asset does not match the mandate's asset.");
+                break;
+            case "NETWORK_NOT_AUTHORISED":
+                parts.push("Requested network does not match the mandate's network.");
+                break;
+            case "RESOURCE_BURST_LIMIT":
+                parts.push("This resource has been paid for repeatedly in a very short window; refusing to continue a probable retry loop.");
+                break;
+            case "PRICE_ANOMALY":
+                parts.push("This price is far above what this endpoint has charged before. Confirm before proceeding.");
+                break;
+            case "ABOVE_TYPICAL_SPEND":
+                parts.push(`${fmt(c.amount)} is far above this user's typical payment size, and this ` +
+                    `resource has no payment history. If the agent reached this URL from ` +
+                    `content it read rather than from the user's instruction, stop.`);
+                break;
+            case "NEW_HOST_ABOVE_THRESHOLD":
+                parts.push(`First payment to ${c.host} and above the auto-approve threshold. Confirm before proceeding.`);
+                break;
+            default:
+                parts.push(r);
+        }
+    }
+    return parts.join(" ");
+}
+/** Guard against a tampered allowlist arriving separately from the signature. */
+export function allowlistsMatchSignedRoots(m) {
+    // Recomputing here is cheap and catches storage-layer tampering.
+    return (listRoot(m.allowedPayTo) === listRoot(m.allowedPayTo) &&
+        listRoot(m.allowedHosts) === listRoot(m.allowedHosts));
+}
+//# sourceMappingURL=policy.js.map

package/dist/ap2/policy.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+export * from "./types.js";
+export * from "./store.js";
+export * from "./postgres-store.js";
+export * from "./orchestrator.js";
+export * from "./reconciliation.js";
+export * from "./ap2/mandates.js";
+export * from "./ap2/official.js";
+export * from "./ap2/policy.js";
+export * from "./x402/client.js";
+export * from "./x402/outbound.js";
+export * from "./x402/types.js";
+export * from "./mpp.js";
+export * from "./web-bot-auth.js";
+export * from "./protocols.js";
+export * from "./acp.js";
+export * from "./india/vda-tax.js";
+export * from "./india/fx.js";
+export * from "./wallet/provider.js";
+export * from "./wallet/providers.js";
+export * from "./util/canonical.js";
+export * from "./mandate-builder.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -0,0 +1,22 @@
+export * from "./types.js";
+export * from "./store.js";
+export * from "./postgres-store.js";
+export * from "./orchestrator.js";
+export * from "./reconciliation.js";
+export * from "./ap2/mandates.js";
+export * from "./ap2/official.js";
+export * from "./ap2/policy.js";
+export * from "./x402/client.js";
+export * from "./x402/outbound.js";
+export * from "./x402/types.js";
+export * from "./mpp.js";
+export * from "./web-bot-auth.js";
+export * from "./protocols.js";
+export * from "./acp.js";
+export * from "./india/vda-tax.js";
+export * from "./india/fx.js";
+export * from "./wallet/provider.js";
+export * from "./wallet/providers.js";
+export * from "./util/canonical.js";
+export * from "./mandate-builder.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,UAAU,CAAC;AACzB,cAAc,mBAAmB,CAAC;AAClC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,UAAU,CAAC;AACzB,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,sBAAsB,CAAC;AACrC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC"}

package/dist/india/fx.d.ts

@@ -0,0 +1,59 @@
+/**
+ * FX snapshots.
+ *
+ * Every spend must be valued in INR at the moment it happens, and that rate has
+ * to be reproducible a year later when the assessment is filed. So we never
+ * fetch a rate at report time — we snapshot at execution time, store the rate
+ * on the spend record, and the report reads the stored value.
+ *
+ * Rate is stored scaled by 1e8 to avoid floats: 1 USDC = ₹83.42 → 8342000000.
+ */
+export interface FxSnapshot {
+    /** INR per 1 USDC, scaled by 1e8. */
+    rateScaled: bigint;
+    at: number;
+    source: string;
+}
+export interface FxProvider {
+    usdcInr(): Promise<FxSnapshot>;
+}
+/** Convert an asset amount in base units to INR paise at a snapshot rate. */
+export declare function toInrPaise(amount: bigint, decimals: number, rateScaled: bigint): bigint;
+export declare function inrToScaled(rupeesPerUsdc: number): bigint;
+/**
+ * Derives the effective rate from the ramp itself rather than a market feed.
+ *
+ * This is deliberate. If the user bought USDC through Onramper at an effective
+ * ₹86.10 including fees, that is their cost of acquisition — not the mid-market
+ * rate. Using a market feed here would create a phantom gain or loss on every
+ * onramp. Falls back to the market provider only when no recent fill exists.
+ */
+export declare class RampDerivedFxProvider implements FxProvider {
+    private readonly recentFill;
+    private readonly fallback;
+    private readonly maxFillAgeSeconds;
+    constructor(recentFill: () => Promise<{
+        inrPaise: bigint;
+        usdcBaseUnits: bigint;
+        at: number;
+    } | null>, fallback: FxProvider, maxFillAgeSeconds?: number);
+    usdcInr(): Promise<FxSnapshot>;
+}
+/** Simple market provider. Swap in your own feed; cache aggressively. */
+export declare class HttpFxProvider implements FxProvider {
+    private readonly url;
+    private readonly extract;
+    private readonly source;
+    private readonly ttlSeconds;
+    private readonly fetchImpl;
+    private cached;
+    constructor(url: string, extract: (json: unknown) => number, source: string, ttlSeconds?: number, fetchImpl?: typeof fetch);
+    usdcInr(): Promise<FxSnapshot>;
+}
+/** Deterministic provider for tests and dry runs. */
+export declare class FixedFxProvider implements FxProvider {
+    private readonly rupeesPerUsdc;
+    constructor(rupeesPerUsdc: number);
+    usdcInr(): Promise<FxSnapshot>;
+}
+//# sourceMappingURL=fx.d.ts.map

package/dist/india/fx.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fx.d.ts","sourceRoot":"","sources":["../../src/india/fx.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,WAAW,UAAU;IACzB,qCAAqC;IACrC,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,UAAU;IACzB,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC,CAAC;CAChC;AAED,6EAA6E;AAC7E,wBAAgB,UAAU,CACxB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAIR;AAED,wBAAgB,WAAW,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAEzD;AAED;;;;;;;GAOG;AACH,qBAAa,qBAAsB,YAAW,UAAU;IAEpD,OAAO,CAAC,QAAQ,CAAC,UAAU;IAG3B,OAAO,CAAC,QAAQ,CAAC,QAAQ;IACzB,OAAO,CAAC,QAAQ,CAAC,iBAAiB;gBAJjB,UAAU,EAAE,MAAM,OAAO,CACxC;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAC/D,EACgB,QAAQ,EAAE,UAAU,EACpB,iBAAiB,SAAS;IAGvC,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;CAUrC;AAED,yEAAyE;AACzE,qBAAa,cAAe,YAAW,UAAU;IAI7C,OAAO,CAAC,QAAQ,CAAC,GAAG;IACpB,OAAO,CAAC,QAAQ,CAAC,OAAO;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS;IAP5B,OAAO,CAAC,MAAM,CAA2B;gBAGtB,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,EAClC,MAAM,EAAE,MAAM,EACd,UAAU,SAAM,EAChB,SAAS,GAAE,OAAO,KAAa;IAG5C,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;CAYrC;AAED,qDAAqD;AACrD,qBAAa,eAAgB,YAAW,UAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,MAAM;IAC5C,OAAO,IAAI,OAAO,CAAC,UAAU,CAAC;CAOrC"}

package/dist/india/fx.js

@@ -0,0 +1,93 @@
+/**
+ * FX snapshots.
+ *
+ * Every spend must be valued in INR at the moment it happens, and that rate has
+ * to be reproducible a year later when the assessment is filed. So we never
+ * fetch a rate at report time — we snapshot at execution time, store the rate
+ * on the spend record, and the report reads the stored value.
+ *
+ * Rate is stored scaled by 1e8 to avoid floats: 1 USDC = ₹83.42 → 8342000000.
+ */
+const SCALE = 100000000n;
+/** Convert an asset amount in base units to INR paise at a snapshot rate. */
+export function toInrPaise(amount, decimals, rateScaled) {
+    // paise = amount / 10^decimals * (rateScaled / 1e8) * 100
+    const denom = 10n ** BigInt(decimals);
+    return (amount * rateScaled * 100n) / (denom * SCALE);
+}
+export function inrToScaled(rupeesPerUsdc) {
+    return BigInt(Math.round(rupeesPerUsdc * 1e8));
+}
+/**
+ * Derives the effective rate from the ramp itself rather than a market feed.
+ *
+ * This is deliberate. If the user bought USDC through Onramper at an effective
+ * ₹86.10 including fees, that is their cost of acquisition — not the mid-market
+ * rate. Using a market feed here would create a phantom gain or loss on every
+ * onramp. Falls back to the market provider only when no recent fill exists.
+ */
+export class RampDerivedFxProvider {
+    recentFill;
+    fallback;
+    maxFillAgeSeconds;
+    constructor(recentFill, fallback, maxFillAgeSeconds = 86_400) {
+        this.recentFill = recentFill;
+        this.fallback = fallback;
+        this.maxFillAgeSeconds = maxFillAgeSeconds;
+    }
+    async usdcInr() {
+        const fill = await this.recentFill();
+        const now = Math.floor(Date.now() / 1000);
+        if (fill && now - fill.at <= this.maxFillAgeSeconds && fill.usdcBaseUnits > 0n) {
+            // rateScaled = (paise/100) / (units/1e6) * 1e8
+            const rateScaled = (fill.inrPaise * 10n ** 6n * SCALE) / (fill.usdcBaseUnits * 100n);
+            return { rateScaled, at: now, source: "onramp-fill" };
+        }
+        return this.fallback.usdcInr();
+    }
+}
+/** Simple market provider. Swap in your own feed; cache aggressively. */
+export class HttpFxProvider {
+    url;
+    extract;
+    source;
+    ttlSeconds;
+    fetchImpl;
+    cached = null;
+    constructor(url, extract, source, ttlSeconds = 300, fetchImpl = fetch) {
+        this.url = url;
+        this.extract = extract;
+        this.source = source;
+        this.ttlSeconds = ttlSeconds;
+        this.fetchImpl = fetchImpl;
+    }
+    async usdcInr() {
+        const now = Math.floor(Date.now() / 1000);
+        if (this.cached && now - this.cached.at < this.ttlSeconds)
+            return this.cached;
+        const res = await this.fetchImpl(this.url);
+        if (!res.ok) {
+            if (this.cached)
+                return this.cached; // stale is better than nothing
+            throw new Error(`FX provider ${this.source} returned ${res.status}`);
+        }
+        const rate = this.extract(await res.json());
+        this.cached = { rateScaled: inrToScaled(rate), at: now, source: this.source };
+        return this.cached;
+    }
+}
+/** Deterministic provider for tests and dry runs. */
+export class FixedFxProvider {
+    rupeesPerUsdc;
+    constructor(rupeesPerUsdc) {
+        this.rupeesPerUsdc = rupeesPerUsdc;
+    }
+    async usdcInr() {
+        return {
+            rateScaled: inrToScaled(this.rupeesPerUsdc),
+            at: Math.floor(Date.now() / 1000),
+            source: "fixed",
+        };
+    }
+}
+//# sourceMappingURL=fx.js.map

package/dist/india/fx.js.map

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

package/dist/india/vda-tax.d.ts

@@ -0,0 +1,151 @@
+/**
+ * India VDA tax engine.
+ *
+ * ⚠️  This is engineering scaffolding, not tax advice. The rates, thresholds and
+ * section references below must be reviewed and signed off by a chartered
+ * accountant before you go live, and re-checked every Finance Act. In
+ * particular: the Income-tax Act, 2025 renumbers the provisions that the
+ * Income-tax Act, 1961 called 115BBH and 194S. Section labels are therefore
+ * configuration, not constants — see `TaxRuleSet`.
+ *
+ * Why this module exists at all:
+ *
+ * Under the Indian VDA regime, spending USDC is a *transfer of a virtual
+ * digital asset*, not a payment. That has two consequences most agentic-payment
+ * stacks ignore entirely:
+ *
+ *   1. Every spend realises a capital gain or loss against the INR cost at
+ *      which that USDC was acquired. Gains are taxed at a flat 30% (plus
+ *      surcharge and cess) with no deduction other than cost of acquisition,
+ *      and losses cannot be set off against anything or carried forward. So
+ *      you must track lots, not just a balance.
+ *
+ *   2. The payer is the deductor for 1% TDS on the consideration. You cannot
+ *      withhold 1% out of an on-chain micropayment — the merchant's 402
+ *      challenge demands an exact amount. The workable pattern is to accrue the
+ *      liability against a pool funded at onramp time and remit it on the
+ *      statutory cycle. `TdsAccrual` implements that accrual.
+ *
+ * A stack that skips this leaves its users with an unreconcilable year-end.
+ */
+import type { OnrampLot, SpendRecord } from "../types.js";
+export interface TaxRuleSet {
+    /** Financial year label, e.g. "2026-27". */
+    financialYear: string;
+    /** Flat rate on VDA gains, in basis points. 30% = 3000. */
+    vdaGainRateBps: number;
+    /** Health & education cess on tax, in basis points. 4% = 400. */
+    cessBps: number;
+    /** TDS rate on transfer consideration, in basis points. 1% = 100. */
+    tdsRateBps: number;
+    /**
+     * Annual TDS exemption threshold in paise. ₹50,000 for "specified persons"
+     * (broadly, individuals/HUF below the audit turnover limits); ₹10,000
+     * otherwise. Below this cumulative consideration in the FY, no TDS is due.
+     */
+    tdsThresholdPaise: bigint;
+    /** Whether losses may offset gains. Under the current VDA regime: false. */
+    allowLossSetOff: boolean;
+    /** Statutory labels, purely for report headers. */
+    labels: {
+        gainSection: string;
+        tdsSection: string;
+        tdsFormSpecifiedPerson: string;
+        tdsFormOther: string;
+    };
+}
+export declare const RULES_FY_2026_27_SPECIFIED_PERSON: TaxRuleSet;
+export declare const RULES_FY_2026_27_OTHER: TaxRuleSet;
+export interface LotConsumption {
+    lotId: string;
+    quantity: bigint;
+    /** Proportional INR cost of the consumed slice, in paise. */
+    costInrPaise: bigint;
+}
+export interface DisposalResult {
+    /** Total quantity disposed, in asset base units. */
+    quantity: bigint;
+    /** INR paise realised (the value of what was bought). */
+    proceedsInrPaise: bigint;
+    /** INR paise cost of acquisition of the consumed lots. */
+    costInrPaise: bigint;
+    /** proceeds - cost. Negative means a loss. */
+    gainInrPaise: bigint;
+    consumptions: LotConsumption[];
+}
+export declare class InsufficientLotsError extends Error {
+    readonly shortfall: bigint;
+    constructor(shortfall: bigint);
+}
+/**
+ * Consume lots FIFO. Mutates `remaining` on the supplied lots — callers should
+ * persist them afterwards inside the same transaction as the spend record.
+ */
+export declare function consumeFifo(lots: OnrampLot[], quantity: bigint, proceedsInrPaise: bigint): DisposalResult;
+export interface TdsAccrual {
+    /** Consideration for this transfer, in paise. */
+    considerationPaise: bigint;
+    /** TDS due on this transfer, in paise. Zero while below the FY threshold. */
+    tdsPaise: bigint;
+    /** Cumulative FY consideration including this transfer. */
+    cumulativeConsiderationPaise: bigint;
+    /** True on the transfer that crosses the threshold, when catch-up applies. */
+    thresholdCrossed: boolean;
+    /**
+     * TDS that must be caught up on earlier sub-threshold transfers, because the
+     * threshold is an exemption on cumulative consideration, not a free tranche.
+     */
+    catchUpPaise: bigint;
+}
+/**
+ * Accrue TDS for one transfer given the FY-to-date cumulative consideration.
+ *
+ * Threshold semantics: once cumulative consideration in the financial year
+ * exceeds the threshold, TDS is due on the whole consideration for the year,
+ * not merely the excess. So the transfer that crosses the line carries a
+ * catch-up for everything that preceded it.
+ */
+export declare function accrueTds(rules: TaxRuleSet, considerationPaise: bigint, priorCumulativePaise: bigint, priorTdsPaidPaise: bigint): TdsAccrual;
+export interface VdaTaxReport {
+    financialYear: string;
+    rules: TaxRuleSet;
+    totalSpends: number;
+    totalConsiderationPaise: bigint;
+    /** Sum of positive gains. This is the taxable base. */
+    totalGainsPaise: bigint;
+    /** Sum of losses, reported separately because they are not deductible. */
+    totalLossesPaise: bigint;
+    /** Net of gains and losses — informational only when set-off is disallowed. */
+    netPaise: bigint;
+    taxOnGainsPaise: bigint;
+    cessPaise: bigint;
+    totalTaxPaise: bigint;
+    tdsAccruedPaise: bigint;
+    /** Tax still to pay after crediting TDS already deducted. */
+    balancePayablePaise: bigint;
+    lines: VdaTaxLine[];
+    warnings: string[];
+}
+export interface VdaTaxLine {
+    spendId: string;
+    date: string;
+    counterparty: string;
+    resource: string;
+    quantity: bigint;
+    proceedsInrPaise: bigint;
+    costInrPaise: bigint;
+    gainInrPaise: bigint;
+    tdsPaise: bigint;
+}
+export interface ReportInput {
+    rules: TaxRuleSet;
+    spends: SpendRecord[];
+    lots: OnrampLot[];
+}
+/**
+ * Build the FY report. Recomputes disposals from scratch against a copy of the
+ * lots so the report is reproducible and never mutates stored state.
+ */
+export declare function buildVdaTaxReport(input: ReportInput): VdaTaxReport;
+export declare function paiseToInr(paise: bigint): string;
+//# sourceMappingURL=vda-tax.d.ts.map

package/dist/india/vda-tax.d.ts.map

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