불변 객체

Sui의 객체는 서로 다른 소유권 유형을 가지며, 주요 범주는 두 가지이다: 불변 객체와 mutable 객체. Immutable 객체는 변경, 전송, 삭제가 불가능하다. 이러한 객체는 owner가 없으며 모든 사용자가 자유롭게 접근할 수 있다.

Create 불변 객체

Object를 immutable하게 만들기 위해서는 transfer module에서 sui::transfer::public_freeze_object 함수를 호출해야 한다:

public native fun public_freeze_object<T: key>(obj: T);

이 함수는 객체를 영구적으로 immutable 상태로 만든다. 이 작업은 되돌릴 수 없다. 수정이 필요하지 않다는 것이 확실할 때에만 객체를 freeze해야 한다.

이 함수의 사용 예시는 color_object example module tests 중 하나에서 확인할 수 있다. 이 테스트는 새로운 (owned) ColorObject를 생성한 후 public_freeze_object를 호출하여 immutable object로 변환한다.

examples/move/color_object/sources/example.move
#[test]
fun test_immutable() {
    let mut ts = ts::begin(@0x0);
    let alice = @0xA;
    let bob = @0xB;

    {
        ts.next_tx(alice);
        let c = new(255, 0, 255, ts.ctx());
        transfer::public_freeze_object(c);
    };

    {
        ts.next_tx(alice);
        assert!(!ts.has_most_recent_for_sender<ColorObject>(), 0);
    };

    {
        ts.next_tx(bob);
        let object: ColorObject = ts.take_immutable();
        let (red, green, blue) = object.get_color();
        assert!(red == 255 && green == 0 && blue == 255, 0);
        ts::return_immutable(object);
    };

    ts.end();
}

이 테스트에서는 처음에 ColorObject를 소유하고 있어야 한다. Object를 freeze한 이후에는 immutable 상태가 되며, owner가 사라진다.

sui::transfer::public_freeze_object 함수는 객체를 값으로 전달해야 한다. 만약 객체를 mutable reference로 전달할 수 있다면, sui::transfer::public_freeze_object 호출 이후에도 객체를 변경할 수 있게 되어 immutable 상태가 되어야 한다는 원칙과 모순된다.

대안으로는 생성 시점에 불변 객체를 만드는 API를 제공할 수 있다:

public fun create_immutable(red: u8, green: u8, blue: u8, ctx: &mut TxContext) {
    let color_object = new(red, green, blue, ctx);
    transfer::public_freeze_object(color_object)
}

이 함수는 새로운 ColorObject를 생성하고, owner가 생기기 전에 즉시 immutable 상태로 만든다.

Use 불변 객체

Object가 immutable 상태가 되면, Sui Move에서 이 객체를 사용할 수 있는 규칙이 달라진다: 불변 객체는 &T 형태의 읽기 전용(immutable) reference로만 Sui Move entry 함수에 전달할 수 있다.

모든 네트워크 참여자는 불변 객체에 접근할 수 있다.

이제 한 객체의 값을 다른 객체로 복사하는 함수를 살펴보자:

public fun copy_into(from: &ColorObject, into: &mut ColorObject);

이 함수에서는 누구나 첫 번째 인자인 from으로 불변 객체를 전달할 수 있지만, 두 번째 인자로는 전달할 수 없다. Immutable 객체는 변경할 수 없기 때문에, 여러 트랜잭션이 동시에 동일한 불변 객체를 사용하더라도 data race가 발생하지 않는다. 따라서 불변 객체의 존재는 consensus에 어떤 요구 사항도 부과하지 않는다.

Test 불변 객체

Unit test에서 불변 객체와 상호작용하기 위해서는 test_scenario::take_immutable<T>를 사용하여 global storage에서 불변 객체 wrapper를 가져오고, test_scenario::return_immutable 을 사용하여 wrapper를 global storage로 다시 반환한다.

Immutable 객체는 오직 read-only reference를 통해서만 접근할 수 있기 때문에 test_scenario::take_immutable<T> 함수가 필요하다. test_scenario runtime은 이 불변 객체의 사용을 추적한다. Compiler가 다음 트랜잭션이 시작되기 전 test_scenario::return_immutable을 통해 객체를 반환하지 않으면 테스트가 중단된다.

