Overview
Thepolicy field on SinkerConfig lets you set guardrails on what the AI agent is allowed to do, directly in your application code. No config file, no restart — just pass it at construction time.
policy: {} is the same as not providing policy at all.
max-queue and rate-limit are sidecar-side operator settings and are not available here.
Set them with sinker policy set on the CLI.PolicyConfig
Tip controls
number
default:"500000"
Hard ceiling on tip size (lamports). The agent cannot recommend above this value
regardless of what current network conditions suggest.
number
default:"5.0"
Tip cannot exceed N% of the transaction’s transfer value.
For example,
3 means the tip is capped at 3% of the amount being transferred.'p50' | 'p75' | 'p95' | 'p99'
default:"'p75'"
The percentile the agent targets when the network is calm.
p75 is a good balance between landing rate and cost for most use cases.
Use p95 or p99 for time-sensitive transactions.number
default:"2000"
Maximum age of tip oracle data in milliseconds before the agent refuses to proceed.
The oracle updates every ~10 seconds; setting this below 400ms (one slot) will cause the
agent to always see the data as stale.
Bundle & retry controls
number
default:"3"
Maximum number of re-submission attempts before the bundle is declared expired and dropped.
number
default:"150"
How many slots past the enqueue slot the agent keeps retrying before dropping the bundle.
At ~400ms per slot, 150 slots is about 60 seconds.
number
default:"5000"
Maximum tip increase per retry cycle (lamports). Prevents the agent from doubling or
tripling the tip in a single escalation step.Must be less than or equal to
maxTipLamports — the constructor throws SinkerPolicyError
if escalationStepLamports > maxTipLamports.'normal' | 'high' | 'urgent' | 'auto'
default:"'auto'"
Priority tier for all bundles submitted through this instance.
auto lets the agent choose based on network conditions.
Pin to high or urgent when every transaction is time-sensitive.Built-in defaults
Constructor validation
TheSinker constructor validates the policy immediately on instantiation.
Hard errors → throws SinkerPolicyError (construction fails):
Soft warnings → logs to
console.warn (construction continues):
sinker.policy
The resolved policy — all defaults filled in — is available after construction assinker.policy.
ResolvedPolicy — all 8 fields present, no optionals.
sinker.validatePolicy()
Returns{ errors, warnings, valid } without throwing. Use this if you want to inspect
the policy programmatically after construction without relying on try/catch.
PolicyValidationResult
string[]
Hard problems that will cause incorrect operation.
string[]
Unusual values that may be intentional but are worth knowing about.
boolean
true when errors is empty. Warnings do not affect valid.SinkerPolicyError
Thrown by the constructor when the policy has hard errors.Relationship to sinker.policy.json
The CLI’ssinker.policy.json and the SDK’s policy config are independent. The CLI file controls what the sidecar and agent enforce at the process level. The SDK policy is in-memory config on the client side.
In practice: set your hard system-wide limits in sinker.policy.json via the CLI, and set per-application constraints in the SDK policy config. The agent will respect whichever is more restrictive.