trac-msb 0.2.4 → 0.2.6

package/tests/unit/state/apply/balanceInitialization/balanceInitializationHappyPathScenario.js

@@ -0,0 +1,82 @@
+import { test } from 'brittle';
+import b4a from 'b4a';
+import { eventFlush } from '../../../../helpers/autobaseTestHelpers.js';
+import nodeEntryUtils from '../../../../../src/core/state/utils/nodeEntry.js';
+import { toTerm } from '../../../../../src/core/state/utils/balance.js';
+import { ZERO_WK } from '../../../../../src/utils/buffer.js';
+import { safeDecodeApplyOperation } from '../../../../../src/utils/protobuf/operationHelpers.js';
+import setupBalanceInitializationScenario, {
+	buildBalanceInitializationPayload
+} from './balanceInitializationScenarioHelpers.js';
+
+export default function balanceInitializationHappyPathScenario() {
+	test('State.apply balanceInitialization credits reader nodes with requested balances - happy path', async t => {
+		const recipientCount = 2;
+		const networkContext = await setupBalanceInitializationScenario(t, recipientCount);
+		const adminNode = networkContext.adminBootstrap;
+		const readerNodes = networkContext.peers.slice(1);
+		const recipients = [];
+
+		for (let i = 0; i < recipientCount; i++) {
+			const peer = readerNodes[i];
+			recipients.push({
+				peer,
+				balance: i === 0 ? toTerm(25n) : toTerm(75n)
+			});
+		}
+
+		const appliedTxHashes = [];
+
+		for (const recipient of recipients) {
+			const payload = await buildBalanceInitializationPayload(
+				networkContext,
+				recipient.peer.wallet.address,
+				recipient.balance
+			);
+			const decodedPayload = safeDecodeApplyOperation(payload);
+			appliedTxHashes.push(decodedPayload.bio.tx.toString('hex'));
+
+			await adminNode.base.append(payload);
+			await adminNode.base.update();
+			await eventFlush();
+		}
+
+		for (const recipient of recipients) {
+			await assertRecipientBalance(
+				t,
+				adminNode.base,
+				recipient.peer.wallet.address,
+				recipient.balance
+			);
+		}
+
+		for (const txHashHex of appliedTxHashes) {
+			const txEntry = await adminNode.base.view.get(txHashHex);
+			t.ok(txEntry, 'operation hash stored to prevent replays');
+		}
+
+		await networkContext.sync();
+
+		for (const recipient of recipients) {
+			await assertRecipientBalance(
+				t,
+				recipient.peer.base,
+				recipient.peer.wallet.address,
+				recipient.balance
+			);
+		}
+	});
+}
+
+async function assertRecipientBalance(t, base, address, expectedBalance) {
+	const nodeEntryRecord = await base.view.get(address);
+	t.ok(nodeEntryRecord, 'recipient node entry exists');
+
+	const decodedEntry = nodeEntryUtils.decode(nodeEntryRecord.value);
+	t.ok(decodedEntry, 'recipient node entry decodes');
+	t.is(decodedEntry.isWriter, false, 'recipient not flagged as writer');
+	t.is(decodedEntry.isIndexer, false, 'recipient not flagged as indexer');
+	t.ok(b4a.equals(decodedEntry.wk, ZERO_WK), 'recipient writing key remains unset');
+	t.ok(b4a.equals(decodedEntry.balance, expectedBalance), 'recipient balance is set');
+	t.ok(b4a.equals(decodedEntry.stakedBalance, toTerm(0n)), 'recipient staked balance is zero');
+}

package/tests/unit/state/apply/balanceInitialization/balanceInitializationScenarioHelpers.js

