token: Specs, parameters and source emission - Eco Docs

The token namespace emits SauceScript for token operations: ERC-20 on an EVM compile target, SPL Token on svm. It is TypeScript that writes SauceScript for a host program; a SauceScript program imports the @sauce/token library instead. token.Token.transfer({ token, to, amount }).toSauceScript("evm") returns an object whose source is a program routes.compileSauceProgram compiles. token.Token is also the root export Token.

import { token } from "@eco-incorp/sauce";

Generated from the type declarations of @eco-incorp/sauce.

`token.isEvmTarget`

Function · @eco-incorp/sauce

export declare function isEvmTarget(target: TokenTarget): boolean;

`token.toAddressBigint`

Function · @eco-incorp/sauce

export declare function toAddressBigint(value: AddressInput, _label: string): bigint;

`token.assertU64Range`

Function · @eco-incorp/sauce Any literal (non-"balance") amount destined for SVM must fit the SPL u64 amount field.

export declare function assertU64Range(amount: bigint, label: string): void;

`token.toAmountBigint`

Function · @eco-incorp/sauce

export declare function toAmountBigint(amount: bigint | number, label: string): bigint;

`token.ownerRef`

Function · @eco-incorp/sauce owner/tokenProgram default names - shared/reused across ops in one program by design (the SPL CPI-target intern is meant to dedupe across ops, unlike per-op instance refs).

export declare function ownerRef(refs: SvmTokenRefs): string;

`token.tokenProgramRef`

Function · @eco-incorp/sauce

export declare function tokenProgramRef(refs: SvmTokenRefs): string;

`token.validateTransferSpec`

Function · @eco-incorp/sauce

export declare function validateTransferSpec(spec: TokenTransferSpec, target: TokenTarget): void;

`token.validateApproveSpec`

Function · @eco-incorp/sauce

export declare function validateApproveSpec(spec: TokenApproveSpec, target: TokenTarget): void;

`token.validateBalanceSpec`

Function · @eco-incorp/sauce

export declare function validateBalanceSpec(spec: TokenBalanceSpec, target: TokenTarget): void;

`token.assertNoDuplicateSvmRefs`

Function · @eco-incorp/sauce Rejects a duplicate SVM instance ref name across DIFFERENT ops in one Token.program(...) call - a collision would silently merge two distinct AccountPlan slots. owner/tokenProgram are exempt (shared by design).

export declare function assertNoDuplicateSvmRefs(specs: readonly TokenSpec[]): void;

`token.Address`

Type · @eco-incorp/sauce A 20-byte EVM address, as an ordinary 0x-prefixed hex string.

export type Address = `0x${string}`;

`token.AddressInput`

Type · @eco-incorp/sauce Anything the token normalizers accept for an address-shaped field.

export type AddressInput = Address | bigint;

`token.TokenTarget`

Type · @eco-incorp/sauce The target a token emitter writes SauceScript for: "evm", "v1" and "v12" select the ERC-20 arm and emit byte-identical text, and "svm" selects the SPL Token arm. compile()’s own target option, not this value, decides what the text is compiled for.

export type TokenTarget = "evm" | "v1" | "v12" | "svm";

`token.TokenOp`

Type · @eco-incorp/sauce

export type TokenOp = "transfer" | "approve" | "balanceOf";

`token.SPL_TRANSFER_CHECKED`

Variable · @eco-incorp/sauce SPL Token TransferChecked instruction discriminant.

SPL_TRANSFER_CHECKED = 12

`token.SPL_APPROVE_CHECKED`

Variable · @eco-incorp/sauce SPL Token ApproveChecked instruction discriminant.

SPL_APPROVE_CHECKED = 13

`token.SPL_AMOUNT_OFFSET`

Variable · @eco-incorp/sauce Offset of the SPL token account’s u64 amount field (identical in classic SPL + Token-2022).

SPL_AMOUNT_OFFSET = 64

`token.MINT_DECIMALS_OFFSET`

Variable · @eco-incorp/sauce Offset of the mint’s decimals byte (identical in the first 82 bytes of both programs’ mints).

MINT_DECIMALS_OFFSET = 44

`token.SvmTokenRefs`

