Testes Baseados em Tempo

Demonstra o uso de warpToSlot para testar lógica de programa dependente de tempo.

Manipulação Básica do Relógio

import { createClient, generateKeyPairSigner } from "@solana/kit";
import { litesvm } from "@solana/kit-plugin-litesvm";
import { signer } from "@solana/kit-plugin-signer";

const mySigner = await generateKeyPairSigner();
const client = createClient().use(signer(mySigner)).use(litesvm());

// Enable sysvars for clock access
client.svm.withSysvars();

// Check initial clock
const initialClock = client.svm.getClock();
console.log("Initial state:");
console.log("  Slot:", initialClock.slot);
console.log("  Epoch:", initialClock.epoch);
console.log("  Unix timestamp:", initialClock.unixTimestamp);

// Warp to slot 1000
client.svm.warpToSlot(1000n);

const afterWarp = client.svm.getClock();
console.log("\nAfter warpToSlot(1000):");
console.log("  Slot:", afterWarp.slot);
console.log("  Epoch:", afterWarp.epoch);

// Warp further
client.svm.warpToSlot(100000n);

const afterWarp2 = client.svm.getClock();
console.log("\nAfter warpToSlot(100000):");
console.log("  Slot:", afterWarp2.slot);
console.log("  Epoch:", afterWarp2.epoch);

Testando Lógica Bloqueada por Tempo

Exemplo de padrão para testar funcionalidade bloqueada por tempo:

import {
  createClient,
  address,
  generateKeyPairSigner,
  lamports
} from "@solana/kit";
import { litesvm } from "@solana/kit-plugin-litesvm";
import { signer } from "@solana/kit-plugin-signer";

const mySigner = await generateKeyPairSigner();
const client = createClient().use(signer(mySigner)).use(litesvm());

client.svm.withSigverify(false).withBlockhashCheck(false).withSysvars();

// Fund payer
client.svm.airdrop(client.payer.address, lamports(10_000_000_000n));

// Set up a time-locked vault account
// Structure: [u8 discriminator, u64 unlock_slot, u64 amount]
const unlockSlot = 10000n;
const lockedAmount = 5_000_000_000n;

const vaultData = new Uint8Array(1 + 8 + 8);
const view = new DataView(vaultData.buffer);
vaultData[0] = 0x01; // discriminator
view.setBigUint64(1, unlockSlot, true); // unlock_slot
view.setBigUint64(9, lockedAmount, true); // amount

const programId = address("TimeLockedVault11111111111111111111111"); // replace or generateKeyPairSigner()
const vaultAddress = address("Vault111111111111111111111111111"); // replace or generateKeyPairSigner()
const minBalance = client.svm.minimumBalanceForRentExemption(
  BigInt(vaultData.length)
);

client.svm.setAccount({
  address: vaultAddress,
  data: vaultData,
  executable: false,
  lamports: lamports(minBalance + lockedAmount),
  programAddress: programId,
  space: BigInt(vaultData.length)
});

console.log("Vault created with unlock slot:", unlockSlot);
console.log("Locked amount:", Number(lockedAmount) / 1e9, "SOL");

// Test 1: Try to withdraw before unlock (should fail)
console.log("\n--- Test 1: Before unlock ---");
const currentClock = client.svm.getClock();
console.log("Current slot:", currentClock.slot);

// In a real test, you would:
// 1. Build a withdraw instruction
// 2. Send it and expect it to fail
console.log("Withdrawal attempt: EXPECTED TO FAIL (too early)");

// Test 2: Warp to after unlock slot
console.log("\n--- Test 2: After unlock ---");
client.svm.warpToSlot(unlockSlot + 100n);

const newClock = client.svm.getClock();
console.log("Current slot:", newClock.slot);

// In a real test:
// 1. Build a withdraw instruction
// 2. Send it and expect it to succeed
console.log("Withdrawal attempt: EXPECTED TO SUCCEED (after unlock)");

// Verify vault state
const updatedVault = client.svm.getAccount(vaultAddress);
if (updatedVault.exists) {
  console.log("\nVault balance:", updatedVault.lamports);
}

Lendo o Agendamento de Epoch

Você pode ler o agendamento de epoch para entender a relação slot/epoch no cluster:

import { createClient, generateKeyPairSigner } from "@solana/kit";
import { litesvm } from "@solana/kit-plugin-litesvm";
import { signer } from "@solana/kit-plugin-signer";

const mySigner = await generateKeyPairSigner();
const client = createClient().use(signer(mySigner)).use(litesvm());
client.svm.withSysvars();

const epochSchedule = client.svm.getEpochSchedule();
console.log("Slots per epoch:", epochSchedule.slotsPerEpoch);
console.log("First normal epoch:", epochSchedule.firstNormalEpoch);
console.log("First normal slot:", epochSchedule.firstNormalSlot);

warpToSlot avança o campo slot do relógio, mas não atualiza automaticamente o epoch ou o unixTimestamp. Use setClock para controle total dos campos do relógio.

Manipulação Manual do Relógio

Quando seu programa lê epoch ou unix_timestamp do sysvar Clock, use setClock para definir esses campos diretamente:

import { createClient, generateKeyPairSigner } from "@solana/kit";
import { litesvm } from "@solana/kit-plugin-litesvm";
import { signer } from "@solana/kit-plugin-signer";

const mySigner = await generateKeyPairSigner();
const client = createClient().use(signer(mySigner)).use(litesvm());
client.svm.withSysvars();

// Get clock, mutate, write back
const clock = client.svm.getClock();
clock.slot = 50000n;
clock.epoch = 5n;
clock.unixTimestamp = 1700000000n;
client.svm.setClock(clock);

const after = client.svm.getClock();
console.log("Slot:", after.slot); // 50000n
console.log("Epoch:", after.epoch); // 5n
console.log("Timestamp:", after.unixTimestamp); // 1700000000n

Isso espelha o padrão Rust set_sysvar(&clock). Use warpToSlot para avanço simples de slot, e setClock quando precisar controlar epoch ou timestamp.

Casos de Uso

A manipulação de tempo é útil para testar:

Cenário	Abordagem
Vesting de tokens	Avançar além do cliff/marcos de vesting
Encerramentos de leilão	Avançar além do slot de encerramento do leilão
Recompensas de staking	Use `setClock` para definir o epoch
Saques bloqueados por tempo	Avançar além do slot de desbloqueio
Limitação de taxa	Avançar entre intervalos permitidos
Ordens com expiração	Avançar além da expiração da ordem

Lembre-se de que warpToSlot altera apenas o slot. O timestamp Unix pode não ser atualizado proporcionalmente, dependendo da implementação do SVM.

Pontos Principais

Habilitar Sysvars: Chame withSysvars() antes de usar os métodos de relógio
Avançar no Tempo: Use warpToSlot(slot) para avançar o slot
Controle Total: Use setClock quando precisar definir epoch, unixTimestamp ou outros campos do relógio
Ler Relógio: Use getClock() para ler o slot, epoch e timestamp atuais
Padrão de Teste: Teste antes e depois dos limites de tempo