@@ -0,0 +1,106 @@
+import b4a from 'b4a';
+import { setupStateNetwork } from '../../../../helpers/StateNetworkFactory.js';
+import {
+	seedBootstrapIndexer,
+	defaultOpenHyperbeeView,
+	deriveIndexerSequenceState,
+	eventFlush
+} from '../../../../helpers/autobaseTestHelpers.js';
+import CompleteStateMessageOperations from '../../../../../src/messages/completeStateMessages/CompleteStateMessageOperations.js';
+import { AUTOBASE_VALUE_ENCODING } from '../../../../../src/utils/constants.js';
+import { toTerm } from '../../../../../src/core/state/utils/balance.js';
+import { safeDecodeApplyOperation, safeEncodeApplyOperation } from '../../../../../src/utils/protobuf/operationHelpers.js';
+import { buildAddAdminRequesterPayload } from '../addAdmin/addAdminScenarioHelpers.js';
+
+export async function setupBalanceInitializationScenario(t, { recipientCount = 2 } = {}) {
+	const context = await setupStateNetwork({
+		nodes: Math.max(recipientCount + 1, 2),
+		valueEncoding: AUTOBASE_VALUE_ENCODING,
+		open: defaultOpenHyperbeeView
+	});
+
+	seedBootstrapIndexer(context);
+
+	t.teardown(async () => {
+		await context.teardown();
+	});
+
+	await bootstrapAdmin(context);
+	return context;
+}
+
+async function bootstrapAdmin(context) {
+	const adminNode = context.adminBootstrap;
+	const addAdminPayload = await buildAddAdminRequesterPayload(context);
+
+	await adminNode.base.append(addAdminPayload);
+	await adminNode.base.update();
+	await eventFlush();
+}
+
+export async function buildBalanceInitializationPayload(context, recipientAddress, balanceBuffer) {
+	const adminNode = context.adminBootstrap;
+	const txValidity = await deriveIndexerSequenceState(adminNode.base);
+	const messages = await CompleteStateMessageOperations.assembleBalanceInitializationMessages(
+		adminNode.wallet,
+		txValidity,
+		[[recipientAddress, balanceBuffer]]
+	);
+	return messages[0];
+}
+
+export async function buildBalanceInitializationPayloadWithTxValidity({
+	context,
+	validPayload,
+	mutatedTxValidity
+}) {
+	const decoded = safeDecodeApplyOperation(validPayload);
+	if (!decoded?.bio?.ia || !decoded?.bio?.am) {
+		return validPayload;
+	}
+
+	const adminNode = context.adminBootstrap;
+	const messages = await CompleteStateMessageOperations.assembleBalanceInitializationMessages(
+		adminNode.wallet,
+		mutatedTxValidity,
+		[[decoded.bio.ia, decoded.bio.am]]
+	);
+	return messages[0];
+}
+
+export async function buildDefaultBalanceInitializationPayload(context) {
+	const recipientPeer = selectRecipientPeer(context);
+	return buildBalanceInitializationPayload(context, recipientPeer.wallet.address, toTerm(25n));
+}
+
+export async function assertBalanceInitializationFailureState(t, context, { skipSync = false } = {}) {
+	const adminNode = context.adminBootstrap;
+	const recipientPeer = selectRecipientPeer(context);
+
+	await assertRecipientAbsent(t, adminNode.base, recipientPeer.wallet.address);
+
+	if (!skipSync) {
+		await context.sync();
+		await assertRecipientAbsent(t, recipientPeer.base, recipientPeer.wallet.address);
+	}
+}
+
+export function mutateBalanceInitializationPayloadForInvalidSchema(t, payload) {
+	const decodedPayload = safeDecodeApplyOperation(payload);
+	t.ok(decodedPayload, 'fixtures decode');
+
+	decodedPayload.bio.tx = b4a.alloc(decodedPayload.bio.tx.length);
+	return safeEncodeApplyOperation(decodedPayload);
+}
+
+function selectRecipientPeer(context, offset = 0) {
+	const readerPeers = context.peers.slice(1);
+	return readerPeers[Math.min(offset, readerPeers.length - 1)];
+}
+
+async function assertRecipientAbsent(t, base, address) {
+	const nodeEntryRecord = await base.view.get(address);
+	t.is(nodeEntryRecord, null, 'recipient node entry remains absent');
+}
+
+export default setupBalanceInitializationScenario;

package/tests/unit/state/apply/balanceInitialization/invalidAmountScenario.js