이는 다음 예시에서 확인할 수 있다:

$ export ADDR=`sui client active-address`

해당 테스트는 sender1 트랜잭션을 제출하며, 불변 객체를 생성하려고 시도한다.

has_most_recent_for_sender<ColorObject> 함수는 해당 객체가 더 이상 소유되지 않기 때문에 더 이상 true를 반환하지 않는다. 해당 객체를 다시 소유하기 위해서는:

$ sui client objects $ADDR

이 객체가 실제로 누구에게도 소유되지 않았음을 보여주기 위해, 다음 트랜잭션을sender2로 시작한다. take_immutable이 사용되었으며 성공했다는 점에 주목해야 한다. 이는 모든 sender가 불변 객체를 가져올 수 있음을 의미한다. Object를 반환하려면 return_immutable 함수를 호출한다.

객체의 변경 불가능함을 검증하기 위해서는 ColorObject를 수정하려는 함수를 생성한다:

$ sui client publish $ROOT/examples/move/color_object --gas-budget <GAS-AMOUNT>

앞서 배운 것처럼, ColorObject는 immutable 상태일 경우 실패한다.

On-chain interactions

먼저 자신이 소유한 객체를 확인한다:

$ sui client call --gas-budget <GAS-AMOUNT> --package $PACKAGE --module "color_object" --function "create" --args 0 255 0

$ sui client objects $ADDR

Sui Client CLI를 사용하여 ColorObject 코드를 on-chain에 publish한다:

팁

Beginning with the Sui v1.24.1 release, the --gas-budget option is no longer required for CLI commands.

$ sui client call --gas-budget <GAS-AMOUNT> --package $PACKAGE --module "color_object" --function "freeze_object" --args \"$OBJECT\"

$PACKAGE 환경 변수가 설정되어 있다면, 패키지 객체 ID를 해당 변수에 할당한다. 이후 새로운 ColorObject를 생성한다:

$ sui client objects $ADDR

새로 생성된 객체 ID를 $OBJECT에 저장한다. 현재 활성화된 주소에 있는 객체 목록을 확인한다:

$ sui client object $OBJECT

$OBJECT로 사용한 ID를 가진 객체가 표시되어야 한다. Immutable 객체로 변환하기 위해서는:

Owner: Immutable  // This field shows the object's immutable status

다시 객체 목록을 확인한다:

$ sui client call --gas-budget <GAS-AMOUNT> --package $PACKAGE --module "color_object" --function "update" --args \"$OBJECT\" 0 0 0

$OBJECT는 더 이상 목록에 표시되지 않는다. 다음 명령어를 사용해 객체 정보를 조회하면 immutable 상태임을 확인할 수 있다:

let sender1 = @0x1;
let scenario_val = test_scenario::begin(sender1);
let scenario = &mut scenario_val;
{
    let ctx = test_scenario::ctx(scenario);
    color_object::create_immutable(255, 0, 255, ctx);
};
scenario.next_tx(sender1);
{
    // has_most_recent_for_sender returns false for immutable objects.
    assert!(!test_scenario::has_most_recent_for_sender<ColorObject>(scenario))
};

출력 결과에는 다음과 같은 정보가 포함된다:

// Any sender can work.
let sender2 = @0x2;
scenario.next_tx(sender2);
{
    let object = test_scenario::take_immutable<ColorObject>(scenario);
    let (red, green, blue) = color_object::get_color(object);
    assert!(red == 255 && green == 0 && blue == 255)
    test_scenario::return_immutable(object);
};

이 객체를 변경하려 시도할 경우, 다음과 같은 결과가 나타난다:

public fun update(
    object: &mut ColorObject,
    red: u8, green: u8, blue: u8,
) {
    object.red = red;
    object.green = green;
    object.blue = blue;
}

출력 결과는 불변 객체를 mutable 인자로 전달할 수 없음을 나타낸다.

Create 불변 객체​

Use 불변 객체​

Test 불변 객체​

On-chain interactions​

Create 불변 객체

Use 불변 객체

Test 불변 객체

On-chain interactions