Skip to main content
Version: 11.x

Class: CairoContractAddress

Defined in: src/utils/cairoDataTypes/contractAddress.ts:28

A Cairo core::starknet::contract_address::ContractAddress : the address of a deployed contract.

On the wire it is a field element like any other, so what this class adds over CairoFelt252 is the narrower bound an address has : ADDR_BOUND, which is what an address is computed modulo and what validateAndParseAddress already refuses to exceed. The 252 bits the RPC spec states are looser than both, and never what binds.

A number, a bigint, a decimal string and a hexadecimal string are all read as the same number. Text is not an accepted input : an address spelled as words is a mistake, not a value.

Example​

// the same address, reached three ways
new CairoContractAddress('0x1234').toBigInt(); // 4660n
new CairoContractAddress(4660).toBigInt(); //    4660n
new CairoContractAddress('4660').toBigInt(); //  4660n

Constructors​

Constructor​

new CairoContractAddress(data): CairoContractAddress

Defined in: src/utils/cairoDataTypes/contractAddress.ts:59

Build from a number or a numeric string, refusing text and anything wider than 252 bits.

Parameters​

data​

unknown

the address to carry, within [0, 2^252 - 1]

Returns​

CairoContractAddress

Throws​

when the value is text, is not a felt252 input, or is out of range

Example​

const result = new CairoContractAddress('0x1234').toApiRequest();
// result = ["4660"]

Properties​

abiSelector​

static abiSelector: "core::starknet::contract_address::ContractAddress" = Literal.ContractAddress

Defined in: src/utils/cairoDataTypes/contractAddress.ts:47

The abi type this class serializes.

Example​

const result = CairoContractAddress.abiSelector;
// result = "core::starknet::contract_address::ContractAddress"

data​

data: bigint

Defined in: src/utils/cairoDataTypes/contractAddress.ts:37

The address, always as a bigint.

Example​

const result = new CairoContractAddress('0x1234').data;
// result = 4660n

Methods​

validate()​

static validate(data): void

Defined in: src/utils/cairoDataTypes/contractAddress.ts:125

Throw unless the value can be carried by a ContractAddress.

Text is refused first, then the value is read as a felt252 — which is what refuses a null, an object or an unsupported type — and finally checked against the bound an address has, which is narrower than the field.

Parameters​

data​

unknown

the value to check

Returns​

void

Throws​

when the value is text, is not a felt252 input, or is out of range

Example​

CairoContractAddress.validate('0x1234'); // passes
CairoContractAddress.validate('abc');
// throws Error("Invalid input: a ContractAddress cannot be built from text")
CairoContractAddress.validate(2n ** 251n);
// throws Error("Value is out of ContractAddress range [0, 3618502788666131106986593281521497120414687020801267626233049500247285300991]")

is()​

static is(data): boolean

Defined in: src/utils/cairoDataTypes/contractAddress.ts:150

Can this value be carried by a ContractAddress?

The non-throwing form of CairoContractAddress.validate, so it answers false for every input that one refuses, whatever the reason.

Parameters​

data​

unknown

the value to test

Returns​

boolean

true when the value fits in a ContractAddress

Example​

const result = CairoContractAddress.is('0x1234');
// result = true
const result2 = CairoContractAddress.is('abc');
// result2 = false     (text, not a number)

isAbiType()​

static isAbiType(abiType): boolean

Defined in: src/utils/cairoDataTypes/contractAddress.ts:173

Is this abi type the one this class serializes?

Parameters​

abiType​

string

the abi type to test

Returns​

boolean

true for core::starknet::contract_address::ContractAddress

Example​

const result = CairoContractAddress.isAbiType(
  'core::starknet::contract_address::ContractAddress'
);
// result = true
const result2 = CairoContractAddress.isAbiType('core::felt252');
// result2 = false

factoryFromApiResponse()​

static factoryFromApiResponse(responseIterator): CairoContractAddress

Defined in: src/utils/cairoDataTypes/contractAddress.ts:188

Read one ContractAddress off a contract response, advancing the iterator past it.

Parameters​

responseIterator​

Iterator<string>

the response felts, positioned on this address

Returns​

CairoContractAddress

the address that was read

Example​

const response = ['0x1234'];
const result = CairoContractAddress.factoryFromApiResponse(response.values()).toBigInt();
// result = 4660n

toApiRequest()​

toApiRequest(): string[]

Defined in: src/utils/cairoDataTypes/contractAddress.ts:73

Serialize to the single felt a contract call carries.

Returns​

string[]

one decimal-string felt, flagged as compiled

Example​

const result = new CairoContractAddress('0x1234').toApiRequest();
// result = ["4660"]

toBigInt()​

toBigInt(): bigint

Defined in: src/utils/cairoDataTypes/contractAddress.ts:86

The address as a number.

Returns​

bigint

the number this address holds

Example​

const result = new CairoContractAddress('0x1234').toBigInt();
// result = 4660n

toHexString()​

toHexString(): string

Defined in: src/utils/cairoDataTypes/contractAddress.ts:104

The address in hexadecimal, without padding.

The 64 hex digits an address is usually written with are not restored here : leading zeros are dropped, as they are everywhere else in the library.

Returns​

string

the address as a 0x-prefixed hex string

Example​

const result = new CairoContractAddress(4660).toHexString();
// result = "0x1234"
const result2 = new CairoContractAddress('0x0034').toHexString();
// result2 = "0x34"     (four digits in, two out)