@@ -0,0 +1,45 @@
+import { eventFlush } from '../../../../helpers/autobaseTestHelpers.js';
+import OperationValidationScenarioBase from '../common/base/OperationValidationScenarioBase.js';
+import { safeDecodeApplyOperation, safeEncodeApplyOperation } from '../../../../../src/utils/protobuf/operationHelpers.js';
+import setupBalanceInitializationScenario, {
+	buildDefaultBalanceInitializationPayload,
+	assertBalanceInitializationFailureState
+} from './balanceInitializationScenarioHelpers.js';
+
+export default function balanceInitializationInvalidAmountScenario() {
+	new OperationValidationScenarioBase({
+		title: 'State.apply balanceInitialization aborts when amount buffer is malformed',
+		setupScenario: setupBalanceInitializationScenario,
+		buildValidPayload: buildDefaultBalanceInitializationPayload,
+		mutatePayload: truncateAmountBuffer,
+		applyInvalidPayload: bypassSchemaAndApply,
+		assertStateUnchanged: assertBalanceInitializationFailureState,
+		expectedLogs: ['Invalid balance.']
+	}).performScenario();
+}
+
+function truncateAmountBuffer(t, payload) {
+	const decodedPayload = safeDecodeApplyOperation(payload);
+	t.ok(decodedPayload, 'fixtures decode');
+
+	decodedPayload.bio.am = decodedPayload.bio.am.slice(0, 8);
+	return safeEncodeApplyOperation(decodedPayload);
+}
+
+async function bypassSchemaAndApply(context, invalidPayload) {
+	const adminNode = context.adminBootstrap;
+	if (!adminNode) {
+		throw new Error('Invalid amount scenario requires admin bootstrap context.');
+	}
+
+	const originalValidator = adminNode.state.check.validateBalanceInitialization;
+	adminNode.state.check.validateBalanceInitialization = () => true;
+
+	try {
+		await adminNode.base.append(invalidPayload);
+		await adminNode.base.update();
+		await eventFlush();
+	} finally {
+		adminNode.state.check.validateBalanceInitialization = originalValidator;
+	}
+}

package/tests/unit/state/apply/balanceInitialization/nodeEntryBalanceUpdateFailureScenario.js

@@ -0,0 +1,81 @@
+import b4a from 'b4a';
+import OperationValidationScenarioBase from '../common/base/OperationValidationScenarioBase.js';
+import { eventFlush } from '../../../../helpers/autobaseTestHelpers.js';
+import { safeDecodeApplyOperation } from '../../../../../src/utils/protobuf/operationHelpers.js';
+import addressUtils from '../../../../../src/core/state/utils/address.js';
+import setupBalanceInitializationScenario, {
+	buildDefaultBalanceInitializationPayload,
+	assertBalanceInitializationFailureState
+} from './balanceInitializationScenarioHelpers.js';
+
+export default function balanceInitializationNodeEntryBalanceUpdateFailureScenario() {
+	new OperationValidationScenarioBase({
+		title: 'State.apply balanceInitialization aborts when updating existing node entry balance fails',
+		setupScenario: setupBalanceInitializationScenario,
+		buildValidPayload: buildDefaultBalanceInitializationPayload,
+		mutatePayload: (_t, payload) => payload,
+		applyInvalidPayload: applyWithCorruptExistingNodeEntry,
+		assertStateUnchanged: (t, context) =>
+			assertBalanceInitializationFailureState(t, context, { skipSync: true }),
+		expectedLogs: ['Failed to set node entry balance.']
+	}).performScenario();
+}
+
+async function applyWithCorruptExistingNodeEntry(context, payload, _t, validPayload) {
+	const node = context.adminBootstrap;
+	if (!node?.base) {
+		throw new Error('Balance update failure scenario requires an admin bootstrap node.');
+	}
+
+	const decoded = safeDecodeApplyOperation(validPayload ?? payload);
+	const targetAddressBuffer = decoded?.bio?.ia;
+	const targetAddressString = targetAddressBuffer
+		? addressUtils.bufferToAddress(targetAddressBuffer)
+		: null;
+	if (!targetAddressString || !targetAddressBuffer) {
+		throw new Error('Failed to resolve recipient address for balance update failure scenario.');
+	}
+
+	const originalApply = node.base._handlers.apply;
+	node.base._handlers.apply = async function patchedApply(nodes, view, baseCtx) {
+		const originalBatch = view.batch;
+		view.batch = function patchedBatch(...args) {
+			const batch = originalBatch.apply(this, args);
+			if (!batch?.get) return batch;
+
+			const originalGet = batch.get.bind(batch);
+			batch.get = async key => {
+				if (isTargetKey(key, targetAddressString, targetAddressBuffer)) {
+					return { key, value: b4a.alloc(1) };
+				}
+				return originalGet(key);
+			};
+
+			return batch;
+		};
+
+		try {
+			return await originalApply.call(this, nodes, view, baseCtx);
+		} finally {
+			view.batch = originalBatch;
+		}
+	};
+
+	try {
+		await node.base.append(payload);
+		await node.base.update();
+		await eventFlush();
+	} finally {
+		node.base._handlers.apply = originalApply;
+	}
+}
+
+function isTargetKey(key, targetAddressString, targetAddressBuffer) {
+	if (typeof key === 'string') {
+		return key === targetAddressString;
+	}
+	if (b4a.isBuffer(key) && targetAddressBuffer) {
+		return b4a.equals(key, targetAddressBuffer);
+	}
+	return false;
+}