Interface · @eco-incorp/sauce SVM account refs a token op needs, as caller-named strings resolved at EXECUTION time (the same contract svmSettleRefs establishes) - never resolved addresses baked into the source. Defaults cover the common single-op case; a multi-op program must pass distinct names per op.

export interface SvmTokenRefs {
    source: string;
    mint?: string;
    dest?: string;
    delegate?: string;
    owner?: string;
    tokenProgram?: string;
}

`token.SvmTokenProgramInput`

Type · @eco-incorp/sauce The SVM CPI target VALUE - a well-known program id by name, or a raw pubkey as a bigint. Always a LITERAL: every account identity a program touches is an attach slot, so a caller-supplied identity belongs in SvmTokenRefs.tokenProgram (the ref this value is pinned against), never in the value.

export type SvmTokenProgramInput = "spl" | "token-2022" | bigint;

`token.TokenTransferSpec`

Interface · @eco-incorp/sauce

export interface TokenTransferSpec {
    token?: AddressInput;
    to?: AddressInput;
    amount: bigint | number | "balance";
    svm?: SvmTokenRefs;
    tokenProgram?: SvmTokenProgramInput;
}

`token.TokenApproveSpec`

Interface · @eco-incorp/sauce

export interface TokenApproveSpec {
    token?: AddressInput;
    spender?: AddressInput;
    amount: bigint | number | "balance";
    svm?: SvmTokenRefs;
    tokenProgram?: SvmTokenProgramInput;
}

`token.TokenBalanceSpec`

Interface · @eco-incorp/sauce

export interface TokenBalanceSpec {
    token?: AddressInput;
    owner?: AddressInput | "pot";
    svm?: Pick<SvmTokenRefs, "source">;
}

`token.TokenSpec`

Type · @eco-incorp/sauce

export type TokenSpec = ({
    op: "transfer";
} & TokenTransferSpec) | ({
    op: "approve";
} & TokenApproveSpec) | ({
    op: "balanceOf";
} & TokenBalanceSpec);

`token.tokenImportLines`

Function · @eco-incorp/sauce The import lines a tokenSource(specs, target) program needs. On an EVM target: IERC20, iff any spec is transfer/approve/balanceOf (always - every op needs the binding). On svm: none (SVM ops use only the built-in svm.sload/svm.call globals).

export declare function tokenImportLines(specs: readonly TokenSpec[], target: TokenTarget): readonly string[];

`token.tokenCallStatement`

Function · @eco-incorp/sauce One statement (transfer/approve) or undefined (balanceOf has no statement form - see tokenExpression) for spec on target, for splicing into a larger, hand-written program. Runs the full per-op/per-target validation. svmState threads dedup across multiple ops in one program (tokenSource’s own concern) - omit it to get a fresh, single-op program.

export declare function tokenCallStatement(spec: TokenSpec, target: TokenTarget, index?: number, svmState?: SvmEmitState): string;

`token.tokenExpression`

Function · @eco-incorp/sauce The expression form of Token.balanceOf(spec) - the only op with one. Throws (named) for transfer/approve, which have no meaningful expression form.

export declare function tokenExpression(spec: TokenSpec, target: TokenTarget): string;

`token.tokenAccountRefs`

Function · @eco-incorp/sauce The account-manifest refs a transfer/approve spec attaches, in order - mirrors svmSettleRefs. Throws for balanceOf (a pure read; its only ref is the caller-supplied source) and for an EVM-target spec (no account manifest on that target).

export declare function tokenAccountRefs(spec: TokenSpec, target: TokenTarget): readonly string[];

`token.tokenSource`

Function · @eco-incorp/sauce A complete, compilable function main() { ... } program: one statement per transfer/approve spec (in order), plus, if the LAST spec is a balanceOf, a trailing return <expr>; - because Token.program’s only consumer (V12Pot.cook) executes the one program it is handed and wants its result, if any, as the return value. A balanceOf in any OTHER position is spliced as a discarded expression statement.

export declare function tokenSource(spec: TokenSpec | readonly TokenSpec[], target: TokenTarget, opts?: TokenSourceOptions): string;

`token.TokenSourceOptions`

Interface · @eco-incorp/sauce

export interface TokenSourceOptions {
    functionName?: string;
    imports?: readonly string[];
}