package/tests/unit/state/apply/balanceInitialization/state.apply.balanceInitialization.test.js

@@ -0,0 +1,189 @@
+import setupBalanceInitializationScenario, {
+	buildDefaultBalanceInitializationPayload,
+	assertBalanceInitializationFailureState,
+	mutateBalanceInitializationPayloadForInvalidSchema,
+	buildBalanceInitializationPayloadWithTxValidity
+} from './balanceInitializationScenarioHelpers.js';
+import balanceInitializationHappyPathScenario from './balanceInitializationHappyPathScenario.js';
+import balanceInitializationInvalidAmountScenario from './invalidAmountScenario.js';
+import balanceInitializationNodeEntryBalanceUpdateFailureScenario from './nodeEntryBalanceUpdateFailureScenario.js';
+import RequesterAddressValidationScenario from '../common/requesterAddressValidationScenario.js';
+import InvalidPayloadValidationScenario from '../common/payload-structure/invalidPayloadValidationScenario.js';
+import InvalidAddressValidationScenario from '../common/payload-structure/invalidAddressValidationScenario.js';
+import createAddressWithInvalidPublicKeyScenario from '../common/payload-structure/addressWithInvalidPublicKeyScenario.js';
+import createRequesterPublicKeyValidationScenario from '../common/requesterPublicKeyValidationScenario.js';
+import InvalidHashValidationScenario from '../common/payload-structure/invalidHashValidationScenario.js';
+import InvalidSignatureValidationScenario, { SignatureMutationStrategy } from '../common/payload-structure/invalidSignatureValidationScenario.js';
+import InvalidMessageComponentValidationScenario, { MessageComponentStrategy } from '../common/invalidMessageComponentValidationScenario.js';
+import InitializationDisabledScenario from '../common/payload-structure/initializationDisabledScenario.js';
+import AdminEntryDecodeFailureScenario from '../common/access-control/adminEntryDecodeFailureScenario.js';
+import AdminOnlyGuardScenario from '../common/access-control/adminOnlyGuardScenario.js';
+import AdminConsistencyMismatchScenario from '../common/access-control/adminConsistencyMismatchScenario.js';
+import IndexerSequenceStateInvalidScenario from '../common/indexer/indexerSequenceStateInvalidScenario.js';
+import TransactionValidityMismatchScenario from '../common/transactionValidityMismatchScenario.js';
+
+balanceInitializationHappyPathScenario();
+
+new InvalidPayloadValidationScenario({
+	title: 'State.apply balanceInitialization rejects payloads that fail schema validation',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	mutatePayload: mutateBalanceInitializationPayloadForInvalidSchema,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	expectedLogs: ['Contract schema validation failed.']
+}).performScenario();
+
+new RequesterAddressValidationScenario({
+	title: 'State.apply balanceInitialization requester address is invalid',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	expectedLogs: ['Requester address is invalid.']
+}).performScenario();
+
+createRequesterPublicKeyValidationScenario({
+	title: 'State.apply balanceInitialization requester public key is invalid',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	expectedLogs: ['Error while decoding requester public key.']
+}).performScenario();
+
+new InvalidAddressValidationScenario({
+	title: 'State.apply balanceInitialization recipient address is invalid',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	addressPath: ['bio', 'ia'],
+	expectedLogs: ['Recipient address is invalid.']
+}).performScenario();
+
+createAddressWithInvalidPublicKeyScenario({
+	title: 'State.apply balanceInitialization recipient public key is invalid',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	addressPath: ['bio', 'ia'],
+	expectedLogs: ['Failed to decode recipient public key.']
+}).performScenario();
+
+balanceInitializationInvalidAmountScenario();
+
+new InitializationDisabledScenario({
+	title: 'State.apply balanceInitialization aborts when initialization is disabled',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	expectedLogs: ['Balance initialization is disabled.']
+}).performScenario();
+
+new AdminEntryDecodeFailureScenario({
+	title: 'State.apply balanceInitialization aborts when admin entry cannot be decoded',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: (t, context) =>
+		assertBalanceInitializationFailureState(t, context, { skipSync: true }),
+	expectedLogs: ['Failed to decode admin entry.']
+}).performScenario();
+
+new AdminOnlyGuardScenario({
+	title: 'State.apply balanceInitialization rejects non-admin nodes',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: (t, context) =>
+		assertBalanceInitializationFailureState(t, context, { skipSync: true }),
+	expectedLogs: ['Node is not allowed to perform this operation. (ADMIN ONLY)']
+}).performScenario();
+
+new AdminConsistencyMismatchScenario({
+	title: 'State.apply balanceInitialization rejects when admin key mismatch occurs',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: (t, context) =>
+		assertBalanceInitializationFailureState(t, context, { skipSync: true }),
+	expectedLogs: ['System admin and node public keys do not match.']
+}).performScenario();
+
+
+new InvalidHashValidationScenario({
+	title: 'State.apply balanceInitialization requester message hash mismatch',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	expectedLogs: ['Message hash does not match the tx_hash.']
+}).performScenario();
+
+new InvalidSignatureValidationScenario({
+	title: 'State.apply balanceInitialization requester signature is invalid (foreign signature)',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	expectedLogs: ['Failed to verify message signature.']
+}).performScenario();
+
+new InvalidSignatureValidationScenario({
+	title: 'State.apply balanceInitialization requester signature is invalid (type mismatch)',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	strategy: SignatureMutationStrategy.TYPE_MISMATCH,
+	expectedLogs: ['Failed to verify message signature.']
+}).performScenario();
+
+new InvalidSignatureValidationScenario({
+	title: 'State.apply balanceInitialization requester signature is invalid (zero fill)',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	strategy: SignatureMutationStrategy.ZERO_FILL,
+	expectedLogs: ['Failed to verify message signature.']
+}).performScenario();
+
+new InvalidSignatureValidationScenario({
+	title: 'State.apply balanceInitialization amount signature is invalid',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	strategy: SignatureMutationStrategy.AMOUNT_SIGNATURE,
+	expectedLogs: ['Message hash does not match the tx_hash.']
+}).performScenario();
+
+new IndexerSequenceStateInvalidScenario({
+	title: 'State.apply balanceInitialization rejects payloads when indexer sequence state is invalid',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: (t, context) =>
+		assertBalanceInitializationFailureState(t, context, { skipSync: true }),
+	expectedLogs: ['Indexer sequence state is invalid.']
+}).performScenario();
+
+new TransactionValidityMismatchScenario({
+	title: 'State.apply balanceInitialization rejects payload when tx validity mismatches indexer state',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	txValidityPath: ['bio', 'txv'],
+	rebuildPayloadWithTxValidity: ({ context, validPayload, mutatedTxValidity }) =>
+		buildBalanceInitializationPayloadWithTxValidity({ context, validPayload, mutatedTxValidity }),
+	expectedLogs: ['Transaction was not executed.']
+}).performScenario();
+
+new InvalidMessageComponentValidationScenario({
+	title: 'State.apply balanceInitialization transaction validity mismatch',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	strategy: MessageComponentStrategy.TX_VALIDITY,
+	expectedLogs: ['Message hash does not match the tx_hash.']
+}).performScenario();
+
+new InvalidMessageComponentValidationScenario({
+	title: 'State.apply balanceInitialization requester nonce mismatch',
+	setupScenario: setupBalanceInitializationScenario,
+	buildValidPayload: buildDefaultBalanceInitializationPayload,
+	assertStateUnchanged: assertBalanceInitializationFailureState,
+	strategy: MessageComponentStrategy.NONCE,
+	expectedLogs: ['Message hash does not match the tx_hash.']
+}).performScenario();
+
+balanceInitializationNodeEntryBalanceUpdateFailureScenario();

package/tests/unit/state/apply/banValidator/banValidatorBanAndReWhitelistScenario.js

@@ -0,0 +1,155 @@
+import { test } from 'brittle';
+import b4a from 'b4a';
+import { eventFlush } from '../../../../helpers/autobaseTestHelpers.js';
+import {
+	selectWriterPeer,
+	buildAddWriterPayload,
+	assertAddWriterSuccessState
+} from '../addWriter/addWriterScenarioHelpers.js';
+import {
+	setupBanValidatorScenario,
+	buildBanValidatorPayload,
+	assertBanValidatorSuccessState
+} from './banValidatorScenarioHelpers.js';
+import {
+	buildAppendWhitelistPayload
+} from '../appendWhitelist/appendWhitelistScenarioHelpers.js';
+import nodeEntryUtils, { ZERO_LICENSE } from '../../../../../src/core/state/utils/nodeEntry.js';
+import addressUtils from '../../../../../src/core/state/utils/address.js';
+import { EntryType } from '../../../../../src/utils/constants.js';
+import { BALANCE_ZERO, toBalance } from '../../../../../src/core/state/utils/balance.js';
+import lengthEntryUtils from '../../../../../src/core/state/utils/lengthEntry.js';
+
+export default function banValidatorBanAndReWhitelistScenario() {
+	test('State.apply banValidator allows re-whitelisting without changing license', async t => {
+		const context = await setupBanValidatorScenario(t);
+		const adminPeer = context.adminBootstrap;
+		const validatorPeer = context.banValidatorScenario?.validatorPeer ?? selectWriterPeer(context);
+
+		const validatorEntryBefore = await adminPeer.base.view.get(validatorPeer.wallet.address);
+		t.ok(validatorEntryBefore, 'validator entry exists before banValidator');
+		const decodedBefore = nodeEntryUtils.decode(validatorEntryBefore?.value);
+		t.ok(decodedBefore, 'validator entry decodes before banValidator');
+		if (!decodedBefore) return;
+
+		const adminEntryBefore = await adminPeer.base.view.get(adminPeer.wallet.address);
+		t.ok(adminEntryBefore, 'admin entry exists before banValidator');
+
+		const banPayload = await buildBanValidatorPayload(context, { adminPeer, validatorPeer });
+
+		await adminPeer.base.append(banPayload);
+		await adminPeer.base.update();
+		await eventFlush();
+
+		await assertBanValidatorSuccessState(t, context, {
+			validatorPeer,
+			adminPeer,
+			validatorEntryBefore,
+			adminEntryBefore,
+			payload: banPayload
+		});
+
+		const bannedEntry = await adminPeer.base.view.get(validatorPeer.wallet.address);
+		t.ok(bannedEntry, 'validator entry exists after ban');
+		const decodedBanned = nodeEntryUtils.decode(bannedEntry?.value);
+		t.ok(decodedBanned, 'validator entry decodes after ban');
+		if (!decodedBanned) return;
+		const bannedBalance = toBalance(decodedBanned.balance);
+		t.ok(bannedBalance, 'balance decodes after ban');
+
+		const whitelistPayload = await buildAppendWhitelistPayload(
+			context,
+			validatorPeer.wallet.address
+		);
+
+		await adminPeer.base.append(whitelistPayload);
+		await adminPeer.base.update();
+		await eventFlush();
+
+	const rewhitelistedEntry = await adminPeer.base.view.get(validatorPeer.wallet.address);
+	t.ok(rewhitelistedEntry, 'validator entry exists after re-whitelist');
+	const decodedRewhitelisted = nodeEntryUtils.decode(rewhitelistedEntry?.value);
+	t.ok(decodedRewhitelisted, 'validator entry decodes after re-whitelist');
+	if (!decodedRewhitelisted || !bannedBalance) return;
+
+		t.is(decodedRewhitelisted.isWhitelisted, true, 'node marked whitelisted after reapply');
+		t.is(decodedRewhitelisted.isWriter, false, 'writer flag remains cleared after reapply');
+		t.is(decodedRewhitelisted.isIndexer, false, 'indexer flag remains cleared after reapply');
+		t.ok(b4a.equals(decodedRewhitelisted.wk, decodedBefore.wk), 'writing key preserved');
+		t.ok(
+			b4a.equals(decodedRewhitelisted.balance, bannedBalance.value),
+			'balance unchanged by re-whitelist'
+		);
+		t.ok(
+			b4a.equals(decodedRewhitelisted.stakedBalance, BALANCE_ZERO.value),
+			'staked balance remains zero after re-whitelist'
+		);
+		t.ok(!b4a.equals(decodedRewhitelisted.license, ZERO_LICENSE), 'license retained after reapply');
+		t.ok(
+			b4a.equals(decodedRewhitelisted.license, decodedBefore.license),
+			'license unchanged after ban and re-whitelist'
+		);
+
+		const licenseId = decodedBefore.license.readUInt32BE();
+		const licenseIndexEntry = await adminPeer.base.view.get(`${EntryType.LICENSE_INDEX}${licenseId}`);
+		t.ok(licenseIndexEntry, 'license index entry persists after re-whitelist');
+		const addressBuffer = addressUtils.addressToBuffer(validatorPeer.wallet.address);
+	if (licenseIndexEntry?.value && addressBuffer) {
+		t.ok(
+			b4a.equals(licenseIndexEntry.value, addressBuffer),
+			'license index still maps to validator address'
+		);
+	}
+
+	const writersLengthEntry = await adminPeer.base.view.get(EntryType.WRITERS_LENGTH);
+	const writersLengthBefore = writersLengthEntry
+		? lengthEntryUtils.decodeBE(writersLengthEntry.value)
+		: 0;
+
+	const addWriterPayload = await buildAddWriterPayload(context, {
+		readerPeer: validatorPeer,
+		validatorPeer: adminPeer
+	});
+
+	await adminPeer.base.append(addWriterPayload);
+	await adminPeer.base.update();
+	await eventFlush();
+
+	await assertAddWriterSuccessState(t, context, {
+		readerPeer: validatorPeer,
+		validatorPeer: adminPeer,
+		writerInitialBalance: decodedRewhitelisted.balance,
+		expectedWriterIndex: writersLengthBefore,
+		payload: addWriterPayload,
+		skipSync: true
+	});
+
+	const repromotedEntry = await adminPeer.base.view.get(validatorPeer.wallet.address);
+	t.ok(repromotedEntry, 'validator entry exists after re-promotion to writer');
+	const decodedRepromoted = nodeEntryUtils.decode(repromotedEntry?.value);
+	t.ok(decodedRepromoted, 'validator entry decodes after re-promotion to writer');
+	if (decodedRepromoted) {
+		t.is(decodedRepromoted.isWhitelisted, true, 'node remains whitelisted after re-promotion');
+		t.is(decodedRepromoted.isWriter, true, 'writer role reassigned after re-promotion');
+		t.is(decodedRepromoted.isIndexer, false, 'indexer flag stays cleared after re-promotion');
+		t.ok(
+			b4a.equals(decodedRepromoted.license, decodedBefore.license),
+			'license unchanged after re-promotion'
+		);
+	}
+
+	await context.sync();
+	const replicatedEntry = await validatorPeer.base.view.get(validatorPeer.wallet.address);
+	t.ok(replicatedEntry, 'replicated entry exists after re-whitelist and re-promotion');
+	const decodedReplicated = nodeEntryUtils.decode(replicatedEntry?.value);
+	t.ok(decodedReplicated, 'replicated entry decodes after re-whitelist and re-promotion');
+	if (decodedReplicated) {
+		t.is(decodedReplicated.isWhitelisted, true, 'replicated entry whitelisted');
+		t.is(decodedReplicated.isWriter, true, 'replicated entry writer flag set');
+		t.ok(
+			b4a.equals(decodedReplicated.license, decodedBefore.license),
+			'replicated entry license unchanged'
+		);
+	}
+	});
+}